speex_bits.h

00001 /* Copyright (C) 2002 Jean-Marc Valin */
00002 /**
00003    @file speex_bits.h
00004    @brief Handles bit packing/unpacking
00005 */
00006 /*
00007    Redistribution and use in source and binary forms, with or without
00008    modification, are permitted provided that the following conditions
00009    are met:
00010    
00011    - Redistributions of source code must retain the above copyright
00012    notice, this list of conditions and the following disclaimer.
00013    
00014    - Redistributions in binary form must reproduce the above copyright
00015    notice, this list of conditions and the following disclaimer in the
00016    documentation and/or other materials provided with the distribution.
00017    
00018    - Neither the name of the Xiph.org Foundation nor the names of its
00019    contributors may be used to endorse or promote products derived from
00020    this software without specific prior written permission.
00021    
00022    THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
00023    ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
00024    LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
00025    A PARTICULAR PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE FOUNDATION OR
00026    CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
00027    EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
00028    PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
00029    PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
00030    LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
00031    NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
00032    SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
00033 
00034 */
00035 
00036 #ifndef BITS_H
00037 #define BITS_H
00038 /** @defgroup SpeexBits SpeexBits: Bit-stream manipulations
00039  *  This is the structure that holds the bit-stream when encoding or decoding
00040  * with Speex. It allows some manipulations as well.
00041  *  @{
00042  */
00043 
00044 #ifdef __cplusplus
00045 extern "C" {
00046 #endif
00047 
00048 /** Bit-packing data structure representing (part of) a bit-stream. */
00049 typedef struct SpeexBits {
00050    char *chars;   /**< "raw" data */
00051    int   nbBits;  /**< Total number of bits stored in the stream*/
00052    int   charPtr; /**< Position of the byte "cursor" */
00053    int   bitPtr;  /**< Position of the bit "cursor" within the current char */
00054    int   owner;   /**< Does the struct "own" the "raw" buffer (member "chars") */
00055    int   overflow;/**< Set to one if we try to read past the valid data */
00056    int   buf_size;/**< Allocated size for buffer */
00057    int   reserved1; /**< Reserved for future use */
00058    void *reserved2; /**< Reserved for future use */
00059 } SpeexBits;
00060 
00061 /** Initializes and allocates resources for a SpeexBits struct */
00062 void speex_bits_init(SpeexBits *bits);
00063 
00064 /** Initializes SpeexBits struct using a pre-allocated buffer*/
00065 void speex_bits_init_buffer(SpeexBits *bits, void *buff, int buf_size);
00066 
00067 /** Sets the bits in a SpeexBits struct to use data from an existing buffer (for decoding without copying data) */
00068 void speex_bits_set_bit_buffer(SpeexBits *bits, void *buff, int buf_size);
00069 
00070 /** 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.*/
00071 void speex_bits_destroy(SpeexBits *bits);
00072 
00073 /** Resets bits to initial value (just after initialization, erasing content)*/
00074 void speex_bits_reset(SpeexBits *bits);
00075 
00076 /** Rewind the bit-stream to the beginning (ready for read) without erasing the content */
00077 void speex_bits_rewind(SpeexBits *bits);
00078 
00079 /** Initializes the bit-stream from the data in an area of memory */
00080 void speex_bits_read_from(SpeexBits *bits, char *bytes, int len);
00081 
00082 /** Append bytes to the bit-stream
00083  * 
00084  * @param bits Bit-stream to operate on
00085  * @param bytes pointer to the bytes what will be appended
00086  * @param len Number of bytes of append
00087  */
00088 void speex_bits_read_whole_bytes(SpeexBits *bits, char *bytes, int len);
00089 
00090 /** Write the content of a bit-stream to an area of memory
00091  * 
00092  * @param bits Bit-stream to operate on
00093  * @param bytes Memory location where to write the bits
00094  * @param max_len Maximum number of bytes to write (i.e. size of the "bytes" buffer)
00095  * @return Number of bytes written to the "bytes" buffer
00096 */
00097 int speex_bits_write(SpeexBits *bits, char *bytes, int max_len);
00098 
00099 /** Like speex_bits_write, but writes only the complete bytes in the stream. Also removes the written bytes from the stream */
00100 int speex_bits_write_whole_bytes(SpeexBits *bits, char *bytes, int max_len);
00101 
00102 /** Append bits to the bit-stream
00103  * @param bits Bit-stream to operate on
00104  * @param data Value to append as integer
00105  * @param nbBits number of bits to consider in "data"
00106  */
00107 void speex_bits_pack(SpeexBits *bits, int data, int nbBits);
00108 
00109 /** Interpret the next bits in the bit-stream as a signed integer
00110  *
00111  * @param bits Bit-stream to operate on
00112  * @param nbBits Number of bits to interpret
00113  * @return A signed integer represented by the bits read
00114  */
00115 int speex_bits_unpack_signed(SpeexBits *bits, int nbBits);
00116 
00117 /** Interpret the next bits in the bit-stream as an unsigned integer
00118  *
00119  * @param bits Bit-stream to operate on
00120  * @param nbBits Number of bits to interpret
00121  * @return An unsigned integer represented by the bits read
00122  */
00123 unsigned int speex_bits_unpack_unsigned(SpeexBits *bits, int nbBits);
00124 
00125 /** Returns the number of bytes in the bit-stream, including the last one even if it is not "full"
00126  *
00127  * @param bits Bit-stream to operate on
00128  * @return Number of bytes in the stream
00129  */
00130 int speex_bits_nbytes(SpeexBits *bits);
00131 
00132 /** Same as speex_bits_unpack_unsigned, but without modifying the cursor position 
00133  * 
00134  * @param bits Bit-stream to operate on
00135  * @param nbBits Number of bits to look for
00136  * @return Value of the bits peeked, interpreted as unsigned
00137  */
00138 unsigned int speex_bits_peek_unsigned(SpeexBits *bits, int nbBits);
00139 
00140 /** Get the value of the next bit in the stream, without modifying the
00141  * "cursor" position 
00142  * 
00143  * @param bits Bit-stream to operate on
00144  * @return Value of the bit peeked (one bit only)
00145  */
00146 int speex_bits_peek(SpeexBits *bits);
00147 
00148 /** Advances the position of the "bit cursor" in the stream 
00149  *
00150  * @param bits Bit-stream to operate on
00151  * @param n Number of bits to advance
00152  */
00153 void speex_bits_advance(SpeexBits *bits, int n);
00154 
00155 /** Returns the number of bits remaining to be read in a stream
00156  *
00157  * @param bits Bit-stream to operate on
00158  * @return Number of bits that can still be read from the stream
00159  */
00160 int speex_bits_remaining(SpeexBits *bits);
00161 
00162 /** Insert a terminator so that the data can be sent as a packet while auto-detecting 
00163  * the number of frames in each packet 
00164  *
00165  * @param bits Bit-stream to operate on
00166  */
00167 void speex_bits_insert_terminator(SpeexBits *bits);
00168 
00169 #ifdef __cplusplus
00170 }
00171 #endif
00172 
00173 /* @} */
00174 #endif