speex_bits.h 6.5 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174
  1. /* Copyright (C) 2002 Jean-Marc Valin */
  2. /**
  3. @file speex_bits.h
  4. @brief Handles bit packing/unpacking
  5. */
  6. /*
  7. Redistribution and use in source and binary forms, with or without
  8. modification, are permitted provided that the following conditions
  9. are met:
  10. - Redistributions of source code must retain the above copyright
  11. notice, this list of conditions and the following disclaimer.
  12. - Redistributions in binary form must reproduce the above copyright
  13. notice, this list of conditions and the following disclaimer in the
  14. documentation and/or other materials provided with the distribution.
  15. - Neither the name of the Xiph.org Foundation nor the names of its
  16. contributors may be used to endorse or promote products derived from
  17. this software without specific prior written permission.
  18. THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
  19. ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
  20. LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
  21. A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR
  22. CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
  23. EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
  24. PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
  25. PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
  26. LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
  27. NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
  28. SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  29. */
  30. #ifndef BITS_H
  31. #define BITS_H
  32. /** @defgroup SpeexBits SpeexBits: Bit-stream manipulations
  33. * This is the structure that holds the bit-stream when encoding or decoding
  34. * with Speex. It allows some manipulations as well.
  35. * @{
  36. */
  37. #ifdef __cplusplus
  38. extern "C" {
  39. #endif
  40. /** Bit-packing data structure representing (part of) a bit-stream. */
  41. typedef struct SpeexBits {
  42. char *chars; /**< "raw" data */
  43. int nbBits; /**< Total number of bits stored in the stream*/
  44. int charPtr; /**< Position of the byte "cursor" */
  45. int bitPtr; /**< Position of the bit "cursor" within the current char */
  46. int owner; /**< Does the struct "own" the "raw" buffer (member "chars") */
  47. int overflow;/**< Set to one if we try to read past the valid data */
  48. int buf_size;/**< Allocated size for buffer */
  49. int reserved1; /**< Reserved for future use */
  50. void *reserved2; /**< Reserved for future use */
  51. } SpeexBits;
  52. /** Initializes and allocates resources for a SpeexBits struct */
  53. void speex_bits_init(SpeexBits *bits);
  54. /** Initializes SpeexBits struct using a pre-allocated buffer*/
  55. void speex_bits_init_buffer(SpeexBits *bits, void *buff, int buf_size);
  56. /** Sets the bits in a SpeexBits struct to use data from an existing buffer (for decoding without copying data) */
  57. void speex_bits_set_bit_buffer(SpeexBits *bits, void *buff, int buf_size);
  58. /** Frees all resources associated to a SpeexBits struct. Right now this does nothing since no resources are allocated, but this could change in the future.*/
  59. void speex_bits_destroy(SpeexBits *bits);
  60. /** Resets bits to initial value (just after initialization, erasing content)*/
  61. void speex_bits_reset(SpeexBits *bits);
  62. /** Rewind the bit-stream to the beginning (ready for read) without erasing the content */
  63. void speex_bits_rewind(SpeexBits *bits);
  64. /** Initializes the bit-stream from the data in an area of memory */
  65. void speex_bits_read_from(SpeexBits *bits, char *bytes, int len);
  66. /** Append bytes to the bit-stream
  67. *
  68. * @param bits Bit-stream to operate on
  69. * @param bytes pointer to the bytes what will be appended
  70. * @param len Number of bytes of append
  71. */
  72. void speex_bits_read_whole_bytes(SpeexBits *bits, char *bytes, int len);
  73. /** Write the content of a bit-stream to an area of memory
  74. *
  75. * @param bits Bit-stream to operate on
  76. * @param bytes Memory location where to write the bits
  77. * @param max_len Maximum number of bytes to write (i.e. size of the "bytes" buffer)
  78. * @return Number of bytes written to the "bytes" buffer
  79. */
  80. int speex_bits_write(SpeexBits *bits, char *bytes, int max_len);
  81. /** Like speex_bits_write, but writes only the complete bytes in the stream. Also removes the written bytes from the stream */
  82. int speex_bits_write_whole_bytes(SpeexBits *bits, char *bytes, int max_len);
  83. /** Append bits to the bit-stream
  84. * @param bits Bit-stream to operate on
  85. * @param data Value to append as integer
  86. * @param nbBits number of bits to consider in "data"
  87. */
  88. void speex_bits_pack(SpeexBits *bits, int data, int nbBits);
  89. /** Interpret the next bits in the bit-stream as a signed integer
  90. *
  91. * @param bits Bit-stream to operate on
  92. * @param nbBits Number of bits to interpret
  93. * @return A signed integer represented by the bits read
  94. */
  95. int speex_bits_unpack_signed(SpeexBits *bits, int nbBits);
  96. /** Interpret the next bits in the bit-stream as an unsigned integer
  97. *
  98. * @param bits Bit-stream to operate on
  99. * @param nbBits Number of bits to interpret
  100. * @return An unsigned integer represented by the bits read
  101. */
  102. unsigned int speex_bits_unpack_unsigned(SpeexBits *bits, int nbBits);
  103. /** Returns the number of bytes in the bit-stream, including the last one even if it is not "full"
  104. *
  105. * @param bits Bit-stream to operate on
  106. * @return Number of bytes in the stream
  107. */
  108. int speex_bits_nbytes(SpeexBits *bits);
  109. /** Same as speex_bits_unpack_unsigned, but without modifying the cursor position
  110. *
  111. * @param bits Bit-stream to operate on
  112. * @param nbBits Number of bits to look for
  113. * @return Value of the bits peeked, interpreted as unsigned
  114. */
  115. unsigned int speex_bits_peek_unsigned(SpeexBits *bits, int nbBits);
  116. /** Get the value of the next bit in the stream, without modifying the
  117. * "cursor" position
  118. *
  119. * @param bits Bit-stream to operate on
  120. * @return Value of the bit peeked (one bit only)
  121. */
  122. int speex_bits_peek(SpeexBits *bits);
  123. /** Advances the position of the "bit cursor" in the stream
  124. *
  125. * @param bits Bit-stream to operate on
  126. * @param n Number of bits to advance
  127. */
  128. void speex_bits_advance(SpeexBits *bits, int n);
  129. /** Returns the number of bits remaining to be read in a stream
  130. *
  131. * @param bits Bit-stream to operate on
  132. * @return Number of bits that can still be read from the stream
  133. */
  134. int speex_bits_remaining(SpeexBits *bits);
  135. /** Insert a terminator so that the data can be sent as a packet while auto-detecting
  136. * the number of frames in each packet
  137. *
  138. * @param bits Bit-stream to operate on
  139. */
  140. void speex_bits_insert_terminator(SpeexBits *bits);
  141. #ifdef __cplusplus
  142. }
  143. #endif
  144. /* @} */
  145. #endif