## GstBitReader

GstBitReader — Reads any number of bits from a memory buffer

## Synopsis

    #include <gst/base/gstbitreader.h>

                        GstBitReader;
    #define             GST_BIT_READER_INIT                 (data,
                                                             size)
    #define             GST_BIT_READER_INIT_FROM_BUFFER     (buffer)
    GstBitReader *      gst_bit_reader_new                  (const guint8 *data,
                                                             guint size);
    GstBitReader *      gst_bit_reader_new_from_buffer      (const GstBuffer *buffer);
    void                gst_bit_reader_free                 (GstBitReader *reader);
    void                gst_bit_reader_init                 (GstBitReader *reader,
                                                             const guint8 *data,
                                                             guint size);
    void                gst_bit_reader_init_from_buffer     (GstBitReader *reader,
                                                             const GstBuffer *buffer);
    guint               gst_bit_reader_get_pos              (const GstBitReader *reader);
    guint               gst_bit_reader_get_remaining        (const GstBitReader *reader);
    gboolean            gst_bit_reader_set_pos              (GstBitReader *reader,
                                                             guint pos);
    guint               gst_bit_reader_get_size             (const GstBitReader *reader);
    gboolean            gst_bit_reader_skip                 (GstBitReader *reader,
                                                             guint nbits);
    gboolean            gst_bit_reader_skip_to_byte         (GstBitReader *reader);
    gboolean            gst_bit_reader_get_bits_uint16      (GstBitReader *reader,
                                                             guint16 *val,
                                                             guint nbits);
    gboolean            gst_bit_reader_get_bits_uint32      (GstBitReader *reader,
                                                             guint32 *val,
                                                             guint nbits);
    gboolean            gst_bit_reader_get_bits_uint64      (GstBitReader *reader,
                                                             guint64 *val,
                                                             guint nbits);
    gboolean            gst_bit_reader_get_bits_uint8       (GstBitReader *reader,
                                                             guint8 *val,
                                                             guint nbits);
    gboolean            gst_bit_reader_peek_bits_uint16     (const GstBitReader *reader,
                                                             guint16 *val,
                                                             guint nbits);
    gboolean            gst_bit_reader_peek_bits_uint32     (const GstBitReader *reader,
                                                             guint32 *val,
                                                             guint nbits);
    gboolean            gst_bit_reader_peek_bits_uint64     (const GstBitReader *reader,
                                                             guint64 *val,
                                                             guint nbits);
    gboolean            gst_bit_reader_peek_bits_uint8      (const GstBitReader *reader,
                                                             guint8 *val,
                                                             guint nbits);
    void                gst_bit_reader_skip_unchecked       (GstBitReader *reader,
                                                             guint nbits);
    void                gst_bit_reader_skip_to_byte_unchecked
                                                            (GstBitReader *reader);
    guint16             gst_bit_reader_get_bits_uint16_unchecked
                                                            (GstBitReader *reader,
                                                             guint nbits);
    guint32             gst_bit_reader_get_bits_uint32_unchecked
                                                            (GstBitReader *reader,
                                                             guint nbits);
    guint64             gst_bit_reader_get_bits_uint64_unchecked
                                                            (GstBitReader *reader,
                                                             guint nbits);
    guint8              gst_bit_reader_get_bits_uint8_unchecked
                                                            (GstBitReader *reader,
                                                             guint nbits);
    guint16             gst_bit_reader_peek_bits_uint16_unchecked
                                                            (const GstBitReader *reader,
                                                             guint nbits);
    guint32             gst_bit_reader_peek_bits_uint32_unchecked
                                                            (const GstBitReader *reader,
                                                             guint nbits);
    guint64             gst_bit_reader_peek_bits_uint64_unchecked
                                                            (const GstBitReader *reader,
                                                             guint nbits);
    guint8              gst_bit_reader_peek_bits_uint8_unchecked
                                                            (const GstBitReader *reader,
                                                             guint nbits);

## Description

GstBitReader provides a bit reader that can read any number of bits from a memory buffer. It provides functions for reading any number of bits into 8, 16, 32 and 64 bit variables.

## Details

### GstBitReader

    typedef struct {
      const guint8 *data;
      guint size;

      guint byte;  /* Byte position */
      guint bit;   /* Bit position in the current byte */
    } GstBitReader;

A bit reader instance.

