RakNet  4.0
Public Member Functions | Static Public Member Functions | List of all members
RakNet::BitStream Class Reference

#include <BitStream.h>

Public Member Functions

 BitStream ()
 Default Constructor.
 
 BitStream (const unsigned int initialBytesToAllocate)
 Create the bitstream, with some number of bytes to immediately allocate.
 
 BitStream (unsigned char *_data, const unsigned int lengthInBytes, bool _copyData)
 Initialize the BitStream, immediately setting the data it contains to a predefined pointer.
 
void Reset (void)
 Resets the bitstream for reuse.
 
template<class templateType >
bool Serialize (bool writeToBitstream, templateType &inOutTemplateVar)
 Bidirectional serialize/deserialize any integral type to/from a bitstream.
 
template<class templateType >
bool SerializeDelta (bool writeToBitstream, templateType &inOutCurrentValue, const templateType &lastValue)
 Bidirectional serialize/deserialize any integral type to/from a bitstream.
 
template<class templateType >
bool SerializeDelta (bool writeToBitstream, templateType &inOutCurrentValue)
 Bidirectional version of SerializeDelta when you don't know what the last value is, or there is no last value.
 
template<class templateType >
bool SerializeCompressed (bool writeToBitstream, templateType &inOutTemplateVar)
 Bidirectional serialize/deserialize any integral type to/from a bitstream.
 
template<class templateType >
bool SerializeCompressedDelta (bool writeToBitstream, templateType &inOutCurrentValue, const templateType &lastValue)
 Bidirectional serialize/deserialize any integral type to/from a bitstream.
 
template<class templateType >
bool SerializeCompressedDelta (bool writeToBitstream, templateType &inOutTemplateVar)
 Save as SerializeCompressedDelta(templateType &currentValue, const templateType &lastValue) when we have an unknown second parameter.
 
bool Serialize (bool writeToBitstream, char *inOutByteArray, const unsigned int numberOfBytes)
 Bidirectional serialize/deserialize an array or casted stream or raw data. This does NOT do endian swapping.
 
bool SerializeFloat16 (bool writeToBitstream, float &inOutFloat, float floatMin, float floatMax)
 Serialize a float into 2 bytes, spanning the range between floatMin and floatMax.
 
template<class serializationType , class sourceType >
bool SerializeCasted (bool writeToBitstream, sourceType &value)
 
template<class templateType >
bool SerializeBitsFromIntegerRange (bool writeToBitstream, templateType &value, const templateType minimum, const templateType maximum, bool allowOutsideRange=false)
 
template<class templateType >
bool SerializeBitsFromIntegerRange (bool writeToBitstream, templateType &value, const templateType minimum, const templateType maximum, const int requiredBits, bool allowOutsideRange=false)
 
template<class templateType >
bool SerializeNormVector (bool writeToBitstream, templateType &x, templateType &y, templateType &z)
 Bidirectional serialize/deserialize a normalized 3D vector, using (at most) 4 bytes + 3 bits instead of 12-24 bytes.
 
template<class templateType >
bool SerializeVector (bool writeToBitstream, templateType &x, templateType &y, templateType &z)
 Bidirectional serialize/deserialize a vector, using 10 bytes instead of 12.
 
template<class templateType >
bool SerializeNormQuat (bool writeToBitstream, templateType &w, templateType &x, templateType &y, templateType &z)
 Bidirectional serialize/deserialize a normalized quaternion in 6 bytes + 4 bits instead of 16 bytes. Slightly lossy.
 
template<class templateType >
bool SerializeOrthMatrix (bool writeToBitstream, templateType &m00, templateType &m01, templateType &m02, templateType &m10, templateType &m11, templateType &m12, templateType &m20, templateType &m21, templateType &m22)
 Bidirectional serialize/deserialize an orthogonal matrix by creating a quaternion, and writing 3 components of the quaternion in 2 bytes each.
 
bool SerializeBits (bool writeToBitstream, unsigned char *inOutByteArray, const BitSize_t numberOfBitsToSerialize, const bool rightAlignedBits=true)
 Bidirectional serialize/deserialize numberToSerialize bits to/from the input.
 
template<class templateType >
void Write (const templateType &inTemplateVar)
 Write any integral type to a bitstream.
 
template<class templateType >
void WritePtr (templateType *inTemplateVar)
 Write the dereferenced pointer to any integral type to a bitstream.
 
template<class templateType >
void WriteDelta (const templateType &currentValue, const templateType &lastValue)
 Write any integral type to a bitstream.
 
template<class templateType >
void WriteDelta (const templateType &currentValue)
 WriteDelta when you don't know what the last value is, or there is no last value.
 
template<class templateType >
void WriteCompressed (const templateType &inTemplateVar)
 Write any integral type to a bitstream.
 
template<class templateType >
void WriteCompressedDelta (const templateType &currentValue, const templateType &lastValue)
 Write any integral type to a bitstream.
 
template<class templateType >
void WriteCompressedDelta (const templateType &currentValue)
 Save as WriteCompressedDelta(const templateType &currentValue, const templateType &lastValue) when we have an unknown second parameter.
 
template<class templateType >
bool Read (templateType &outTemplateVar)
 Read any integral type from a bitstream.
 
template<class templateType >
bool ReadDelta (templateType &outTemplateVar)
 Read any integral type from a bitstream.
 
template<class templateType >
bool ReadCompressed (templateType &outTemplateVar)
 Read any integral type from a bitstream.
 
template<class templateType >
bool ReadCompressedDelta (templateType &outTemplateVar)
 Read any integral type from a bitstream.
 
bool Read (BitStream *bitStream, BitSize_t numberOfBits)
 Read one bitstream to another.
 
void Write (const char *inputByteArray, const unsigned int numberOfBytes)
 Write an array or casted stream or raw data. This does NOT do endian swapping.
 
void Write (BitStream *bitStream, BitSize_t numberOfBits)
 Write one bitstream to another.
 
