GlueGen: com.jogamp.common.util.Bitstream< T > Class Template Reference

GlueGen v2.6.0-rc-20250706 GlueGen, Native Binding Generator for Java™ (public API).

Classes | Public Member Functions | Static Public Member Functions | Static Public Attributes | Protected Member Functions | List of all members
com.jogamp.common.util.Bitstream< T > Class Template Reference

Versatile Bitstream implementation supporting: More...

Collaboration diagram for com.jogamp.common.util.Bitstream< T >:

## Classes

class | ByteArrayStream
| Specific `byte stream`. More...
class | ByteBufferStream
| Specific `byte stream`. More...
class | ByteInputStream
| Specific `byte stream`. More...
class | ByteOutputStream
| Specific `byte stream`. More...
interface | ByteStream
| General byte stream. More...

## Public Member Functions

| Bitstream (final ByteStream< T > stream, final boolean outputMode) throws IllegalArgumentException
final void | setThrowIOExceptionOnEOF (final boolean enable)
| Enables or disables throwing an `IOException` in case `EOS` appears. More...
final boolean | getThrowIOExceptionOnEOF ()
| Returns true if I/O methods throw an `IOException` if `EOS` appears, otherwise false (default). More...
final void | setStream (final T stream, final boolean outputMode) throws IllegalArgumentException, IOException
| Sets the underlying stream, without `close()`ing the previous one. More...
final ByteStream< T > | getStream ()
| Returns the currently used `ByteStream`. More...
final T | getSubStream ()
| Returns the currently used `ByteStream`'s `ByteStream#getStream()`. More...
final void | close () throws IOException
| Closing the underlying stream, implies `flush()`. More...
final int | flush () throws IllegalStateException, IOException
| Synchronizes all underlying `output stream` operations, or do nothing. More...
final boolean | canInput ()
| Return true if stream can handle input, i.e. More...
final boolean | canOutput ()
| Return true if stream can handle output, i.e. More...
final void | mark (final int readLimit) throws IllegalStateException
| Set `markpos` to current position, allowing the stream to be `reset()`. More...
final void | reset () throws IllegalStateException, IOException
| Reset stream position to markpos as set via `mark(int)`. More...
final int | getBitCount ()
| Number of remaining bits in cache to read before next byte-read (input mode) or number of remaining bits to be cached before next byte-write (output mode). More...
final int | getLastBitPos ()
| Return the last bit number read or written counting from [0..7]. More...
final int | getBitPosition ()
| Return the next bit number to be read or write counting from [0..7]. More...
final int | getBitBuffer ()
| Returns the current bit buffer. More...
final long | position ()
| Returns the bit position in the stream. More...
final long | position (final long newPosition) throws UnsupportedOperationException, IllegalArgumentException, IllegalStateException, IOException
| Sets this stream's bit position. More...
final int | readBit (final boolean msbFirst) throws UnsupportedOperationException, IllegalStateException, IOException
final int | writeBit (final boolean msbFirst, final int bit) throws IllegalStateException, IOException
long | skip (final long n) throws IllegalStateException, IOException
| It is implementation dependent, whether backward skip giving a negative number is supported or not. More...
int | readBits31 (final int n) throws IllegalArgumentException, IOException
| Return incoming bits as read via `readBit(boolean)` LSB-first as little-endian. More...
int | writeBits31 (final int n, final int bits) throws IllegalStateException, IllegalArgumentException, IOException
| Write the given bits via `writeBit(boolean, int)` LSB-first as little-endian. More...
final int | readUInt8 () throws IllegalStateException, IOException
| Return incoming `uint8_t` as read via `readBits31(int)`. More...
final int | writeInt8 (final byte int8) throws IllegalStateException, IOException
| Write the given 8 bits via `writeBits31(int, int)`. More...
final int | readUInt16 (final boolean bigEndian) throws IllegalStateException, IOException
| Return incoming `uint16_t` as read via `readBits31(int)` LSB-first as little-endian, hence bytes are swapped if bigEndian. More...
final int | writeInt16 (final boolean bigEndian, final short int16) throws IllegalStateException, IOException
| Write the given 16 bits via `writeBits31(int, int)` LSB-first as little-endian, hence bytes are swapped if bigEndian. More...
final long | readUInt32 (final boolean bigEndian) throws IllegalStateException, IOException
| Return incoming `uint32_t` as read via `readBits31(int)` LSB-first as little-endian, hence bytes are swapped if bigEndian. More...
final int | writeInt32 (final boolean bigEndian, final int int32) throws IllegalStateException, IOException
| Write the given 32 bits via `writeBits31(int, int)` LSB-first as little-endian, hence bytes are swapped if bigEndian. More...
String | toString ()

