APE.c File Reference

Arithmetic Word Encoder, implementation file. More...

#include <LDT/APE.h>
#include <APC.h>
#include <PBI/FFS.ih>
#include <PBI/PTR.h>

Typedefs
typedef enum _APE_symType	APE_symType
	Typedef for enum _APE_symType.
Enumerations
enum	_APE_symType {   APE_SYMTYPE_K_ARRAY_BYTE = 0,   APE_SYMTYPE_K_ARRAY_SHORT = 1 }
	The symbol type being encoded. More...
Functions
static __inline unsigned long long	scale (APE_cv cv, const unsigned int table[2])
	Scales the input lo and hi condition value/limits using the table values.
static __inline unsigned long long int	reduce_h01 (APE_cv cv, int cnt)
	Reduces the specified condition values when the both the lo and hi limits lie in the same half, i.e. either both are in the lower half or both are in the upper half.
static __inline unsigned long long int	reduce_q12 (APE_cv cv)
	Reduces the specified condition values when the lo and hi straddle the mid-point, i.e. the lo limit is in Q1 and the hi limit is in Q2.
static __inline int	immediate_encode (APE_etx *etx, const unsigned int *table, unsigned int sym)
	Encodes a symbol.
static __inline int	encode (APE_etx *etx, const unsigned int *table, const void *syms, int nsyms, int symType)
	Encodes an immediate value array of unsigned char symbols array of unsigned short int symbols.
static __inline int	encode_list (APE_etx *etx, const unsigned int **tables, const void *syms, int nsyms, int symType)
	Encodes an array of unsigned char symbols array of unsigned short int symbols.
