Chris@69: /* Copyright (c) 2001-2011 Timothy B. Terriberry Chris@69: Copyright (c) 2008-2009 Xiph.Org Foundation */ Chris@69: /* Chris@69: Redistribution and use in source and binary forms, with or without Chris@69: modification, are permitted provided that the following conditions Chris@69: are met: Chris@69: Chris@69: - Redistributions of source code must retain the above copyright Chris@69: notice, this list of conditions and the following disclaimer. Chris@69: Chris@69: - Redistributions in binary form must reproduce the above copyright Chris@69: notice, this list of conditions and the following disclaimer in the Chris@69: documentation and/or other materials provided with the distribution. Chris@69: Chris@69: THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS Chris@69: ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT Chris@69: LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR Chris@69: A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER Chris@69: OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, Chris@69: EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, Chris@69: PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR Chris@69: PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF Chris@69: LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING Chris@69: NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS Chris@69: SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. Chris@69: */ Chris@69: Chris@69: #if !defined(_entenc_H) Chris@69: # define _entenc_H (1) Chris@69: # include Chris@69: # include "entcode.h" Chris@69: Chris@69: /*Initializes the encoder. Chris@69: _buf: The buffer to store output bytes in. Chris@69: _size: The size of the buffer, in chars.*/ Chris@69: void ec_enc_init(ec_enc *_this,unsigned char *_buf,opus_uint32 _size); Chris@69: /*Encodes a symbol given its frequency information. Chris@69: The frequency information must be discernable by the decoder, assuming it Chris@69: has read only the previous symbols from the stream. Chris@69: It is allowable to change the frequency information, or even the entire Chris@69: source alphabet, so long as the decoder can tell from the context of the Chris@69: previously encoded information that it is supposed to do so as well. Chris@69: _fl: The cumulative frequency of all symbols that come before the one to be Chris@69: encoded. Chris@69: _fh: The cumulative frequency of all symbols up to and including the one to Chris@69: be encoded. Chris@69: Together with _fl, this defines the range [_fl,_fh) in which the Chris@69: decoded value will fall. Chris@69: _ft: The sum of the frequencies of all the symbols*/ Chris@69: void ec_encode(ec_enc *_this,unsigned _fl,unsigned _fh,unsigned _ft); Chris@69: Chris@69: /*Equivalent to ec_encode() with _ft==1<<_bits.*/ Chris@69: void ec_encode_bin(ec_enc *_this,unsigned _fl,unsigned _fh,unsigned _bits); Chris@69: Chris@69: /* Encode a bit that has a 1/(1<<_logp) probability of being a one */ Chris@69: void ec_enc_bit_logp(ec_enc *_this,int _val,unsigned _logp); Chris@69: Chris@69: /*Encodes a symbol given an "inverse" CDF table. Chris@69: _s: The index of the symbol to encode. Chris@69: _icdf: The "inverse" CDF, such that symbol _s falls in the range Chris@69: [_s>0?ft-_icdf[_s-1]:0,ft-_icdf[_s]), where ft=1<<_ftb. Chris@69: The values must be monotonically non-increasing, and the last value Chris@69: must be 0. Chris@69: _ftb: The number of bits of precision in the cumulative distribution.*/ Chris@69: void ec_enc_icdf(ec_enc *_this,int _s,const unsigned char *_icdf,unsigned _ftb); Chris@69: Chris@69: /*Encodes a raw unsigned integer in the stream. Chris@69: _fl: The integer to encode. Chris@69: _ft: The number of integers that can be encoded (one more than the max). Chris@69: This must be at least 2, and no more than 2**32-1.*/ Chris@69: void ec_enc_uint(ec_enc *_this,opus_uint32 _fl,opus_uint32 _ft); Chris@69: Chris@69: /*Encodes a sequence of raw bits in the stream. Chris@69: _fl: The bits to encode. Chris@69: _ftb: The number of bits to encode. Chris@69: This must be between 1 and 25, inclusive.*/ Chris@69: void ec_enc_bits(ec_enc *_this,opus_uint32 _fl,unsigned _ftb); Chris@69: Chris@69: /*Overwrites a few bits at the very start of an existing stream, after they Chris@69: have already been encoded. Chris@69: This makes it possible to have a few flags up front, where it is easy for Chris@69: decoders to access them without parsing the whole stream, even if their Chris@69: values are not determined until late in the encoding process, without having Chris@69: to buffer all the intermediate symbols in the encoder. Chris@69: In order for this to work, at least _nbits bits must have already been Chris@69: encoded using probabilities that are an exact power of two. Chris@69: The encoder can verify the number of encoded bits is sufficient, but cannot Chris@69: check this latter condition. Chris@69: _val: The bits to encode (in the least _nbits significant bits). Chris@69: They will be decoded in order from most-significant to least. Chris@69: _nbits: The number of bits to overwrite. Chris@69: This must be no more than 8.*/ Chris@69: void ec_enc_patch_initial_bits(ec_enc *_this,unsigned _val,unsigned _nbits); Chris@69: Chris@69: /*Compacts the data to fit in the target size. Chris@69: This moves up the raw bits at the end of the current buffer so they are at Chris@69: the end of the new buffer size. Chris@69: The caller must ensure that the amount of data that's already been written Chris@69: will fit in the new size. Chris@69: _size: The number of bytes in the new buffer. Chris@69: This must be large enough to contain the bits already written, and Chris@69: must be no larger than the existing size.*/ Chris@69: void ec_enc_shrink(ec_enc *_this,opus_uint32 _size); Chris@69: Chris@69: /*Indicates that there are no more symbols to encode. Chris@69: All reamining output bytes are flushed to the output buffer. Chris@69: ec_enc_init() must be called before the encoder can be used again.*/ Chris@69: void ec_enc_done(ec_enc *_this); Chris@69: Chris@69: #endif