c830d30d9c449d3066c956e7d8d2ef472e72f916
[speexdsp.git] / libspeex / speex_bits.h
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 /** Maximum size of the bit-stream (for fixed-size allocation) */
44 #define MAX_BYTES_PER_FRAME 2000
45
46 /** Bit-packing data structure representing (part of) a bit-stream. */
47 typedef struct SpeexBits {
48    char *bytes;   /**< "raw" data */
49    int   nbBits;  /**< Total number of bits stored in the stream*/
50    int   bytePtr; /**< Position of the byte "cursor" */
51    int   bitPtr;  /**< Position of the bit "cursor" within the current byte */
52    int   owner;   /**< Does the struct "own" the "raw" buffer (member "bytes") */
53    int   overflow;/**< Set to one if we try to read past the valid data */
54    int   buf_size;/**< Allocated size for buffer */
55 } SpeexBits;
56
57 /** Initializes and allocates resources for a SpeexBits struct */
58 void speex_bits_init(SpeexBits *bits);
59
60 /** Initializes SpeexBits struct using a pre-allocated buffer*/
61 void speex_bits_init_buffer(SpeexBits *bits, void *buff, int buf_size);
62
63 /** 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.*/
64 void speex_bits_destroy(SpeexBits *bits);
65
66 /** Resets bits to initial value (just after initialization, erasing content)*/
67 void speex_bits_reset(SpeexBits *bits);
68
69 /** Rewind the bit-stream to the beginning (ready for read) without erasing the content */
70 void speex_bits_rewind(SpeexBits *bits);
71
72 /** Initializes the bit-stream from the data in an area of memory */
73 void speex_bits_read_from(SpeexBits *bits, char *bytes, int len);
74
75 /** Append bytes to the bit-stream
76  * @param bits Bit-stream to operate on
77  * @param bytes pointer to the bytes what will be appended
78  * @param len Number of bytes of append
79  */
80 void speex_bits_read_whole_bytes(SpeexBits *bits, char *bytes, int len);
81
82 /** Write the content of a bit-stream to an area of memory */
83 int speex_bits_write(SpeexBits *bits, char *bytes, int max_len);
84
85 /** Like speex_bits_write, but writes only the complete bytes in the stream. Also removes the written bytes from the stream */
86 int speex_bits_write_whole_bytes(SpeexBits *bits, char *bytes, int max_len);
87
88 /** Append bits to the bit-stream
89  * @param bits Bit-stream to operate on
90  * @param data Value to append as integer
91  * @param nbBits number of bits to consider in "data"
92  */
93 void speex_bits_pack(SpeexBits *bits, int data, int nbBits);
94
95 /** Interpret the next bits in the bit-stream as a signed integer
96  *
97  * @param bits Bit-stream to operate on
98  * @param nbBits Number of bits to interpret
99  * @return A signed integer represented by the bits read
100  */
101 int speex_bits_unpack_signed(SpeexBits *bits, int nbBits);
102
103 /** Interpret the next bits in the bit-stream as an unsigned integer
104  *
105  * @param bits Bit-stream to operate on
106  * @param nbBits Number of bits to interpret
107  * @return An unsigned integer represented by the bits read
108  */
109 unsigned int speex_bits_unpack_unsigned(SpeexBits *bits, int nbBits);
110
111 /** Returns the number of bytes in the bit-stream, including the last one even if it is not "full"
112  *
113  * @param bits Bit-stream to operate on
114  * @return Number of bytes in the stream
115  */
116 int speex_bits_nbytes(SpeexBits *bits);
117
118 /** Same as speex_bits_unpack_unsigned, but without modifying the cursor position */
119 unsigned int speex_bits_peek_unsigned(SpeexBits *bits, int nbBits);
120
121 /** Get the value of the next bit in the stream, without modifying the
122  * "cursor" position 
123  * 
124  * @param bits Bit-stream to operate on
125  */
126 int speex_bits_peek(SpeexBits *bits);
127
128 /** Advances the position of the "bit cursor" in the stream 
129  *
130  * @param bits Bit-stream to operate on
131  * @param n Number of bits to advance
132  */
133 void speex_bits_advance(SpeexBits *bits, int n);
134
135 /** Returns the number of bits remaining to be read in a stream
136  *
137  * @param bits Bit-stream to operate on
138  */
139 int speex_bits_remaining(SpeexBits *bits);
140
141 #ifdef __cplusplus
142 }
143 #endif
144
145 #endif