Jenkins Software

Bitstream Overview
Description

The bitstream class is a helper class under the namespace RakNet that is used to wrap a dynamic array for the purpose of packing and unpacking bits. Its main three benefits are:
  1. Creating packets dynamically
  2. Compression
  3. Writing Bits
With structs you have to predefine your structures and cast them to a (char*). With a bitstream, you can choose to write blocks at runtime, depending on the context. Bitstreams can compress the native types.

The compression is quite simple and uses the following algorithm:
1. Is the upper half all 0's (1's for unsigned types)?
TRUE - Write a 1
FALSE - Write a 0, and the upper half
2. Repeat with the lower half, until we are at half a byte.
What this means is you will save bits if your data under half its maximum range. So if you know this is usually the case in advance, you can use WriteCompressed instead of Write and ReadCompressed instead of read.

Finally, you can write bits. Most of the time you will not care about this. However, when writing booleans it will automatically only write one bit. This can also be very useful for encryption since your data will no longer be byte aligned.

Writing Data

Bitstream is templated to take any type of data. If this is a built-in type, such as NetworkIDObject, it uses partial template specialization to write the type more efficiently. If it's a native type, or a structure, it writes the individual bits, similar to memcpy. You can pass structs containing multiple data members to bitstreams. However, you may wish to serialize each individual element to do correct endian swapping (needed for communication between PCs and Macs, for example). Note: if you want to support endian swapping, you should also comment out __BITSTREAM_NATIVE_END in RakNetDefines.h. This is uncommented by default as a speed optimization.

struct MyVector
{
float x,y,z;
} myVector;

// No endian swapping
bitStream.Write(myVector);

// With endian swapping
#undef __BITSTREAM_NATIVE_END
bitStream.Write(myVector.x);
bitStream.Write(myVector.y);
bitStream.Write(myVector.z);

// You can also override operator left shift and right shift
RakNet::BitStream& operator << (RakNet::BitStream& out, MyVector& in)
{
out.WriteNormVector(in.x,in.y,in.z);
return out;
}
RakNet::BitStream& operator >> (RakNet::BitStream& in, MyVector& out)
{
bool success = in.ReadNormVector(out.x,out.y,out.z);
assert(success);
return in;
}

// Read from bitstream
myVector << bitStream;
// Write to bitstream
myVector >> bitStream;

Optional - One of the constructor versions takes a length in bytes as a parameter. If you have an idea of the size of your data you can pass this number when creating the bitstream to avoid internal reallocations.

See Creating Packets for more details.

Reading Data

Reading data is equally simple. Create a bitstream, and in the constructor assign it your data.

// Assuming we have a Packet *
BitStream myBitStream(packet->data, packet->length, false);
struct MyVector
{
float x,y,z;
} myVector;

// No endian swapping
bitStream.Read(myVector);

// With endian swapping (__BITSTREAM_NATIVE_END should just be commented in RakNetDefines.h)
#undef __BITSTREAM_NATIVE_END
#include "BitStream.h" bitStream.Read(myVector.x);
bitStream.Read(myVector.y);
bitStream.Read(myVector.z);

See Receiving Packets for a more complete example.

Serializing Data

You can have the same function read and write, by using BitStream::Serialize() instead of Read() or Write().

struct MyVector
{
float x,y,z;
// writeToBitstream==true means write, writeToBitstream==false means read
void Serialize(bool writeToBitstream, BitStream *bs)
{
bs->Serialize(writeToBitstream, x);
bs->Serialize(writeToBitstream, y);
bs->Serialize(writeToBitstream, z);
}
} myVector;

See Receiving Packets for a more complete example.

Major functions
See BitStream.h for a full list of functions.

Constructor
BitStream(int initialBytesToAllocate);
Use the constuctor version that takes an int to determine how many bytes to initially allocate. While not necessary, you can avoid reallocations when doing writes this way.

Constructor
BitStream(const char* _data, unsigned int lengthInBytes, bool _copyData);
This version of the constructor gives the bitstream some initial data. This is used for interpreting an existing data stream as a bitstream, which you will almost always do when recieving a bitstream that you sent previously. Use false for _copyData to simply point to the existing data (used for pure reading). Use true if you want to make an internal copy, either to save the data or if you plan to change it.

Write functions
The write functions write data to the bitstream at the end of the bitstream. You should use the analogous Read to get the data back out.

WriteCompressed functions
The write functions write data to the bitstream at the end of the bitstream. You should use the analogous ReadCompressed to get the data back out

Read functions
The read functions read data already in the bitstream, in order from beginning to end. The read function returns false if there is no more data in the bitstream.

ReadCompressed functions
The read compressed functions read data already in the bitstream, in order from beginning to end, written with WriteCompressed. The ReadCompressed function returns false if there is no more data in the bitstream.

GetNumberOfBitsUsed
GetNumberOfBytesUsed
Gives you the number of bytes or bits written.

GetData
Gives you a pointer to the internal data of the bitstream. This is a (char*) allocated with malloc and is presented in case you need direct assess to the data.
See Also
Index
Creating Packets
Receiving Packets