const guint8 *`data`; | Data from which the bit reader will read
guint `size`; | Size of `data` in bytes
guint `byte`; | Current byte position
guint `bit`; | Bit position in the current byte

### GST_BIT_READER_INIT()

    #define GST_BIT_READER_INIT(data, size) {data, size, 0, 0}

A GstBitReader must be initialized with this macro, before it can be used. This macro can used be to initialize a variable, but it cannot be assigned to a variable. In that case you have to use `gst_bit_reader_init()`.

`data` : | Data from which the GstBitReader should read
`size` : | Size of `data` in bytes

Since 0.10.22

### GST_BIT_READER_INIT_FROM_BUFFER()

    #define GST_BIT_READER_INIT_FROM_BUFFER(buffer) {GST_BUFFER_DATA (buffer), GST_BUFFER_SIZE (buffer), 0, 0}

A GstBitReader must be initialized with this macro, before it can be used. This macro can used be to initialize a variable, but it cannot be assigned to a variable. In that case you have to use `gst_bit_reader_init()`.

`buffer` : | Buffer from which the GstBitReader should read

Since 0.10.22

### gst_bit_reader_new ()

    GstBitReader *      gst_bit_reader_new                  (const guint8 *data,
                                                             guint size);

Create a new GstBitReader instance, which will read from `data`.

Free-function: gst_bit_reader_free

`data` : | Data from which the GstBitReader should read
`size` : | Size of `data` in bytes
Returns : | a new GstBitReader instance. [transfer full]

Since 0.10.22

### gst_bit_reader_new_from_buffer ()

    GstBitReader *      gst_bit_reader_new_from_buffer      (const GstBuffer *buffer);

Create a new GstBitReader instance, which will read from the GstBuffer `buffer`.

Free-function: gst_bit_reader_free

`buffer` : | Buffer from which the GstBitReader should read
Returns : | a new GstBitReader instance. [transfer full]

Since 0.10.22

### gst_bit_reader_free ()

    void                gst_bit_reader_free                 (GstBitReader *reader);

Frees a GstBitReader instance, which was previously allocated by `gst_bit_reader_new()` or `gst_bit_reader_new_from_buffer()`.

`reader` : | a GstBitReader instance. [in][transfer full]

Since 0.10.22

### gst_bit_reader_init ()

    void                gst_bit_reader_init                 (GstBitReader *reader,
                                                             const guint8 *data,
                                                             guint size);

Initializes a GstBitReader instance to read from `data`. This function can be called on already initialized instances.

`reader` : | a GstBitReader instance
`data` : | data from which the bit reader should read. [in][array length=size]
`size` : | Size of `data` in bytes

Since 0.10.22

### gst_bit_reader_init_from_buffer ()

    void                gst_bit_reader_init_from_buffer     (GstBitReader *reader,
                                                             const GstBuffer *buffer);

Initializes a GstBitReader instance to read from `buffer`. This function can be called on already initialized instances.

`reader` : | a GstBitReader instance
`buffer` : | Buffer from which the GstBitReader should read. [transfer none]

Since 0.10.22

### gst_bit_reader_get_pos ()

    guint               gst_bit_reader_get_pos              (const GstBitReader *reader);

Returns the current position of a GstBitReader instance in bits.

`reader` : | a GstBitReader instance
Returns : | The current position of `reader` in bits.

Since 0.10.22

### gst_bit_reader_get_remaining ()

    guint               gst_bit_reader_get_remaining        (const GstBitReader *reader);

Returns the remaining number of bits of a GstBitReader instance.

`reader` : | a GstBitReader instance
Returns : | The remaining number of bits of `reader` instance.

Since 0.10.22

### gst_bit_reader_set_pos ()

    gboolean            gst_bit_reader_set_pos              (GstBitReader *reader,
                                                             guint pos);

Sets the new position of a GstBitReader instance to `pos` in bits.

`reader` : | a GstBitReader instance
`pos` : | The new position in bits
Returns : | `TRUE` if the position could be set successfully, `FALSE` otherwise.

Since 0.10.22

### gst_bit_reader_get_size ()

    guint               gst_bit_reader_get_size             (const GstBitReader *reader);

Returns the total number of bits of a GstBitReader instance.

`reader` : | a GstBitReader instance
Returns : | The total number of bits of `reader` instance.