void WriteFloat16 (float x, float floatMin, float floatMax)
 Write a float into 2 bytes, spanning the range between floatMin and floatMax.
 
template<class serializationType , class sourceType >
void WriteCasted (const sourceType &value)
 
template<class templateType >
void WriteBitsFromIntegerRange (const templateType value, const templateType minimum, const templateType maximum, bool allowOutsideRange=false)
 
template<class templateType >
void WriteBitsFromIntegerRange (const templateType value, const templateType minimum, const templateType maximum, const int requiredBits, bool allowOutsideRange=false)
 
template<class templateType >
void WriteNormVector (templateType x, templateType y, templateType z)
 Write a normalized 3D vector, using (at most) 4 bytes + 3 bits instead of 12-24 bytes.
 
template<class templateType >
void WriteVector (templateType x, templateType y, templateType z)
 Write a vector, using 10 bytes instead of 12.
 
template<class templateType >
void WriteNormQuat (templateType w, templateType x, templateType y, templateType z)
 Write a normalized quaternion in 6 bytes + 4 bits instead of 16 bytes. Slightly lossy.
 
template<class templateType >
void WriteOrthMatrix (templateType m00, templateType m01, templateType m02, templateType m10, templateType m11, templateType m12, templateType m20, templateType m21, templateType m22)
 Write an orthogonal matrix by creating a quaternion, and writing 3 components of the quaternion in 2 bytes each.
 
bool Read (char *output, const unsigned int numberOfBytes)
 Read an array or casted stream of byte.
 
bool ReadFloat16 (float &outFloat, float floatMin, float floatMax)
 Read a float into 2 bytes, spanning the range between floatMin and floatMax.
 
template<class serializationType , class sourceType >
bool ReadCasted (sourceType &value)
 
template<class templateType >
bool ReadBitsFromIntegerRange (templateType &value, const templateType minimum, const templateType maximum, bool allowOutsideRange=false)
 
template<class templateType >
bool ReadBitsFromIntegerRange (templateType &value, const templateType minimum, const templateType maximum, const int requiredBits, bool allowOutsideRange=false)
 
template<class templateType >
bool ReadNormVector (templateType &x, templateType &y, templateType &z)
 Read a normalized 3D vector, using (at most) 4 bytes + 3 bits instead of 12-24 bytes.
 
template<class templateType >
bool ReadVector (templateType &x, templateType &y, templateType &z)
 Read 3 floats or doubles, using 10 bytes, where those float or doubles comprise a vector.
 
template<class templateType >
bool ReadNormQuat (templateType &w, templateType &x, templateType &y, templateType &z)
 Read a normalized quaternion in 6 bytes + 4 bits instead of 16 bytes.
 
template<class templateType >
bool ReadOrthMatrix (templateType &m00, templateType &m01, templateType &m02, templateType &m10, templateType &m11, templateType &m12, templateType &m20, templateType &m21, templateType &m22)
 Read an orthogonal matrix from a quaternion, reading 3 components of the quaternion in 2 bytes each and extrapolatig the 4th.
 
void ResetReadPointer (void)
 Sets the read pointer back to the beginning of your data.
 
void ResetWritePointer (void)
 Sets the write pointer back to the beginning of your data.
 
void AssertStreamEmpty (void)
 This is good to call when you are done with the stream to make sure you didn't leave any data left over void.
 
void PrintBits (char *out) const
 RAKNET_DEBUG_PRINTF the bits in the stream. Great for debugging.
 
void IgnoreBits (const BitSize_t numberOfBits)
 Ignore data we don't intend to read.
 
void IgnoreBytes (const unsigned int numberOfBytes)
 Ignore data we don't intend to read.
 
void SetWriteOffset (const BitSize_t offset)
 Move the write pointer to a position on the array.
 
BitSize_t GetNumberOfBitsUsed (void) const
 Returns the length in bits of the stream.
 
BitSize_t GetNumberOfBytesUsed (void) const
 Returns the length in bytes of the stream.
 
BitSize_t GetReadOffset (void) const
 Returns the number of bits into the stream that we have read.
 
void SetReadOffset (const BitSize_t newReadOffset)
 Sets the read bit index.
 
BitSize_t GetNumberOfUnreadBits (void) const
 Returns the number of bits left in the stream that haven't been read.
 
BitSize_t CopyData (unsigned char **_data) const
 Makes a copy of the internal data for you _data will point to the stream. Partial bytes are left aligned.
 
unsigned char * GetData (void) const
 
void WriteBits (const unsigned char *inByteArray, BitSize_t numberOfBitsToWrite, const bool rightAlignedBits=true)
 Write numberToWrite bits from the input source.
 
void WriteAlignedBytes (const unsigned char *inByteArray, const unsigned int numberOfBytesToWrite)
 Align the bitstream to the byte boundary and then write the specified number of bits.
 
void WriteAlignedBytesSafe (const char *inByteArray, const unsigned int inputLength, const unsigned int maxBytesToWrite)
 Aligns the bitstream, writes inputLength, and writes input. Won't write beyond maxBytesToWrite.
 
bool ReadAlignedBytes (unsigned char *inOutByteArray, const unsigned int numberOfBytesToRead)
 Read bits, starting at the next aligned bits.
 
bool ReadAlignedBytesSafe (char *inOutByteArray, int &inputLength, const int maxBytesToRead)
 Reads what was written by WriteAlignedBytesSafe.
 
bool ReadAlignedBytesSafeAlloc (char **outByteArray, int &inputLength, const unsigned int maxBytesToRead)
 Same as ReadAlignedBytesSafe() but allocates the memory for you using new, rather than assuming it is safe to write to.
 
void AlignWriteToByteBoundary (void)
 Align the next write and/or read to a byte boundary.
 
void AlignReadToByteBoundary (void)
 Align the next write and/or read to a byte boundary.
 
bool ReadBits (unsigned char *inOutByteArray, BitSize_t numberOfBitsToRead, const bool alignBitsToRight=true)
 Read numberOfBitsToRead bits to the output source.
 
