Main Page Modules Namespaces C++ Classes Compound List File List Index
TNL: TNL::BitStream Class Reference

# TNL::BitStream Class Reference

`#include <tnlBitStream.h>`

Inheritance diagram for TNL::BitStream:

## Detailed Description

BitStream provides a bit-level stream interface to a data buffer.

## Public Member Functions

void | setMaxSizes (U32 maxReadSize, U32 maxWriteSize=0)
| Sets the maximum read and write sizes for the BitStream.
void | setMaxBitSizes (U32 maxReadBitSize, U32 maxWriteBitSize=0)
| Sets the maximum read and write bit sizes for the BitStream.
void | reset ()
| resets the read/write position to 0 and clears any error state.
void | clearStringBuffer ()
| clears the string compression buffer.
void | setStringTable (ConnectionStringTable *table)
| sets the ConnectionStringTable for compressing string table entries across the network
void | clearError ()
| clears the error state from an attempted read or write overrun
U8 * | getBytePtr ()
| Returns a pointer to the next byte in the BitStream from the current bit position.
U32 | getBytePosition () const
| Returns the current position in the stream rounded up to the next byte.
U32 | getBitPosition () const
| Returns the current bit position in the stream.
void | setBytePosition (const U32 newPosition)
| Sets the position in the stream to the first bit of byte newPosition.
void | setBitPosition (const U32 newBitPosition)
| Sets the position in the stream to newBitPosition.
void | advanceBitPosition (const S32 numBits)
| Advances the position in the stream by numBits.
U32 | getMaxReadBitPosition () const
| Returns the maximum readable bit position.
U32 | getBitSpaceAvailable () const
| Returns the number of bits that can be written into the BitStream without resizing.
void | zeroToByteBoundary ()
| Pads the bits up to the next byte boundary with 0's.
void | writeInt (U32 value, U8 bitCount)
| Writes an unsigned integer value between 0 and 2^(bitCount - 1) into the stream.
U32 | readInt (U8 bitCount)
| Reads an unsigned integer value between 0 and 2^(bitCount - 1) from the stream.
void | writeIntAt (U32 value, U8 bitCount, U32 bitPosition)
| Writes an unsigned integer value between 0 and 2^(bitCount -1) into the stream at the specified position, without changing the current write position.
void | writeSignedInt (S32 value, U8 bitCount)
| Writes a signed integer value between -2^(bitCount-1) and 2^(bitCount-1) - 1.
S32 | readSignedInt (U8 bitCount)
| Reads a signed integer value between -2^(bitCount-1) and 2^(bitCount-1) - 1.
void | writeRangedU32 (U32 value, U32 rangeStart, U32 rangeEnd)
| Writes an unsigned integer value in the range rangeStart to rangeEnd inclusive.
U32 | readRangedU32 (U32 rangeStart, U32 rangeEnd)
| Reads an unsigned integer value in the range rangeStart to rangeEnd inclusive.
void | writeEnum (U32 enumValue, U32 enumRange)
| Writes an enumeration value in the range of 0 ... enumRange - 1.
U32 | readEnum (U32 enumRange)
| Reads an enumeration value in the range 0 ... enumRange - 1.
void | writeFloat (F32 f, U8 bitCount)
| Writes a float from 0 to 1 inclusive, using bitCount bits of precision.
F32 | readFloat (U8 bitCount)
| Reads a float from 0 to 1 inclusive, using bitCount bits of precision.
void | writeSignedFloat (F32 f, U8 bitCount)
| Writes a signed float from -1 to 1 inclusive, using bitCount bits of precision.
F32 | readSignedFloat (U8 bitCount)
| Reads a signed float from -1 to 1 inclusive, using bitCount bits of precision.
void | writeClassId (U32 classId, U32 classType, U32 classGroup)
| Writes an object's class ID, given its class type and class group.
U32 | readClassId (U32 classType, U32 classGroup)
| Reads a class ID for an object, given a class type and class group. Returns -1 if the class type is out of range.
void | writeNormalVector (const Point3F &vec, U8 bitCount)
| Writes a normalized vector into the stream, using bitCount bits for the precision of angles phi and theta.
void | readNormalVector (Point3F *vec, U8 bitCount)
| Reads a normalized vector from the stream, using bitCount bits for the precision of angles phi and theta.
void | writeNormalVector (const Point3F &vec, U8 angleBitCount, U8 zBitCount)
| Writes a normalized vector by writing a z value and theta angle.
void | readNormalVector (Point3F *vec, U8 angleBitCount, U8 zBitCount)
| Reads a normalized vector by reading a z value and theta angle.
void | setPointCompression (const Point3F &p)
| Sets a reference point for subsequent compressed point writing.
void | clearPointCompression ()
| Disables compression of point.
void | writePointCompressed (const Point3F &p, F32 scale)
| Writes a point into the stream, to a precision denoted by scale.
void | readPointCompressed (Point3F *p, F32 scale)
| Reads a compressed point from the stream, to a precision denoted by scale.
bool | writeBits (U32 bitCount, const void *bitPtr)
| Writes bitCount bits into the stream from bitPtr.
bool | readBits (U32 bitCount, void *bitPtr)
| Reads bitCount bits from the stream into bitPtr.
bool | write (const ByteBuffer *theBuffer)
| Writes a ByteBuffer into the stream. The ByteBuffer can be no larger than 1024 bytes in size.
bool | read (ByteBuffer *theBuffer)
| Reads a ByteBuffer in from the stream.
bool | writeFlag (bool val)
| Writes a single boolean flag (bit) into the stream, and returns the boolean that was written.
bool | readFlag ()
| Reads a single bit from the stream.
bool | write (bool value)
bool | read (bool *value)
void | writeString (const char *stringBuf, U8 maxLen=255)
| Writes a huffman compressed string into the stream.
void | readString (char stringBuf[256])
| Reads a huffman compressed string from the stream.
void | writeStringTableEntry (const StringTableEntry &ste)
| Writes a string table entry into the stream.
void | readStringTableEntry (StringTableEntry *ste)
| Reads a string table entry from the stream.
bool | write (const U32 in_numBytes, const void *in_pBuffer)
| Writes byte data into the stream.
bool | read (const U32 in_numBytes, void *out_pBuffer)
| Reads byte data from the stream.
bool | setBit (U32 bitCount, bool set)
| Sets the bit at position bitCount to the value of set.
bool | testBit (U32 bitCount)
| Tests the value of the bit at position bitCount.
bool | isFull ()
| Returns whether the BitStream writing has exceeded the write target size.
bool | isValid ()
| Returns whether the stream has generated an error condition due to reading or writing past the end of the buffer.
void | hashAndEncrypt (U32 hashDigestSize, U32 encryptStartOffset, SymmetricCipher *theCipher)
| Hashes the BitStream, writing the hash digest into the end of the buffer, and then encrypts with the given cipher.
bool | decryptAndCheckHash (U32 hashDigestSize, U32 decryptStartOffset, SymmetricCipher *theCipher)
| Decrypts the BitStream, then checks the hash digest at the end of the buffer to validate the contents.
Constructors
Note that the BitStream essentially wraps an existing buffer, so to use a bitstream you must have an existing buffer for it to work with!
| BitStream (U8 *bufPtr, U32 bufSize)
| Default to maximum write size being the size of the buffer.
| BitStream (U8 *bufPtr, U32 bufSize, U32 maxWriteSize)
| Optionally, specify a maximum write size.
| BitStream ()
| Creates a resizable BitStream.
Various types that the BitStream can read and write...
bool | write (U8 value)
bool | read (U8 *value)
bool | write (S8 value)
bool | read (S8 *value)
bool | write (U16 value)
bool | read (U16 *value)
bool | write (S16 value)
bool | read (S16 *value)
bool | write (U32 value)
bool | read (U32 *value)
bool | write (S32 value)
bool | read (S32 *value)
bool | write (S64 value)
bool | read (S64 *value)
bool | write (U64 value)
bool | read (U64 *value)
bool | write (F32 value)
bool | read (F32 *value)
bool | write (F64 value)
bool | read (F64 *value)