static int	set (APE_etx *etx, unsigned char *out, unsigned int boff, const unsigned char *max)
	Sets the output 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_blencode (APE_etx *etx, const unsigned int **tables, unsigned char const *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_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_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.
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_finish (APE_etx *etx)
	Finishes the encoding by flushing out any currently buffered bits.

---

Detailed Description

Arithmetic Word Encoder, implementation file.

Author:

JJRussell - russell@slac.stanford.edu

Implementation of the routines to encode symbols using an arithmetic probability encoding technique. To achieve performance goals, these routines must be used with a model builder that forces a particular normalization of the cumulative probability. While such tables may be constructed in a variety of ways, APM_build is an example of such a routine and is anticipated to be the model table builder.

---

Enumeration Type Documentation

enum _APE_symType

The symbol type being encoded.

Enumerator:

APE_SYMTYPE_K_ARRAY_BYTE	Symbol type is an byte array
APE_SYMTYPE_K_ARRAY_SHORT	Symbol type is a short array

---

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.

References APE_bencode(), APE_finish(), and APE_start().

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

References APE_SYMTYPE_K_ARRAY_BYTE, and encode().

Referenced by APE_bcompress().

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

References APE_SYMTYPE_K_ARRAY_BYTE, and encode_list().

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

References immediate_encode().

unsigned 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.

References _APE_etx::ba, _APE_etx::bbeg, _APE_etx::beg, _BA::buffer, _APE_etx::cv, _APE_cv_ui::lo, _APE_etx::max, _BA::out, _APE_etx::tofollow, _BA::togo, and _APE_cv::ui.

Referenced by APE_bcompress().

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

References _APE_etx::ba, _BA::buffer, _BA::out, and _BA::togo.

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

References APE_SYMTYPE_K_ARRAY_SHORT, and encode().

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

References APE_SYMTYPE_K_ARRAY_SHORT, and encode_list().

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.

References _APE_etx::ba, _BA::buffer, _APE_etx::cv, _APE_cv_ui::hi, _APE_cv_ui::lo, _BA::out, _APE_etx::tofollow, _BA::togo, and _APE_cv::ui.

Referenced by APE_bcompress().

static int encode	(	APE_etx *	etx,
		const unsigned int *	table,
		const void *	syms,
		int	nsyms,
		int	symType
	)			[static]

Encodes an

1. immediate value
2. array of unsigned char symbols
3. array of unsigned short int 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
	symType	The type of symbol(s) being encoded < 0 => immediate value = 0 => array of unsigned char symbols > 0 => array of unsigned short int symbols

References _APE_etx::ba, _BA::buffer, _APE_etx::cv, _APE_cv_ui::hi, _APE_cv::hiLo, _APE_cv_ui::lo, _APE_etx::max, _BA::out, reduce_h01(), reduce_q12(), scale(), _APE_etx::tofollow, _BA::togo, and _APE_cv::ui.

static __inline int encode_list	(	APE_etx *	etx,
		const unsigned int **	tables,
		const void *	syms,
		int	nsyms,
		int	symType
	)			[static]

Encodes an

1. array of unsigned char symbols
2. array of unsigned short int 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
	symType	The type of symbol(s) being encoded < 0 => immediate value = 0 => array of unsigned char symbols > 0 => array of unsigned short int symbols

References _APE_etx::ba, _BA::buffer, _APE_etx::cv, _APE_cv_ui::hi, _APE_cv::hiLo, _APE_cv_ui::lo, _APE_etx::max, _BA::out, reduce_h01(), reduce_q12(), scale(), _APE_etx::tofollow, _BA::togo, and _APE_cv::ui.

Referenced by APE_blencode(), and APE_slencode().

static int immediate_encode	(	APE_etx *	etx,
		const unsigned int *	table,
		unsigned int	sym
	)			[static]

Encodes a symbol.

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
	sym	The symbol to encode

References _APE_etx::ba, _BA::buffer, _APE_etx::cv, _APE_cv_ui::hi, _APE_cv::hiLo, _APE_cv_ui::lo, _APE_etx::max, _BA::out, reduce_h01(), reduce_q12(), scale(), _APE_etx::tofollow, _BA::togo, and _APE_cv::ui.

Referenced by APE_encode().

static __inline unsigned long long int reduce_h01	(	APE_cv	cv,
		int	cnt
	)			[static]

Reduces the specified condition values when the both the lo and hi limits lie in the same half, i.e. either both are in the lower half or both are in the upper half.

Returns:

The new condition value

Parameters:

	cv	The condition values to reduce.
	cnt	The number of identical bits.

These number of bits specified by cnt are removed from the top of both the lo and hi limits. The lo limit replaces these bits on the bottom with 0's, while the high limit replaces them with 1's

References _APE_cv_ui::hi, _APE_cv::hiLo, _APE_cv_ui::lo, and _APE_cv::ui.

Referenced by encode(), encode_list(), and immediate_encode().

static __inline unsigned long long int reduce_q12

(

APE_cv

cv

)

[static]

Reduces the specified condition values when the lo and hi straddle the mid-point, i.e. the lo limit is in Q1 and the hi limit is in Q2.

Returns:

The new condition value

Parameters:

cv

The condition values to reduce.

In this reduction, only the top bit of each the lo and hi limits is removed.

References _APE_cv_ui::hi, _APE_cv::hiLo, _APE_cv_ui::lo, and _APE_cv::ui.

Referenced by encode(), encode_list(), and immediate_encode().

static __inline unsigned long long scale	(	APE_cv	cv,
		const unsigned int	table[2]
	)			[static]

Scales the input lo and hi condition value/limits using the table values.

Returns:

The rescaled lo and hi condition values/limits

Parameters:

	cv	The current condtion value
	table	The table values

References _APE_cv_ui::hi, _APE_cv::hiLo, _APE_cv_ui::lo, and _APE_cv::ui.

Referenced by encode(), encode_list(), and immediate_encode().

int set	(	APE_etx *	etx,
		unsigned char *	out,
		unsigned int	boff,
		const unsigned char *	max
	)			[static]

Sets the output context.

Returns:

The bit offset into the current output

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.

References _APE_etx::ba, _APE_etx::bbeg, _APE_etx::beg, _APE_etx::max, and _BA::out.