void Write0 (void)
 Write a 0.
 
void Write1 (void)
 Write a 1.
 
bool ReadBit (void)
 Reads 1 bit and returns true if that bit is 1 and false if it is 0.
 
void AssertCopyData (void)
 If we used the constructor version with copy data off, this *makes sure it is set to on and the data pointed to is copied.
 
void SetNumberOfBitsAllocated (const BitSize_t lengthInBits)
 Use this if you pass a pointer copy to the constructor *(_copyData==false) and want to overallocate to prevent reallocation.
 
void AddBitsAndReallocate (const BitSize_t numberOfBitsToWrite)
 Reallocates (if necessary) in preparation of writing numberOfBitsToWrite.
 
bool Read (char *varString)
 Read strings, non reference.
 
void PadWithZeroToByteLength (unsigned int bytes)
 Write zeros until the bitstream is filled up to bytes.
 
template<>
void Write (const bool &inTemplateVar)
 Write a bool to a bitstream.
 
template<>
void Write (const SystemAddress &inTemplateVar)
 Write a systemAddress to a bitstream.
 
template<>
void Write (const RakString &inTemplateVar)
 Write a string to a bitstream.
 
template<>
void WriteDelta (const bool &currentValue, const bool &lastValue)
 Write a bool delta. Same thing as just calling Write.
 
template<>
void WriteCompressed (const float &inTemplateVar)
 For values between -1 and 1.
 
template<>
void WriteCompressed (const double &inTemplateVar)
 For values between -1 and 1.
 
template<>
void WriteCompressed (const RakString &inTemplateVar)
 Compress the string.
 
template<>
void WriteCompressedDelta (const bool &currentValue, const bool &lastValue)
 Write a bool delta. Same thing as just calling Write.
 
template<>
void WriteCompressedDelta (const bool &currentValue)
 Save as WriteCompressedDelta(bool currentValue, const templateType &lastValue) when we have an unknown second bool.
 
template<>
bool Read (bool &outTemplateVar)
 Read a bool from a bitstream.
 
template<>
bool Read (SystemAddress &outTemplateVar)
 Read a systemAddress from a bitstream.
 
template<>
bool ReadDelta (bool &outTemplateVar)
 Read a bool from a bitstream.
 
template<>
bool ReadCompressed (float &outTemplateVar)
 For values between -1 and 1.
 
template<>
bool ReadCompressed (double &outTemplateVar)
 For values between -1 and 1.
 
template<>
bool ReadCompressed (RakString &outTemplateVar)
 For strings.
 
template<>
bool ReadCompressedDelta (bool &outTemplateVar)
 Read a bool from a bitstream.
 

Static Public Member Functions

static int NumberOfLeadingZeroes (uint8_t x)
 
static bool DoEndianSwap (void)
 -— Member function template specialization declarations -—
 

Detailed Description

This class allows you to write and read native types as a string of bits. BitStream is used extensively throughout RakNet and is designed to be used by users as well.

See Also
BitStreamSample.txt

Constructor & Destructor Documentation

RakNet::BitStream::BitStream ( const unsigned int  initialBytesToAllocate)

Create the bitstream, with some number of bytes to immediately allocate.

There is no benefit to calling this, unless you know exactly how many bytes you need and it is greater than BITSTREAM_STACK_ALLOCATION_SIZE. In that case all it does is save you one or more realloc calls.

Parameters
[in]initialBytesToAllocatethe number of bytes to pre-allocate.
RakNet::BitStream::BitStream ( unsigned char *  _data,
const unsigned int  lengthInBytes,
bool  _copyData 
)

Initialize the BitStream, immediately setting the data it contains to a predefined pointer.

Set _copyData to true if you want to make an internal copy of the data you are passing. Set it to false to just save a pointer to the data. You shouldn't call Write functions with _copyData as false, as this will write to unallocated memory 99% of the time you will use this function to cast Packet::data to a bitstream for reading, in which case you should write something as follows:

RakNet::BitStream bs(packet->data, packet->length, false);
Parameters
[in]_dataAn array of bytes.
[in]lengthInBytesSize of the _data.
[in]_copyDatatrue or false to make a copy of _data or not.

Member Function Documentation

void RakNet::BitStream::AlignReadToByteBoundary ( void  )
inline

Align the next write and/or read to a byte boundary.

This can be used to 'waste' bits to byte align for efficiency reasons It can also be used to force coalesced bitstreams to start on byte boundaries so so WriteAlignedBits and ReadAlignedBits both calculate the same offset when aligning.

void RakNet::BitStream::AlignWriteToByteBoundary ( void  )
inline

Align the next write and/or read to a byte boundary.

This can be used to 'waste' bits to byte align for efficiency reasons It can also be used to force coalesced bitstreams to start on byte boundaries so so WriteAlignedBits and ReadAlignedBits both calculate the same offset when aligning.

BitSize_t RakNet::BitStream::CopyData ( unsigned char **  _data) const

Makes a copy of the internal data for you _data will point to the stream. Partial bytes are left aligned.

Parameters
[out]_dataThe allocated copy of GetData()
Returns
The length in bits of the stream.
unsigned char* RakNet::BitStream::GetData ( void  ) const
inline

Gets the data that BitStream is writing to / reading from. Partial bytes are left aligned.

Returns
A pointer to the internal state
void RakNet::BitStream::IgnoreBits ( const BitSize_t  numberOfBits)

Ignore data we don't intend to read.

Parameters
[in]numberOfBitsThe number of bits to ignore
void RakNet::BitStream::IgnoreBytes ( const unsigned int  numberOfBytes)

Ignore data we don't intend to read.

Parameters
[in]numberOfBitsThe number of bytes to ignore
static int RakNet::BitStream::NumberOfLeadingZeroes ( uint8_t  x)
static

Get the number of leading zeros for a number

