qccenthuffmantablecreatedecodetable.3

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

.TH QCCENTHUFFMANTABLECREATEDECODETABLE 3 "QCCPACK" ""
.SH NAME
QccENTHuffmanTableCreateDecodeTable,
QccENTHuffmanTableCreateEncodeTable \- 
create
.B QccENTHuffmanTable
tables for Huffman decoding and encoding
.SH SYNOPSIS
.B #include "libQccPack.h"
.sp
.BI "int QccENTHuffmanTableCreateDecodeTable(QccENTHuffmanTable *" table );
.br
.BI "int QccENTHuffmanTableCreateEncodeTable(QccENTHuffmanTable *" table );
.SH DESCRIPTION
The routines
.BR QccENTHuffmanTableCreateDecodeTable()
and
.BR QccENTHuffmanTableCreateEncodeTable()
create tables for Huffman decoding and encoding, respectively,
assuming that one already knows the distribution of the codeword lengths,
that is, the number of codewords for each codeword length.
To create Huffman tables for encoding/decoding from a probability
distribution, use
.BR QccENTHuffmanDesign (3).
.LP
A number of arrays and array lengths internal to
.I table
must be set before calling these routines.
.IR table -> num_codewords_list
is a list of the number of codewords of each length.
The first entry in the list,
.IR table -> num_codewords_list [0],
gives the number of codewords with length equal to one bit;
the second entry in the list,
.IR table -> num_codewords_list [1],
gives the number of codewords with length equal to two bits;
etc.  A zero indicates that there are no codewords of a
particular length.
.IR table -> num_codewords_list_length
is the number of entries in
.IR table -> num_codewords_list ;
.IR table -> num_codewords_list_length
must be greater than zero, but less than or equal to
.BR QCCENTHUFFMAN_MAXCODEWORDLEN
(defined to be 31 bits).
If
.IR table -> num_codewords_list_length
is less than
.BR QCCENTHUFFMAN_MAXCODEWORDLEN ,
it is assumed that the number of codewords of lengths between
.IR table -> num_codewords_list_length
and
.BR QCCENTHUFFMAN_MAXCODEWORDLEN
is zero.
.LP
.IR table -> symbol_list
lists the symbols, in order, corresponding to the codewords implied by
.IR table -> num_codewords_list .
.IR table -> symbol_list_length
gives the length of the
.IR table -> symbol_list
list.
.IR table -> symbol_list_length
must be exactly equal to the sum of all the lengths in
.IR table -> num_codewords_list 
for
.IR table -> num_codewords_list
and
.IR table -> symbol_list
to be consistent with each other;
.BR QccENTHuffmanTableCreateDecodeTable()
checks for this and returns an error if the two tables
are not consistent in this way.
.LP
.BR QccENTHuffmanTableCreateDecodeTable()
returns a Huffman table with
.IR table -> table_type
set to
.BR QCCENTHUFFMAN_DECODETABLE ,
which means that
.I table
is suitable for Huffman decoding with
.BR QccENTHuffmanDecode (3).
.LP
.BR QccENTHuffmanTableCreateEncodeTable()
returns a Huffman table with
.IR table -> table_type
set to
.BR QCCENTHUFFMAN_ENCODETABLE ,
which means that
.I table
is suitable for Huffman encoding with
.BR QccENTHuffmanEncode (3).
.BR QccENTHuffmanTableCreateEncodeTable()
first calls
.BR QccENTHuffmanTableCreateDecodeTable()
to generate a decoding table, then reorganizes the decoding table
so as to provide a lookup table indexed by the symbol value for
quick encoding.
Typically, this encoding-table format occupies much more memory
than the corresponding decoding table.
.LP
Both
.BR QccENTHuffmanTableCreateEncodeTable()
and
.BR QccENTHuffmanTableCreateDecodeTable()
allocate space for
.IR table -> table
via a call to
.BR QccENTHuffmanTableAlloc (3),
so this should not be done prior to
calling these routines.
.SH "EXAMPLE"
Suppose we have the following declarations
.RS
.nf

QccENTHuffmanTable table;
int num_codewords_list[] = { 0, 2, 1, 2 };
int symbol_list[] = { 'a', 'b', 'c', 'd', 'e' };

table.num_codewords_list_length = 4;
table.symbol_list_length = 5;
table.num_codewords_list = num_codewords_list;
table.symbol_list = symbol_list;
.fi
.RE
Then
.BR QccENTHuffmanTableCreateDecodeTable()
will assign the following Huffman codewords to the symbols:
.RS
.nf

  Symbol     Codeword Length      Codeword
-------------------------------------------
   'a'              2                00
   'b'              2                01
   'c'              3                100
   'd'              4                1010
   'e'              4                1011

.fi
.RE
Note that
.I num_codewords_list
specifies zero length-1 codewords, two length-2 codewords, one length-3
codeword, and two length-4 codewords, and that the
.I symbol_list
symbols are given in the order corresponding to the lengths; i.e.,
both symbols 'a' and 'b' are to be assigned length-2 codewords.
.SH "NOTE"
These routines are based upon the implementations of Huffman encoding and
decoding suggested in Annexes C & F of the JPEG
standard, ISO/IEC 10918.
.SH "RETURN VALUE"
These routines return 0 on success, and 1 on failure.
.SH "SEE ALSO"
.BR QccENTHuffmanDecode (3),
.BR QccENTHuffmanEncode (3),
.BR QccENTHuffmanDesign (3),
.BR QccENTHuffmanTable (3),
.BR QccPackENT (3),
.BR QccPack (3)
.LP
D. A. Huffman, "A Method for the Construction of Minimum-Redundancy Codes,"
.IR "Proceedings of the IRE" ,
vol. 40, pp. 1098-1101, September 1952.
.LP
ISO/IEC 10918,
.IR "Digital compression and coding of continuous-tone still images" ,
1994.
.SH AUTHOR
Copyright (C) 1997-2009  James E. Fowler
.\"  The programs herein are free software; you can redistribute them an.or
.\"  modify them under the terms of the GNU General Public License
.\"  as published by the Free Software Foundation; either version 2
.\"  of the License, or (at your option) any later version.
.\"  
.\"  These programs are distributed in the hope that they will be useful,
.\"  but WITHOUT ANY WARRANTY; without even the implied warranty of
.\"  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
.\"  GNU General Public License for more details.
.\"  
.\"  You should have received a copy of the GNU General Public License
.\"  along with these programs; if not, write to the Free Software
.\"  Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.