## Static Public Member Functions

static final int | readUInt16 (final boolean bigEndian, final byte[] bytes, final int offset) throws IndexOutOfBoundsException
| Return incoming `uint16_t` value and swap bytes according to bigEndian. More...
static final long | readUInt32 (final boolean bigEndian, final byte[] bytes, final int offset) throws IndexOutOfBoundsException
| Return incoming `uint32_t` and swap bytes according to bigEndian. More...
static final long | toUInt32Long (final int int32)
| Reinterpret the given `int32_t` value as `uint32_t`, i.e. More...
static final int | toUInt32Int (final int int32)
| Returns the reinterpreted given `int32_t` value as `uint32_t` if ≤ `Integer#MAX_VALUE` as within an `int` storage. More...
static final int | uint32LongToInt (final long uint32)
| Returns the given `uint32_t` value `long` value as `int` if ≤ `Integer#MAX_VALUE`. More...
static String | toBinString (final boolean msbFirst, final int v, final int bitCount)
static String | toHexBinString (final boolean msbFirst, final int v, final int bitCount)
static final String | toHexBinString (final boolean msbFirst, final byte[] data, final int offset, final int len)
static final String | toHexBinString (final boolean msbFirst, final ByteBuffer data, final int offset, final int len)
static void | checkBounds (final byte[] sb, final int offset, final int remaining) throws IndexOutOfBoundsException

## Static Public Attributes

static final int | EOS = -1
| End of stream marker, {@value} or 0xFFFFFFFF. More...

## Protected Member Functions

String | toStringImpl ()

## Detailed Description

Versatile Bitstream implementation supporting:

- Utilize I/O operations on I/O streams, buffers and arrays
- Consider MSBfirst / LSBfirst mode
- Linear bit R/W operations
- Bulk R/W operations w/ endian related type conversion
- Allow mark/reset and switching streams and input/output mode
- Optimized operations

Definition at line 51 of file Bitstream.java.

## Constructor & Destructor Documentation

## ◆ Bitstream()

com.jogamp.common.util.Bitstream< T >.Bitstream | ( | final ByteStream< T > | stream,
|  | final boolean | outputMode
| ) |  | throws IllegalArgumentException

Parameters

  stream |
  outputMode |

Exceptions

  IllegalArgumentException | if requested outputMode doesn't match stream's `canInput()` and `canOutput()`.

Definition at line 624 of file Bitstream.java.

## Member Function Documentation

## ◆ canInput()

final boolean com.jogamp.common.util.Bitstream< T >.canInput | ( |  | ) |

Return true if stream can handle input, i.e.

`readBit(boolean)`.

Definition at line 740 of file Bitstream.java.

## ◆ canOutput()

final boolean com.jogamp.common.util.Bitstream< T >.canOutput | ( |  | ) |

Return true if stream can handle output, i.e.

`writeBit(boolean, int)`.

Definition at line 743 of file Bitstream.java.

## ◆ checkBounds()

static void com.jogamp.common.util.Bitstream< T >.checkBounds | ( | final byte[] | sb,
|  | final int | offset,
|  | final int | remaining
| ) |  | throws IndexOutOfBoundsException

static

Definition at line 1558 of file Bitstream.java.

Here is the caller graph for this function:

## ◆ close()

final void com.jogamp.common.util.Bitstream< T >.close | ( |  | ) | throws IOException

Closing the underlying stream, implies `flush()`.

Implementation will `null` the stream references, hence `setStream(Object)` must be called before re-using instance.

If the closed stream was in `output mode`, `flush()` is being called.

Exceptions

  IOException |

Definition at line 701 of file Bitstream.java.

Here is the call graph for this function:
Here is the caller graph for this function:

## ◆ flush()

final int com.jogamp.common.util.Bitstream< T >.flush | ( |  | ) | throws IllegalStateException, IOException

Synchronizes all underlying `output stream` operations, or do nothing.