Parameters
[in]xNumber to test
template<class templateType >
bool RakNet::BitStream::Read ( templateType &  outTemplateVar)
inline

Read any integral type from a bitstream.

Read any integral type from a bitstream. Define __BITSTREAM_NATIVE_END if you need endian swapping.

Define __BITSTREAM_NATIVE_END if you need endian swapping.

Parameters
[in]outTemplateVarThe value to read
Returns
true on success, false on failure.
Parameters
[in]outTemplateVarThe value to read
bool RakNet::BitStream::Read ( BitStream bitStream,
BitSize_t  numberOfBits 
)

Read one bitstream to another.

Parameters
[in]numberOfBitsbits to read
bitStreamthe bitstream to read into from
Returns
true on success, false on failure.
bool RakNet::BitStream::Read ( char *  output,
const unsigned int  numberOfBytes 
)

Read an array or casted stream of byte.

The array is raw data. There is no automatic endian conversion with this function

Parameters
[in]outputThe result byte array. It should be larger than numberOfBytes.
[in]numberOfBytesThe number of byte to read
Returns
true on success false if there is some missing bytes.
template<>
bool RakNet::BitStream::Read ( bool &  outTemplateVar)
inline

Read a bool from a bitstream.

Parameters
[in]outTemplateVarThe value to read
template<>
bool RakNet::BitStream::Read ( SystemAddress outTemplateVar)
inline

Read a systemAddress from a bitstream.

Parameters
[in]outTemplateVarThe value to read
bool RakNet::BitStream::ReadAlignedBytes ( unsigned char *  inOutByteArray,
const unsigned int  numberOfBytesToRead 
)

Read bits, starting at the next aligned bits.

Note that the modulus 8 starting offset of the sequence must be the same as was used with WriteBits. This will be a problem with packet coalescence unless you byte align the coalesced packets.

Parameters
[in]inOutByteArrayThe byte array larger than numberOfBytesToRead
[in]numberOfBytesToReadThe number of byte to read from the internal state
Returns
true if there is enough byte.
bool RakNet::BitStream::ReadAlignedBytesSafe ( char *  inOutByteArray,
int &  inputLength,
const int  maxBytesToRead 
)

Reads what was written by WriteAlignedBytesSafe.

Parameters
[in]inOutByteArrayThe data
[in]maxBytesToReadMaximum number of bytes to read
Returns
true on success, false on failure.
bool RakNet::BitStream::ReadAlignedBytesSafeAlloc ( char **  outByteArray,
int &  inputLength,
const unsigned int  maxBytesToRead 
)

Same as ReadAlignedBytesSafe() but allocates the memory for you using new, rather than assuming it is safe to write to.

Parameters
[in]outByteArrayoutByteArray will be deleted if it is not a pointer to 0
Returns
true on success, false on failure.
bool RakNet::BitStream::ReadBits ( unsigned char *  inOutByteArray,
BitSize_t  numberOfBitsToRead,
const bool  alignBitsToRight = true 
)

Read numberOfBitsToRead bits to the output source.

alignBitsToRight should be set to true to convert internal bitstream data to userdata. It should be false if you used WriteBits with rightAlignedBits false

Parameters
[in]inOutByteArrayThe resulting bits array
[in]numberOfBitsToReadThe number of bits to read
[in]alignBitsToRightif true bits will be right aligned.
Returns
true if there is enough bits to read
template<class templateType >
bool RakNet::BitStream::ReadBitsFromIntegerRange ( templateType &  value,
const templateType  minimum,
const templateType  maximum,
bool  allowOutsideRange = false 
)

Given the minimum and maximum values for an integer type, figure out the minimum number of bits to represent the range Then read only those bits

Note
A static is used so that the required number of bits for (maximum-minimum) is only calculated once. This does require that minimum and are fixed values for a given line of code for the life of the program
Parameters
[in]valueInteger value to read, which should be between minimum and maximum
[in]minimumMinimum value of value
[in]maximumMaximum value of value
[in]allowOutsideRangeIf true, all sends will take an extra bit, however value can deviate from outside minimum and maximum. If false, will assert if the value deviates. This should match the corresponding value passed to Write().
template<class templateType >
bool RakNet::BitStream::ReadBitsFromIntegerRange ( templateType &  value,
const templateType  minimum,
const templateType  maximum,
const int  requiredBits,
bool  allowOutsideRange = false 
)
Parameters
[in]requiredBitsPrimarily for internal use, called from above function() after calculating number of bits needed to represent maximum-minimum
template<class serializationType , class sourceType >
bool RakNet::BitStream::ReadCasted ( sourceType &  value)

Read one type serialized to another (smaller) type, to save bandwidth serializationType should be uint8_t, uint16_t, uint24_t, or uint32_t Example: int num; ReadCasted<uint8_t>(num); would read 1 bytefrom the stream, and put the value in an integer

Parameters
[in]valueThe value to write
template<class templateType >
bool RakNet::BitStream::ReadCompressed ( templateType &  outTemplateVar)
inline

Read any integral type from a bitstream.

Undefine __BITSTREAM_NATIVE_END if you need endian swapping. For floating point, this is lossy, using 2 bytes for a float and 4 for a double. The range must be between -1 and +1. For non-floating point, this is lossless, but only has benefit if you use less than half the bits of the type If you are not using __BITSTREAM_NATIVE_END the opposite is true for types larger than 1 byte

Parameters
[in]outTemplateVarThe value to read
Returns
true on success, false on failure.

Undefine __BITSTREAM_NATIVE_END if you need endian swapping. For floating point, this is lossy, using 2 bytes for a float and 4 for a double. The range must be between -1 and +1. For non-floating point, this is lossless, but only has benefit if you use less than half the bits of the type If you are not using __BITSTREAM_NATIVE_END the opposite is true for types larger than 1 byte

Parameters
[in]outTemplateVarThe value to read
template<class templateType >
bool RakNet::BitStream::ReadCompressedDelta ( templateType &  outTemplateVar)
inline

Read any integral type from a bitstream.