## Static Public Member Functions

static Point3F | dumbDownNormal (const Point3F &vec, U8 bitCount)
| Uses the same method as in writeNormalVector to reduce the precision of a normal vector to determine what will be read from the stream.

## Protected Types

enum | { ResizePad = 1500 }

## Protected Member Functions

bool | resizeBits (U32 numBitsNeeded)

## Protected Attributes

U32 | bitNum
| The current bit position for reading/writing in the bit stream.
bool | error
| Flag set if a user operation attempts to read or write past the max read/write sizes.
bool | mCompressRelative
| Flag set if the bit stream should compress points relative to a compression point.
Point3F | mCompressPoint
| Reference point for relative point compression.
U32 | maxReadBitNum
| Last valid read bit position.
U32 | maxWriteBitNum
| Last valid write bit position.
ConnectionStringTable * | mStringTable
| String table used to compress StringTableEntries over the network.
char | mStringBuffer [256]
| String buffer holds the last string written into the stream for substring compression.

## Member Enumeration Documentation

anonymous enum`[protected]`

Enumerator:

  ResizePad |

## Constructor & Destructor Documentation

TNL::BitStream::BitStream | ( | U8 * | bufPtr,
|  | U32 | bufSize |
| ) |  |  | `[inline]`

Default to maximum write size being the size of the buffer.