Method also flushes incomplete bytes to the underlying `ByteStream` and hence skips to the next byte position.

Returns
  `EOS` caused by writing, otherwise zero.

Exceptions

  IllegalStateException | if not in output mode or stream closed
  IOException |

Definition at line 720 of file Bitstream.java.

## ◆ getBitBuffer()

final int com.jogamp.common.util.Bitstream< T >.getBitBuffer | ( |  | ) |

Returns the current bit buffer.

See also
  getBitCount()

Definition at line 821 of file Bitstream.java.

## ◆ getBitCount()

final int com.jogamp.common.util.Bitstream< T >.getBitCount | ( |  | ) |

Number of remaining bits in cache to read before next byte-read (input mode) or number of remaining bits to be cached before next byte-write (output mode).

Counting down from 7..0 7..0, starting with 0.

In input mode, zero indicates reading a new byte and cont. w/ 7. In output mode, the cached byte is written when flipping over to 0.

Definition at line 791 of file Bitstream.java.

## ◆ getBitPosition()

final int com.jogamp.common.util.Bitstream< T >.getBitPosition | ( |  | ) |

Return the next bit number to be read or write counting from [0..7].

If no bit access has been performed, 0 is returned.

Returned value is normalized [0..7], i.e. independent from msb or lsb read order.

Definition at line 809 of file Bitstream.java.

## ◆ getLastBitPos()

final int com.jogamp.common.util.Bitstream< T >.getLastBitPos | ( |  | ) |

Return the last bit number read or written counting from [0..7].

If no bit access has been performed, 7 is returned.

Returned value is normalized [0..7], i.e. independent from msb or lsb read order.

Definition at line 800 of file Bitstream.java.

## ◆ getStream()

final ByteStream< T > com.jogamp.common.util.Bitstream< T >.getStream | ( |  | ) |

Returns the currently used `ByteStream`.

Definition at line 683 of file Bitstream.java.

## ◆ getSubStream()

final T com.jogamp.common.util.Bitstream< T >.getSubStream | ( |  | ) |

Returns the currently used `ByteStream`'s `ByteStream#getStream()`.

Definition at line 686 of file Bitstream.java.

## ◆ getThrowIOExceptionOnEOF()

final boolean com.jogamp.common.util.Bitstream< T >.getThrowIOExceptionOnEOF | ( |  | ) |

Returns true if I/O methods throw an `IOException` if `EOS` appears, otherwise false (default).

Definition at line 661 of file Bitstream.java.

## ◆ mark()

final void com.jogamp.common.util.Bitstream< T >.mark | ( | final int | readLimit | ) | throws IllegalStateException

Set `markpos` to current position, allowing the stream to be `reset()`.

Parameters

  readlimit | maximum number of bytes able to read before invalidating the `markpos`.

Exceptions

  IllegalStateException | if not in input mode or stream closed

Definition at line 750 of file Bitstream.java.

## ◆ position() [1/2]

final long com.jogamp.common.util.Bitstream< T >.position | ( |  | ) |

Returns the bit position in the stream.

Definition at line 826 of file Bitstream.java.

## ◆ position() [2/2]

final long com.jogamp.common.util.Bitstream< T >.position | ( | final long | newPosition | ) | throws UnsupportedOperationException, IllegalArgumentException, IllegalStateException, IOException

Sets this stream's bit position.

A set mark is cleared.

Returns `Bitstream#EOS` is end-of-stream is reached, otherwise the new position.

Known supporting implementation is `ByteBufferStream` and `ByteArrayStream`.

Parameters

  newPosition | The new positive position.

Returns
  The new set position or `Bitstream#EOS` if end-of-stream is reached.

Exceptions

  UnsupportedOperationException | if not supported, i.e. `ByteInputStream` or `ByteOutputStream`
  IllegalArgumentException | If the `newPosition` is negative
  IOException | if read error occurs or EOS is reached and `setThrowIOExceptionOnEOF(boolean)` is set to true.
  IllegalStateException |

Definition at line 861 of file Bitstream.java.

Here is the call graph for this function:

## ◆ readBit()

final int com.jogamp.common.util.Bitstream< T >.readBit | ( | final boolean | msbFirst | ) | throws UnsupportedOperationException, IllegalStateException, IOException

