GStreamer 1.0 Library Reference Manual: GstBitReader

## GstBitReader GstBitReader — Reads any number of bits from a memory buffer |

## Functions

#define | GST_BIT_READER_INIT()
GstBitReader * | gst_bit_reader_new ()
void | gst_bit_reader_free ()
void | gst_bit_reader_init ()
guint | gst_bit_reader_get_pos ()
guint | gst_bit_reader_get_remaining ()
gboolean | gst_bit_reader_set_pos ()
guint | gst_bit_reader_get_size ()
gboolean | gst_bit_reader_skip ()
gboolean | gst_bit_reader_skip_to_byte ()
gboolean | gst_bit_reader_get_bits_uint16 ()
gboolean | gst_bit_reader_get_bits_uint32 ()
gboolean | gst_bit_reader_get_bits_uint64 ()
gboolean | gst_bit_reader_get_bits_uint8 ()
gboolean | gst_bit_reader_peek_bits_uint16 ()
gboolean | gst_bit_reader_peek_bits_uint32 ()
gboolean | gst_bit_reader_peek_bits_uint64 ()
gboolean | gst_bit_reader_peek_bits_uint8 ()
void | gst_bit_reader_skip_unchecked ()
void | gst_bit_reader_skip_to_byte_unchecked ()
guint16 | gst_bit_reader_get_bits_uint16_unchecked ()
guint32 | gst_bit_reader_get_bits_uint32_unchecked ()
guint64 | gst_bit_reader_get_bits_uint64_unchecked ()
guint8 | gst_bit_reader_get_bits_uint8_unchecked ()
guint16 | gst_bit_reader_peek_bits_uint16_unchecked ()
guint32 | gst_bit_reader_peek_bits_uint32_unchecked ()
guint64 | gst_bit_reader_peek_bits_uint64_unchecked ()
guint8 | gst_bit_reader_peek_bits_uint8_unchecked ()

## Types and Values

| GstBitReader

## Includes

    #include <gst/base/gstbitreader.h>

## 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.

## Functions

### 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()`.

#### Parameters

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

### 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

#### Parameters

data | Data from which the GstBitReader should read. | [array length=size]
size | Size of `data` in bytes |

#### Returns

a new GstBitReader instance.

[transfer full]

### gst_bit_reader_free ()

    void
    gst_bit_reader_free (GstBitReader *reader);

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

#### Parameters

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

### 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.

#### Parameters

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

### gst_bit_reader_get_pos ()

    guint
    gst_bit_reader_get_pos (const GstBitReader *reader);

Returns the current position of a GstBitReader instance in bits.

#### Parameters

reader | a GstBitReader instance |

#### Returns

The current position of `reader` in bits.

### gst_bit_reader_get_remaining ()

    guint
    gst_bit_reader_get_remaining (const GstBitReader *reader);

Returns the remaining number of bits of a GstBitReader instance.

#### Parameters

reader | a GstBitReader instance |

#### Returns

The remaining number of bits of `reader` instance.

### 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.

#### Parameters

reader | a GstBitReader instance |
pos | The new position in bits |

#### Returns

`TRUE` if the position could be set successfully, `FALSE` otherwise.

### gst_bit_reader_get_size ()

    guint
    gst_bit_reader_get_size (const GstBitReader *reader);

Returns the total number of bits of a GstBitReader instance.

#### Parameters

reader | a GstBitReader instance |

#### Returns

The total number of bits of `reader` instance.

### gst_bit_reader_skip ()

    gboolean
    gst_bit_reader_skip (GstBitReader *reader,
                         guint nbits);

Skips `nbits` bits of the GstBitReader instance.

#### Parameters

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

#### Returns

`TRUE` if `nbits` bits could be skipped, `FALSE` otherwise.

### gst_bit_reader_skip_to_byte ()

    gboolean
    gst_bit_reader_skip_to_byte (GstBitReader *reader);

Skips until the next byte.

#### Parameters

reader | a GstBitReader instance |

#### Returns

`TRUE` if successful, `FALSE` otherwise.

### 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.

#### Parameters

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.

### 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.

#### Parameters

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.

### 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.

#### Parameters

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.

### 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.

#### Parameters

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.

### 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.

#### Parameters

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.

### 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.

#### Parameters

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.

### 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.

#### Parameters

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.

### 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.

#### Parameters

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.

### 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.

#### Parameters

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

### 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.

#### Parameters

reader | a GstBitReader instance |

### 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.

#### Parameters

reader | a GstBitReader instance |
nbits | number of bits to read |

#### Returns

unsigned 16 bit integer with the bits.

### 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.

#### Parameters

reader | a GstBitReader instance |
nbits | number of bits to read |

#### Returns

unsigned 32 bit integer with the bits.

### 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.

#### Parameters

reader | a GstBitReader instance |
nbits | number of bits to read |

#### Returns

unsigned 64 bit integer with the bits.

### 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.

#### Parameters

reader | a GstBitReader instance |
nbits | number of bits to read |

#### Returns

unsigned 8 bit integer with the bits.

### 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

#### Parameters

reader | a GstBitReader instance |
nbits | number of bits to read |

#### Returns

unsigned 16 bit integer with the bits.

### 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

#### Parameters

reader | a GstBitReader instance |
nbits | number of bits to read |

#### Returns

unsigned 32 bit integer with the bits.

### gst_bit_reader_peek_bits_uint64_unchecked ()

    guint64
    gst_bit_reader_peek_bits_uint64_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

#### Parameters

reader | a GstBitReader instance |
nbits | number of bits to read |

#### Returns

unsigned 64 bit integer with the bits.

### 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

#### Parameters

reader | a GstBitReader instance |
nbits | number of bits to read |

#### Returns

unsigned 8 bit integer with the bits.

## Types and Values

### 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.

#### Members

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