Implemented "raw bits"
[opus.git] / libcelt / entenc.h
1 /* (C) 2001-2008 Timothy B. Terriberry
2    (C) 2008 Jean-Marc Valin */
3 /*
4    Redistribution and use in source and binary forms, with or without
5    modification, are permitted provided that the following conditions
6    are met:
7
8    - Redistributions of source code must retain the above copyright
9    notice, this list of conditions and the following disclaimer.
10
11    - Redistributions in binary form must reproduce the above copyright
12    notice, this list of conditions and the following disclaimer in the
13    documentation and/or other materials provided with the distribution.
14
15    - Neither the name of the Xiph.org Foundation nor the names of its
16    contributors may be used to endorse or promote products derived from
17    this software without specific prior written permission.
18
19    THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
20    ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
21    LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
22    A PARTICULAR PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE FOUNDATION OR
23    CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
24    EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
25    PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
26    PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
27    LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
28    NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
29    SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
30 */
31
32 #if !defined(_entenc_H)
33 # define _entenc_H (1)
34 # include <stddef.h>
35 # include "entcode.h"
36
37
38
39 typedef struct ec_enc ec_enc;
40
41
42
43 /*The entropy encoder.*/
44 struct ec_enc{
45    /*Buffered output.*/
46    ec_byte_buffer *buf;
47    /*A buffered output symbol, awaiting carry propagation.*/
48    int             rem;
49    /*Number of extra carry propagating symbols.*/
50    size_t          ext;
51    /*The number of values in the current range.*/
52    ec_uint32       rng;
53    /*The low end of the current range (inclusive).*/
54    ec_uint32       low;
55    /*Byte that will be written at the end*/
56    unsigned char   end_byte;
57    /*Number of valid bits in end_byte*/
58    int             end_bits_left;
59    int             nb_end_bits;
60 };
61
62
63 /*Initializes the encoder.
64   _buf: The buffer to store output bytes in.
65         This must have already been initialized for writing and reset.*/
66 void ec_enc_init(ec_enc *_this,ec_byte_buffer *_buf);
67 /*Encodes a symbol given its frequency information.
68   The frequency information must be discernable by the decoder, assuming it
69    has read only the previous symbols from the stream.
70   It is allowable to change the frequency information, or even the entire
71    source alphabet, so long as the decoder can tell from the context of the
72    previously encoded information that it is supposed to do so as well.
73   _fl: The cumulative frequency of all symbols that come before the one to be
74         encoded.
75   _fh: The cumulative frequency of all symbols up to and including the one to
76         be encoded.
77        Together with _fl, this defines the range [_fl,_fh) in which the
78         decoded value will fall.
79   _ft: The sum of the frequencies of all the symbols*/
80 void ec_encode(ec_enc *_this,unsigned _fl,unsigned _fh,unsigned _ft);
81 void ec_encode_bin(ec_enc *_this,unsigned _fl,unsigned _fh,unsigned bits);
82 /*Encodes a sequence of raw bits in the stream.
83   _fl:  The bits to encode.
84   _ftb: The number of bits to encode.
85         This must be at least one, and no more than 32.*/
86 void ec_enc_bits(ec_enc *_this,ec_uint32 _fl,int _ftb);
87 /*Encodes a sequence of raw bits in the stream.
88   _fl:  The bits to encode.
89   _ftb: The number of bits to encode.
90         This must be at least one, and no more than 64.*/
91 void ec_enc_bits64(ec_enc *_this,ec_uint64 _fl,int _ftb);
92 /*Encodes a raw unsigned integer in the stream.
93   _fl: The integer to encode.
94   _ft: The number of integers that can be encoded (one more than the max).
95        This must be at least one, and no more than 2**32-1.*/
96 void ec_enc_uint(ec_enc *_this,ec_uint32 _fl,ec_uint32 _ft);
97 /*Encodes a raw unsigned integer in the stream.
98   _fl: The integer to encode.
99   _ft: The number of integers that can be encoded (one more than the max).
100        This must be at least one, and no more than 2**64-1.*/
101 void ec_enc_uint64(ec_enc *_this,ec_uint64 _fl,ec_uint64 _ft);
102
103 /*Returns the number of bits "used" by the encoded symbols so far.
104   The actual number of bits may be larger, due to rounding to whole bytes, or
105    smaller, due to trailing zeros that can be stripped, so this is not an
106    estimate of the true packet size.
107   This same number can be computed by the decoder, and is suitable for making
108    coding decisions.
109   _b: The number of extra bits of precision to include.
110       At most 16 will be accurate.
111   Return: The number of bits scaled by 2**_b.
112           This will always be slightly larger than the exact value (e.g., all
113            rounding error is in the positive direction).*/
114 long ec_enc_tell(ec_enc *_this,int _b);
115
116 /*Indicates that there are no more symbols to encode.
117   All reamining output bytes are flushed to the output buffer.
118   ec_enc_init() must be called before the encoder can be used again.*/
119 void ec_enc_done(ec_enc *_this);
120
121 #endif