--- /dev/null
+/*\r
+ * GPAC - Multimedia Framework C SDK\r
+ *\r
+ * Copyright (c) Jean Le Feuvre 2000-2005 \r
+ * All rights reserved\r
+ *\r
+ * This file is part of GPAC / common tools sub-project\r
+ *\r
+ * GPAC is free software; you can redistribute it and/or modify\r
+ * it under the terms of the GNU Lesser General Public License as published by\r
+ * the Free Software Foundation; either version 2, or (at your option)\r
+ * any later version.\r
+ * \r
+ * GPAC is distributed in the hope that it will be useful,\r
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of\r
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the\r
+ * GNU Lesser General Public License for more details.\r
+ * \r
+ * You should have received a copy of the GNU Lesser General Public\r
+ * License along with this library; see the file COPYING. If not, write to\r
+ * the Free Software Foundation, 675 Mass Ave, Cambridge, MA 02139, USA. \r
+ *\r
+ */\r
+\r
+#ifndef _GF_BITSTREAM_H_\r
+#define _GF_BITSTREAM_H_\r
+\r
+#ifdef __cplusplus\r
+extern "C" {\r
+#endif\r
+\r
+/*!\r
+ * \file <gpac/bitstream.h>\r
+ * \brief bitstream functions.\r
+ */\r
+\r
+/*!\r
+ * \addtogroup bs_grp bitstream\r
+ * \ingroup utils_grp\r
+ * \brief BitStream object\r
+ *\r
+ * This section documents the bitstream object of the GPAC framework.\r
+ * \note Unless specified, all functions assume Big-Endian ordering of data in the bitstream.\r
+ * @{\r
+ */\r
+\r
+#include <gpac/tools.h>\r
+\r
+\r
+enum\r
+{\r
+ GF_BITSTREAM_READ = 0,\r
+ GF_BITSTREAM_WRITE,\r
+};\r
+\r
+typedef struct __tag_bitstream GF_BitStream;\r
+\r
+/*!\r
+ * \brief bitstream constructor\r
+ *\r
+ * Constructs a bitstream from a buffer (read or write mode)\r
+ * \param 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.\r
+ * \param size size of the buffer given. \r
+ * \param mode operation mode for this bitstream: GF_BITSTREAM_READ for read, GF_BITSTREAM_WRITE for write.\r
+ * \return new bitstream object\r
+ * \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 \r
+ * does not write more than possible.\r
+ */\r
+GF_BitStream *gf_bs_new(char *buffer, u64 size, u32 mode);\r
+/*!\r
+ * \brief bitstream constructor from file handle\r
+ *\r
+ * Creates a bitstream from a file handle. \r
+ * \param f handle of the file to use. This handle must be created with binary mode.\r
+ * \param mode operation mode for this bitstream: GF_BITSTREAM_READ for read, GF_BITSTREAM_WRITE for write.\r
+ * \return new bitstream object\r
+ * \note - You have to open your file in the appropriated mode:\n\r
+ * - GF_BITSTREAM_READ: bitstream is constructed for reading\n\r
+ * - GF_BITSTREAM_WRITE: bitstream is constructed for writing\n\r
+ * \note - you may use any of these modes for a file with read/write access.\r
+ * \warning RESULTS ARE UNEXPECTED IF YOU TOUCH THE FILE WHILE USING THE BITSTREAM.\r
+ */\r
+GF_BitStream *gf_bs_from_file(FILE *f, u32 mode);\r
+/*!\r
+ * \brief bitstream constructor from file handle\r
+ *\r
+ * Deletes the bitstream object. If the buffer was created by the bitstream, it is deleted if still present.\r
+ */\r
+void gf_bs_del(GF_BitStream *bs);\r
+\r
+/*!\r
+ * \brief integer reading\r
+ *\r
+ * Reads an integer coded on a number of bit.\r
+ * \param bs the target bitstream \r
+ * \param nBits the number of bits to read\r
+ * \return the integer value read.\r
+ */\r
+u32 gf_bs_read_int(GF_BitStream *bs, u32 nBits);\r
+/*!\r
+ * \brief large integer reading\r
+ *\r
+ * Reads a large integer coded on a number of bit bigger than 32.\r
+ * \param bs the target bitstream \r
+ * \param nBits the number of bits to read\r
+ * \return the large integer value read.\r
+ */\r
+u64 gf_bs_read_long_int(GF_BitStream *bs, u32 nBits);\r
+/*!\r
+ * \brief float reading\r
+ *\r
+ * Reads a float coded as IEEE 32 bit format.\r
+ * \param bs the target bitstream \r
+ * \return the float value read.\r
+ */\r
+Float gf_bs_read_float(GF_BitStream *bs);\r
+/*!\r
+ * \brief double reading\r
+ *\r
+ * Reads a double coded as IEEE 64 bit format.\r
+ * \param bs the target bitstream \r
+ * \return the double value read.\r
+ */\r
+Double gf_bs_read_double(GF_BitStream *bs);\r
+/*!\r
+ * \brief data reading\r
+ *\r
+ * Reads a data buffer\r
+ * \param bs the target bitstream \r
+ * \param data the data buffer to be filled\r
+ * \param nbBytes the amount of bytes to read\r
+ * \return the number of bytes actually read.\r
+ * \warning the data buffer passed must be large enough to hold the desired amount of bytes.\r
+ */\r
+u32 gf_bs_read_data(GF_BitStream *bs, char *data, u32 nbBytes);\r
+\r
+/*!\r
+ * \brief align char reading\r
+ *\r
+ * Reads an integer coded on 8 bits starting at a byte boundary in the bitstream.\r
+ * \warning you must not use this function if the bitstream is not aligned\r
+ * \param bs the target bitstream \r
+ * \return the char value read.\r
+ */\r
+u32 gf_bs_read_u8(GF_BitStream *bs);\r
+/*!\r
+ * \brief align short reading\r
+ *\r
+ * Reads an integer coded on 16 bits starting at a byte boundary in the bitstream.\r
+ * \warning you must not use this function if the bitstream is not aligned\r
+ * \param bs the target bitstream \r
+ * \return the short value read.\r
+ */\r
+u32 gf_bs_read_u16(GF_BitStream *bs);\r
+/*!\r
+ * \brief align 24-bit integer reading\r
+ *\r
+ * Reads an integer coded on 24 bits starting at a byte boundary in the bitstream.\r
+ * \warning you must not use this function if the bitstream is not aligned\r
+ * \param bs the target bitstream \r
+ * \return the integer value read.\r
+ */\r
+u32 gf_bs_read_u24(GF_BitStream *bs);\r
+/*!\r
+ * \brief align integer reading\r
+ *\r
+ * Reads an integer coded on 32 bits starting at a byte boundary in the bitstream.\r
+ * \warning you must not use this function if the bitstream is not aligned\r
+ * \param bs the target bitstream \r
+ * \return the integer value read.\r
+ */\r
+u32 gf_bs_read_u32(GF_BitStream *bs);\r
+/*!\r
+ * \brief align large integer reading\r
+ *\r
+ * Reads an integer coded on 64 bits starting at a byte boundary in the bitstream.\r
+ * \warning you must not use this function if the bitstream is not aligned\r
+ * \param bs the target bitstream \r
+ * \return the large integer value read.\r
+ */\r
+u64 gf_bs_read_u64(GF_BitStream *bs);\r
+/*!\r
+ * \brief little endian integer reading\r
+ *\r
+ * Reads an integer coded on 32 bits in little-endian order.\r
+ * \param bs the target bitstream \r
+ * \return the integer value read.\r
+ */\r
+u32 gf_bs_read_u32_le(GF_BitStream *bs);\r
+/*!\r
+ * \brief little endian integer reading\r
+ *\r
+ * Reads an integer coded on 16 bits in little-endian order.\r
+ * \param bs the target bitstream \r
+ * \return the integer value read.\r
+ */\r
+u16 gf_bs_read_u16_le(GF_BitStream *bs);\r
+\r
+\r
+/*!\r
+ * \brief variable length integer reading\r
+ *\r
+ * 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.\r
+ * \param bs the target bitstream \r
+ * \return the integer value read.\r
+ */\r
+u32 gf_bs_read_vluimsbf5(GF_BitStream *bs);\r
+\r
+/*!\r
+ * \brief bit position\r
+ *\r
+ * Returns current bit position in the bitstream - only works in memory mode.\r
+ * \param bs the target bitstream \r
+ * \return the integer value read.\r
+ */\r
+u32 gf_bs_get_bit_offset(GF_BitStream *bs);\r
+\r
+/*!\r
+ * \brief current bit position\r
+ *\r
+ * Returns bit position in the current byte of the bitstream - only works in memory mode.\r
+ * \param bs the target bitstream \r
+ * \return the integer value read.\r
+ */\r
+u32 gf_bs_get_bit_position(GF_BitStream *bs);\r
+\r
+\r
+/*!\r
+ * \brief integer writing\r
+ *\r
+ * Writes an integer on a given number of bits.\r
+ * \param bs the target bitstream \r
+ * \param value the integer to write\r
+ * \param nBits number of bits used to code the integer\r
+ */\r
+void gf_bs_write_int(GF_BitStream *bs, s32 value, s32 nBits);\r
+/*!\r
+ * \brief large integer writing\r
+ *\r
+ * Writes an integer on a given number of bits greater than 32.\r
+ * \param bs the target bitstream \r
+ * \param value the large integer to write\r
+ * \param nBits number of bits used to code the integer\r
+ */\r
+void gf_bs_write_long_int(GF_BitStream *bs, s64 value, s32 nBits);\r
+/*!\r
+ * \brief float writing\r
+ *\r
+ * Writes a float in IEEE 32 bits format.\r
+ * \param bs the target bitstream \r
+ * \param value the float to write\r
+ */\r
+void gf_bs_write_float(GF_BitStream *bs, Float value);\r
+/*!\r
+ * \brief double writing\r
+ *\r
+ * Writes a double in IEEE 64 bits format.\r
+ * \param bs the target bitstream \r
+ * \param value the double to write\r
+ */\r
+void gf_bs_write_double(GF_BitStream *bs, Double value);\r
+/*!\r
+ * \brief data writing\r
+ *\r
+ * Writes a data buffer.\r
+ * \param bs the target bitstream \r
+ * \param data the data to write\r
+ * \param nbBytes number of data bytes to write\r
+ */\r
+u32 gf_bs_write_data(GF_BitStream *bs, char *data, u32 nbBytes);\r
+\r
+/*!\r
+ * \brief align char writing\r
+ *\r
+ * Writes an integer on 8 bits starting at a byte boundary in the bitstream.\r
+ * \warning you must not use this function if the bitstream is not aligned\r
+ * \param bs the target bitstream \r
+ * \param value the char value to write\r
+ */\r
+void gf_bs_write_u8(GF_BitStream *bs, u32 value);\r
+/*!\r
+ * \brief align short writing\r
+ *\r
+ * Writes an integer on 16 bits starting at a byte boundary in the bitstream.\r
+ * \warning you must not use this function if the bitstream is not aligned\r
+ * \param bs the target bitstream \r
+ * \param value the short value to write\r
+ */\r
+void gf_bs_write_u16(GF_BitStream *bs, u32 value);\r
+/*!\r
+ * \brief align 24-bits integer writing\r
+ *\r
+ * Writes an integer on 24 bits starting at a byte boundary in the bitstream.\r
+ * \warning you must not use this function if the bitstream is not aligned\r
+ * \param bs the target bitstream \r
+ * \param value the integer value to write\r
+ */\r
+void gf_bs_write_u24(GF_BitStream *bs, u32 value);\r
+/*!\r
+ * \brief align integer writing\r
+ *\r
+ * Writes an integer on 32 bits starting at a byte boundary in the bitstream.\r
+ * \warning you must not use this function if the bitstream is not aligned\r
+ * \param bs the target bitstream \r
+ * \param value the integer value to write\r
+ */\r
+void gf_bs_write_u32(GF_BitStream *bs, u32 value);\r
+/*!\r
+ * \brief align large integer writing\r
+ *\r
+ * Writes an integer on 64 bits starting at a byte boundary in the bitstream.\r
+ * \warning you must not use this function if the bitstream is not aligned\r
+ * \param bs the target bitstream \r
+ * \param value the large integer value to write\r
+ */\r
+void gf_bs_write_u64(GF_BitStream *bs, u64 value);\r
+/*!\r
+ * \brief little endian integer writing\r
+ *\r
+ * Writes an integer on 32 bits in little-endian order.\r
+ * \param bs the target bitstream\r
+ * \param value the integer value to write\r
+ */\r
+void gf_bs_write_u32_le(GF_BitStream *bs, u32 value);\r
+/*!\r
+ * \brief little endian short writing\r
+ *\r
+ * Writes an integer on 16 bits in little-endian order.\r
+ * \param bs the target bitstream\r
+ * \param value the short value to write\r
+ */\r
+void gf_bs_write_u16_le(GF_BitStream *bs, u32 value);\r
+\r
+/*!\r
+ * \brief end of bitstream management\r
+ *\r
+ * Assigns a notification callback function for end of stream signaling in read mode\r
+ * \param bs the target bitstream\r
+ * \param EndOfStream the notification function to use\r
+ * \param par opaque user data passed to the bitstream\r
+ */\r
+void gf_bs_set_eos_callback(GF_BitStream *bs, void (*EndOfStream)(void *par), void *par);\r
+\r
+/*!\r
+ * \brief bitstream alignment\r
+ *\r
+ * Aligns bitstream to next byte boundary. In write mode, this will write 0 bit values until alignment.\r
+ * \param bs the target bitstream\r
+ * \return the number of bits read/written until alignment\r
+ */\r
+u8 gf_bs_align(GF_BitStream *bs);\r
+/*!\r
+ * \brief capacity query\r
+ *\r
+ * Returns the number of bytes still available in the bitstream in read mode.\r
+ * \param bs the target bitstream\r
+ * \return the number of bytes still available in read mode, -1 in write modes.\r
+ */\r
+u64 gf_bs_available(GF_BitStream *bs);\r
+/*!\r
+ * \brief buffer fetching\r
+ *\r
+ * 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.\r
+ * \param bs the target bitstream\r
+ * \param output address of a memory block to be allocated for bitstream data.\r
+ * \param outSize set to the size of the allocated memory block.\r
+ * \note \r
+ * It is the user responsability to destroy the allocated buffer\r
+ * Once this function has been called, the internal bitstream buffer is reseted.\r
+ */\r
+void gf_bs_get_content(GF_BitStream *bs, char **output, u32 *outSize);\r
+/*!\r
+ * \brief byte skipping\r
+ *\r
+ * Skips bytes in the bitstream. In Write mode, this will write the 0 integer value for memory-based bitstreams or seek the stream\r
+ for file-based bitstream.\r
+ * \param bs the target bitstream\r
+ * \param nbBytes the number of bytes to skip\r
+ */\r
+void gf_bs_skip_bytes(GF_BitStream *bs, u64 nbBytes);\r
+\r
+/*!\r
+ *\brief bitstream seeking\r
+ *\r
+ *Seeks the bitstream to a given offset after the begining of the stream. This will perform alignment of the bitstream in all modes.\r
+ *\warning Results are unpredictable if seeking beyond the bitstream end is performed.\r
+ *\param bs the target bitstream\r
+ *\param offset buffer/file offset to seek to\r
+ */\r
+GF_Err gf_bs_seek(GF_BitStream *bs, u64 offset);\r
+\r
+/*!\r
+ *\brief bit peeking \r
+ *\r
+ *Peeks a given number of bits (read without moving the position indicator) for read modes only.\r
+ *\param bs the target bitstream\r
+ *\param numBits the number of bits to peek\r
+ *\param byte_offset\r
+ * if set, bitstream is aligned and moved from byte_offset before peeking (byte-aligned picking)\r
+ * otherwise, bitstream is not aligned and bits are peeked from current state\r
+ *\return the integer value read\r
+*/\r
+u32 gf_bs_peek_bits(GF_BitStream *bs, u32 numBits, u32 byte_offset);\r
+\r
+/*!\r
+ *\brief bit reservoir query\r
+ *\r
+ * Queries the number of bits available in read mode.\r
+ *\param bs the target bitstream\r
+ *\return number of available bits if position is in the last byte of the buffer/stream, 8 otherwise\r
+ */\r
+u8 gf_bs_bits_available(GF_BitStream *bs);\r
+/*!\r
+ *\brief position query\r
+ *\r
+ *Returns the reading/writting position in the buffer/file.\r
+ *\param bs the target bitstream\r
+ *\return the read/write position of the bitstream\r
+ */\r
+u64 gf_bs_get_position(GF_BitStream *bs);\r
+/*!\r
+ *\brief size query\r
+ *\r
+ *Returns the size of the associated buffer/file.\r
+ *\param bs the target bitstream\r
+ *\return the size of the bitstream\r
+ */\r
+u64 gf_bs_get_size(GF_BitStream *bs);\r
+/*!\r
+ *\brief file-based size query\r
+ *\r
+ *Returns the size of a file-based bitstream and force a seek to end of file. This is used in case the file handle\r
+ *describes a file being constructed on disk while being read?\r
+ *\r
+ *\param bs the target bitstream\r
+ *\return the disk size of the associated file\r
+ */\r
+u64 gf_bs_get_refreshed_size(GF_BitStream *bs);\r
+\r
+\r
+\r
+/*! @} */\r
+\r
+#ifdef __cplusplus\r
+}\r
+#endif\r
+\r
+\r
+#endif /*_GF_BITSTREAM_H_*/\r
+\r
OSDN Git Service
