BitStream

BitStream

This class enables bool, int and float sequential serialization with bit precision. Once you write values to the stream, you can both read them back or access the underlying buffer.

This class is particularly useful for critical network data compressing. Say you need to constantly send some ints through the internet but you know that these numbers are always between 0 and 7. This way, they can be stored with only 3 bits. Using BitStream it is possible to compress them together just so you have this byte[] where every 3 bits represents a number you wrote. On the receiving end, you can recover these numbers from the byte[].

byte[] GetBuffer()

Get access to the underlying buffer. You can send this to the internet. Values you write are stored here.

void LoadBuffer( byte[] buffer )

Loads a buffer to the stream. After you do this, you can then begin reading values from it.

bool ReadBool()

Reads a boolean from the stream. Booleans are stored with only one bit for maximum compression.

int ReadInt( int bitCount )

Reads an integer from the stream. bitCount is the number of bits used to represent this number.

float ReadFloat( int bitCount, int fixedPointScale )

Reads a floating point (decimal) number from the stream. The number read is actually an integer which is scaled back (divided) by fixedPointScale and then converted to a float. Say the number you'll read needs at most two decimal digits, then fixedPointScale would be 100 because it will divide a number like 134 by 100 and get 1.34 which is the number originally serialized. bitCount is the number of bits used to represent the serialized number (134 in the example above).

void Write( bool b )

Writes a boolean to stream. Booleans are stored with only one bit for maximum compression.

bool Write( int value, int bitCount )

Writes an integer to stream. bitCount is the number of bits used to represent this number.

bool Write( float value, int bitCount, int fixedPointScale )

Writes a floating point (decimal) number to the stream. This decimal number first is scaled (multiplyed) by fixedPointScale and then converted to an integer. Say you need at most two decimal digits, then fixedPointScale would be 100 because it will multiply a number like 1.34 by 100 and you'll have 134 which is the number going to be serialized. bitCount is the number of bits used to represent the scaled number (134 in the example above).

Example

using UnityEngine;
using BitStrap;

public sealed class MyScript : MonoBehaviour
{
    private BitStream myStream = new BitStream( 10 ); // Initialize BitStream with capacity of 10 bits

    private void Start()
    {
        myStream.Write( true ); // Writes true and uses 1 bit
        myStream.Write( 7, 3 ); // Writes 7 and uses 3 bits
        myStream.Write( 5.5, 6, 10 ); // Writes 5.5 (actually 55, which is 5.5 * 10, is stored) and uses 6 bits

        byte[] myBuffer = myStream.GetBuffer();
        Debug.Log( myBuffer.ToStringFull() ); // Here you could send myBuffer over the internet

        myStream.LoadBuffer( myBuffer ); // Say you received myBuffer from the internet

        // Now you can read its values (order is important!)
        bool boolValue = myStream.ReadBool(); // Reads true and uses 1 bit
        int intValue = myStream.ReadInt( 3 ); // Reads 7 and uses 3 bits
        float floatValue = myStream.ReadFloat( 6, 10 ); // Reads 5.5 (55, which is 5.5 * 10, was stored) and uses 6 bits
    }
}