ghost/libentcode/entdec.h

   1 #if !defined(_entdec_H)
   2 # define _entdec_H (1)
   3 # include "entcode.h"
   4
   5
   6
   7 typedef struct ec_dec ec_dec;
   8
   9
  10
  11 /*The entropy decoder.*/
  12 struct ec_dec{
  13    /*The buffer to decode.*/
  14    ec_byte_buffer *buf;
  15    /*The remainder of a buffered input symbol.*/
  16    int             rem;
  17    /*The number of values in the current range.*/
  18    ec_uint32       rng;
  19    /*The difference between the input value and the lowest value in the current
  20       range.*/
  21    ec_uint32       dif;
  22    /*Normalization factor.*/
  23    ec_uint32       nrm;
  24 };
  25
  26
  27 /*Initializes the decoder.
  28   _buf: The input buffer to use.
  29   Return: 0 on success, or a negative value on error.*/
  30 void ec_dec_init(ec_dec *_this,ec_byte_buffer *_buf);
  31 /*Calculates the cumulative frequency for the next symbol.
  32   This can then be fed into the probability model to determine what that
  33    symbol is, and the additional frequency information required to advance to
  34    the next symbol.
  35   This function cannot be called more than once without a corresponding call to
  36    ec_dec_update(), or decoding will not proceed correctly.
  37   _ft: The total frequency of the symbols in the alphabet the next symbol was
  38         encoded with.
  39   Return: A cumulative frequency representing the encoded symbol.
  40           If the cumulative frequency of all the symbols before the one that
  41            was encoded was fl, and the cumulative frequency of all the symbols
  42            up to and including the one encoded is fh, then the returned value
  43            will fall in the range [fl,fh).*/
  44 unsigned ec_decode(ec_dec *_this,unsigned _ft);
  45 /*Advance the decoder past the next symbol using the frequency information the
  46    symbol was encoded with.
  47   Exactly one call to ec_decode() must have been made so that all necessary
  48    intermediate calculations are performed.
  49   _fl:  The cumulative frequency of all symbols that come before the symbol
  50          decoded.
  51   _fh:  The cumulative frequency of all symbols up to and including the symbol
  52          decoded.
  53         Together with _fl, this defines the range [_fl,_fh) in which the value
  54          returned above must fall.
  55   _ft:  The total frequency of the symbols in the alphabet the symbol decoded
  56          was encoded in.
  57         This must be the same as passed to the preceding call to ec_decode().*/
  58 void ec_dec_update(ec_dec *_this,unsigned _fl,unsigned _fh,
  59  unsigned _ft);
  60 /*Extracts a sequence of raw bits from the stream.
  61   The bits must have been encoded with ec_enc_bits().
  62   No call to ec_dec_update() is necessary after this call.
  63   _ftb: The number of bits to extract.
  64         This must be at least one, and no more than 32.
  65   Return: The decoded bits.*/
  66 ec_uint32 ec_dec_bits(ec_dec *_this,int _ftb);
  67 /*Extracts a sequence of raw bits from the stream.
  68   The bits must have been encoded with ec_enc_bits64().
  69   No call to ec_dec_update() is necessary after this call.
  70   _ftb: The number of bits to extract.
  71         This must be at least one, and no more than 64.
  72   Return: The decoded bits.*/
  73 ec_uint64 ec_dec_bits64(ec_dec *_this,int _ftb);
  74 /*Extracts a raw unsigned integer with a non-power-of-2 range from the stream.
  75   The bits must have been encoded with ec_enc_uint().
  76   No call to ec_dec_update() is necessary after this call.
  77   _ft: The number of integers that can be decoded (one more than the max).
  78        This must be at least one, and no more than 2**32-1.
  79   Return: The decoded bits.*/
  80 ec_uint32 ec_dec_uint(ec_dec *_this,ec_uint32 _ft);
  81 /*Extracts a raw unsigned integer with a non-power-of-2 range from the stream.
  82   The bits must have been encoded with ec_enc_uint64().
  83   No call to ec_dec_update() is necessary after this call.
  84   _ft: The number of integers that can be decoded (one more than the max).
  85        This must be at least one, and no more than 2**64-1.
  86   Return: The decoded bits.*/
  87 ec_uint64 ec_dec_uint64(ec_dec *_this,ec_uint64 _ft);
  88
  89 /*Returns the number of bits "used" by the decoded symbols so far.
  90   The actual number of bits may be larger, due to rounding to whole bytes, or
  91    smaller, due to trailing zeros that were be stripped, so this is not an
  92    estimate of the true packet size.
  93   This same number can be computed by the encoder, and is suitable for making
  94    coding decisions.
  95   _b: The number of extra bits of precision to include.
  96       At most 16 will be accurate.
  97   Return: The number of bits scaled by 2**_b.
  98           This will always be slightly larger than the exact value (e.g., all
  99            rounding error is in the positive direction).*/
 100 long ec_dec_tell(ec_dec *_this,int _b);
 101
 102 #endif