APE.h File Reference

Arithmetic Word Encoder interface file. More...

#include "LDT/BA.h"

Include dependency graph for APE.h:

This graph shows which files directly or indirectly include this file:


Data Structures
struct	_APE_cv_ui
	Defines the limits of the condition value as two 32-bit integers. More...
struct	_APE_cv
	Defines the limits of the condition value as union between the field definition two 32-bit integers and an interpretted 64-bit number. More...
struct	_APE_etx
	Encoding context. More...
Typedefs
typedef _APE_cv_ui	APE_cv_ui
	Typedef for APE_cv_ui.
typedef _APE_cv	APE_cv
	Typedef for APE_cv.
typedef _APE_etx	APE_etx
	Typedef for struct _APE_etx.
Functions
unsigned int	APE_bcompress (unsigned char out, unsigned int boff, unsigned char max, const unsigned int table, const unsigned char in, int cnt, int *unencoded)
	Convenience routine to compress a byte stream.
int	APE_reset (APE_etx etx, unsigned char out, unsigned int boff, const unsigned char *max)
	Resets the output context.
int	APE_start (APE_etx etx, unsigned char out, unsigned int boff, const unsigned char *max)
	Initializes the encoding context.
int	APE_encode (APE_etx etx, const unsigned int table, unsigned int sym)
	Encodes one symbol.
int	APE_bencode (APE_etx etx, const unsigned int table, const unsigned char *syms, int nsyms)
	Encodes an array of unsigned char symbols.
int	APE_sencode (APE_etx etx, const unsigned int table, const unsigned short *syms, int nsyms)
	Encodes an array of unsigned char symbols.
int	APE_blencode (APE_etx etx, const unsigned int tables, unsigned char const syms, int nsyms)
	Encodes an array of unsigned char symbols.
int	APE_slencode (APE_etx etx, const unsigned int tables, unsigned short const syms, int nsyms)
	Encodes an array of unsigned short integer symbols each with their own table.
int	APE_finish (APE_etx *etx)
	Finishes the encoding by flushing out any currently buffered bits.

Detailed Description

Arithmetic Word Encoder interface file.

Author:: JJRussell - russell@slac.stanford.edu

    CVS $Id: APE.h,v 1.3 2006/09/13 17:58:40 russell Exp $

Interface specification for routines to encode symbols using an arithmetic encoding technique. The encoding tables are 32-bits wide. This allows probabilities to (in principle) hold a range of 1/2**32.

Do not confuse the width of the symbol being encoded with the width of the probability tables. The width of the symbol being encoded is not a fundamental property of these routines. That is, these routines can be used to encode symbols of different widths. All that the user needs to do is provide a probability table that can be indexed by a symbol to give the cumulative probability of that symbol occuring. It is the width of the symbol (or more appropriately, the range of the symbol), that determines the number of elements in the table.

The choice of using 32-bit wide probability tables is a trade-off between two performance metrics, CPU vs compress efficiency. Smaller width tables will give slightly better CPU performance on certain machines, while wider width tables will come closer to achieving the maximum compression possible. It was found, that with careful coding, the CPU performance differences where small. Most this difference can be traced to the increased memory access (read cache misses) intrinsic in accessing a wider table. Thus it was decided to offer only the 32-bit width table as a one-size-fits-all solution.

Typedef Documentation

APE_etx

Typedef for struct _APE_etx.
While this is defined in the public interface, this structure should be treated like a C++ private member. All manipulation of this structure should be through the APE routines.

Function Documentation

unsigned int APE_bcompress ( unsigned char * out,

unsigned int boff,

unsigned char * max,

const unsigned int * table,

const unsigned char * in,

int cnt,

int * unencoded

)

Convenience routine to compress a byte stream.

Returns:
The number of bits needed to encoded the byte stream. If negative the all the symbols could not be encoded and unencoded should be checked for the count of those symbols not encoded.

Parameters:

out The output buffer

boff The current bit offset

max The maximum output address (actually 1 byte past it)

table The encoding table

