libgpac  0.5.0
Typedefs | Enumerations | Functions
bitstream

BitStream object. More...

Typedefs

typedef struct __tag_bitstream GF_BitStream
 

Enumerations

enum  { GF_BITSTREAM_READ = 0, GF_BITSTREAM_WRITE }
 

Functions

GF_BitStream * gf_bs_new (const char *buffer, u64 size, u32 mode)
 bitstream constructor
 
GF_BitStream * gf_bs_from_file (FILE *f, u32 mode)
 bitstream constructor from file handle
 
void gf_bs_del (GF_BitStream *bs)
 bitstream constructor from file handle
 
u32 gf_bs_read_int (GF_BitStream *bs, u32 nBits)
 integer reading
 
u64 gf_bs_read_long_int (GF_BitStream *bs, u32 nBits)
 large integer reading
 
Float gf_bs_read_float (GF_BitStream *bs)
 float reading
 
Double gf_bs_read_double (GF_BitStream *bs)
 double reading
 
u32 gf_bs_read_data (GF_BitStream *bs, char *data, u32 nbBytes)
 data reading
 
u32 gf_bs_read_u8 (GF_BitStream *bs)
 align char reading
 
u32 gf_bs_read_u16 (GF_BitStream *bs)
 align short reading
 
u32 gf_bs_read_u24 (GF_BitStream *bs)
 align 24-bit integer reading
 
u32 gf_bs_read_u32 (GF_BitStream *bs)
 align integer reading
 
u64 gf_bs_read_u64 (GF_BitStream *bs)
 align large integer reading
 
u32 gf_bs_read_u32_le (GF_BitStream *bs)
 little endian integer reading
 
u16 gf_bs_read_u16_le (GF_BitStream *bs)
 little endian integer reading
 
u32 gf_bs_read_vluimsbf5 (GF_BitStream *bs)
 variable length integer reading
 
u32 gf_bs_get_bit_offset (GF_BitStream *bs)
 bit position
 
u32 gf_bs_get_bit_position (GF_BitStream *bs)
 current bit position
 
void gf_bs_write_int (GF_BitStream *bs, s32 value, s32 nBits)
 integer writing
 
void gf_bs_write_long_int (GF_BitStream *bs, s64 value, s32 nBits)
 large integer writing
 
void gf_bs_write_float (GF_BitStream *bs, Float value)
 float writing
 
void gf_bs_write_double (GF_BitStream *bs, Double value)
 double writing
 
u32 gf_bs_write_data (GF_BitStream *bs, const char *data, u32 nbBytes)
 data writing
 
void gf_bs_write_u8 (GF_BitStream *bs, u32 value)
 align char writing
 
void gf_bs_write_u16 (GF_BitStream *bs, u32 value)
 align short writing
 
void gf_bs_write_u24 (GF_BitStream *bs, u32 value)
 align 24-bits integer writing
 
void gf_bs_write_u32 (GF_BitStream *bs, u32 value)
 align integer writing
 
void gf_bs_write_u64 (GF_BitStream *bs, u64 value)
 align large integer writing
 
void gf_bs_write_u32_le (GF_BitStream *bs, u32 value)
 little endian integer writing
 
void gf_bs_write_u16_le (GF_BitStream *bs, u32 value)
 little endian short writing
 
u32 gf_bs_write_byte (GF_BitStream *bs, u8 byte, u32 count)
 write byte multiple times
 
void gf_bs_set_eos_callback (GF_BitStream *bs, void(*EndOfStream)(void *par), void *par)
 end of bitstream management
 
u8 gf_bs_align (GF_BitStream *bs)
 bitstream alignment
 
u64 gf_bs_available (GF_BitStream *bs)
 capacity query
 
void gf_bs_get_content (GF_BitStream *bs, char **output, u32 *outSize)
 buffer fetching
 
void gf_bs_skip_bytes (GF_BitStream *bs, u64 nbBytes)
 byte skipping
 
GF_Err gf_bs_seek (GF_BitStream *bs, u64 offset)
 bitstream seeking
 
void gf_bs_truncate (GF_BitStream *bs)
 bitstream truncation
 
