Adds 3rd clause to CELT license
[opus.git] / celt / entdec.h
1 /* Copyright (c) 2001-2011 Timothy B. Terriberry
2    Copyright (c) 2008-2009 Xiph.Org Foundation */
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 Internet Society, IETF or IETF Trust, nor the
16    names of specific contributors, may be used to endorse or promote
17    products derived from this software without specific prior written
18    permission.
19
20    THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
21    ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
22    LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
23    A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER
24    OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
25    EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
26    PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
27    PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
28    LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
29    NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
30    SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
31 */
32
33 #if !defined(_entdec_H)
34 # define _entdec_H (1)
35 # include <limits.h>
36 # include "entcode.h"
37
38 /*Initializes the decoder.
39   _buf: The input buffer to use.
40   Return: 0 on success, or a negative value on error.*/
41 void ec_dec_init(ec_dec *_this,unsigned char *_buf,opus_uint32 _storage);
42
43 /*Calculates the cumulative frequency for the next symbol.
44   This can then be fed into the probability model to determine what that
45    symbol is, and the additional frequency information required to advance to
46    the next symbol.
47   This function cannot be called more than once without a corresponding call to
48    ec_dec_update(), or decoding will not proceed correctly.
49   _ft: The total frequency of the symbols in the alphabet the next symbol was
50         encoded with.
51   Return: A cumulative frequency representing the encoded symbol.
52           If the cumulative frequency of all the symbols before the one that
53            was encoded was fl, and the cumulative frequency of all the symbols
54            up to and including the one encoded is fh, then the returned value
55            will fall in the range [fl,fh).*/
56 unsigned ec_decode(ec_dec *_this,unsigned _ft);
57
58 /*Equivalent to ec_decode() with _ft==1<<_bits.*/
59 unsigned ec_decode_bin(ec_dec *_this,unsigned _bits);
60
61 /*Advance the decoder past the next symbol using the frequency information the
62    symbol was encoded with.
63   Exactly one call to ec_decode() must have been made so that all necessary
64    intermediate calculations are performed.
65   _fl:  The cumulative frequency of all symbols that come before the symbol
66          decoded.
67   _fh:  The cumulative frequency of all symbols up to and including the symbol
68          decoded.
69         Together with _fl, this defines the range [_fl,_fh) in which the value
70          returned above must fall.
71   _ft:  The total frequency of the symbols in the alphabet the symbol decoded
72          was encoded in.
73         This must be the same as passed to the preceding call to ec_decode().*/
74 void ec_dec_update(ec_dec *_this,unsigned _fl,unsigned _fh,unsigned _ft);
75
76 /* Decode a bit that has a 1/(1<<_logp) probability of being a one */
77 int ec_dec_bit_logp(ec_dec *_this,unsigned _logp);
78
79 /*Decodes a symbol given an "inverse" CDF table.
80   No call to ec_dec_update() is necessary after this call.
81   _icdf: The "inverse" CDF, such that symbol s falls in the range
82           [s>0?ft-_icdf[s-1]:0,ft-_icdf[s]), where ft=1<<_ftb.
83          The values must be monotonically non-increasing, and the last value
84           must be 0.
85   _ftb: The number of bits of precision in the cumulative distribution.
86   Return: The decoded symbol s.*/
87 int ec_dec_icdf(ec_dec *_this,const unsigned char *_icdf,unsigned _ftb);
88
89 /*Extracts a raw unsigned integer with a non-power-of-2 range from the stream.
90   The bits must have been encoded with ec_enc_uint().
91   No call to ec_dec_update() is necessary after this call.
92   _ft: The number of integers that can be decoded (one more than the max).
93        This must be at least one, and no more than 2**32-1.
94   Return: The decoded bits.*/
95 opus_uint32 ec_dec_uint(ec_dec *_this,opus_uint32 _ft);
96
97 /*Extracts a sequence of raw bits from the stream.
98   The bits must have been encoded with ec_enc_bits().
99   No call to ec_dec_update() is necessary after this call.
100   _ftb: The number of bits to extract.
101         This must be between 0 and 25, inclusive.
102   Return: The decoded bits.*/
103 opus_uint32 ec_dec_bits(ec_dec *_this,unsigned _ftb);
104
105 #endif