Part of GStreamer Family
SourceForge Logo

A highly-optimized bitstream library

Bitstream operations are very common in compression schemes, because the need to read and write particular numbers of bits is so pervasive. Yet it's also one of the most ignored areas of optimization, even though hardware codecs have had custom silicon to solve this problem for decades.

In looking through most of the available codecs on the net, I've found that almost every single one uses a different bitstream subsystem structure, and many of them are so simplistic that they are losing a large percentage of their CPU time because of that. bitstream is an attempt at creating a single unified bitstream library that can be used by all of these projects, yet at the same time allowing significant fundamental optimization and specialization.

What is the goal?

The basic goal is to provide a library which can be used by all existing codecs, and thus has a simple but comprehensive API, but is also very fast and very specializable. It must be capable of not only reading bitstreams, but writing them. These goals are quite self-contradictory, but they can be reconciled with some work.

API Overview

The API for bitstream comes from experience with about a dozen various bitstream implementations and codecs, so hopefully it has incorporated all the require features:

  • typedef struct bitstream_s bitstream_t

    This is the object that contains all the state for a given bitstream. It should be considered opaque unless you really know what you're doing.

  • bitstream_t *bitstream_new (void)

    This function creates a new bitstream structure, with all the basic fields initialized to a default state.

  • void bitstream_next_buffer (bitstream_t *bs, uint8_t *buf, uint32_t len)

    Used to provide a new buffer to the bitstream library. { This buffer will be queued immediately following all previous buffers, and concatenated on byte boundaries. }

  • void bitstream_set_fill_func (bitstream_t *bs, uint32_t (*fill_func) (uint8_t **, void *), void *private)

    Provide the bitstream structure with a function that will procure more data on demand. { .... }

  • uint32_t bitstream_get (bitstream_t *bs, uint32_t num_bits)

    Irrevocably retrieve num_bits from the bitstream.

  • uint32_t bitstream_show (bitstream_t *bs, uint32_t num_bits)

    Peek num_bits from the bitstream, without deleting them. num_bits must be less than or equal to 32 bits.

  • void bitstream_void (bitstream_t *bs, uint32_t num_bits)

    Toss away num_bits from the front of the bitstream. Typically used in conjunction with bitstream_show.

  • void bitstream_unget (bitstream_t *bs, uint32_t data, uint32_t num_bits)

    Places num_bits out of data back into the bitstream buffer temporarily (until the next get/flush). num_bits must be limitted to 32 bits.

{ These functions are temporary, and will be replaced with something less annoying later on, in conjunction with SpeciaLib.

  • void bitstream_set_vable_c (bitstream_t *bs)

    Sets the vtable for the bitstream struct bs up to use the C implementation.

  • void bitstream_set_vable_mmx (bitstream_t *bs)

    Sets the vtable for the bitstream struct bs up to use the x86 MMX implementation.