u32 gf_bs_peek_bits (GF_BitStream *bs, u32 numBits, u32 byte_offset)
 bit peeking
 
u8 gf_bs_bits_available (GF_BitStream *bs)
 bit reservoir query
 
u64 gf_bs_get_position (GF_BitStream *bs)
 position query
 
u64 gf_bs_get_size (GF_BitStream *bs)
 size query
 
u64 gf_bs_get_refreshed_size (GF_BitStream *bs)
 file-based size query
 

Detailed Description

This section documents the bitstream object of the GPAC framework.

Note
Unless specified, all functions assume Big-Endian ordering of data in the bitstream.

Function Documentation

GF_BitStream* gf_bs_new ( const char *  buffer,
u64  size,
u32  mode 
)

Constructs a bitstream from a buffer (read or write mode)

Parameters
bufferbuffer to read or write. In WRITE mode, this can be NULL to let the bitstream object dynamically allocate memory, in which case the size param is ignored.
sizesize of the buffer given.
modeoperation mode for this bitstream: GF_BITSTREAM_READ for read, GF_BITSTREAM_WRITE for write.
Returns
new bitstream object
Note
In write mode on an existing data buffer, data overflow is never signaled but simply ignored, it is the caller responsability to ensure it does not write more than possible.
GF_BitStream* gf_bs_from_file ( FILE *  f,
u32  mode 
)

Creates a bitstream from a file handle.

Parameters
fhandle of the file to use. This handle must be created with binary mode.
modeoperation mode for this bitstream: GF_BITSTREAM_READ for read, GF_BITSTREAM_WRITE for write.
Returns
new bitstream object
Note
- You have to open your file in the appropriated mode:
  • GF_BITSTREAM_READ: bitstream is constructed for reading
  • GF_BITSTREAM_WRITE: bitstream is constructed for writing
- you may use any of these modes for a file with read/write access.
Warning
RESULTS ARE UNEXPECTED IF YOU TOUCH THE FILE WHILE USING THE BITSTREAM.
void gf_bs_del ( GF_BitStream *  bs)

Deletes the bitstream object. If the buffer was created by the bitstream, it is deleted if still present.

u32 gf_bs_read_int ( GF_BitStream *  bs,
u32  nBits 
)

Reads an integer coded on a number of bit.

Parameters
bsthe target bitstream
nBitsthe number of bits to read
Returns
the integer value read.
u64 gf_bs_read_long_int ( GF_BitStream *  bs,
u32  nBits 
)

Reads a large integer coded on a number of bit bigger than 32.

Parameters
bsthe target bitstream
nBitsthe number of bits to read
Returns
the large integer value read.
Float gf_bs_read_float ( GF_BitStream *  bs)

Reads a float coded as IEEE 32 bit format.

Parameters
bsthe target bitstream
Returns
the float value read.
Double gf_bs_read_double ( GF_BitStream *  bs)

Reads a double coded as IEEE 64 bit format.

Parameters
bsthe target bitstream
Returns
the double value read.
u32 gf_bs_read_data ( GF_BitStream *  bs,
char *  data,
u32  nbBytes 
)

Reads a data buffer

Parameters
bsthe target bitstream
datathe data buffer to be filled
nbBytesthe amount of bytes to read
Returns
the number of bytes actually read.
Warning
the data buffer passed must be large enough to hold the desired amount of bytes.
u32 gf_bs_read_u8 ( GF_BitStream *  bs)

Reads an integer coded on 8 bits starting at a byte boundary in the bitstream.

Warning
you must not use this function if the bitstream is not aligned
Parameters
bsthe target bitstream
Returns
the char value read.
u32 gf_bs_read_u16 ( GF_BitStream *  bs)

Reads an integer coded on 16 bits starting at a byte boundary in the bitstream.

Warning
you must not use this function if the bitstream is not aligned
Parameters
bsthe target bitstream
Returns
the short value read.
u32 gf_bs_read_u24 ( GF_BitStream *  bs)

Reads an integer coded on 24 bits starting at a byte boundary in the bitstream.

Warning
you must not use this function if the bitstream is not aligned
Parameters
bsthe target bitstream
Returns
the integer value read.
u32 gf_bs_read_u32 ( GF_BitStream *  bs)