TNL::BitStream::BitStream | ( | U8 * | bufPtr,
|  | U32 | bufSize,
|  | U32 | maxWriteSize |
| ) |  |  | `[inline]`

Optionally, specify a maximum write size.

TNL::BitStream::BitStream | ( |  | ) | `[inline]`

Creates a resizable BitStream.

## Member Function Documentation

bool TNL::BitStream::resizeBits | ( | U32 | numBitsNeeded | ) | `[protected]`

void TNL::BitStream::setMaxSizes | ( | U32 | maxReadSize,
|  | U32 | maxWriteSize = `0` |
| ) |  |  |

Sets the maximum read and write sizes for the BitStream.

void TNL::BitStream::setMaxBitSizes | ( | U32 | maxReadBitSize,
|  | U32 | maxWriteBitSize = `0` |
| ) |  |  |

Sets the maximum read and write bit sizes for the BitStream.

void TNL::BitStream::reset | ( |  | ) |

resets the read/write position to 0 and clears any error state.

void TNL::BitStream::clearStringBuffer | ( |  | ) | `[inline]`

clears the string compression buffer.

void TNL::BitStream::setStringTable | ( | ConnectionStringTable * | table | ) | `[inline]`

sets the ConnectionStringTable for compressing string table entries across the network

void TNL::BitStream::clearError | ( |  | ) | `[inline]`

clears the error state from an attempted read or write overrun

U8* TNL::BitStream::getBytePtr | ( |  | ) |

Returns a pointer to the next byte in the BitStream from the current bit position.

U32 TNL::BitStream::getBytePosition | ( |  | ) | const`[inline]`

Returns the current position in the stream rounded up to the next byte.

U32 TNL::BitStream::getBitPosition | ( |  | ) | const`[inline]`

Returns the current bit position in the stream.

void TNL::BitStream::setBytePosition | ( | const U32 | newPosition | ) | `[inline]`

Sets the position in the stream to the first bit of byte newPosition.

void TNL::BitStream::setBitPosition | ( | const U32 | newBitPosition | ) | `[inline]`

Sets the position in the stream to newBitPosition.

void TNL::BitStream::advanceBitPosition | ( | const S32 | numBits | ) | `[inline]`

Advances the position in the stream by numBits.

U32 TNL::BitStream::getMaxReadBitPosition | ( |  | ) | const`[inline]`

Returns the maximum readable bit position.

U32 TNL::BitStream::getBitSpaceAvailable | ( |  | ) | const`[inline]`

Returns the number of bits that can be written into the BitStream without resizing.

void TNL::BitStream::zeroToByteBoundary | ( |  | ) | `[inline]`

Pads the bits up to the next byte boundary with 0's.

void TNL::BitStream::writeInt | ( | U32 | value,
|  | U8 | bitCount |
| ) |  |  |

Writes an unsigned integer value between 0 and 2^(bitCount - 1) into the stream.

U32 TNL::BitStream::readInt | ( | U8 | bitCount | ) |

Reads an unsigned integer value between 0 and 2^(bitCount - 1) from the stream.

void TNL::BitStream::writeIntAt | ( | U32 | value,
|  | U8 | bitCount,
|  | U32 | bitPosition |
| ) |  |  | `[inline]`

Writes an unsigned integer value between 0 and 2^(bitCount -1) into the stream at the specified position, without changing the current write position.

void TNL::BitStream::writeSignedInt | ( | S32 | value,
|  | U8 | bitCount |
| ) |  |  |

Writes a signed integer value between -2^(bitCount-1) and 2^(bitCount-1) - 1.

S32 TNL::BitStream::readSignedInt | ( | U8 | bitCount | ) |

Reads a signed integer value between -2^(bitCount-1) and 2^(bitCount-1) - 1.

void TNL::BitStream::writeRangedU32 | ( | U32 | value,
|  | U32 | rangeStart,
|  | U32 | rangeEnd |
| ) |  |  | `[inline]`

Writes an unsigned integer value in the range rangeStart to rangeEnd inclusive.

U32 TNL::BitStream::readRangedU32 | ( | U32 | rangeStart,
|  | U32 | rangeEnd |
| ) |  |  | `[inline]`

Reads an unsigned integer value in the range rangeStart to rangeEnd inclusive.

