APD.h File Reference

Arithmetic Word Decoder interface file. More...

Classes
struct	_APD_dtx
	Decoding context. More...
Typedefs
typedef struct _APD_dtx	APD_dtx
	Typedef for struct _APD_dtx.
Functions
void	APD_start (APD_dtx *dtx, const void *src, unsigned int boff)
	Begins a decoding session.
unsigned int	APD_decode (APD_dtx *dtx, const unsigned int *table)
	Decodes the next symbol.
int	APD_bdecompress (unsigned char *dst, int cnt, const void *src, unsigned int boff, const unsigned int *table)
	Convenience routine to decode a bit stream using the specified table into a byte array.
int	APD_finish (APD_dtx *dtx)
	Finishes the decoding, cleaning up any inprogress context.
void	APD32_start (APD_dtx *dtx, const void *src, unsigned int boff)
	Begins a decoding session.
unsigned int	APD32_decode (APD_dtx *dtx, const unsigned int *table)
	Decodes the next symbol.
int	APD32_bdecompress (unsigned char *dst, int cnt, const void *src, unsigned int boff, const unsigned int *table)
	Convenience routine to decode a bit stream using the specified table.
int	APD32_finish (APD_dtx *dtx)
	Finishes the decoding, cleaning up any inprogress context.

---

Detailed Description

Arithmetic Word Decoder interface file.

Author:

JJRussell - russell@slac.stanford.edu

CVS $Id: APD.h,v 1.2 2006/01/24 00:20:23 russell Exp $ 

Overview

Interface specification for routines to decode streams using an arithmetic probability encoding technique. It is based on a 32-bit table giving the probabilities of the encoded symbols.

More Info

For details on the implementation and design choices see the documentation in APD.c

APD vs APD32 Interface

The APD routines decode a byte stream of encoded symbols, while the APD32 routines decode a 32-bit stream of encoded symbols.

Note:

The encoding side of these routines writes the encoded data as a big endian byte-stream, where the big endian refers to the fact that the bits within the bytes are serially accessed starting at the most significant bit to the least significant bit.

APD32, Typical Usage

One application of the APD32 routines is when the input stream that the encoded symbols are embedded in is treated as a 32-bit big endian stream. Typically what one will do is byte-swap this stream on little endian machines, so that the 32-bit words are in the correct order. Once this is done, one should use APD32_ routines to correctly access the input stream on either big or little-endian machines.

Note:

Given that the APE encoding routines write a big-endian oriented byte-stream, the APD and APD32 routines are exactly the same on big-endian machines. As an implementation note, these routines truly are the same on big-endian machines, with the equivalent names being aliased.

Note:

This more than a convenience to the user. One might argue that the user could just undo the byte-swapping, but this is not true in all cases. Specifically, if the user does not know the length of the encoded symbols (e.g. the encoded stream itself contains the end-of-stream information, he will be unable to determine how many words to byte-swap.

---

Typedef Documentation

APD_dtx

Typedef for struct _APD_dtx.

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 APD or APD32 routines.

---

Function Documentation

int APD32_bdecompress	(	unsigned char *	dst,
		int	cnt,
		const void *	src,
		unsigned int	boff,
		const unsigned int *	table
	)

Convenience routine to decode a bit stream using the specified table.

Returns:

The number of bits that were decoded.

Parameters:

	dst	The destination/output buffer
	cnt	The number of bytes available in the output buffer
	src	The encode source/input stream
	boff	The bit offset to start at in the input buffer
	table	The decoding table

This is a convenience routine, combining APD_start, APD_decode and APD_finish. This routine can only be used if the decoding table is the same for all symbols in the input stream.

The input stream to be decoded must be 32-bit byte-swapped. See APD32_bdecompress for decoding byte oriented streams.

unsigned int APD32_decode	(	APD_dtx *	dtx,
		const unsigned int *	table
	)

Decodes the next symbol.

Returns:

The decoded symbol

Parameters:

	dtx	The decoding context
	table	The table to use in the decoding

The input stream to be decoded must be 32-bit byte-swapped. See APD32_bdecompress for decoding byte oriented streams.

int APD32_finish

(

APD_dtx *

dtx

)

Finishes the decoding, cleaning up any inprogress context.

Returns:

The number of bits decoded

This routine indicates the user is finish decoding a 32-bit byte-swapped stream. See APD32_finish for finishing a byte stream.

void APD32_start	(	APD_dtx *	dtx,
		const void *	src,
		unsigned int	boff
	)

Begins a decoding session.

Parameters:

	dtx	The decoding context to be initialized
	src	The encoded source/input bit stream
	boff	The bit offset into the input bit stream

This routine initializes a decoding context for 32-bit byte-swapped streams. See APD32_start for accessing byte oriented streams.

int APD_bdecompress	(	unsigned char *	dst,
		int	cnt,
		const void *	src,
		unsigned int	boff,
		const unsigned int *	table
	)

Convenience routine to decode a bit stream using the specified table into a byte array.

Returns:

The number of bits that were decoded.

Parameters:

	dst	The destination/output buffer
	cnt	The number of bytes available in the output buffer
	src	The encoded source/input buffer
	boff	The bit offset to start at in the input buffer
	table	The decoding table

This is a convenience routine, combining APD_start, APD_decode and APD_finish. This routine can only be used if the decoding table is the same for all symbols in the input stream.

The input stream to be decoded must be big-endian byte. See APD32_bdecompress for decoding 32-bit byte-swapped streams.

unsigned int APD_decode	(	APD_dtx *	dtx,
		const unsigned int *	table
	)

Decodes the next symbol.

Returns:

The decoded symbol

Parameters:

	dtx	The decoding context
	table	The table to use in the decoding

The input stream to be decoded must be big-endian byte. See APD32_bdecompress for decoding 32-bit byte-swapped streams.

int APD_finish

(

APD_dtx *

dtx

)

Finishes the decoding, cleaning up any inprogress context.

Returns:

The number of bits decoded

This routine indicates the user is finish decoding a byte oriented stream. See APD32_finish for finishing a 32-bit byte-swapped stream.

void APD_start	(	APD_dtx *	dtx,
		const void *	src,
		unsigned int	boff
	)

Begins a decoding session.

Parameters:

	dtx	The decoding context to be initialized
	src	The encoded source/input bit stream
	boff	The bit offset into the input bit stream

This routine initializes a decoding context for byte-oriented encoded streams. See APD32_start for accessing 32-bit byte-swapped streams.