If the written value differed from the value compared against in the write function, var will be updated. Otherwise it will retain the current value. the current value will be updated. For floating point, this is lossy, using 2 bytes for a float and 4 for a double. The range must be between -1 and +1. For non-floating point, this is lossless, but only has benefit if you use less than half the bits of the type If you are not using __BITSTREAM_NATIVE_END the opposite is true for types larger than 1 byte ReadCompressedDelta is only valid from a previous call to WriteDelta

Parameters
[in]outTemplateVarThe value to read
Returns
true on success, false on failure.

If the written value differed from the value compared against in the write function, var will be updated. Otherwise it will retain the current value. the current value will be updated. For floating point, this is lossy, using 2 bytes for a float and 4 for a double. The range must be between -1 and +1. For non-floating point, this is lossless, but only has benefit if you use less than half the bits of the type If you are not using __BITSTREAM_NATIVE_END the opposite is true for types larger than 1 byte ReadCompressedDelta is only valid from a previous call to WriteDelta

Parameters
[in]outTemplateVarThe value to read
template<>
bool RakNet::BitStream::ReadCompressedDelta ( bool &  outTemplateVar)
inline

Read a bool from a bitstream.

Parameters
[in]outTemplateVarThe value to read
template<class templateType >
bool RakNet::BitStream::ReadDelta ( templateType &  outTemplateVar)
inline

Read any integral type from a bitstream.

If the written value differed from the value compared against in the write function, var will be updated. Otherwise it will retain the current value. ReadDelta is only valid from a previous call to WriteDelta

Parameters
[in]outTemplateVarThe value to read
Returns
true on success, false on failure.

If the written value differed from the value compared against in the write function, var will be updated. Otherwise it will retain the current value. ReadDelta is only valid from a previous call to WriteDelta

Parameters
[in]outTemplateVarThe value to read
template<>
bool RakNet::BitStream::ReadDelta ( bool &  outTemplateVar)
inline

Read a bool from a bitstream.

Parameters
[in]outTemplateVarThe value to read
bool RakNet::BitStream::ReadFloat16 ( float &  outFloat,
float  floatMin,
float  floatMax 
)

Read a float into 2 bytes, spanning the range between floatMin and floatMax.

Parameters
[in]outFloatThe float to read
[in]floatMinPredetermined minimum value of f
[in]floatMaxPredetermined maximum value of f
template<class templateType >
bool RakNet::BitStream::ReadNormQuat ( templateType &  w,
templateType &  x,
templateType &  y,
templateType &  z 
)

Read a normalized quaternion in 6 bytes + 4 bits instead of 16 bytes.

Parameters
[in]ww
[in]xx
[in]yy
[in]zz
Returns
true on success, false on failure.
template<class templateType >
bool RakNet::BitStream::ReadNormVector ( templateType &  x,
templateType &  y,
templateType &  z 
)

Read a normalized 3D vector, using (at most) 4 bytes + 3 bits instead of 12-24 bytes.

Will further compress y or z axis aligned vectors. Accurate to 1/32767.5.

Parameters
[in]xx
[in]yy
[in]zz
Returns
true on success, false on failure.
template<class templateType >
bool RakNet::BitStream::ReadOrthMatrix ( templateType &  m00,
templateType &  m01,
templateType &  m02,
templateType &  m10,
templateType &  m11,
templateType &  m12,
templateType &  m20,
templateType &  m21,
templateType &  m22 
)

Read an orthogonal matrix from a quaternion, reading 3 components of the quaternion in 2 bytes each and extrapolatig the 4th.

Use 6 bytes instead of 36 Lossy, although the result is renormalized

Returns
true on success, false on failure.
template<class templateType >
bool RakNet::BitStream::ReadVector ( templateType &  x,
templateType &  y,
templateType &  z 
)

Read 3 floats or doubles, using 10 bytes, where those float or doubles comprise a vector.

Loses accuracy to about 3/10ths and only saves 2 bytes, so only use if accuracy is not important.

Parameters
[in]xx
[in]yy
[in]zz
Returns
true on success, false on failure.
template<class templateType >
bool RakNet::BitStream::Serialize ( bool  writeToBitstream,
templateType &  inOutTemplateVar 
)
inline

Bidirectional serialize/deserialize any integral type to/from a bitstream.

Undefine __BITSTREAM_NATIVE_END if you need endian swapping.

Parameters
[in]writeToBitstreamtrue to write from your data to this bitstream. False to read from this bitstream and write to your data
[in]inOutTemplateVarThe value to write
Returns
true if writeToBitstream is true. true if writeToBitstream is false and the read was successful. false if writeToBitstream is false and the read was not successful.
bool RakNet::BitStream::Serialize ( bool  writeToBitstream,
char *  inOutByteArray,
const unsigned int  numberOfBytes 
)
inline

Bidirectional serialize/deserialize an array or casted stream or raw data. This does NOT do endian swapping.

Parameters
[in]writeToBitstreamtrue to write from your data to this bitstream. False to read from this bitstream and write to your data
[in]inOutByteArraya byte buffer
[in]numberOfBytesthe size of input in bytes
Returns
true if writeToBitstream is true. true if writeToBitstream is false and the read was successful. false if writeToBitstream is false and the read was not successful.
bool RakNet::BitStream::SerializeBits ( bool  writeToBitstream,
unsigned char *  inOutByteArray,
const BitSize_t  numberOfBitsToSerialize,
const bool  rightAlignedBits = true 
)
inline

Bidirectional serialize/deserialize numberToSerialize bits to/from the input.

Right aligned data means in the case of a partial byte, the bits are aligned from the right (bit 0) rather than the left (as in the normal internal representation) You would set this to true when writing user data, and false when copying bitstream data, such as writing one bitstream to another