in The input buffer of symbols.

cnt The number of input symbols.

unencoded The number of input symbols left to encode. If successful this will be 0.

This is a convenience routine, combining APE_start(), APE_encode() and APE_finish(). It can be used iff the same table is used to encode all the symbols.

int APE_bencode ( APE_etx * etx,

const unsigned int * table,

const unsigned char * syms,

int nsyms

)

Encodes an array of unsigned char symbols.

Returns:
Number of symbols remaining to be encoded. If this is 0, all symbols where encoded.

Parameters:

etx The encoding context

table The encoding table

syms The array of symbols to encode

nsyms The number of symbols

int APE_blencode ( APE_etx * etx,

const unsigned int ** tables,

unsigned char const * syms,

int nsyms

)

Encodes an array of unsigned char symbols.

Returns:
Number of symbols remaining to be encoded. If this is 0, all symbols where encoded.

Parameters:

etx The encoding context

tables The encoding table

syms The array of symbols to encode

nsyms The number of symbols

int APE_encode ( APE_etx * etx,

const unsigned int * table,

unsigned int sym

)

Encodes one symbol.

Returns:
Number of symbols remaining to be encoded. If this is 0, the symbol was successfully encoded.

Parameters:

etx The encoding context

table The encoding table

sym The symbol to encode

int APE_finish ( APE_etx * etx )

Finishes the encoding by flushing out any currently buffered bits.

Return values:

If > 0, the number of encoded bits. If < 0, the number of bits needed to encode the final piece

Parameters:

etx The encoding context

At the end of the encoding, there is some context that needs flushing. This flushing may contribute more bits to the output stream. If there are not enough bits to hold this context, the number of extra bits needed to flush the context are returned as a negative number. In this case, the user should write all the currently committed data and then reset the output buffer.
The array to write out is from etx->beg + etx->bbeg (the beginning output address + beginning bit number to ext->ba.out (the current output address). Once written, the user should call APE_reset to reset the output buffer.
If there is enough room, the number of encoded bits is returned as a positive number.

int APE_reset ( APE_etx * etx,

unsigned char * out,

unsigned int boff,

const unsigned char * max

)

Resets the output context.

Return values:

0,If successful

-1,If failed to provide at least 1 byte of memory.

Parameters:

etx The encoding context to reset

out The output buffer.

boff The bit offset into the output buffer.

max The maximum output address (actually 1 byte past it)

Note that since the AWx routines are bit encoders/decoders, one needs to specify the offsets into the buffers as bit offsets. In general, at least one byte of memory needs to be provided. There is no check for this failure

int APE_sencode ( APE_etx * etx,

const unsigned int * table,

const unsigned short * syms,

int nsyms

)

Encodes an array of unsigned char symbols.

Returns:
Number of symbols remaining to be encoded. If this is 0, all symbols where encoded.

Parameters:

etx The encoding context

table The encoding table

syms The array of symbols to encode

nsyms The number of symbols

int APE_slencode ( APE_etx * etx,

const unsigned int ** tables,

unsigned short const * syms,

int nsyms

)

Encodes an array of unsigned short integer symbols each with their own table.

Returns:
Number of symbols remaining to be encoded. If this is 0, all symbols where encoded.

Parameters:

etx The encoding context

tables The encoding table

syms The array of symbols to encode

nsyms The number of symbols

int APE_start ( APE_etx * etx,

unsigned char * out,

unsigned int boff,

const unsigned char * max

)

Initializes the encoding context.

Return values:

0,Currently,always 0. This may expand to a status code if necessary

Parameters:

etx The encoding context to initialize

out The output buffer

boff The bit offset into the output buffer

max The maximum output address (actually 1 byte past it)

Note that since the AWx routines are bit encoders/decoders, one needs to specify the offsets into the buffers as bit offsets.

Generated on Mon Nov 20 04:10:50 2006 by

1.4.4

APE.h File Reference

Data Structures

Typedefs

Functions

Detailed Description

Typedef Documentation

Function Documentation