tstools/DtsEdit/src/gpac/bitstream.h

   1 /*\r
   2  *                      GPAC - Multimedia Framework C SDK\r
   3  *\r
   4  *                      Copyright (c) Jean Le Feuvre 2000-2005 \r
   5  *                                      All rights reserved\r
   6  *\r
   7  *  This file is part of GPAC / common tools sub-project\r
   8  *\r
   9  *  GPAC is free software; you can redistribute it and/or modify\r
  10  *  it under the terms of the GNU Lesser General Public License as published by\r
  11  *  the Free Software Foundation; either version 2, or (at your option)\r
  12  *  any later version.\r
  13  *   \r
  14  *  GPAC is distributed in the hope that it will be useful,\r
  15  *  but WITHOUT ANY WARRANTY; without even the implied warranty of\r
  16  *  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the\r
  17  *  GNU Lesser General Public License for more details.\r
  18  *   \r
  19  *  You should have received a copy of the GNU Lesser General Public\r
  20  *  License along with this library; see the file COPYING.  If not, write to\r
  21  *  the Free Software Foundation, 675 Mass Ave, Cambridge, MA 02139, USA. \r
  22  *\r
  23  */\r
  24 \r
  25 #ifndef _GF_BITSTREAM_H_\r
  26 #define _GF_BITSTREAM_H_\r
  27 \r
  28 #ifdef __cplusplus\r
  29 extern "C" {\r
  30 #endif\r
  31 \r
  32 /*!\r
  33  *      \file <gpac/bitstream.h>\r
  34  *      \brief bitstream functions.\r
  35  */\r
  36 \r
  37 /*!\r
  38  *      \addtogroup bs_grp bitstream\r
  39  *      \ingroup utils_grp\r
  40  *      \brief BitStream object\r
  41  *\r
  42  *      This section documents the bitstream object of the GPAC framework.\r
  43  *      \note Unless specified, all functions assume Big-Endian ordering of data in the bitstream.\r
  44  *      @{\r
  45  */\r
  46 \r
  47 #include <gpac/tools.h>\r
  48 \r
  49 \r
  50 enum\r
  51 {\r
  52         GF_BITSTREAM_READ = 0,\r
  53         GF_BITSTREAM_WRITE,\r
  54 };\r
  55 \r
  56 typedef struct __tag_bitstream GF_BitStream;\r
  57 \r
  58 /*!\r
  59  *      \brief bitstream constructor\r
  60  *\r
  61  *      Constructs a bitstream from a buffer (read or write mode)\r
  62  *      \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
  63  *      \param size size of the buffer given. \r
  64  *      \param mode operation mode for this bitstream: GF_BITSTREAM_READ for read, GF_BITSTREAM_WRITE for write.\r
  65  *      \return new bitstream object\r
  66  *      \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
  67  *      does not write more than possible.\r
  68  */\r
  69 GF_BitStream *gf_bs_new(char *buffer, u64 size, u32 mode);\r
  70 /*!\r
  71  *      \brief bitstream constructor from file handle\r
  72  *\r
  73  * Creates a bitstream from a file handle. \r
  74  * \param f handle of the file to use. This handle must be created with binary mode.\r
  75  *      \param mode operation mode for this bitstream: GF_BITSTREAM_READ for read, GF_BITSTREAM_WRITE for write.\r
  76  *      \return new bitstream object\r
  77  *      \note - You have to open your file in the appropriated mode:\n\r
  78  *      - GF_BITSTREAM_READ: bitstream is constructed for reading\n\r
  79  *      - GF_BITSTREAM_WRITE: bitstream is constructed for writing\n\r
  80  *      \note - you may use any of these modes for a file with read/write access.\r
  81  *      \warning RESULTS ARE UNEXPECTED IF YOU TOUCH THE FILE WHILE USING THE BITSTREAM.\r
  82  */\r
  83 GF_BitStream *gf_bs_from_file(FILE *f, u32 mode);\r
  84 /*!\r
  85  *      \brief bitstream constructor from file handle\r
  86  *\r
  87  * Deletes the bitstream object. If the buffer was created by the bitstream, it is deleted if still present.\r
  88  */\r
  89 void gf_bs_del(GF_BitStream *bs);\r
  90 \r
  91 /*!\r
  92  *      \brief integer reading\r
  93  *\r
  94  *      Reads an integer coded on a number of bit.\r
  95  *      \param bs the target bitstream \r
  96  *      \param nBits the number of bits to read\r
  97  *      \return the integer value read.\r
  98  */\r
  99 u32 gf_bs_read_int(GF_BitStream *bs, u32 nBits);\r
 100 /*!\r
 101  *      \brief large integer reading\r
 102  *\r
 103  *      Reads a large integer coded on a number of bit bigger than 32.\r
 104  *      \param bs the target bitstream \r
 105  *      \param nBits the number of bits to read\r
 106  *      \return the large integer value read.\r
 107  */\r
 108 u64 gf_bs_read_long_int(GF_BitStream *bs, u32 nBits);\r
 109 /*!\r
 110  *      \brief float reading\r
 111  *\r
 112  *      Reads a float coded as IEEE 32 bit format.\r
 113  *      \param bs the target bitstream \r
 114  *      \return the float value read.\r
 115  */\r
 116 Float gf_bs_read_float(GF_BitStream *bs);\r
 117 /*!\r
 118  *      \brief double reading\r
 119  *\r
 120  *      Reads a double coded as IEEE 64 bit format.\r
 121  *      \param bs the target bitstream \r
 122  *      \return the double value read.\r
 123  */\r
 124 Double gf_bs_read_double(GF_BitStream *bs);\r
 125 /*!\r
 126  *      \brief data reading\r
 127  *\r
 128  *      Reads a data buffer\r
 129  *      \param bs the target bitstream \r
 130  *      \param data the data buffer to be filled\r
 131  *      \param nbBytes the amount of bytes to read\r
 132  *      \return the number of bytes actually read.\r
 133  *      \warning the data buffer passed must be large enough to hold the desired amount of bytes.\r
 134  */\r
 135 u32 gf_bs_read_data(GF_BitStream *bs, char *data, u32 nbBytes);\r
 136 \r
 137 /*!\r
 138  *      \brief align char reading\r
 139  *\r
 140  *      Reads an integer coded on 8 bits starting at a byte boundary in the bitstream.\r
 141  *      \warning you must not use this function if the bitstream is not aligned\r
 142  *      \param bs the target bitstream \r
 143  *      \return the char value read.\r
 144  */\r
 145 u32 gf_bs_read_u8(GF_BitStream *bs);\r
 146 /*!\r
 147  *      \brief align short reading\r
 148  *\r
 149  *      Reads an integer coded on 16 bits starting at a byte boundary in the bitstream.\r
 150  *      \warning you must not use this function if the bitstream is not aligned\r
 151  *      \param bs the target bitstream \r
 152  *      \return the short value read.\r
 153  */\r
 154 u32 gf_bs_read_u16(GF_BitStream *bs);\r
 155 /*!\r
 156  *      \brief align 24-bit integer reading\r
 157  *\r
 158  *      Reads an integer coded on 24 bits starting at a byte boundary in the bitstream.\r
 159  *      \warning you must not use this function if the bitstream is not aligned\r
 160  *      \param bs the target bitstream \r
 161  *      \return the integer value read.\r
 162  */\r
 163 u32 gf_bs_read_u24(GF_BitStream *bs);\r
 164 /*!\r
 165  *      \brief align integer reading\r
 166  *\r
 167  *      Reads an integer coded on 32 bits starting at a byte boundary in the bitstream.\r
 168  *      \warning you must not use this function if the bitstream is not aligned\r
 169  *      \param bs the target bitstream \r
 170  *      \return the integer value read.\r
 171  */\r
 172 u32 gf_bs_read_u32(GF_BitStream *bs);\r
 173 /*!\r
 174  *      \brief align large integer reading\r
 175  *\r
 176  *      Reads an integer coded on 64 bits starting at a byte boundary in the bitstream.\r
 177  *      \warning you must not use this function if the bitstream is not aligned\r
 178  *      \param bs the target bitstream \r
 179  *      \return the large integer value read.\r
 180  */\r
 181 u64 gf_bs_read_u64(GF_BitStream *bs);\r
 182 /*!\r
 183  *      \brief little endian integer reading\r
 184  *\r
 185  *      Reads an integer coded on 32 bits in little-endian order.\r
 186  *      \param bs the target bitstream \r
 187  *      \return the integer value read.\r
 188  */\r
 189 u32 gf_bs_read_u32_le(GF_BitStream *bs);\r
 190 /*!\r
 191  *      \brief little endian integer reading\r
 192  *\r
 193  *      Reads an integer coded on 16 bits in little-endian order.\r
 194  *      \param bs the target bitstream \r
 195  *      \return the integer value read.\r
 196  */\r
 197 u16 gf_bs_read_u16_le(GF_BitStream *bs);\r
 198 \r
 199 \r
 200 /*!\r
 201  *      \brief variable length integer reading\r
 202  *\r
 203  *      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
 204  *      \param bs the target bitstream \r
 205  *      \return the integer value read.\r
 206  */\r
 207 u32 gf_bs_read_vluimsbf5(GF_BitStream *bs);\r
 208 \r
 209 /*!\r
 210  *      \brief bit position\r
 211  *\r
 212  *      Returns current bit position in the bitstream - only works in memory mode.\r
 213  *      \param bs the target bitstream \r
 214  *      \return the integer value read.\r
 215  */\r
 216 u32 gf_bs_get_bit_offset(GF_BitStream *bs);\r
 217 \r
 218 /*!\r
 219  *      \brief current bit position\r
 220  *\r
 221  *      Returns bit position in the current byte of the bitstream - only works in memory mode.\r
 222  *      \param bs the target bitstream \r
 223  *      \return the integer value read.\r
 224  */\r
 225 u32 gf_bs_get_bit_position(GF_BitStream *bs);\r
 226 \r
 227 \r
 228 /*!\r
 229  *      \brief integer writing\r
 230  *\r
 231  *      Writes an integer on a given number of bits.\r
 232  *      \param bs the target bitstream \r
 233  *      \param value the integer to write\r
 234  *      \param nBits number of bits used to code the integer\r
 235  */\r
 236 void gf_bs_write_int(GF_BitStream *bs, s32 value, s32 nBits);\r
 237 /*!\r
 238  *      \brief large integer writing\r
 239  *\r
 240  *      Writes an integer on a given number of bits greater than 32.\r
 241  *      \param bs the target bitstream \r
 242  *      \param value the large integer to write\r
 243  *      \param nBits number of bits used to code the integer\r
 244  */\r
 245 void gf_bs_write_long_int(GF_BitStream *bs, s64 value, s32 nBits);\r
 246 /*!\r
 247  *      \brief float writing\r
 248  *\r
 249  *      Writes a float in IEEE 32 bits format.\r
 250  *      \param bs the target bitstream \r
 251  *      \param value the float to write\r
 252  */\r
 253 void gf_bs_write_float(GF_BitStream *bs, Float value);\r
 254 /*!\r
 255  *      \brief double writing\r
 256  *\r
 257  *      Writes a double in IEEE 64 bits format.\r
 258  *      \param bs the target bitstream \r
 259  *      \param value the double to write\r
 260  */\r
 261 void gf_bs_write_double(GF_BitStream *bs, Double value);\r
 262 /*!\r
 263  *      \brief data writing\r
 264  *\r
 265  *      Writes a data buffer.\r
 266  *      \param bs the target bitstream \r
 267  *      \param data the data to write\r
 268  *      \param nbBytes number of data bytes to write\r
 269  */\r
 270 u32 gf_bs_write_data(GF_BitStream *bs, char *data, u32 nbBytes);\r
 271 \r
 272 /*!\r
 273  *      \brief align char writing\r
 274  *\r
 275  *      Writes an integer on 8 bits starting at a byte boundary in the bitstream.\r
 276  *      \warning you must not use this function if the bitstream is not aligned\r
 277  *      \param bs the target bitstream \r
 278  *      \param value the char value to write\r
 279  */\r
 280 void gf_bs_write_u8(GF_BitStream *bs, u32 value);\r
 281 /*!\r
 282  *      \brief align short writing\r
 283  *\r
 284  *      Writes an integer on 16 bits starting at a byte boundary in the bitstream.\r
 285  *      \warning you must not use this function if the bitstream is not aligned\r
 286  *      \param bs the target bitstream \r
 287  *      \param value the short value to write\r
 288  */\r
 289 void gf_bs_write_u16(GF_BitStream *bs, u32 value);\r
 290 /*!\r
 291  *      \brief align 24-bits integer writing\r
 292  *\r
 293  *      Writes an integer on 24 bits starting at a byte boundary in the bitstream.\r
 294  *      \warning you must not use this function if the bitstream is not aligned\r
 295  *      \param bs the target bitstream \r
 296  *      \param value the integer value to write\r
 297  */\r
 298 void gf_bs_write_u24(GF_BitStream *bs, u32 value);\r
 299 /*!\r
 300  *      \brief align integer writing\r
 301  *\r
 302  *      Writes an integer on 32 bits starting at a byte boundary in the bitstream.\r
 303  *      \warning you must not use this function if the bitstream is not aligned\r
 304  *      \param bs the target bitstream \r
 305  *      \param value the integer value to write\r
 306  */\r
 307 void gf_bs_write_u32(GF_BitStream *bs, u32 value);\r
 308 /*!\r
 309  *      \brief align large integer writing\r
 310  *\r
 311  *      Writes an integer on 64 bits starting at a byte boundary in the bitstream.\r
 312  *      \warning you must not use this function if the bitstream is not aligned\r
 313  *      \param bs the target bitstream \r
 314  *      \param value the large integer value to write\r
 315  */\r
 316 void gf_bs_write_u64(GF_BitStream *bs, u64 value);\r
 317 /*!\r
 318  *      \brief little endian integer writing\r
 319  *\r
 320  *      Writes an integer on 32 bits in little-endian order.\r
 321  *      \param bs the target bitstream\r
 322  *      \param value the integer value to write\r
 323  */\r
 324 void gf_bs_write_u32_le(GF_BitStream *bs, u32 value);\r
 325 /*!\r
 326  *      \brief little endian short writing\r
 327  *\r
 328  *      Writes an integer on 16 bits in little-endian order.\r
 329  *      \param bs the target bitstream\r
 330  *      \param value the short value to write\r
 331  */\r
 332 void gf_bs_write_u16_le(GF_BitStream *bs, u32 value);\r
 333 \r
 334 /*!\r
 335  *      \brief end of bitstream management\r
 336  *\r
 337  *      Assigns a notification callback function for end of stream signaling in read mode\r
 338  *      \param bs the target bitstream\r
 339  *      \param EndOfStream the notification function to use\r
 340  *      \param par opaque user data passed to the bitstream\r
 341  */\r
 342 void gf_bs_set_eos_callback(GF_BitStream *bs, void (*EndOfStream)(void *par), void *par);\r
 343 \r
 344 /*!\r
 345  *      \brief bitstream alignment\r
 346  *\r
 347  *      Aligns bitstream to next byte boundary. In write mode, this will write 0 bit values until alignment.\r
 348  *      \param bs the target bitstream\r
 349  *      \return the number of bits read/written until alignment\r
 350  */\r
 351 u8 gf_bs_align(GF_BitStream *bs);\r
 352 /*!\r
 353  *      \brief capacity query\r
 354  *\r
 355  *      Returns the number of bytes still available in the bitstream in read mode.\r
 356  *      \param bs the target bitstream\r
 357  *      \return the number of bytes still available in read mode, -1 in write modes.\r
 358  */\r
 359 u64 gf_bs_available(GF_BitStream *bs);\r
 360 /*!\r
 361  *      \brief buffer fetching\r
 362  *\r
 363  *      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
 364  *      \param bs the target bitstream\r
 365  *      \param output address of a memory block to be allocated for bitstream data.\r
 366  *      \param outSize set to the size of the allocated memory block.\r
 367  *      \note \r
 368         * It is the user responsability to destroy the allocated buffer\r
 369         * Once this function has been called, the internal bitstream buffer is reseted.\r
 370  */\r
 371 void gf_bs_get_content(GF_BitStream *bs, char **output, u32 *outSize);\r
 372 /*!\r
 373  *      \brief byte skipping\r
 374  *\r
 375  *      Skips bytes in the bitstream. In Write mode, this will write the 0 integer value for memory-based bitstreams or seek the stream\r
 376  for file-based bitstream.\r
 377  *      \param bs the target bitstream\r
 378  *      \param nbBytes the number of bytes to skip\r
 379  */\r
 380 void gf_bs_skip_bytes(GF_BitStream *bs, u64 nbBytes);\r
 381 \r
 382 /*!\r
 383  *\brief bitstream seeking\r
 384  *\r
 385  *Seeks the bitstream to a given offset after the begining of the stream. This will perform alignment of the bitstream in all modes.\r
 386  *\warning Results are unpredictable if seeking beyond the bitstream end is performed.\r
 387  *\param bs the target bitstream\r
 388  *\param offset buffer/file offset to seek to\r
 389  */\r
 390 GF_Err gf_bs_seek(GF_BitStream *bs, u64 offset);\r
 391 \r
 392 /*!\r
 393  *\brief bit peeking \r
 394  *\r
 395  *Peeks a given number of bits (read without moving the position indicator) for read modes only.\r
 396  *\param bs the target bitstream\r
 397  *\param numBits the number of bits to peek\r
 398  *\param byte_offset\r
 399         * if set, bitstream is aligned and moved from byte_offset before peeking (byte-aligned picking)\r
 400         * otherwise, bitstream is not aligned and bits are peeked from current state\r
 401  *\return the integer value read\r
 402 */\r
 403 u32 gf_bs_peek_bits(GF_BitStream *bs, u32 numBits, u32 byte_offset);\r
 404 \r
 405 /*!\r
 406  *\brief bit reservoir query\r
 407  *\r
 408  * Queries the number of bits available in read mode.\r
 409  *\param bs the target bitstream\r
 410  *\return number of available bits if position is in the last byte of the buffer/stream, 8 otherwise\r
 411  */\r
 412 u8 gf_bs_bits_available(GF_BitStream *bs);\r
 413 /*!\r
 414  *\brief position query\r
 415  *\r
 416  *Returns the reading/writting position in the buffer/file.\r
 417  *\param bs the target bitstream\r
 418  *\return the read/write position of the bitstream\r
 419  */\r
 420 u64 gf_bs_get_position(GF_BitStream *bs);\r
 421 /*!\r
 422  *\brief size query\r
 423  *\r
 424  *Returns the size of the associated buffer/file.\r
 425  *\param bs the target bitstream\r
 426  *\return the size of the bitstream\r
 427  */\r
 428 u64 gf_bs_get_size(GF_BitStream *bs);\r
 429 /*!\r
 430  *\brief file-based size query\r
 431  *\r
 432  *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
 433  *describes a file being constructed on disk while being read?\r
 434  *\r
 435  *\param bs the target bitstream\r
 436  *\return the disk size of the associated file\r
 437  */\r
 438 u64 gf_bs_get_refreshed_size(GF_BitStream *bs);\r
 439 \r
 440 \r
 441 \r
 442 /*! @} */\r
 443 \r
 444 #ifdef __cplusplus\r
 445 }\r
 446 #endif\r
 447 \r
 448 \r
 449 #endif          /*_GF_BITSTREAM_H_*/\r
 450 \r