Parameters
[in]writeToBitstreamtrue to write from your data to this bitstream. False to read from this bitstream and write to your data
[in]inOutByteArrayThe data
[in]numberOfBitsToSerializeThe number of bits to write
[in]rightAlignedBitsif true data will be right aligned
Returns
true if writeToBitstream is true. true if writeToBitstream is false and the read was successful. false if writeToBitstream is false and the read was not successful.
template<class templateType >
bool RakNet::BitStream::SerializeBitsFromIntegerRange ( bool  writeToBitstream,
templateType &  value,
const templateType  minimum,
const templateType  maximum,
bool  allowOutsideRange = false 
)

Given the minimum and maximum values for an integer type, figure out the minimum number of bits to represent the range Then serialize only those bits

Note
A static is used so that the required number of bits for (maximum-minimum) is only calculated once. This does require that minimum and are fixed values for a given line of code for the life of the program
Parameters
[in]writeToBitstreamtrue to write from your data to this bitstream. False to read from this bitstream and write to your data
[in]valueInteger value to write, which should be between minimum and maximum
[in]minimumMinimum value of value
[in]maximumMaximum value of value
[in]allowOutsideRangeIf true, all sends will take an extra bit, however value can deviate from outside minimum and maximum. If false, will assert if the value deviates
template<class templateType >
bool RakNet::BitStream::SerializeBitsFromIntegerRange ( bool  writeToBitstream,
templateType &  value,
const templateType  minimum,
const templateType  maximum,
const int  requiredBits,
bool  allowOutsideRange = false 
)
Parameters
[in]requiredBitsPrimarily for internal use, called from above function() after calculating number of bits needed to represent maximum-minimum
template<class serializationType , class sourceType >
bool RakNet::BitStream::SerializeCasted ( bool  writeToBitstream,
sourceType &  value 
)

Serialize one type casted to another (smaller) type, to save bandwidth serializationType should be uint8_t, uint16_t, uint24_t, or uint32_t Example: int num=53; SerializeCasted<uint8_t>(true, num); would use 1 byte to write what would otherwise be an integer (4 or 8 bytes)

Parameters
[in]writeToBitstreamtrue to write from your data to this bitstream. False to read from this bitstream and write to your data
[in]valueThe value to serialize
template<class templateType >
bool RakNet::BitStream::SerializeCompressed ( bool  writeToBitstream,
templateType &  inOutTemplateVar 
)
inline

Bidirectional serialize/deserialize any integral type to/from a bitstream.

Undefine __BITSTREAM_NATIVE_END if you need endian swapping. If you are not using __BITSTREAM_NATIVE_END the opposite is true for types larger than 1 byte For floating point, this is lossy, using 2 bytes for a float and 4 for a double. The range must be between -1 and +1. For non-floating point, this is lossless, but only has benefit if you use less than half the bits of the type

Parameters
[in]writeToBitstreamtrue to write from your data to this bitstream. False to read from this bitstream and write to your data
[in]inOutTemplateVarThe value to write
Returns
true if writeToBitstream is true. true if writeToBitstream is false and the read was successful. false if writeToBitstream is false and the read was not successful.
template<class templateType >
bool RakNet::BitStream::SerializeCompressedDelta ( bool  writeToBitstream,
templateType &  inOutCurrentValue,
const templateType &  lastValue 
)
inline

Bidirectional serialize/deserialize any integral type to/from a bitstream.

If the current value is different from the last value the current value will be written. Otherwise, a single bit will be written For floating point, this is lossy, using 2 bytes for a float and 4 for a double. The range must be between -1 and +1. For non-floating point, this is lossless, but only has benefit if you use less than half the bits of the type If you are not using __BITSTREAM_NATIVE_END the opposite is true for types larger than 1 byte

Parameters
[in]writeToBitstreamtrue to write from your data to this bitstream. False to read from this bitstream and write to your data
[in]inOutCurrentValueThe current value to write
[in]lastValueThe last value to compare against. Only used if writeToBitstream is true.
Returns
true if writeToBitstream is true. true if writeToBitstream is false and the read was successful. false if writeToBitstream is false and the read was not successful.
template<class templateType >
bool RakNet::BitStream::SerializeCompressedDelta ( bool  writeToBitstream,
templateType &  inOutTemplateVar 
)
inline

Save as SerializeCompressedDelta(templateType &currentValue, const templateType &lastValue) when we have an unknown second parameter.

Returns
true on data read. False on insufficient data in bitstream
template<class templateType >
bool RakNet::BitStream::SerializeDelta ( bool  writeToBitstream,
templateType &  inOutCurrentValue,
const templateType &  lastValue 
)
inline

Bidirectional serialize/deserialize any integral type to/from a bitstream.

If the current value is different from the last value the current value will be written. Otherwise, a single bit will be written

Parameters
[in]writeToBitstreamtrue to write from your data to this bitstream. False to read from this bitstream and write to your data
[in]inOutCurrentValueThe current value to write
[in]lastValueThe last value to compare against. Only used if writeToBitstream is true.
Returns
true if writeToBitstream is true. true if writeToBitstream is false and the read was successful. false if writeToBitstream is false and the read was not successful.
template<class templateType >
bool RakNet::BitStream::SerializeDelta ( bool  writeToBitstream,
templateType &  inOutCurrentValue 
)
inline

Bidirectional version of SerializeDelta when you don't know what the last value is, or there is no last value.

Parameters
[in]writeToBitstreamtrue to write from your data to this bitstream. False to read from this bitstream and write to your data
[in]inOutCurrentValueThe current value to write
Returns
true if writeToBitstream is true. true if writeToBitstream is false and the read was successful. false if writeToBitstream is false and the read was not successful.
bool RakNet::BitStream::SerializeFloat16 ( bool  writeToBitstream,
float &  inOutFloat,
float  floatMin,
float  floatMax 
)

Serialize a float into 2 bytes, spanning the range between floatMin and floatMax.