Reads an integer coded on 32 bits starting at a byte boundary in the bitstream.

Warning
you must not use this function if the bitstream is not aligned
Parameters
bsthe target bitstream
Returns
the integer value read.
u64 gf_bs_read_u64 ( GF_BitStream *  bs)

Reads an integer coded on 64 bits starting at a byte boundary in the bitstream.

Warning
you must not use this function if the bitstream is not aligned
Parameters
bsthe target bitstream
Returns
the large integer value read.
u32 gf_bs_read_u32_le ( GF_BitStream *  bs)

Reads an integer coded on 32 bits in little-endian order.

Parameters
bsthe target bitstream
Returns
the integer value read.
u16 gf_bs_read_u16_le ( GF_BitStream *  bs)

Reads an integer coded on 16 bits in little-endian order.

Parameters
bsthe target bitstream
Returns
the integer value read.
u32 gf_bs_read_vluimsbf5 ( GF_BitStream *  bs)

Reads an integer coded on a variable number of 4-bits chunks. The number of chunks is given by the number of non-0 bits at the begining.

Parameters
bsthe target bitstream
Returns
the integer value read.
u32 gf_bs_get_bit_offset ( GF_BitStream *  bs)

Returns current bit position in the bitstream - only works in memory mode.

Parameters
bsthe target bitstream
Returns
the integer value read.
u32 gf_bs_get_bit_position ( GF_BitStream *  bs)

Returns bit position in the current byte of the bitstream - only works in memory mode.

Parameters
bsthe target bitstream
Returns
the integer value read.
void gf_bs_write_int ( GF_BitStream *  bs,
s32  value,
s32  nBits 
)

Writes an integer on a given number of bits.

Parameters
bsthe target bitstream
valuethe integer to write
nBitsnumber of bits used to code the integer
void gf_bs_write_long_int ( GF_BitStream *  bs,
s64  value,
s32  nBits 
)

Writes an integer on a given number of bits greater than 32.

Parameters
bsthe target bitstream
valuethe large integer to write
nBitsnumber of bits used to code the integer
void gf_bs_write_float ( GF_BitStream *  bs,
Float  value 
)

Writes a float in IEEE 32 bits format.

Parameters
bsthe target bitstream
valuethe float to write
void gf_bs_write_double ( GF_BitStream *  bs,
Double  value 
)

Writes a double in IEEE 64 bits format.

Parameters
bsthe target bitstream
valuethe double to write
u32 gf_bs_write_data ( GF_BitStream *  bs,
const char *  data,
u32  nbBytes 
)

Writes a data buffer.

Parameters
bsthe target bitstream
datathe data to write
nbBytesnumber of data bytes to write
void gf_bs_write_u8 ( GF_BitStream *  bs,
u32  value 
)

Writes an integer on 8 bits starting at a byte boundary in the bitstream.

Warning
you must not use this function if the bitstream is not aligned
Parameters
bsthe target bitstream
valuethe char value to write
void gf_bs_write_u16 ( GF_BitStream *  bs,
u32  value 
)

Writes an integer on 16 bits starting at a byte boundary in the bitstream.

Warning
you must not use this function if the bitstream is not aligned
Parameters
bsthe target bitstream
valuethe short value to write
void gf_bs_write_u24 ( GF_BitStream *  bs,
u32  value 
)

Writes an integer on 24 bits starting at a byte boundary in the bitstream.

Warning
you must not use this function if the bitstream is not aligned
Parameters
bsthe target bitstream
valuethe integer value to write
void gf_bs_write_u32 ( GF_BitStream *  bs,
u32  value 
)

Writes an integer on 32 bits starting at a byte boundary in the bitstream.

Warning
you must not use this function if the bitstream is not aligned
Parameters
bsthe target bitstream
valuethe integer value to write
void gf_bs_write_u64 ( GF_BitStream *  bs,
u64  value 
)

Writes an integer on 64 bits starting at a byte boundary in the bitstream.

