News SF.net Project Frequently Asked Questions Documentation Downloads Mailing Lists How to Contribute

SourceForge.net Logo

Changing the way games are made and played.

TNL::BitStream class Reference

TNL::BitStream Class Reference

#include <tnlBitStream.h>

Inheritance diagram for TNL::BitStream:

TNL::ByteBuffer TNL::Object TNL::PacketStream

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

U8getBytePtr ()
 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

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.

ConnectionStringTablemStringTable
 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]
 

Enumeration values:
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.

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.