Parameters
[in]writeToBitstreamtrue to write from your data to this bitstream. False to read from this bitstream and write to your data
[in]inOutFloatThe float to write
[in]floatMinPredetermined minimum value of f
[in]floatMaxPredetermined maximum value of f
template<class templateType >
bool RakNet::BitStream::SerializeNormQuat ( bool  writeToBitstream,
templateType &  w,
templateType &  x,
templateType &  y,
templateType &  z 
)
inline

Bidirectional serialize/deserialize a normalized quaternion in 6 bytes + 4 bits instead of 16 bytes. Slightly lossy.

Parameters
[in]writeToBitstreamtrue to write from your data to this bitstream. False to read from this bitstream and write to your data
[in]ww
[in]xx
[in]yy
[in]zz
Returns
true if writeToBitstream is true. true if writeToBitstream is false and the read was successful. false if writeToBitstream is false and the read was not successful.
template<class templateType >
bool RakNet::BitStream::SerializeNormVector ( bool  writeToBitstream,
templateType &  x,
templateType &  y,
templateType &  z 
)
inline

Bidirectional serialize/deserialize a normalized 3D vector, using (at most) 4 bytes + 3 bits instead of 12-24 bytes.

Will further compress y or z axis aligned vectors. Accurate to 1/32767.5.

Parameters
[in]writeToBitstreamtrue to write from your data to this bitstream. False to read from this bitstream and write to your data
[in]xx
[in]yy
[in]zz
Returns
true if writeToBitstream is true. true if writeToBitstream is false and the read was successful. false if writeToBitstream is false and the read was not successful.
template<class templateType >
bool RakNet::BitStream::SerializeOrthMatrix ( bool  writeToBitstream,
templateType &  m00,
templateType &  m01,
templateType &  m02,
templateType &  m10,
templateType &  m11,
templateType &  m12,
templateType &  m20,
templateType &  m21,
templateType &  m22 
)
inline

Bidirectional serialize/deserialize an orthogonal matrix by creating a quaternion, and writing 3 components of the quaternion in 2 bytes each.

Use 6 bytes instead of 36 Lossy, although the result is renormalized

Returns
true on success, false on failure.
template<class templateType >
bool RakNet::BitStream::SerializeVector ( bool  writeToBitstream,
templateType &  x,
templateType &  y,
templateType &  z 
)
inline

Bidirectional serialize/deserialize a vector, using 10 bytes instead of 12.

Loses accuracy to about 3/10ths and only saves 2 bytes, so only use if accuracy is not important.

Parameters
[in]writeToBitstreamtrue to write from your data to this bitstream. False to read from this bitstream and write to your data
[in]xx
[in]yy
[in]zz
Returns
true if writeToBitstream is true. true if writeToBitstream is false and the read was successful. false if writeToBitstream is false and the read was not successful.
void RakNet::BitStream::SetWriteOffset ( const BitSize_t  offset)

Move the write pointer to a position on the array.

Parameters
[in]offsetthe offset from the start of the array.
Attention

Dangerous if you don't know what you are doing! For efficiency reasons you can only write mid-stream if your data is byte aligned.

template<class templateType >
void RakNet::BitStream::Write ( const templateType &  inTemplateVar)
inline

Write any integral type to a bitstream.

Undefine __BITSTREAM_NATIVE_END if you need endian swapping.

Parameters
[in]inTemplateVarThe value to write
void RakNet::BitStream::Write ( const char *  inputByteArray,
const unsigned int  numberOfBytes 
)

Write an array or casted stream or raw data. This does NOT do endian swapping.

Parameters
[in]inputByteArraya byte buffer
[in]numberOfBytesthe size of input in bytes
void RakNet::BitStream::Write ( BitStream bitStream,
BitSize_t  numberOfBits 
)

Write one bitstream to another.

Parameters
[in]numberOfBitsbits to write
bitStreamthe bitstream to copy from
template<>
void RakNet::BitStream::Write ( const bool &  inTemplateVar)
inline

Write a bool to a bitstream.

Parameters
[in]inTemplateVarThe value to write
template<>
void RakNet::BitStream::Write ( const SystemAddress inTemplateVar)
inline

Write a systemAddress to a bitstream.

Parameters
[in]inTemplateVarThe value to write
template<>
void RakNet::BitStream::Write ( const RakString inTemplateVar)
inline

Write a string to a bitstream.

Parameters
[in]varThe value to write
void RakNet::BitStream::WriteAlignedBytes ( const unsigned char *  inByteArray,
const unsigned int  numberOfBytesToWrite 
)

Align the bitstream to the byte boundary and then write the specified number of bits.

This is faster than WriteBits but wastes the bits to do the alignment and requires you to call ReadAlignedBits at the corresponding read position.

Parameters
[in]inByteArrayThe data
[in]numberOfBytesToWriteThe size of input.
void RakNet::BitStream::WriteAlignedBytesSafe ( const char *  inByteArray,
const unsigned int  inputLength,
const unsigned int  maxBytesToWrite 
)

Aligns the bitstream, writes inputLength, and writes input. Won't write beyond maxBytesToWrite.

Parameters
[in]inByteArrayThe data
[in]inputLengthThe size of input.
[in]maxBytesToWriteMax bytes to write
void RakNet::BitStream::WriteBits ( const unsigned char *  inByteArray,
BitSize_t  numberOfBitsToWrite,
const bool  rightAlignedBits = true 
)

Write numberToWrite bits from the input source.

Right aligned data means in the case of a partial byte, the bits are aligned from the right (bit 0) rather than the left (as in the normal internal representation) You would set this to true when writing user data, and false when copying bitstream data, such as writing one bitstream to another.

Parameters
[in]inByteArrayThe data
[in]numberOfBitsToWriteThe number of bits to write
[in]rightAlignedBitsif true data will be right aligned
template<class templateType >
void RakNet::BitStream::WriteBitsFromIntegerRange ( const templateType  value,
const templateType  minimum,
const templateType  maximum,
bool  allowOutsideRange = false 
)

Given the minimum and maximum values for an integer type, figure out the minimum number of bits to represent the range Then write only those bits