void TNL::BitStream::writeEnum | ( | U32 | enumValue,
|  | U32 | enumRange |
| ) |  |  | `[inline]`

Writes an enumeration value in the range of 0 ... enumRange - 1.

U32 TNL::BitStream::readEnum | ( | U32 | enumRange | ) | `[inline]`

Reads an enumeration value in the range 0 ... enumRange - 1.

void TNL::BitStream::writeFloat | ( | F32 | f,
|  | U8 | bitCount |
| ) |  |  |

Writes a float from 0 to 1 inclusive, using bitCount bits of precision.

F32 TNL::BitStream::readFloat | ( | U8 | bitCount | ) |

Reads a float from 0 to 1 inclusive, using bitCount bits of precision.

void TNL::BitStream::writeSignedFloat | ( | F32 | f,
|  | U8 | bitCount |
| ) |  |  |

Writes a signed float from -1 to 1 inclusive, using bitCount bits of precision.

F32 TNL::BitStream::readSignedFloat | ( | U8 | bitCount | ) |

Reads a signed float from -1 to 1 inclusive, using bitCount bits of precision.

void TNL::BitStream::writeClassId | ( | U32 | classId,
|  | U32 | classType,
|  | U32 | classGroup |
| ) |  |  |

Writes an object's class ID, given its class type and class group.

U32 TNL::BitStream::readClassId | ( | U32 | classType,
|  | U32 | classGroup |
| ) |  |  |

Reads a class ID for an object, given a class type and class group. Returns -1 if the class type is out of range.

void TNL::BitStream::writeNormalVector | ( | const Point3F & | vec,
|  | U8 | bitCount |
| ) |  |  |

Writes a normalized vector into the stream, using bitCount bits for the precision of angles phi and theta.

void TNL::BitStream::readNormalVector | ( | Point3F * | vec,
|  | U8 | bitCount |
| ) |  |  |

Reads a normalized vector from the stream, using bitCount bits for the precision of angles phi and theta.

static Point3F TNL::BitStream::dumbDownNormal | ( | const Point3F & | vec,
|  | U8 | bitCount |
| ) |  |  | `[static]`

Uses the same method as in writeNormalVector to reduce the precision of a normal vector to determine what will be read from the stream.

void TNL::BitStream::writeNormalVector | ( | const Point3F & | vec,
|  | U8 | angleBitCount,
|  | U8 | zBitCount |
| ) |  |  |

Writes a normalized vector by writing a z value and theta angle.

void TNL::BitStream::readNormalVector | ( | Point3F * | vec,
|  | U8 | angleBitCount,
|  | U8 | zBitCount |
| ) |  |  |

Reads a normalized vector by reading a z value and theta angle.

void TNL::BitStream::setPointCompression | ( | const Point3F & | p | ) |

Sets a reference point for subsequent compressed point writing.

void TNL::BitStream::clearPointCompression | ( |  | ) |

Disables compression of point.

void TNL::BitStream::writePointCompressed | ( | const Point3F & | p,
|  | F32 | scale |
| ) |  |  |

Writes a point into the stream, to a precision denoted by scale.

void TNL::BitStream::readPointCompressed | ( | Point3F * | p,
|  | F32 | scale |
| ) |  |  |

Reads a compressed point from the stream, to a precision denoted by scale.

bool TNL::BitStream::writeBits | ( | U32 | bitCount,
|  | const void * | bitPtr |
| ) |  |  |

Writes bitCount bits into the stream from bitPtr.

bool TNL::BitStream::readBits | ( | U32 | bitCount,
|  | void * | bitPtr |
| ) |  |  |

Reads bitCount bits from the stream into bitPtr.

bool TNL::BitStream::write | ( | const ByteBuffer * | theBuffer | ) |

Writes a ByteBuffer into the stream. The ByteBuffer can be no larger than 1024 bytes in size.

bool TNL::BitStream::read | ( | ByteBuffer * | theBuffer | ) |

Reads a ByteBuffer in from the stream.

bool TNL::BitStream::writeFlag | ( | bool | val | ) |

Writes a single boolean flag (bit) into the stream, and returns the boolean that was written.

This is set up so you can do...

       if(stream->writeFlag(foo == bar))
       {
         ... write other stuff ...
       }

bool TNL::BitStream::readFlag | ( |  | ) | `[inline]`

Reads a single bit from the stream.

This is set up so you can do...

       if(stream->readFlag())
       {
         ... read other stuff ...
       }

bool TNL::BitStream::write | ( | bool | value | ) | `[inline]`

bool TNL::BitStream::read | ( | bool * | value | ) | `[inline]`

