134680572440d7894ef8dafce81d8039ed80726a2Torne (Richard Coles)/* Copyright (C) 2002 Jean-Marc Valin */ 234680572440d7894ef8dafce81d8039ed80726a2Torne (Richard Coles)/** 334680572440d7894ef8dafce81d8039ed80726a2Torne (Richard Coles) @file speex_bits.h 434680572440d7894ef8dafce81d8039ed80726a2Torne (Richard Coles) @brief Handles bit packing/unpacking 534680572440d7894ef8dafce81d8039ed80726a2Torne (Richard Coles)*/ 634680572440d7894ef8dafce81d8039ed80726a2Torne (Richard Coles)/* 734680572440d7894ef8dafce81d8039ed80726a2Torne (Richard Coles) Redistribution and use in source and binary forms, with or without 834680572440d7894ef8dafce81d8039ed80726a2Torne (Richard Coles) modification, are permitted provided that the following conditions 934680572440d7894ef8dafce81d8039ed80726a2Torne (Richard Coles) are met: 1034680572440d7894ef8dafce81d8039ed80726a2Torne (Richard Coles) 1134680572440d7894ef8dafce81d8039ed80726a2Torne (Richard Coles) - Redistributions of source code must retain the above copyright 1234680572440d7894ef8dafce81d8039ed80726a2Torne (Richard Coles) notice, this list of conditions and the following disclaimer. 1334680572440d7894ef8dafce81d8039ed80726a2Torne (Richard Coles) 1434680572440d7894ef8dafce81d8039ed80726a2Torne (Richard Coles) - Redistributions in binary form must reproduce the above copyright 1534680572440d7894ef8dafce81d8039ed80726a2Torne (Richard Coles) notice, this list of conditions and the following disclaimer in the 1634680572440d7894ef8dafce81d8039ed80726a2Torne (Richard Coles) documentation and/or other materials provided with the distribution. 1734680572440d7894ef8dafce81d8039ed80726a2Torne (Richard Coles) 1834680572440d7894ef8dafce81d8039ed80726a2Torne (Richard Coles) - Neither the name of the Xiph.org Foundation nor the names of its 1934680572440d7894ef8dafce81d8039ed80726a2Torne (Richard Coles) contributors may be used to endorse or promote products derived from 2034680572440d7894ef8dafce81d8039ed80726a2Torne (Richard Coles) this software without specific prior written permission. 2134680572440d7894ef8dafce81d8039ed80726a2Torne (Richard Coles) 2234680572440d7894ef8dafce81d8039ed80726a2Torne (Richard Coles) THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS 2334680572440d7894ef8dafce81d8039ed80726a2Torne (Richard Coles) ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT 2434680572440d7894ef8dafce81d8039ed80726a2Torne (Richard Coles) LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR 2534680572440d7894ef8dafce81d8039ed80726a2Torne (Richard Coles) A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR 2634680572440d7894ef8dafce81d8039ed80726a2Torne (Richard Coles) CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, 2734680572440d7894ef8dafce81d8039ed80726a2Torne (Richard Coles) EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, 2834680572440d7894ef8dafce81d8039ed80726a2Torne (Richard Coles) PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR 2934680572440d7894ef8dafce81d8039ed80726a2Torne (Richard Coles) PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF 3034680572440d7894ef8dafce81d8039ed80726a2Torne (Richard Coles) LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING 3134680572440d7894ef8dafce81d8039ed80726a2Torne (Richard Coles) NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS 3234680572440d7894ef8dafce81d8039ed80726a2Torne (Richard Coles) SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. 3334680572440d7894ef8dafce81d8039ed80726a2Torne (Richard Coles) 3434680572440d7894ef8dafce81d8039ed80726a2Torne (Richard Coles)*/ 3534680572440d7894ef8dafce81d8039ed80726a2Torne (Richard Coles) 3634680572440d7894ef8dafce81d8039ed80726a2Torne (Richard Coles)#ifndef BITS_H 3734680572440d7894ef8dafce81d8039ed80726a2Torne (Richard Coles)#define BITS_H 3834680572440d7894ef8dafce81d8039ed80726a2Torne (Richard Coles)/** @defgroup SpeexBits SpeexBits: Bit-stream manipulations 3934680572440d7894ef8dafce81d8039ed80726a2Torne (Richard Coles) * This is the structure that holds the bit-stream when encoding or decoding 4034680572440d7894ef8dafce81d8039ed80726a2Torne (Richard Coles) * with Speex. It allows some manipulations as well. 4134680572440d7894ef8dafce81d8039ed80726a2Torne (Richard Coles) * @{ 4234680572440d7894ef8dafce81d8039ed80726a2Torne (Richard Coles) */ 4334680572440d7894ef8dafce81d8039ed80726a2Torne (Richard Coles) 4434680572440d7894ef8dafce81d8039ed80726a2Torne (Richard Coles)#ifdef __cplusplus 4534680572440d7894ef8dafce81d8039ed80726a2Torne (Richard Coles)extern "C" { 4634680572440d7894ef8dafce81d8039ed80726a2Torne (Richard Coles)#endif 4734680572440d7894ef8dafce81d8039ed80726a2Torne (Richard Coles) 4834680572440d7894ef8dafce81d8039ed80726a2Torne (Richard Coles)/** Bit-packing data structure representing (part of) a bit-stream. */ 4934680572440d7894ef8dafce81d8039ed80726a2Torne (Richard Coles)typedef struct SpeexBits { 5034680572440d7894ef8dafce81d8039ed80726a2Torne (Richard Coles) char *chars; /**< "raw" data */ 5134680572440d7894ef8dafce81d8039ed80726a2Torne (Richard Coles) int nbBits; /**< Total number of bits stored in the stream*/ 5234680572440d7894ef8dafce81d8039ed80726a2Torne (Richard Coles) int charPtr; /**< Position of the byte "cursor" */ 5334680572440d7894ef8dafce81d8039ed80726a2Torne (Richard Coles) int bitPtr; /**< Position of the bit "cursor" within the current char */ 5434680572440d7894ef8dafce81d8039ed80726a2Torne (Richard Coles) int owner; /**< Does the struct "own" the "raw" buffer (member "chars") */ 5534680572440d7894ef8dafce81d8039ed80726a2Torne (Richard Coles) int overflow;/**< Set to one if we try to read past the valid data */ 5634680572440d7894ef8dafce81d8039ed80726a2Torne (Richard Coles) int buf_size;/**< Allocated size for buffer */ 5734680572440d7894ef8dafce81d8039ed80726a2Torne (Richard Coles) int reserved1; /**< Reserved for future use */ 5834680572440d7894ef8dafce81d8039ed80726a2Torne (Richard Coles) void *reserved2; /**< Reserved for future use */ 5934680572440d7894ef8dafce81d8039ed80726a2Torne (Richard Coles)} SpeexBits; 6034680572440d7894ef8dafce81d8039ed80726a2Torne (Richard Coles) 6134680572440d7894ef8dafce81d8039ed80726a2Torne (Richard Coles)/** Initializes and allocates resources for a SpeexBits struct */ 6234680572440d7894ef8dafce81d8039ed80726a2Torne (Richard Coles)void speex_bits_init(SpeexBits *bits); 6334680572440d7894ef8dafce81d8039ed80726a2Torne (Richard Coles) 6434680572440d7894ef8dafce81d8039ed80726a2Torne (Richard Coles)/** Initializes SpeexBits struct using a pre-allocated buffer*/ 6534680572440d7894ef8dafce81d8039ed80726a2Torne (Richard Coles)void speex_bits_init_buffer(SpeexBits *bits, void *buff, int buf_size); 6634680572440d7894ef8dafce81d8039ed80726a2Torne (Richard Coles) 6734680572440d7894ef8dafce81d8039ed80726a2Torne (Richard Coles)/** Sets the bits in a SpeexBits struct to use data from an existing buffer (for decoding without copying data) */ 6834680572440d7894ef8dafce81d8039ed80726a2Torne (Richard Coles)void speex_bits_set_bit_buffer(SpeexBits *bits, void *buff, int buf_size); 6934680572440d7894ef8dafce81d8039ed80726a2Torne (Richard Coles) 7034680572440d7894ef8dafce81d8039ed80726a2Torne (Richard Coles)/** 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.*/ 7134680572440d7894ef8dafce81d8039ed80726a2Torne (Richard Coles)void speex_bits_destroy(SpeexBits *bits); 7234680572440d7894ef8dafce81d8039ed80726a2Torne (Richard Coles) 7334680572440d7894ef8dafce81d8039ed80726a2Torne (Richard Coles)/** Resets bits to initial value (just after initialization, erasing content)*/ 7434680572440d7894ef8dafce81d8039ed80726a2Torne (Richard Coles)void speex_bits_reset(SpeexBits *bits); 7534680572440d7894ef8dafce81d8039ed80726a2Torne (Richard Coles) 7634680572440d7894ef8dafce81d8039ed80726a2Torne (Richard Coles)/** Rewind the bit-stream to the beginning (ready for read) without erasing the content */ 7734680572440d7894ef8dafce81d8039ed80726a2Torne (Richard Coles)void speex_bits_rewind(SpeexBits *bits); 7834680572440d7894ef8dafce81d8039ed80726a2Torne (Richard Coles) 7934680572440d7894ef8dafce81d8039ed80726a2Torne (Richard Coles)/** Initializes the bit-stream from the data in an area of memory */ 8034680572440d7894ef8dafce81d8039ed80726a2Torne (Richard Coles)void speex_bits_read_from(SpeexBits *bits, char *bytes, int len); 8134680572440d7894ef8dafce81d8039ed80726a2Torne (Richard Coles) 8234680572440d7894ef8dafce81d8039ed80726a2Torne (Richard Coles)/** Append bytes to the bit-stream 8334680572440d7894ef8dafce81d8039ed80726a2Torne (Richard Coles) * 8434680572440d7894ef8dafce81d8039ed80726a2Torne (Richard Coles) * @param bits Bit-stream to operate on 8534680572440d7894ef8dafce81d8039ed80726a2Torne (Richard Coles) * @param bytes pointer to the bytes what will be appended 8634680572440d7894ef8dafce81d8039ed80726a2Torne (Richard Coles) * @param len Number of bytes of append 8734680572440d7894ef8dafce81d8039ed80726a2Torne (Richard Coles) */ 8834680572440d7894ef8dafce81d8039ed80726a2Torne (Richard Coles)void speex_bits_read_whole_bytes(SpeexBits *bits, char *bytes, int len); 8934680572440d7894ef8dafce81d8039ed80726a2Torne (Richard Coles) 9034680572440d7894ef8dafce81d8039ed80726a2Torne (Richard Coles)/** Write the content of a bit-stream to an area of memory 9134680572440d7894ef8dafce81d8039ed80726a2Torne (Richard Coles) * 9234680572440d7894ef8dafce81d8039ed80726a2Torne (Richard Coles) * @param bits Bit-stream to operate on 9334680572440d7894ef8dafce81d8039ed80726a2Torne (Richard Coles) * @param bytes Memory location where to write the bits 9434680572440d7894ef8dafce81d8039ed80726a2Torne (Richard Coles) * @param max_len Maximum number of bytes to write (i.e. size of the "bytes" buffer) 9534680572440d7894ef8dafce81d8039ed80726a2Torne (Richard Coles) * @return Number of bytes written to the "bytes" buffer 9634680572440d7894ef8dafce81d8039ed80726a2Torne (Richard Coles)*/ 9734680572440d7894ef8dafce81d8039ed80726a2Torne (Richard Coles)int speex_bits_write(SpeexBits *bits, char *bytes, int max_len); 9834680572440d7894ef8dafce81d8039ed80726a2Torne (Richard Coles) 9934680572440d7894ef8dafce81d8039ed80726a2Torne (Richard Coles)/** Like speex_bits_write, but writes only the complete bytes in the stream. Also removes the written bytes from the stream */ 10034680572440d7894ef8dafce81d8039ed80726a2Torne (Richard Coles)int speex_bits_write_whole_bytes(SpeexBits *bits, char *bytes, int max_len); 10134680572440d7894ef8dafce81d8039ed80726a2Torne (Richard Coles) 10234680572440d7894ef8dafce81d8039ed80726a2Torne (Richard Coles)/** Append bits to the bit-stream 10334680572440d7894ef8dafce81d8039ed80726a2Torne (Richard Coles) * @param bits Bit-stream to operate on 10434680572440d7894ef8dafce81d8039ed80726a2Torne (Richard Coles) * @param data Value to append as integer 10534680572440d7894ef8dafce81d8039ed80726a2Torne (Richard Coles) * @param nbBits number of bits to consider in "data" 10634680572440d7894ef8dafce81d8039ed80726a2Torne (Richard Coles) */ 10734680572440d7894ef8dafce81d8039ed80726a2Torne (Richard Coles)void speex_bits_pack(SpeexBits *bits, int data, int nbBits); 10834680572440d7894ef8dafce81d8039ed80726a2Torne (Richard Coles) 10934680572440d7894ef8dafce81d8039ed80726a2Torne (Richard Coles)/** Interpret the next bits in the bit-stream as a signed integer 11034680572440d7894ef8dafce81d8039ed80726a2Torne (Richard Coles) * 11134680572440d7894ef8dafce81d8039ed80726a2Torne (Richard Coles) * @param bits Bit-stream to operate on 11234680572440d7894ef8dafce81d8039ed80726a2Torne (Richard Coles) * @param nbBits Number of bits to interpret 11334680572440d7894ef8dafce81d8039ed80726a2Torne (Richard Coles) * @return A signed integer represented by the bits read 11434680572440d7894ef8dafce81d8039ed80726a2Torne (Richard Coles) */ 11534680572440d7894ef8dafce81d8039ed80726a2Torne (Richard Coles)int speex_bits_unpack_signed(SpeexBits *bits, int nbBits); 11634680572440d7894ef8dafce81d8039ed80726a2Torne (Richard Coles) 11734680572440d7894ef8dafce81d8039ed80726a2Torne (Richard Coles)/** Interpret the next bits in the bit-stream as an unsigned integer 11834680572440d7894ef8dafce81d8039ed80726a2Torne (Richard Coles) * 11934680572440d7894ef8dafce81d8039ed80726a2Torne (Richard Coles) * @param bits Bit-stream to operate on 12034680572440d7894ef8dafce81d8039ed80726a2Torne (Richard Coles) * @param nbBits Number of bits to interpret 12134680572440d7894ef8dafce81d8039ed80726a2Torne (Richard Coles) * @return An unsigned integer represented by the bits read 12234680572440d7894ef8dafce81d8039ed80726a2Torne (Richard Coles) */ 12334680572440d7894ef8dafce81d8039ed80726a2Torne (Richard Coles)unsigned int speex_bits_unpack_unsigned(SpeexBits *bits, int nbBits); 12434680572440d7894ef8dafce81d8039ed80726a2Torne (Richard Coles) 12534680572440d7894ef8dafce81d8039ed80726a2Torne (Richard Coles)/** Returns the number of bytes in the bit-stream, including the last one even if it is not "full" 12634680572440d7894ef8dafce81d8039ed80726a2Torne (Richard Coles) * 12734680572440d7894ef8dafce81d8039ed80726a2Torne (Richard Coles) * @param bits Bit-stream to operate on 12834680572440d7894ef8dafce81d8039ed80726a2Torne (Richard Coles) * @return Number of bytes in the stream 12934680572440d7894ef8dafce81d8039ed80726a2Torne (Richard Coles) */ 13034680572440d7894ef8dafce81d8039ed80726a2Torne (Richard Coles)int speex_bits_nbytes(SpeexBits *bits); 13134680572440d7894ef8dafce81d8039ed80726a2Torne (Richard Coles) 13234680572440d7894ef8dafce81d8039ed80726a2Torne (Richard Coles)/** Same as speex_bits_unpack_unsigned, but without modifying the cursor position 13334680572440d7894ef8dafce81d8039ed80726a2Torne (Richard Coles) * 13434680572440d7894ef8dafce81d8039ed80726a2Torne (Richard Coles) * @param bits Bit-stream to operate on 13534680572440d7894ef8dafce81d8039ed80726a2Torne (Richard Coles) * @param nbBits Number of bits to look for 13634680572440d7894ef8dafce81d8039ed80726a2Torne (Richard Coles) * @return Value of the bits peeked, interpreted as unsigned 13734680572440d7894ef8dafce81d8039ed80726a2Torne (Richard Coles) */ 13834680572440d7894ef8dafce81d8039ed80726a2Torne (Richard Coles)unsigned int speex_bits_peek_unsigned(SpeexBits *bits, int nbBits); 13934680572440d7894ef8dafce81d8039ed80726a2Torne (Richard Coles) 14034680572440d7894ef8dafce81d8039ed80726a2Torne (Richard Coles)/** Get the value of the next bit in the stream, without modifying the 14134680572440d7894ef8dafce81d8039ed80726a2Torne (Richard Coles) * "cursor" position 14234680572440d7894ef8dafce81d8039ed80726a2Torne (Richard Coles) * 14334680572440d7894ef8dafce81d8039ed80726a2Torne (Richard Coles) * @param bits Bit-stream to operate on 14434680572440d7894ef8dafce81d8039ed80726a2Torne (Richard Coles) * @return Value of the bit peeked (one bit only) 14534680572440d7894ef8dafce81d8039ed80726a2Torne (Richard Coles) */ 14634680572440d7894ef8dafce81d8039ed80726a2Torne (Richard Coles)int speex_bits_peek(SpeexBits *bits); 14734680572440d7894ef8dafce81d8039ed80726a2Torne (Richard Coles) 14834680572440d7894ef8dafce81d8039ed80726a2Torne (Richard Coles)/** Advances the position of the "bit cursor" in the stream 14934680572440d7894ef8dafce81d8039ed80726a2Torne (Richard Coles) * 15034680572440d7894ef8dafce81d8039ed80726a2Torne (Richard Coles) * @param bits Bit-stream to operate on 15134680572440d7894ef8dafce81d8039ed80726a2Torne (Richard Coles) * @param n Number of bits to advance 15234680572440d7894ef8dafce81d8039ed80726a2Torne (Richard Coles) */ 15334680572440d7894ef8dafce81d8039ed80726a2Torne (Richard Coles)void speex_bits_advance(SpeexBits *bits, int n); 15434680572440d7894ef8dafce81d8039ed80726a2Torne (Richard Coles) 15534680572440d7894ef8dafce81d8039ed80726a2Torne (Richard Coles)/** Returns the number of bits remaining to be read in a stream 15634680572440d7894ef8dafce81d8039ed80726a2Torne (Richard Coles) * 15734680572440d7894ef8dafce81d8039ed80726a2Torne (Richard Coles) * @param bits Bit-stream to operate on 15834680572440d7894ef8dafce81d8039ed80726a2Torne (Richard Coles) * @return Number of bits that can still be read from the stream 15934680572440d7894ef8dafce81d8039ed80726a2Torne (Richard Coles) */ 16034680572440d7894ef8dafce81d8039ed80726a2Torne (Richard Coles)int speex_bits_remaining(SpeexBits *bits); 16134680572440d7894ef8dafce81d8039ed80726a2Torne (Richard Coles) 16234680572440d7894ef8dafce81d8039ed80726a2Torne (Richard Coles)/** Insert a terminator so that the data can be sent as a packet while auto-detecting 16334680572440d7894ef8dafce81d8039ed80726a2Torne (Richard Coles) * the number of frames in each packet 16434680572440d7894ef8dafce81d8039ed80726a2Torne (Richard Coles) * 16534680572440d7894ef8dafce81d8039ed80726a2Torne (Richard Coles) * @param bits Bit-stream to operate on 16634680572440d7894ef8dafce81d8039ed80726a2Torne (Richard Coles) */ 16734680572440d7894ef8dafce81d8039ed80726a2Torne (Richard Coles)void speex_bits_insert_terminator(SpeexBits *bits); 16834680572440d7894ef8dafce81d8039ed80726a2Torne (Richard Coles) 16934680572440d7894ef8dafce81d8039ed80726a2Torne (Richard Coles)#ifdef __cplusplus 17034680572440d7894ef8dafce81d8039ed80726a2Torne (Richard Coles)} 17134680572440d7894ef8dafce81d8039ed80726a2Torne (Richard Coles)#endif 17234680572440d7894ef8dafce81d8039ed80726a2Torne (Richard Coles) 17334680572440d7894ef8dafce81d8039ed80726a2Torne (Richard Coles)/* @} */ 17434680572440d7894ef8dafce81d8039ed80726a2Torne (Richard Coles)#endif 175