libcelt/entdec.h

   1 /* Copyright (c) 2001-2008 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 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(_entdec_H)
  33 # define _entdec_H (1)
  34 # include <limits.h>
  35 # include "entcode.h"
  36
  37
  38
  39 typedef struct ec_dec ec_dec;
  40
  41
  42
  43 /*The entropy decoder.*/
  44 struct ec_dec{
  45    /*The buffer to decode.*/
  46    ec_byte_buffer *buf;
  47    /*The remainder of a buffered input symbol.*/
  48    int             rem;
  49    /*The number of values in the current range.*/
  50    ec_uint32       rng;
  51    /*The difference between the top of the current range and the input value,
  52       minus one.*/
  53    ec_uint32       dif;
  54    /*Normalization factor.*/
  55    ec_uint32       nrm;
  56    /*Bits that were written at the end.*/
  57    ec_window       end_window;
  58    /*Number of valid bits in end_window.*/
  59    int             nend_bits;
  60    /*The total number of whole bits read.*/
  61    int             nbits_total;
  62    /*Nonzero if an error occurred.*/
  63    int             error;
  64 };
  65
  66
  67 /*Initializes the decoder.
  68   _buf: The input buffer to use.
  69   Return: 0 on success, or a negative value on error.*/
  70 void ec_dec_init(ec_dec *_this,ec_byte_buffer *_buf);
  71 /*Calculates the cumulative frequency for the next symbol.
  72   This can then be fed into the probability model to determine what that
  73    symbol is, and the additional frequency information required to advance to
  74    the next symbol.
  75   This function cannot be called more than once without a corresponding call to
  76    ec_dec_update(), or decoding will not proceed correctly.
  77   _ft: The total frequency of the symbols in the alphabet the next symbol was
  78         encoded with.
  79   Return: A cumulative frequency representing the encoded symbol.
  80           If the cumulative frequency of all the symbols before the one that
  81            was encoded was fl, and the cumulative frequency of all the symbols
  82            up to and including the one encoded is fh, then the returned value
  83            will fall in the range [fl,fh).*/
  84 unsigned ec_decode(ec_dec *_this,unsigned _ft);
  85 unsigned ec_decode_bin(ec_dec *_this,unsigned _bits);
  86
  87 /*Advance the decoder past the next symbol using the frequency information the
  88    symbol was encoded with.
  89   Exactly one call to ec_decode() must have been made so that all necessary
  90    intermediate calculations are performed.
  91   _fl:  The cumulative frequency of all symbols that come before the symbol
  92          decoded.
  93   _fh:  The cumulative frequency of all symbols up to and including the symbol
  94          decoded.
  95         Together with _fl, this defines the range [_fl,_fh) in which the value
  96          returned above must fall.
  97   _ft:  The total frequency of the symbols in the alphabet the symbol decoded
  98          was encoded in.
  99         This must be the same as passed to the preceding call to ec_decode().*/
 100 void ec_dec_update(ec_dec *_this,unsigned _fl,unsigned _fh,
 101  unsigned _ft);
 102 /*Extracts a sequence of raw bits from the stream.
 103   The bits must have been encoded with ec_enc_bits().
 104   No call to ec_dec_update() is necessary after this call.
 105   _ftb: The number of bits to extract.
 106         This must be between 0 and 25, inclusive.
 107   Return: The decoded bits.*/
 108 ec_uint32 ec_dec_bits(ec_dec *_this,unsigned _ftb);
 109 /*Extracts a raw unsigned integer with a non-power-of-2 range from the stream.
 110   The bits must have been encoded with ec_enc_uint().
 111   No call to ec_dec_update() is necessary after this call.
 112   _ft: The number of integers that can be decoded (one more than the max).
 113        This must be at least one, and no more than 2**32-1.
 114   Return: The decoded bits.*/
 115 ec_uint32 ec_dec_uint(ec_dec *_this,ec_uint32 _ft);
 116 /*Decodes a symbol given an "inverse" CDF table.
 117   No call to ec_dec_update() is necessary after this call.
 118   _icdf: The "inverse" CDF, such that symbol s falls in the range
 119           [s>0?ft-_icdf[s-1]:0,ft-_icdf[s]), where ft=1<<_ftb.
 120          The values must be monotonically non-increasing, and the last value
 121           must be 0.
 122   _ftb: The number of bits of precision in the cumulative distribution.
 123   Return: The decoded symbol s.*/
 124 int ec_dec_icdf(ec_dec *_this,const unsigned char *_icdf,unsigned _ftb);
 125
 126 /* Decode a bit that has a _prob/65536 probability of being a one */
 127 int ec_dec_bit_prob(ec_dec *_this,unsigned _prob);
 128
 129 /* Decode a bit that has a 1/(1<<_logp) probability of being a one */
 130 int ec_dec_bit_logp(ec_dec *_this,unsigned _logp);
 131
 132 /*Returns the number of bits "used" by the encoded symbols so far.
 133   This same number can be computed by the encoder, and is suitable for making
 134    coding decisions.
 135   _b: The number of extra bits of precision to include.
 136       At most 16 will be accurate.
 137   Return: The number of bits scaled by 2**_b.
 138           This will always be slightly larger than the exact value (e.g., all
 139            rounding error is in the positive direction).*/
 140 ec_uint32 ec_dec_tell(ec_dec *_this,int _b);
 141
 142 /*Return: A nonzero value if any error has been detected during decoding.*/
 143 int ec_dec_get_error(ec_dec *_this);
 144
 145 #endif