bitstream
[utils]

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
GF_Err	gf_bs_set_output_buffering (GF_BitStream *bs, u32 size)
	sets bitstream write cache size
u32	gf_bs_get_output_buffering (GF_BitStream *bs)
	gets bitstream write cache size
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_u8_until_delimiter (GF_BitStream *bs, u8 delimiter, u8 *out, u32 max_length)
	align char reading until reaching the given value
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
GF_Err	gf_bs_transfer (GF_BitStream *dst, GF_BitStream *src)
	transfer content from source bitstream to destination bitstream

---

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:

	buffer	buffer 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.
	size	size of the buffer given.
	mode	operation 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:

	f	handle of the file to use. This handle must be created with binary mode.
	mode	operation 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.

GF_Err gf_bs_set_output_buffering	(	GF_BitStream *	bs,
		u32	size
	)

Sets the write cache size for file-based bitstreams.

Parameters:

	bs	the target bitstream
	size	size of the write cache in bytes

Returns:

error if any.

u32 gf_bs_get_output_buffering

(

GF_BitStream *

bs

)

Gets the write cache size for file-based bitstreams.

Parameters:

bs

the target bitstream

Returns:

size of the write cache in bytes, 0 if no cache

u32 gf_bs_read_int	(	GF_BitStream *	bs,
		u32	nBits
	)

Reads an integer coded on a number of bit.

Parameters:

	bs	the target bitstream
	nBits	the 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:

	bs	the target bitstream
	nBits	the 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:

bs

the 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:

bs

the target bitstream

Returns:

the double value read.

u32 gf_bs_read_data	(	GF_BitStream *	bs,
		char *	data,
		u32	nbBytes
	)

Reads a data buffer

Parameters:

	bs	the target bitstream
	data	the data buffer to be filled
	nbBytes	the 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:

bs

the target bitstream

Returns:

the char value read.

u32 gf_bs_read_u8_until_delimiter	(	GF_BitStream *	bs,
		u8	delimiter,
		u8 *	out,
		u32	max_length
	)

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

Note:

the bytes read in the bitstream will only be update if the delimiter is found

Parameters:

	bs	the target bitstream
	delimiter	the stop condition
	out	the resulting value
	max_lengh	the maximum length of the output

Returns:

the number of 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:

bs

the 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:

bs

the 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:

bs

the 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:

bs

the 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:

bs

the 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:

bs

the 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:

bs

the 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:

bs

the 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:

bs

the 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:

	bs	the target bitstream
	value	the integer to write
	nBits	number 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:

	bs	the target bitstream
	value	the large integer to write
	nBits	number 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:

	bs	the target bitstream
	value	the float to write

void gf_bs_write_double	(	GF_BitStream *	bs,
		Double	value
	)

Writes a double in IEEE 64 bits format.

Parameters:

	bs	the target bitstream
	value	the double to write

u32 gf_bs_write_data	(	GF_BitStream *	bs,
		const char *	data,
		u32	nbBytes
	)

Writes a data buffer.

Parameters:

	bs	the target bitstream
	data	the data to write
	nbBytes	number 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:

	bs	the target bitstream
	value	the 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:

	bs	the target bitstream
	value	the 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:

	bs	the target bitstream
	value	the 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:

	bs	the target bitstream
	value	the 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:

	bs	the target bitstream
	value	the 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:

	bs	the target bitstream
	value	the 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:

	bs	the target bitstream
	value	the short value to write

u32 gf_bs_write_byte	(	GF_BitStream *	bs,
		u8	byte,
		u32	count
	)

Writes a give byte multiple times.

Parameters:

	bs	the target bitstream
	byte	the byte value to write
	count	the 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:

	bs	the target bitstream
	EndOfStream	the notification function to use
	par	opaque 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:

bs

the 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:

bs

the 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:

	bs	the target bitstream
	output	address of a memory block to be allocated for bitstream data.
	outSize	set 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:

	bs	the target bitstream
	nbBytes	the 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:

	bs	the target bitstream
	offset	buffer/file offset to seek to

void gf_bs_truncate

(

GF_BitStream *

bs

)

Truncates the bitstream at the current position

Parameters:

bs

the 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:

	bs	the target bitstream
	numBits	the number of bits to peek
	byte_offset	if 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:

bs

the 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:

bs

the 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:

bs

the 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:

bs

the target bitstream

Returns:

the disk size of the associated file

GF_Err gf_bs_transfer	(	GF_BitStream *	dst,
		GF_BitStream *	src
	)

Returns the size of the associated buffer/file.

Parameters:

	dst	the target bitstream
	src	the source bitstream. This bitstream is empty after calling teh function

Returns:

error if any