Doxygen...
[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    This library is free software; you can redistribute it and/or
8    modify it under the terms of the GNU Lesser General Public
9    License as published by the Free Software Foundation; either
10    version 2.1 of the License, or (at your option) any later version.
11    
12    This library is distributed in the hope that it will be useful,
13    but WITHOUT ANY WARRANTY; without even the implied warranty of
14    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
15    Lesser General Public License for more details.
16    
17    You should have received a copy of the GNU Lesser General Public
18    License along with this library; if not, write to the Free Software
19    Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
20
21 */
22
23 #ifndef BITS_H
24 #define BITS_H
25
26 #ifdef __cplusplus
27 extern "C" {
28 #endif
29
30 /** Maximum size of the bit-stream (for fixed-size allocation) */
31 #define MAX_BYTES_PER_FRAME 1000
32
33 /** Bit-packing data structure representing (part of) a bit-stream. */
34 typedef struct SpeexBits {
35    char *bytes; /**< "raw" data */
36    int  nbBits; /**< Total number of bits stored in the stream*/
37    int  bytePtr; /**< Position of the byte "cursor" */
38    int  bitPtr;  /**< Position of the bit "cursor" within the current byte */
39    int  owner; /**< Does the struct "own" the "raw" buffer (member "bytes") */
40 } SpeexBits;
41
42 /** Initializes and allocates resources for a SpeexBits struct */
43 void speex_bits_init(SpeexBits *bits);
44
45 /** Initializes SpeexBits struct using a pre-allocated buffer*/
46 void speex_bits_init_buffer(SpeexBits *bits, void *buff);
47
48 /** Frees all resources assiociated to a SpeexBits struct. Right now this does nothing since no resources are allocated, but this could change in the future.*/
49 void speex_bits_destroy(SpeexBits *bits);
50
51 /** Resets bits to initial value (just after initialization, erasing content)*/
52 void speex_bits_reset(SpeexBits *bits);
53
54 /** Rewind the bit-stream to the beginning (ready for read) without erasing the content */
55 void speex_bits_rewind(SpeexBits *bits);
56
57 /** Initializes the bit-stream from the data in an area of memory */
58 void speex_bits_read_from(SpeexBits *bits, char *bytes, int len);
59
60 /** Append bytes to the bit-stream
61  * @param bits Bit-stream to operate on
62  * @param bytes pointer to the bytes what will be appended
63  * @param len Number of bytes of append
64  */
65 void speex_bits_read_whole_bytes(SpeexBits *bits, char *bytes, int len);
66
67 /** Write the content of a bit-stream to an area of memory */
68 int speex_bits_write(SpeexBits *bits, char *bytes, int max_len);
69
70 /** Like speex_bits_write, but writes only the complete bytes in the stream. Also removes the written bytes from the stream */
71 int speex_bits_write_whole_bytes(SpeexBits *bits, char *bytes, int max_len);
72
73 /** Append bits to the bit-stream
74  * @param bits Bit-stream to operate on
75  * @param data Value to append as integer
76  * @param nbBits number of bits to consider in "data"
77  */
78 void speex_bits_pack(SpeexBits *bits, int data, int nbBits);
79
80 /** Interpret the next bits in the bit-stream as a signed integer
81  *
82  * @param bits Bit-stream to operate on
83  * @param nbBits Number of bits to interpret
84  * @return A signed integer represented by the bits read
85  */
86 int speex_bits_unpack_signed(SpeexBits *bits, int nbBits);
87
88 /** Interpret the next bits in the bit-stream as an unsigned integer
89  *
90  * @param bits Bit-stream to operate on
91  * @param nbBits Number of bits to interpret
92  * @return An unsigned integer represented by the bits read
93  */
94 unsigned int speex_bits_unpack_unsigned(SpeexBits *bits, int nbBits);
95
96 /** Returns the number of bytes in the bit-stream, including the last one even if it is not "full"
97  *
98  * @param bits Bit-stream to operate on
99  * @return Number of bytes in the stream
100  */
101 int speex_bits_nbytes(SpeexBits *bits);
102
103 /** Same as speex_bits_unpack_unsigned, but without modifying the cursor position */
104 unsigned int speex_bits_peek_unsigned(SpeexBits *bits, int nbBits);
105
106 /** Get the value of the next bit in the stream, without modifying the
107  * "cursor" position 
108  * 
109  * @param bits Bit-stream to operate on
110  */
111 int speex_bits_peek(SpeexBits *bits);
112
113 /** Advances the position of the "bit cursor" in the stream 
114  *
115  * @param bits Bit-stream to operate on
116  * @param n Number of bits to advance
117  * */
118 void speex_bits_advance(SpeexBits *bits, int n);
119
120 #ifdef __cplusplus
121 }
122 #endif
123
124 #endif