Since 0.10.26

### gst_bit_reader_skip ()

    gboolean            gst_bit_reader_skip                 (GstBitReader *reader,
                                                             guint nbits);

Skips `nbits` bits of the GstBitReader instance.

`reader` : | a GstBitReader instance
`nbits` : | the number of bits to skip
Returns : | `TRUE` if `nbits` bits could be skipped, `FALSE` otherwise.

Since 0.10.22

### gst_bit_reader_skip_to_byte ()

    gboolean            gst_bit_reader_skip_to_byte         (GstBitReader *reader);

Skips until the next byte.

`reader` : | a GstBitReader instance
Returns : | `TRUE` if successful, `FALSE` otherwise.

Since 0.10.22

### gst_bit_reader_get_bits_uint16 ()

    gboolean            gst_bit_reader_get_bits_uint16      (GstBitReader *reader,
                                                             guint16 *val,
                                                             guint nbits);

Read `nbits` bits into `val` and update the current position.

`reader` : | a GstBitReader instance
`val` : | Pointer to a guint16 to store the result. [out]
`nbits` : | number of bits to read
Returns : | `TRUE` if successful, `FALSE` otherwise.

Since 0.10.22

### gst_bit_reader_get_bits_uint32 ()

    gboolean            gst_bit_reader_get_bits_uint32      (GstBitReader *reader,
                                                             guint32 *val,
                                                             guint nbits);

Read `nbits` bits into `val` and update the current position.

`reader` : | a GstBitReader instance
`val` : | Pointer to a guint32 to store the result. [out]
`nbits` : | number of bits to read
Returns : | `TRUE` if successful, `FALSE` otherwise.

Since 0.10.22

### gst_bit_reader_get_bits_uint64 ()

    gboolean            gst_bit_reader_get_bits_uint64      (GstBitReader *reader,
                                                             guint64 *val,
                                                             guint nbits);

Read `nbits` bits into `val` and update the current position.

`reader` : | a GstBitReader instance
`val` : | Pointer to a guint64 to store the result. [out]
`nbits` : | number of bits to read
Returns : | `TRUE` if successful, `FALSE` otherwise.

Since 0.10.22

### gst_bit_reader_get_bits_uint8 ()

    gboolean            gst_bit_reader_get_bits_uint8       (GstBitReader *reader,
                                                             guint8 *val,
                                                             guint nbits);

Read `nbits` bits into `val` and update the current position.

`reader` : | a GstBitReader instance
`val` : | Pointer to a guint8 to store the result. [out]
`nbits` : | number of bits to read
Returns : | `TRUE` if successful, `FALSE` otherwise.

Since 0.10.22

### gst_bit_reader_peek_bits_uint16 ()

    gboolean            gst_bit_reader_peek_bits_uint16     (const GstBitReader *reader,
                                                             guint16 *val,
                                                             guint nbits);

Read `nbits` bits into `val` but keep the current position.

`reader` : | a GstBitReader instance
`val` : | Pointer to a guint16 to store the result. [out]
`nbits` : | number of bits to read
Returns : | `TRUE` if successful, `FALSE` otherwise.

Since 0.10.22

### gst_bit_reader_peek_bits_uint32 ()

    gboolean            gst_bit_reader_peek_bits_uint32     (const GstBitReader *reader,
                                                             guint32 *val,
                                                             guint nbits);

Read `nbits` bits into `val` but keep the current position.

`reader` : | a GstBitReader instance
`val` : | Pointer to a guint32 to store the result. [out]
`nbits` : | number of bits to read
Returns : | `TRUE` if successful, `FALSE` otherwise.

Since 0.10.22

### gst_bit_reader_peek_bits_uint64 ()

    gboolean            gst_bit_reader_peek_bits_uint64     (const GstBitReader *reader,
                                                             guint64 *val,
                                                             guint nbits);

Read `nbits` bits into `val` but keep the current position.

`reader` : | a GstBitReader instance
`val` : | Pointer to a guint64 to store the result. [out]
`nbits` : | number of bits to read
Returns : | `TRUE` if successful, `FALSE` otherwise.

Since 0.10.22

### gst_bit_reader_peek_bits_uint8 ()

    gboolean            gst_bit_reader_peek_bits_uint8      (const GstBitReader *reader,
                                                             guint8 *val,
                                                             guint nbits);

