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