Parameters

  msbFirst | if true incoming stream bit order is MSB to LSB, otherwise LSB to MSB.

Returns
  the read bit or `EOS` if end-of-stream is reached.

Exceptions

  IOException |
  IllegalStateException | if not in input mode or stream closed

Definition at line 879 of file Bitstream.java.

Here is the caller graph for this function:

## ◆ readBits31()

int com.jogamp.common.util.Bitstream< T >.readBits31 | ( | final int | n | ) | throws IllegalArgumentException, IOException

Return incoming bits as read via `readBit(boolean)` LSB-first as little-endian.

The incoming bit order is from low- to most-significant-bit, maintaining bit LSB-first order.

Parameters

  n | number of bits, maximum 31 bits

Returns
  the read bits from 0-n in the given order or `EOS`.

Exceptions

  IllegalStateException | if not in input mode or stream closed
  IllegalArgumentException | if n > 31
  IOException |

Definition at line 1031 of file Bitstream.java.

Here is the call graph for this function:
Here is the caller graph for this function:

## ◆ readUInt16() [1/2]

final int com.jogamp.common.util.Bitstream< T >.readUInt16 | ( | final boolean | bigEndian | ) | throws IllegalStateException, IOException

Return incoming `uint16_t` as read via `readBits31(int)` LSB-first as little-endian, hence bytes are swapped if bigEndian.

In case of a `int16_t` 2-complement signed value, simply cast the result to `short` after checking for `EOS`.

Parameters

  bigEndian | if true, swap incoming bytes to little-endian, otherwise leave them as little-endian.

Returns
  `EOS` or the 16bit unsigned value within the lower bits.

Exceptions

  IllegalStateException | if not in input mode or stream closed
  IOException |

Definition at line 1231 of file Bitstream.java.

Here is the call graph for this function:

## ◆ readUInt16() [2/2]

static final int com.jogamp.common.util.Bitstream< T >.readUInt16 | ( | final boolean | bigEndian,
|  | final byte[] | bytes,
|  | final int | offset
| ) |  | throws IndexOutOfBoundsException

static

Return incoming `uint16_t` value and swap bytes according to bigEndian.

In case of a `int16_t` 2-complement signed value, simply cast the result to `short`.

Parameters

  bigEndian | if false, swap incoming bytes to little-endian, otherwise leave them as big-endian.

Returns
  the 16bit unsigned value within the lower bits.

Exceptions

  IndexOutOfBoundsException |

Definition at line 1272 of file Bitstream.java.

Here is the call graph for this function:

## ◆ readUInt32() [1/2]

final long com.jogamp.common.util.Bitstream< T >.readUInt32 | ( | final boolean | bigEndian | ) | throws IllegalStateException, IOException

Return incoming `uint32_t` as read via `readBits31(int)` LSB-first as little-endian, hence bytes are swapped if bigEndian.

In case of a `int32_t` 2-complement signed value, simply cast the result to `int` after checking for `EOS`.

Parameters

  bigEndian | if true, swap incoming bytes to little-endian, otherwise leave them as little-endian.

Returns
  `EOS` or the 32bit unsigned value within the lower bits.

Exceptions

  IllegalStateException | if not in input mode or stream closed
  IOException |

Definition at line 1338 of file Bitstream.java.

Here is the call graph for this function:

## ◆ readUInt32() [2/2]

static final long com.jogamp.common.util.Bitstream< T >.readUInt32 | ( | final boolean | bigEndian,
|  | final byte[] | bytes,
|  | final int | offset
| ) |  | throws IndexOutOfBoundsException

static

Return incoming `uint32_t` and swap bytes according to bigEndian.

In case of a `int32_t` 2-complement signed value, simply cast the result to `int`.

Parameters

  bigEndian | if false, swap incoming bytes to little-endian, otherwise leave them as big-endian.

Returns
  the 32bit unsigned value within the lower bits.

Exceptions

  IndexOutOfBoundsException |

Definition at line 1384 of file Bitstream.java.

Here is the call graph for this function:

## ◆ readUInt8()

final int com.jogamp.common.util.Bitstream< T >.readUInt8 | ( |  | ) | throws IllegalStateException, IOException

Return incoming `uint8_t` as read via `readBits31(int)`.

In case of a `int8_t` 2-complement signed value, simply cast the result to `byte` after checking for `EOS`.