Read `nbits` bits into `val` but keep the current position.

`reader` : | a GstBitReader instance
`val` : | Pointer to a guint8 to store the result. [out]
`nbits` : | number of bits to read
Returns : | `TRUE` if successful, `FALSE` otherwise.

Since 0.10.22

### gst_bit_reader_skip_unchecked ()

    void                gst_bit_reader_skip_unchecked       (GstBitReader *reader,
                                                             guint nbits);

Skips `nbits` bits of the GstBitReader instance without checking if there are enough bits available in the bit reader.

`reader` : | a GstBitReader instance
`nbits` : | the number of bits to skip

Since 0.10.31

### gst_bit_reader_skip_to_byte_unchecked ()

    void                gst_bit_reader_skip_to_byte_unchecked
                                                            (GstBitReader *reader);

Skips until the next byte without checking if there are enough bits available in the bit reader.

`reader` : | a GstBitReader instance

Since 0.10.31

### gst_bit_reader_get_bits_uint16_unchecked ()

    guint16             gst_bit_reader_get_bits_uint16_unchecked
                                                            (GstBitReader *reader,
                                                             guint nbits);

Read `nbits` bits into `val` and update the current position without checking if there are enough bits available in the bit reader.

`reader` : | a GstBitReader instance
`nbits` : | number of bits to read
Returns : | unsigned 16 bit integer with the bits.

Since 0.10.31

### gst_bit_reader_get_bits_uint32_unchecked ()

    guint32             gst_bit_reader_get_bits_uint32_unchecked
                                                            (GstBitReader *reader,
                                                             guint nbits);

Read `nbits` bits into `val` and update the current position without checking if there are enough bits available in the bit reader.

`reader` : | a GstBitReader instance
`nbits` : | number of bits to read
Returns : | unsigned 32 bit integer with the bits.

Since 0.10.31

### gst_bit_reader_get_bits_uint64_unchecked ()

    guint64             gst_bit_reader_get_bits_uint64_unchecked
                                                            (GstBitReader *reader,
                                                             guint nbits);

Read `nbits` bits into `val` and update the current position without checking if there are enough bits available in the bit reader.

`reader` : | a GstBitReader instance
`nbits` : | number of bits to read
Returns : | unsigned 64 bit integer with the bits.

Since 0.10.31

### gst_bit_reader_get_bits_uint8_unchecked ()

    guint8              gst_bit_reader_get_bits_uint8_unchecked
                                                            (GstBitReader *reader,
                                                             guint nbits);

Read `nbits` bits into `val` and update the current position without checking if there are enough bits available in the bit reader.

`reader` : | a GstBitReader instance
`nbits` : | number of bits to read
Returns : | unsigned 8 bit integer with the bits.

Since 0.10.31

### gst_bit_reader_peek_bits_uint16_unchecked ()

    guint16             gst_bit_reader_peek_bits_uint16_unchecked
                                                            (const GstBitReader *reader,
                                                             guint nbits);

Read `nbits` bits into `val` but keep the current position without checking if there are enough bits available in the bit reader

`reader` : | a GstBitReader instance
`nbits` : | number of bits to read
Returns : | unsigned 64 bit integer with the bits.

Since 0.10.31

### gst_bit_reader_peek_bits_uint32_unchecked ()

    guint32             gst_bit_reader_peek_bits_uint32_unchecked
                                                            (const GstBitReader *reader,
                                                             guint nbits);

Read `nbits` bits into `val` but keep the current position without checking if there are enough bits available in the bit reader

`reader` : | a GstBitReader instance
`nbits` : | number of bits to read
Returns : | unsigned 32 bit integer with the bits.

Since 0.10.31

### gst_bit_reader_peek_bits_uint64_unchecked ()

    guint64             gst_bit_reader_peek_bits_uint64_unchecked
                                                            (const GstBitReader *reader,
                                                             guint nbits);

### gst_bit_reader_peek_bits_uint8_unchecked ()

    guint8              gst_bit_reader_peek_bits_uint8_unchecked
                                                            (const GstBitReader *reader,
                                                             guint nbits);

Read `nbits` bits into `val` but keep the current position without checking if there are enough bits available in the bit reader

`reader` : | a GstBitReader instance
`nbits` : | number of bits to read
Returns : | unsigned 8 bit integer with the bits.

Since 0.10.31