Note
A static is used so that the required number of bits for (maximum-minimum) is only calculated once. This does require that minimum and are fixed values for a given line of code for the life of the program
Parameters
[in]valueInteger value to write, which should be between minimum and maximum
[in]minimumMinimum value of value
[in]maximumMaximum value of value
[in]allowOutsideRangeIf true, all sends will take an extra bit, however value can deviate from outside minimum and maximum. If false, will assert if the value deviates. This should match the corresponding value passed to Read().
template<class templateType >
void RakNet::BitStream::WriteBitsFromIntegerRange ( const templateType  value,
const templateType  minimum,
const templateType  maximum,
const int  requiredBits,
bool  allowOutsideRange = false 
)
Parameters
[in]requiredBitsPrimarily for internal use, called from above function() after calculating number of bits needed to represent maximum-minimum
template<class destinationType , class sourceType >
void RakNet::BitStream::WriteCasted ( const sourceType &  value)

Write one type serialized as another (smaller) type, to save bandwidth serializationType should be uint8_t, uint16_t, uint24_t, or uint32_t Example: int num=53; WriteCasted<uint8_t>(num); would use 1 byte to write what would otherwise be an integer (4 or 8 bytes)

Parameters
[in]valueThe value to write
template<class templateType >
void RakNet::BitStream::WriteCompressed ( const templateType &  inTemplateVar)
inline

Write any integral type to a bitstream.

Undefine __BITSTREAM_NATIVE_END if you need endian swapping. If you are not using __BITSTREAM_NATIVE_END the opposite is true for types larger than 1 byte For floating point, this is lossy, using 2 bytes for a float and 4 for a double. The range must be between -1 and +1. For non-floating point, this is lossless, but only has benefit if you use less than half the bits of the type

Parameters
[in]inTemplateVarThe value to write

Undefine __BITSTREAM_NATIVE_END if you need endian swapping. For floating point, this is lossy, using 2 bytes for a float and 4 for a double. The range must be between -1 and +1. For non-floating point, this is lossless, but only has benefit if you use less than half the bits of the type If you are not using __BITSTREAM_NATIVE_END the opposite is true for types larger than 1 byte

Parameters
[in]inTemplateVarThe value to write
template<class templateType >
void RakNet::BitStream::WriteCompressedDelta ( const templateType &  currentValue,
const templateType &  lastValue 
)
inline

Write any integral type to a bitstream.

If the current value is different from the last value the current value will be written. Otherwise, a single bit will be written For floating point, this is lossy, using 2 bytes for a float and 4 for a double. The range must be between -1 and +1. For non-floating point, this is lossless, but only has benefit if you use less than half the bits of the type If you are not using __BITSTREAM_NATIVE_END the opposite is true for types larger than 1 byte

Parameters
[in]currentValueThe current value to write
[in]lastValueThe last value to compare against
template<>
void RakNet::BitStream::WriteCompressedDelta ( const bool &  currentValue,
const bool &  lastValue 
)
inline

Write a bool delta. Same thing as just calling Write.

Parameters
[in]currentValueThe current value to write
[in]lastValueThe last value to compare against
template<class templateType >
void RakNet::BitStream::WriteDelta ( const templateType &  currentValue,
const templateType &  lastValue 
)
inline

Write any integral type to a bitstream.

If the current value is different from the last value the current value will be written. Otherwise, a single bit will be written

Parameters
[in]currentValueThe current value to write
[in]lastValueThe last value to compare against
template<class templateType >
void RakNet::BitStream::WriteDelta ( const templateType &  currentValue)
inline

WriteDelta when you don't know what the last value is, or there is no last value.

Parameters
[in]currentValueThe current value to write
template<>
void RakNet::BitStream::WriteDelta ( const bool &  currentValue,
const bool &  lastValue 
)
inline

Write a bool delta. Same thing as just calling Write.

Parameters
[in]currentValueThe current value to write
[in]lastValueThe last value to compare against
void RakNet::BitStream::WriteFloat16 ( float  x,
float  floatMin,
float  floatMax 
)

Write a float into 2 bytes, spanning the range between floatMin and floatMax.

Parameters
[in]xThe float to write
[in]floatMinPredetermined minimum value of f
[in]floatMaxPredetermined maximum value of f
template<class templateType >
void RakNet::BitStream::WriteNormQuat ( templateType  w,
templateType  x,
templateType  y,
templateType  z 
)

Write a normalized quaternion in 6 bytes + 4 bits instead of 16 bytes. Slightly lossy.

Parameters
[in]ww
[in]xx
[in]yy
[in]zz
template<class templateType >
void RakNet::BitStream::WriteNormVector ( templateType  x,
templateType  y,
templateType  z 
)

Write a normalized 3D vector, using (at most) 4 bytes + 3 bits instead of 12-24 bytes.

Will further compress y or z axis aligned vectors. Accurate to 1/32767.5.

Parameters
[in]xx
[in]yy
[in]zz
template<class templateType >
void RakNet::BitStream::WriteOrthMatrix ( templateType  m00,
templateType  m01,
templateType  m02,
templateType  m10,
templateType  m11,
templateType  m12,
templateType  m20,
templateType  m21,
templateType  m22 
)

Write an orthogonal matrix by creating a quaternion, and writing 3 components of the quaternion in 2 bytes each.

Use 6 bytes instead of 36 Lossy, although the result is renormalized

template<class templateType >
void RakNet::BitStream::WritePtr ( templateType *  inTemplateVar)
inline

Write the dereferenced pointer to any integral type to a bitstream.

Undefine __BITSTREAM_NATIVE_END if you need endian swapping.

Parameters
[in]inTemplateVarThe value to write
template<class templateType >
void RakNet::BitStream::WriteVector ( templateType  x,
templateType  y,
templateType  z 
)

Write a vector, using 10 bytes instead of 12.

Loses accuracy to about 3/10ths and only saves 2 bytes, so only use if accuracy is not important.

Parameters
[in]xx
[in]yy
[in]zz

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