Returns
  `EOS` or the 8bit unsigned value within the lower bits.

Exceptions

  IllegalStateException | if not in input mode or stream closed
  IOException |

Definition at line 1181 of file Bitstream.java.

Here is the call graph for this function:

## ◆ reset()

final void com.jogamp.common.util.Bitstream< T >.reset | ( |  | ) | throws IllegalStateException, IOException

Reset stream position to markpos as set via `mark(int)`.

markpos is kept, hence `reset()` can be called multiple times.

Exceptions

  IllegalStateException | if not in input mode or stream closed
  IllegalStateException | if markpos has not been set via `mark(int)` or reset operation failed.
  IOException | if reset operation failed.

Definition at line 768 of file Bitstream.java.

## ◆ setStream()

final void com.jogamp.common.util.Bitstream< T >.setStream | ( | final T | stream,
|  | final boolean | outputMode
| ) |  | throws IllegalArgumentException, IOException

Sets the underlying stream, without `close()`ing the previous one.

If the previous stream was in `output mode`, `flush()` is being called.

Exceptions

  IllegalArgumentException | if requested outputMode doesn't match stream's `canInput()` and `canOutput()`.
  IOException | could be caused by `flush()`.

Definition at line 672 of file Bitstream.java.

Here is the call graph for this function:

## ◆ setThrowIOExceptionOnEOF()

final void com.jogamp.common.util.Bitstream< T >.setThrowIOExceptionOnEOF | ( | final boolean | enable | ) |

Enables or disables throwing an `IOException` in case `EOS` appears.

Default behavior for I/O methods is not to throw an `IOException`, but to return `EOS`.

Definition at line 656 of file Bitstream.java.

## ◆ skip()

long com.jogamp.common.util.Bitstream< T >.skip | ( | final long | n | ) | throws IllegalStateException, IOException

It is implementation dependent, whether backward skip giving a negative number is supported or not.

Parameters

  n | number of bits to skip

Returns
  actual skipped bits

Exceptions

  IOException | if read error occurs or EOS is reached and `setThrowIOExceptionOnEOF(boolean)` is set to true.
  IllegalStateException | if closed

Definition at line 952 of file Bitstream.java.

Here is the call graph for this function:

## ◆ toBinString()

static String com.jogamp.common.util.Bitstream< T >.toBinString | ( | final boolean | msbFirst,
|  | final int | v,
|  | final int | bitCount
| ) |  |

static

Definition at line 1516 of file Bitstream.java.

Here is the caller graph for this function:

## ◆ toHexBinString() [1/3]

static final String com.jogamp.common.util.Bitstream< T >.toHexBinString | ( | final boolean | msbFirst,
|  | final byte[] | data,
|  | final int | offset,
|  | final int | len
| ) |  |

static

Definition at line 1537 of file Bitstream.java.

Here is the call graph for this function:

## ◆ toHexBinString() [2/3]

static final String com.jogamp.common.util.Bitstream< T >.toHexBinString | ( | final boolean | msbFirst,
|  | final ByteBuffer | data,
|  | final int | offset,
|  | final int | len
| ) |  |

static

Definition at line 1547 of file Bitstream.java.

Here is the call graph for this function:

## ◆ toHexBinString() [3/3]

static String com.jogamp.common.util.Bitstream< T >.toHexBinString | ( | final boolean | msbFirst,
|  | final int | v,
|  | final int | bitCount
| ) |  |

static

Definition at line 1533 of file Bitstream.java.

Here is the call graph for this function:
Here is the caller graph for this function:

## ◆ toString()

String com.jogamp.common.util.Bitstream< T >.toString | ( |  | ) |

Definition at line 1498 of file Bitstream.java.

Here is the call graph for this function:

## ◆ toStringImpl()

String com.jogamp.common.util.Bitstream< T >.toStringImpl | ( |  | ) |

protected

Definition at line 1501 of file Bitstream.java.

Here is the call graph for this function:
Here is the caller graph for this function:

## ◆ toUInt32Int()

static final int com.jogamp.common.util.Bitstream< T >.toUInt32Int | ( | final int | int32 | ) |

static

Returns the reinterpreted given `int32_t` value as `uint32_t` if ≤ `Integer#MAX_VALUE` as within an `int` storage.