Warning
you must not use this function if the bitstream is not aligned
Parameters
bsthe target bitstream
valuethe large integer value to write
void gf_bs_write_u32_le ( GF_BitStream *  bs,
u32  value 
)

Writes an integer on 32 bits in little-endian order.

Parameters
bsthe target bitstream
valuethe integer value to write
void gf_bs_write_u16_le ( GF_BitStream *  bs,
u32  value 
)

Writes an integer on 16 bits in little-endian order.

Parameters
bsthe target bitstream
valuethe short value to write
u32 gf_bs_write_byte ( GF_BitStream *  bs,
u8  byte,
u32  count 
)

Writes a give byte multiple times.

Parameters
bsthe target bitstream
bytethe byte value to write
countthe number of times the byte should be written
Returns
the number of bytes written
void gf_bs_set_eos_callback ( GF_BitStream *  bs,
void(*)(void *par)  EndOfStream,
void *  par 
)

Assigns a notification callback function for end of stream signaling in read mode

Parameters
bsthe target bitstream
EndOfStreamthe notification function to use
paropaque user data passed to the bitstream
u8 gf_bs_align ( GF_BitStream *  bs)

Aligns bitstream to next byte boundary. In write mode, this will write 0 bit values until alignment.

Parameters
bsthe target bitstream
Returns
the number of bits read/written until alignment
u64 gf_bs_available ( GF_BitStream *  bs)

Returns the number of bytes still available in the bitstream in read mode.

Parameters
bsthe target bitstream
Returns
the number of bytes still available in read mode, -1 in write modes.
void gf_bs_get_content ( GF_BitStream *  bs,
char **  output,
u32 *  outSize 
)

Fetches the internal bitstream buffer in write mode. If a buffer was given at the bitstream construction, or if the bitstream is in read mode, this does nothing.

Parameters
bsthe target bitstream
outputaddress of a memory block to be allocated for bitstream data.
outSizeset to the size of the allocated memory block.
Note
It is the user responsability to destroy the allocated buffer Once this function has been called, the internal bitstream buffer is reseted.
void gf_bs_skip_bytes ( GF_BitStream *  bs,
u64  nbBytes 
)
    Skips bytes in the bitstream. In Write mode, this will write the 0 integer value for memory-based bitstreams or seek the stream

for file-based bitstream.

Parameters
bsthe target bitstream
nbBytesthe number of bytes to skip
GF_Err gf_bs_seek ( GF_BitStream *  bs,
u64  offset 
)

*Seeks the bitstream to a given offset after the begining of the stream. This will perform alignment of the bitstream in all modes.

Warning
Results are unpredictable if seeking beyond the bitstream end is performed.
Parameters
bsthe target bitstream
offsetbuffer/file offset to seek to
void gf_bs_truncate ( GF_BitStream *  bs)

*Truncates the bitstream at the current position

Parameters
bsthe target bitstream
u32 gf_bs_peek_bits ( GF_BitStream *  bs,
u32  numBits,
u32  byte_offset 
)

*Peeks a given number of bits (read without moving the position indicator) for read modes only.

Parameters
bsthe target bitstream
numBitsthe number of bits to peek
byte_offsetif set, bitstream is aligned and moved from byte_offset before peeking (byte-aligned picking) otherwise, bitstream is not aligned and bits are peeked from current state
Returns
the integer value read
u8 gf_bs_bits_available ( GF_BitStream *  bs)

Queries the number of bits available in read mode.

Parameters
bsthe target bitstream
Returns
number of available bits if position is in the last byte of the buffer/stream, 8 otherwise
u64 gf_bs_get_position ( GF_BitStream *  bs)

*Returns the reading/writting position in the buffer/file.

Parameters
bsthe target bitstream
Returns
the read/write position of the bitstream
u64 gf_bs_get_size ( GF_BitStream *  bs)

*Returns the size of the associated buffer/file.

Parameters
bsthe target bitstream
Returns
the size of the bitstream
u64 gf_bs_get_refreshed_size ( GF_BitStream *  bs)

*Returns the size of a file-based bitstream and force a seek to end of file. This is used in case the file handle *describes a file being constructed on disk while being read?

Parameters
bsthe target bitstream
Returns
the disk size of the associated file