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 THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS 16 ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT 17 LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR 18 A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER 19 OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, 20 EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, 21 PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR 22 PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF 23 LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING 24 NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS 25 SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. 26 */ 27 28 #if !defined(_entenc_H) 29 # define _entenc_H (1) 30 # include <stddef.h> 31 # include "entcode.h" 32 33 /*Initializes the encoder. 34 _buf: The buffer to store output bytes in. 35 _size: The size of the buffer, in chars.*/ 36 void ec_enc_init(ec_enc *_this,unsigned char *_buf,opus_uint32 _size); 37 /*Encodes a symbol given its frequency information. 38 The frequency information must be discernable by the decoder, assuming it 39 has read only the previous symbols from the stream. 40 It is allowable to change the frequency information, or even the entire 41 source alphabet, so long as the decoder can tell from the context of the 42 previously encoded information that it is supposed to do so as well. 43 _fl: The cumulative frequency of all symbols that come before the one to be 44 encoded. 45 _fh: The cumulative frequency of all symbols up to and including the one to 46 be encoded. 47 Together with _fl, this defines the range [_fl,_fh) in which the 48 decoded value will fall. 49 _ft: The sum of the frequencies of all the symbols*/ 50 void ec_encode(ec_enc *_this,unsigned _fl,unsigned _fh,unsigned _ft); 51 52 /*Equivalent to ec_encode() with _ft==1<<_bits.*/ 53 void ec_encode_bin(ec_enc *_this,unsigned _fl,unsigned _fh,unsigned _bits); 54 55 /* Encode a bit that has a 1/(1<<_logp) probability of being a one */ 56 void ec_enc_bit_logp(ec_enc *_this,int _val,unsigned _logp); 57 58 /*Encodes a symbol given an "inverse" CDF table. 59 _s: The index of the symbol to encode. 60 _icdf: The "inverse" CDF, such that symbol _s falls in the range 61 [_s>0?ft-_icdf[_s-1]:0,ft-_icdf[_s]), where ft=1<<_ftb. 62 The values must be monotonically non-increasing, and the last value 63 must be 0. 64 _ftb: The number of bits of precision in the cumulative distribution.*/ 65 void ec_enc_icdf(ec_enc *_this,int _s,const unsigned char *_icdf,unsigned _ftb); 66 67 /*Encodes a symbol given an "inverse" CDF table. 68 _s: The index of the symbol to encode. 69 _icdf: The "inverse" CDF, such that symbol _s falls in the range 70 [_s>0?ft-_icdf[_s-1]:0,ft-_icdf[_s]), where ft=1<<_ftb. 71 The values must be monotonically non-increasing, and the last value 72 must be 0. 73 _ftb: The number of bits of precision in the cumulative distribution.*/ 74 void ec_enc_icdf16(ec_enc *_this,int _s,const opus_uint16 *_icdf,unsigned _ftb); 75 76 /*Encodes a raw unsigned integer in the stream. 77 _fl: The integer to encode. 78 _ft: The number of integers that can be encoded (one more than the max). 79 This must be at least 2, and no more than 2**32-1.*/ 80 void ec_enc_uint(ec_enc *_this,opus_uint32 _fl,opus_uint32 _ft); 81 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 between 1 and 25, inclusive.*/ 86 void ec_enc_bits(ec_enc *_this,opus_uint32 _fl,unsigned _ftb); 87 88 /*Overwrites a few bits at the very start of an existing stream, after they 89 have already been encoded. 90 This makes it possible to have a few flags up front, where it is easy for 91 decoders to access them without parsing the whole stream, even if their 92 values are not determined until late in the encoding process, without having 93 to buffer all the intermediate symbols in the encoder. 94 In order for this to work, at least _nbits bits must have already been 95 encoded using probabilities that are an exact power of two. 96 The encoder can verify the number of encoded bits is sufficient, but cannot 97 check this latter condition. 98 _val: The bits to encode (in the least _nbits significant bits). 99 They will be decoded in order from most-significant to least. 100 _nbits: The number of bits to overwrite. 101 This must be no more than 8.*/ 102 void ec_enc_patch_initial_bits(ec_enc *_this,unsigned _val,unsigned _nbits); 103 104 /*Compacts the data to fit in the target size. 105 This moves up the raw bits at the end of the current buffer so they are at 106 the end of the new buffer size. 107 The caller must ensure that the amount of data that's already been written 108 will fit in the new size. 109 _size: The number of bytes in the new buffer. 110 This must be large enough to contain the bits already written, and 111 must be no larger than the existing size.*/ 112 void ec_enc_shrink(ec_enc *_this,opus_uint32 _size); 113 114 /*Indicates that there are no more symbols to encode. 115 All reamining output bytes are flushed to the output buffer. 116 ec_enc_init() must be called before the encoder can be used again.*/ 117 void ec_enc_done(ec_enc *_this); 118 119 #endif 120