Otherwise return -1.

Definition at line 1480 of file Bitstream.java.

Here is the call graph for this function:

## ◆ toUInt32Long()

static final long com.jogamp.common.util.Bitstream< T >.toUInt32Long | ( | final int | int32 | ) |

static

Reinterpret the given `int32_t` value as `uint32_t`, i.e.

perform the following cast to `long`:

      final long l = 0xffffffffL & int32;

Definition at line 1470 of file Bitstream.java.

Here is the caller graph for this function:

## ◆ uint32LongToInt()

static final int com.jogamp.common.util.Bitstream< T >.uint32LongToInt | ( | final long | uint32 | ) |

static

Returns the given `uint32_t` value `long` value as `int` if ≤ `Integer#MAX_VALUE`.

Otherwise return -1.

Definition at line 1489 of file Bitstream.java.

Here is the caller graph for this function:

## ◆ writeBit()

final int com.jogamp.common.util.Bitstream< T >.writeBit | ( | final boolean | msbFirst,
|  | final int | bit
| ) |  | throws IllegalStateException, IOException

Parameters

  msbFirst | if true outgoing stream bit order is MSB to LSB, otherwise LSB to MSB.
  bit |

Returns
  the currently written byte or `EOS` if end-of-stream is reached.

Exceptions

  IOException |
  IllegalStateException | if not in output mode or stream closed

Definition at line 915 of file Bitstream.java.

Here is the caller graph for this function:

## ◆ writeBits31()

int com.jogamp.common.util.Bitstream< T >.writeBits31 | ( | final int | n,
|  | final int | bits
| ) |  | throws IllegalStateException, IllegalArgumentException, IOException

Write the given bits via `writeBit(boolean, int)` LSB-first as little-endian.

The outgoing bit order is from low- to most-significant-bit, maintaining bit LSB-first order.

Parameters

  n | number of bits, maximum 31 bits
  bits | the bits to write

Returns
  the written bits or `EOS`.

Exceptions

  IllegalStateException | if not in output mode or stream closed
  IllegalArgumentException | if n > 31
  IOException |

Definition at line 1108 of file Bitstream.java.

Here is the call graph for this function:
Here is the caller graph for this function:

## ◆ writeInt16()

final int com.jogamp.common.util.Bitstream< T >.writeInt16 | ( | final boolean | bigEndian,
|  | final short | int16
| ) |  | throws IllegalStateException, IOException

Write the given 16 bits via `writeBits31(int, int)` LSB-first as little-endian, hence bytes are swapped if bigEndian.

Parameters

  bigEndian | if true, swap given bytes to little-endian, otherwise leave them as little-endian.

Returns
  `EOS` or the written 16bit value.

Exceptions

  IllegalStateException | if not in output mode or stream closed
  IOException |

Definition at line 1292 of file Bitstream.java.

Here is the call graph for this function:

## ◆ writeInt32()

final int com.jogamp.common.util.Bitstream< T >.writeInt32 | ( | final boolean | bigEndian,
|  | final int | int32
| ) |  | throws IllegalStateException, IOException

Write the given 32 bits via `writeBits31(int, int)` LSB-first as little-endian, hence bytes are swapped if bigEndian.

Parameters

  bigEndian | if true, swap given bytes to little-endian, otherwise leave them as little-endian.

Returns
  `EOS` or the written 32bit value.

Exceptions

  IllegalStateException | if not in output mode or stream closed
  IOException |

Definition at line 1405 of file Bitstream.java.

Here is the call graph for this function:

## ◆ writeInt8()

final int com.jogamp.common.util.Bitstream< T >.writeInt8 | ( | final byte | int8 | ) | throws IllegalStateException, IOException

Write the given 8 bits via `writeBits31(int, int)`.

Returns
  `EOS` or the written 8bit value.

Exceptions

  IllegalStateException | if not in output mode or stream closed
  IOException |

Definition at line 1203 of file Bitstream.java.

Here is the call graph for this function:

## Member Data Documentation

## ◆ EOS

final int com.jogamp.common.util.Bitstream< T >.EOS = -1

static

End of stream marker, {@value} or 0xFFFFFFFF.

Definition at line 55 of file Bitstream.java.

The documentation for this class was generated from the following file:

- src/java/com/jogamp/common/util/Bitstream.java