void TNL::BitStream::writeString | ( | const char * | stringBuf,
|  | U8 | maxLen = `255` |
| ) |  |  |

Writes a huffman compressed string into the stream.

void TNL::BitStream::readString | ( | char | stringBuf[256] | ) |

Reads a huffman compressed string from the stream.

void TNL::BitStream::writeStringTableEntry | ( | const StringTableEntry & | ste | ) |

Writes a string table entry into the stream.

void TNL::BitStream::readStringTableEntry | ( | StringTableEntry * | ste | ) |

Reads a string table entry from the stream.

bool TNL::BitStream::write | ( | const U32 | in_numBytes,
|  | const void * | in_pBuffer |
| ) |  |  | `[inline]`

Writes byte data into the stream.

bool TNL::BitStream::read | ( | const U32 | in_numBytes,
|  | void * | out_pBuffer |
| ) |  |  | `[inline]`

Reads byte data from the stream.

bool TNL::BitStream::write | ( | U8 | value | ) | `[inline]`

bool TNL::BitStream::read | ( | U8 * | value | ) | `[inline]`

bool TNL::BitStream::write | ( | S8 | value | ) | `[inline]`

bool TNL::BitStream::read | ( | S8 * | value | ) | `[inline]`

bool TNL::BitStream::write | ( | U16 | value | ) | `[inline]`

bool TNL::BitStream::read | ( | U16 * | value | ) | `[inline]`

bool TNL::BitStream::write | ( | S16 | value | ) | `[inline]`

bool TNL::BitStream::read | ( | S16 * | value | ) | `[inline]`

bool TNL::BitStream::write | ( | U32 | value | ) | `[inline]`

bool TNL::BitStream::read | ( | U32 * | value | ) | `[inline]`

bool TNL::BitStream::write | ( | S32 | value | ) | `[inline]`

bool TNL::BitStream::read | ( | S32 * | value | ) | `[inline]`

bool TNL::BitStream::write | ( | S64 | value | ) | `[inline]`

bool TNL::BitStream::read | ( | S64 * | value | ) | `[inline]`

bool TNL::BitStream::write | ( | U64 | value | ) | `[inline]`

bool TNL::BitStream::read | ( | U64 * | value | ) | `[inline]`

bool TNL::BitStream::write | ( | F32 | value | ) | `[inline]`

bool TNL::BitStream::read | ( | F32 * | value | ) | `[inline]`

bool TNL::BitStream::write | ( | F64 | value | ) | `[inline]`

bool TNL::BitStream::read | ( | F64 * | value | ) | `[inline]`

bool TNL::BitStream::setBit | ( | U32 | bitCount,
|  | bool | set |
| ) |  |  |

Sets the bit at position bitCount to the value of set.

bool TNL::BitStream::testBit | ( | U32 | bitCount | ) |

Tests the value of the bit at position bitCount.

bool TNL::BitStream::isFull | ( |  | ) | `[inline]`

Returns whether the BitStream writing has exceeded the write target size.

bool TNL::BitStream::isValid | ( |  | ) | `[inline]`

Returns whether the stream has generated an error condition due to reading or writing past the end of the buffer.

void TNL::BitStream::hashAndEncrypt | ( | U32 | hashDigestSize,
|  | U32 | encryptStartOffset,
|  | SymmetricCipher * | theCipher |
| ) |  |  |

Hashes the BitStream, writing the hash digest into the end of the buffer, and then encrypts with the given cipher.

bool TNL::BitStream::decryptAndCheckHash | ( | U32 | hashDigestSize,
|  | U32 | decryptStartOffset,
|  | SymmetricCipher * | theCipher |
| ) |  |  |

Decrypts the BitStream, then checks the hash digest at the end of the buffer to validate the contents.

## Field Documentation

U32 TNL::BitStream::bitNum`[protected]`

The current bit position for reading/writing in the bit stream.

bool TNL::BitStream::error`[protected]`

Flag set if a user operation attempts to read or write past the max read/write sizes.

bool TNL::BitStream::mCompressRelative`[protected]`

Flag set if the bit stream should compress points relative to a compression point.

Point3F TNL::BitStream::mCompressPoint`[protected]`

Reference point for relative point compression.

U32 TNL::BitStream::maxReadBitNum`[protected]`

Last valid read bit position.

U32 TNL::BitStream::maxWriteBitNum`[protected]`

Last valid write bit position.

ConnectionStringTable* TNL::BitStream::mStringTable`[protected]`

String table used to compress StringTableEntries over the network.

char TNL::BitStream::mStringBuffer[256]`[protected]`

String buffer holds the last string written into the stream for substring compression.