qccentarithmeticencode.3

spiht for linux this is used to decod and encode vedio i wich all enjoy

.TH QCCENTARITHMETICENCODE 3 "QCCPACK" ""
.SH NAME
QccENTArithmeticEncodeStart, QccENTArithmeticEncodeEnd,
QccENTArithmeticEncode, QccENTArithmeticEncodeFlush,
QccENTArithmeticDecodeStart, QccENTArithmeticDecodeRestart,
QccENTArithmeticDecode \- arithmetic encoding and decoding
.SH SYNOPSIS
.B #include "libQccPack.h"
.sp
.BI "QccENTArithmeticModel *QccENTArithmeticEncodeStart(const int *" num_symbols ", int " num_contexts ", QccENTArithmeticGetContext " context_function ", int " target_num_bits );
.br
.BI "int QccENTArithmeticEncodeEnd(QccENTArithmeticModel *" model ", int " final_context ", QccBitBuffer *" output_buffer );
.br
.BI "int QccENTArithmeticEncode(const int *" symbol_stream ", int " symbol_stream_length ", QccENTArithmeticModel *" model ", QccBitBuffer *" output_buffer );
.br
.BI "int QccENTArithmeticEncodeFlush(QccENTArithmeticModel *" model ", QccBitBuffer *" output_buffer );
.br
.BI "QccENTArithmeticModel *QccENTArithmeticDecodeStart(QccBitBuffer *" input_buffer ", const int *" num_symbols ", int " num_contexts ", QccENTArithmeticGetContext " context_function ", int " target_num_bits );
.br
.BI "int QccENTArithmeticDecodeRestart(QccBitBuffer *" input_buffer ", QccENTArithmeticModel *" model ", int " target_num_bits );
.br
.BI "int QccENTArithmeticDecode(QccBitBuffer *" input_buffer ", QccENTArithmeticModel *" model ", int *" symbol_stream ", int " symbol_stream_length );
.SH DESCRIPTION
QccPack provides multiple-context adaptive and nonadaptive arithmetic coding
with an arbitrary number of symbols. For both encoding and decoding,
an arithmetic coding model of type
.BR QccENTArithmeticModel (3)
is allocated. This model contains the probability models for the different
contexts which are, by default, adapted as coding and decoding progresses.
The 
.BR QccENTArithmeticModel (3)
structure can also contain a pointer to a callback function which is
used to obtain the context of the current symbol during encoding
and decoding, and the adaptiveness of the model can be enabled
and disabled via calls to
.BR QccENTArithmeticSetModelAdaption (3).
.LP
In general, in both encoding and decoding, a
.I num_contexts
value is specified at the time of arithmetic-coding model
creation, and this value indicates the number of contexts to be
used for coding and decoding.
.I num_contexts
must be 1 or greater.
Additionally, an array,
.IR num_symbols ,
is also passed at the time of model creation.
.I num_symbols
is an array of
.I num_context
integers which indicates the number of symbols for each context.
Finally, during encoding and decoding, valid symbols for context
.I i
are integers greater than or equal to 0, and less than or equal
.IR num_symbols [ i "] - 1."
The contexts themselves are assumed to be numbered from 0 up to, and including,
.IR num_contexts " - 1."
.SS "Encoding"
.BR QccENTArithmeticEncodeStart()
should be the first function called in the arithmetic-encoding process.
.BR QccENTArithmeticEncodeStart()
allocates a
.BR QccENTArithmeticModel (3)
structure, initializes the probability models for each context in the model,
and returns a pointer to the model.
.I num_contexts
gives the number of contexts for encoding,
.I num_symbols
gives the number of symbols for each context, and
.I context_function
is a pointer to a callback function of type
.BR QccENTArithmeticGetContext (3)
which is called to obtain the current context.
.I context_function
can be the
.B NULL
pointer, in which case the
.I current_context
field of the arithmetic model is used to set the
current context directly by a calling routine.
If
.I target_num_bits
is different from
.BR QCCENT_ANYNUMBITS ,
then the arithmetic coder can be forced to stop outputting bits
when the total number of bits output to the bitstream
(i.e., 
.IR output_buffer -> bit_cnt )
is equal to
.IR target_num_bits .
Note that this is a global stopping point;
i.e., any bits output
before the call to
.BR QccENTArithmeticEncodeStart()
are included when comparing the bits output to
.IR target_num_bits .
For example, when a binary header via calls to functions like
.BR QccBitBufferPutChar (3)
is output before starting the arithmetic coder, these header bits
are included in the total number of bits counted.
If 
.I target_num_bits
is set to
.BR QCCENT_ANYNUMBITS ,
then the arithmetic encoded output can have any number of bits output
and should be explicitly terminated via a call to
.BR QccENTArithmeticEncodeEnd() .
.LP
.BR QccENTArithmeticEncode()
performs arithmetic encoding of the stream of symbols,
.IR symbol_stream ,
which is an array of valid symbols.
.I symbol_stream_length
gives the length of the stream to be encoded, while
.I model
is the pointer to the 
.BR QccENTArithmeticModel
structure previously returned by the call to
.BR QccENTArithmeticEncodeStart() .
Finally,
.I output_buffer
is a pointer to a
.BR QccBitBuffer (3)
structure; this
.I output_buffer
must already be opened for writing via a prior call to
.BR QccBitBufferStart (3).
If
.IR target_num_bits ,
as set during the initial call to
.BR QccENTArithmeticEncodeStart() ,
is not equal to
.BR QCCENT_ANYNUMBITS ,
then
.BR QccENTArithmeticEncode()
will stop outputting bits and return prematurely when
.IR output_buffer -> bit_cnt
is equal to
.IR target_num_bits ,
regardless of whether all symbols in
.I symbol_stream
have been processed or not.
If
.I target_num_bits
is equal to
.BR QCCENT_ANYNUMBITS ,
then
.BR QccENTArithmeticEncode()
will return only when all symbols in
.I symbol_stream
have been processed.
If
.BR QccENTArithmeticEncode()
returns prematurely due to
.I target_num_bits
being output, then
.BR QccENTArithmeticEncode()
returns with a value of 2; otherwise, it returns a 0 on success, or a
1 on failure.
.LP
.BR QccENTArithmeticEncodeEnd()
terminates arithmetic encoding by encoding a special EOF symbol
to the bitstream, and then calling
.BR QccENTArithmeticEncodeFlush() .
.I final_context
is the context that is to be used for the EOF symbol. If the
.I num_contexts
in the arithmetic model is 1 (i.e., single-context coding),
the value of
.I final_context
is ignored.
.LP
.BR QccENTArithmeticEncodeFlush()
flushes the state of the arithmetic encoder.
Usually, after the last symbol is processed by
.BR QccENTArithmeticEncode() ,
there are several bits that remain to be output from the arithmetic encoder.
.BR QccENTArithmeticEncodeFlush()
forces these bits to be output, and then calls
.BR QccBitBufferFlush (3)
to guarantee that the bits are actually written to the output file.
After a call to
.BR QccENTArithmeticEncodeFlush() ,
subsequent bits output will start on the next byte boundary of the
output file; consequently,
one can follow a call to
.BR QccENTArithmeticEncodeFlush()
with a subsequent call to
.BR QccENTArithmeticEncode()
to force encoded "blocks" to be "byte-aligned."
Note: if such byte-alignment is done during encoding, during decoding,
the decoder must be "restart" at the start of each block with a call
to
.BR QccENTArithmeticDecodeRestart()
(see below).
.SS "Decoding"
.BR QccENTArithmeticDecodeStart()
should be the first function called in the arithmetic-decoding process.
For the decoding to make sense, the values of
.IR num_contexts ,
and
.IR num_symbols 
should be the same as used in encoding, and
.I context_function
should be the same function used in encoding.
.I target_num_bits
can be used to force
.BR QccENTArithmeticDecode()
to return prematurely when 
.IR input_buffer -> bit_cnt
meets or exceeds
.IR target_num_bits .
.LP
.BR QccENTArithmeticDecode()
attempts to decode
.I symbol_stream_length
symbols from
.IR input_buffer .
The decoded symbols are placed in the array
.IR symbol_stream
which must be allocated with space sufficient for
.I symbol_stream_length
symbols prior to the call to
.BR QccENTArithmeticDecode() .
If
.I target_num_bits
was not equal to
.B QCCENT_ANYNUMBITS
with the immediately preceding call to
.BR QccENTArithmeticDecodeStart()
or
.BR QccENTArithmeticDecodeRestart() ,
then
.BR QccENTArithmeticDecode()
will return prematurely when the
.IR input_buffer -> bit_cnt
meets or exceeds 
.IR target_num_bits .
That is,
.BR QccENTArithmeticDecode()
will not read past the
.I target_num_bits
bit in the bitstream, even if
.I symbol_stream_length
symbols have not been decoded.
If, on the other hand,
.I target_num_bits
is equal to
.BR QCCENT_ANYNUMBITS ,
.BR QccENTArithmeticDecode()
will return when
.I symbol_stream_length
symbols are decoded.
.BR QccENTArithmeticDecode()
returns 2 if the special EOF 
symbol is encountered while decoding;
1 if the end of the bitstream is reached while decoding;
1 if the
.I target_num_bits
bit limit is reached; or
0 if no error occurs.
.LP
.BR QccENTArithmeticDecodeRestart()
can be used to start the arithmetic decoder on any byte boundary.
That is, if, during encoding,
.BR QccENTArithmeticEncodeFlush()
is used to force byte alignment of "blocks" of bits, then
one can use 
.BR fseek (3)
to position the bitstream to the byte at the start of the block,
and then call
.BR QccENTArithmeticDecodeRestart()
to restart the decoder at the byte-aligned boundary.
In this case,
.I target_num_bits
can be set to
.I input_buffer -> bit_cnt 
plus the length (in bits) of the block to stop the decoder
again after the block has been decoded.
.SH "MODEL ADAPTION"
Arithmetic coding can be either adaptive, in which the frequency-count
information in the arithmetic model is updated after each symbol is
encoded, or nonadaptive, in which the frequency counts stay static.
By default, when a model is created, it is set to be an adaptive
model, but one can enable or disable adaption at any time via calls to
.BR QccENTArithmeticSetModelAdaption (3).
.LP
For a nonadaptive model, one can explicitly ("manually") change the
frequency-count information in the model by passing a
probability distribution to the model via a call to
.BR QccENTArithmeticSetModelProbabilities (3).
.SH "RETURN VALUE"
.BR QccENTArithmeticEncode()
returns 0 on success, 1 on failure, or
2 in the case that encoding is terminated prematurely due to
.I target_num_bits
being output.
.LP
.BR QccENTArithmeticDecode()
returns 0 on success, 1 on failure to read
all requested symbols, or 2 if the special EOF symbol is encountered.
.LP
.BR QccENTArithmeticEncodeStart()
and
.BR QccENTArithmeticDecodeStart()
return 
.B NULL
on error, or a pointer to a
.BR QccENTArithmeticModel (3)
structure on success.
.LP
.BR QccENTArithmeticDecodeRestart()
and
.BR QccENTArithmeticEncodeFlush()
return 0 on success, and 1 on failure.
.SH "EXAMPLES"
.SS "Single-Context Adaptive Arithmetic Coding"
Straightforward single-context adaptive encoding.
.br
.sp
Encoder:
.RS
.nf

/*  ENCODER  */

#include "QccPack.h"

main(int argc, char *argv[])
{
  int symbol_stream[SYMBOL_STREAM_LENGTH];
  QccBitBuffer output_buffer;
  QccENTArithmeticModel *model = NULL;
  
  QccInit(argc, argv);
  QccBitBufferInitialize(&output_buffer);
  
  /*  obtain symbols here */
  
  output_buffer.type = QCCBITBUFFER_OUTPUT;
  if (QccBitBufferStart(&output_buffer))
    {
      QccErrorAddMessage("%s: Error calling QccBitBufferStart()",
                         argv[0]);
      QccErrorExit();
    }
  
  if ((model = QccENTArithmeticEncodeStart(&NUM_SYMBOLS,
                                           1,
                                           NULL,
                                           QCCENT_ANYNUMBITS)) == NULL)
    {
      QccErrorAddMessage("%s: Error calling QccENTArithmeticEncodeStart()",
                         argv[0]);
      QccErrorExit();
    }
  
  if (QccENTArithmeticEncode(symbol_stream, 
                             SYMBOL_STREAM_LENGTH,
                             model,
                             &output_buffer))
    {
      QccErrorAddMessage("%s: Error calling QccENTArithmeticEncode()",
                         argv[0]);
      QccErrorExit();
    }
  
  if (QccENTArithmeticEncodeEnd(model,
                                0,
                                &output_buffer))
    {
      QccErrorAddMessage("%s: Error calling QccENTArithmeticEncodeEnd()");
      QccErrorExit();
    }
  
  if (QccBitBufferEnd(&output_buffer))
    {
      QccErrorAddMessage("%s: Error calling QccBitBufferEnd()",
                         argv[0]);
      QccErrorExit();
    }
  
  QccENTArithmeticFreeModel(model);
  
  QccExit;
}

.fi
.RE
.sp
.sp
.sp
Decoder:
.RS
.nf

/*  DECODER  */

#include "QccPack.h"

main(int argc, char *argv[])
{
  int symbol_stream[SYMBOL_STREAM_LENGTH];
  QccBitBuffer input_buffer;
  QccENTArithmeticModel *model = NULL;
  
  QccInit(argc, argv);
  QccBitBufferInitialize(&input_buffer);
  
  input_buffer.type = QCCBITBUFFER_INPUT;
  if (QccBitBufferStart(&input_buffer))
    {
      QccErrorAddMessage("%s: Error calling QccBitBufferStart()",
                         argv[0]);
      QccErrorExit();
    }
  
  if ((model = QccENTArithmeticDecodeStart(&input_buffer,
                                           &NUM_SYMBOLS,
                                           1,
                                           NULL,
                                           QCCENT_ANYNUMBITS)) == NULL)
    {
      QccErrorAddMessage("%s: Error calling QccENTArithmeticDecodeStart()",
                         argv[0]);
      QccErrorExit();
    }
  
  if (QccENTArithmeticDecode(&input_buffer,
                             model,
                             symbol_stream, 
                             SYMBOL_STREAM_LENGTH))
    {
      QccErrorAddMessage("%s: Error calling QccENTArithmeticDecode()",
                         argv[0]);
      QccErrorExit();
    }
  
  if (QccBitBufferEnd(&input_buffer))
    {
      QccErrorAddMessage("%s: Error calling QccBitBufferEnd()",
                         argv[0]);
      QccErrorExit();
    }
  
  QccENTArithmeticFreeModel(model);
  
  /*  output symbols stream here  */

  QccExit;
}

.fi
.RE
.SS "Simple Multiple-Context Adaptive Arithmetic Coding"
Multiple-context adaptive
arithmetic coding in which there are two contexts, each
with the same number of symbols. In this example, the symbols are
coded in two blocks; the first block is encoded with the first context,
and the second block is encoded with the second context. The trailing EOF
symbol is output in the second context.
.br
.sp
Encoder:
.RS
.nf

/*  ENCODER  */

#include "QccPack.h"

#define FIRST_CONTEXT 0
#define SECOND_CONTEXT 1

main(int argc, char *argv[])
{
  int symbol_stream[SYMBOL_STREAM_LENGTH];
  QccBitBuffer output_buffer;
  QccENTArithmeticModel *model = NULL;
  
  int num_contexts = 2;
  int num_symbols[2];

  QccInit(argc, argv);
  QccBitBufferInitialize(&output_buffer);
  
  for (context = 0; context < 2; context++)
    num_symbols[context] = NUM_SYMBOLS;
      
  /*  obtain symbols here */
  
  output_buffer.type = QCCBITBUFFER_OUTPUT;
  if (QccBitBufferStart(&output_buffer))
    {
      QccErrorAddMessage("%s: Error calling QccBitBufferStart()",
                         argv[0]);
      QccErrorExit();
    }
  
  if ((model = QccENTArithmeticEncodeStart(num_symbols,
                                           2,
                                           NULL,
                                           QCCENT_ANYNUMBITS)) == NULL)
    {
      QccErrorAddMessage("%s: Error calling QccENTArithmeticEncodeStart()",
                         argv[0]);
      QccErrorExit();
    }
  
  if (QccENTArithmeticSetModelContext(model, FIRST_CONTEXT))
    {
      QccErrorAddMessage("%s: Error calling QccENTArithmeticSetModelContext()",
                         argv[0]);
      QccErrorExit();
    }

  if (QccENTArithmeticEncode(symbol_stream, 
                             FIRST_BLOCK_LENGTH,
                             model,
                             &output_buffer))
    {
      QccErrorAddMessage("%s: Error calling QccENTArithmeticEncode()",
                         argv[0]);
      QccErrorExit();
    }
  
  if (QccENTArithmeticSetModelContext(model, SECOND_CONTEXT))
    {
      QccErrorAddMessage("%s: Error calling QccENTArithmeticSetModelContext()",
                         argv[0]);
      QccErrorExit();
    }

  if (QccENTArithmeticEncode(&symbol_stream[FIRST_BLOCK_LENGTH],