\hypertarget{APE_8h}{
\section{APE.h File Reference}
\label{APE_8h}\index{APE.h@{APE.h}}
}
Arithmetic Word Encoder interface file. 

{\tt \#include \char`\"{}LDT/BA.h\char`\"{}}\par


Include dependency graph for APE.h:\nopagebreak
\begin{figure}[H]
\begin{center}
\leavevmode
\includegraphics[width=59pt]{APE_8h__incl}
\end{center}
\end{figure}


This graph shows which files directly or indirectly include this file:\nopagebreak
\begin{figure}[H]
\begin{center}
\leavevmode
\includegraphics[width=43pt]{APE_8h__dep__incl}
\end{center}
\end{figure}
\subsection*{Classes}
\begin{CompactItemize}
\item 
struct \hyperlink{struct__APE__cv__ui}{\_\-APE\_\-cv\_\-ui}
\begin{CompactList}\small\item\em Defines the limits of the condition value as two 32-bit integers. \item\end{CompactList}\item 
struct \hyperlink{union__APE__cv}{\_\-APE\_\-cv}
\begin{CompactList}\small\item\em Defines the limits of the condition value as union between the field definition two 32-bit integers and an interpretted 64-bit number. \item\end{CompactList}\item 
struct \hyperlink{struct__APE__etx}{\_\-APE\_\-etx}
\begin{CompactList}\small\item\em Encoding context. \item\end{CompactList}\end{CompactItemize}
\subsection*{Typedefs}
\begin{CompactItemize}
\item 
\hypertarget{APE_8h_c75d2a7fd69130557907ada77b31abc8}{
typedef struct \hyperlink{struct__APE__cv__ui}{\_\-APE\_\-cv\_\-ui} \hyperlink{APE_8h_c75d2a7fd69130557907ada77b31abc8}{APE\_\-cv\_\-ui}}
\label{APE_8h_c75d2a7fd69130557907ada77b31abc8}

\begin{CompactList}\small\item\em Typedef for APE\_\-cv\_\-ui. \item\end{CompactList}\item 
\hypertarget{APE_8h_61df3ecb9d291b0f9976bd162094a03e}{
typedef union \hyperlink{union__APE__cv}{\_\-APE\_\-cv} \hyperlink{APE_8h_61df3ecb9d291b0f9976bd162094a03e}{APE\_\-cv}}
\label{APE_8h_61df3ecb9d291b0f9976bd162094a03e}

\begin{CompactList}\small\item\em Typedef for APE\_\-cv. \item\end{CompactList}\item 
typedef struct \hyperlink{struct__APE__etx}{\_\-APE\_\-etx} \hyperlink{APE_8h_46e8b0bc5e870dab17b7cd543daf382a}{APE\_\-etx}
\begin{CompactList}\small\item\em Typedef for struct {\em \hyperlink{struct__APE__etx}{\_\-APE\_\-etx}\/}. \item\end{CompactList}\end{CompactItemize}
\subsection*{Functions}
\begin{CompactItemize}
\item 
unsigned int \hyperlink{APE_8h_6e5bf225c4335dc77e5f03c69193a300}{APE\_\-bcompress} (unsigned char $\ast$out, unsigned int boff, unsigned char $\ast$max, const unsigned int $\ast$table, const unsigned char $\ast$in, int cnt, int $\ast$unencoded)
\begin{CompactList}\small\item\em Convenience routine to compress a byte stream. \item\end{CompactList}\item 
int \hyperlink{APE_8h_96d50e9d31bf7a651c77a21596863674}{APE\_\-reset} (\hyperlink{struct__APE__etx}{APE\_\-etx} $\ast$etx, unsigned char $\ast$out, unsigned int boff, const unsigned char $\ast$max)
\begin{CompactList}\small\item\em Resets the output context. \item\end{CompactList}\item 
int \hyperlink{APE_8h_88d2c574b45a8a27314fad84ca9f2eea}{APE\_\-start} (\hyperlink{struct__APE__etx}{APE\_\-etx} $\ast$etx, unsigned char $\ast$out, unsigned int boff, const unsigned char $\ast$max)
\begin{CompactList}\small\item\em Initializes the encoding context. \item\end{CompactList}\item 
int \hyperlink{APE_8h_9c837ca41b6686cf90421d70a922c8d7}{APE\_\-encode} (\hyperlink{struct__APE__etx}{APE\_\-etx} $\ast$etx, const unsigned int $\ast$table, unsigned int sym)
\begin{CompactList}\small\item\em Encodes one symbol. \item\end{CompactList}\item 
int \hyperlink{APE_8h_3876be55c4dccbd38ee28dcb28a14a82}{APE\_\-bencode} (\hyperlink{struct__APE__etx}{APE\_\-etx} $\ast$etx, const unsigned int $\ast$table, const unsigned char $\ast$syms, int nsyms)
\begin{CompactList}\small\item\em Encodes an array of unsigned char symbols. \item\end{CompactList}\item 
int \hyperlink{APE_8h_2f54e98eb1bf7b80b9385929e18c3218}{APE\_\-sencode} (\hyperlink{struct__APE__etx}{APE\_\-etx} $\ast$etx, const unsigned int $\ast$table, const unsigned short $\ast$syms, int nsyms)
\begin{CompactList}\small\item\em Encodes an array of unsigned char symbols. \item\end{CompactList}\item 
int \hyperlink{APE_8h_7e9749f69a8ca2b4c167199a280d3a66}{APE\_\-blencode} (\hyperlink{struct__APE__etx}{APE\_\-etx} $\ast$etx, const unsigned int $\ast$$\ast$tables, unsigned char const $\ast$syms, int nsyms)
\begin{CompactList}\small\item\em Encodes an array of unsigned char symbols. \item\end{CompactList}\item 
int \hyperlink{APE_8h_762086e55ef44742cd9aedc2ccea9f3c}{APE\_\-slencode} (\hyperlink{struct__APE__etx}{APE\_\-etx} $\ast$etx, const unsigned int $\ast$$\ast$tables, unsigned short const $\ast$syms, int nsyms)
\begin{CompactList}\small\item\em Encodes an array of unsigned short integer symbols each with their own table. \item\end{CompactList}\item 
int \hyperlink{APE_8h_4959206e3623da947d475411633e8ccc}{APE\_\-finish} (\hyperlink{struct__APE__etx}{APE\_\-etx} $\ast$etx)
\begin{CompactList}\small\item\em Finishes the encoding by flushing out any currently buffered bits. \item\end{CompactList}\end{CompactItemize}


\subsection{Detailed Description}
Arithmetic Word Encoder interface file. 

\begin{Desc}
\item[Author:]JJRussell - \href{mailto:russell@slac.stanford.edu}{\tt russell@slac.stanford.edu}\end{Desc}


\footnotesize\begin{verbatim}
    CVS $Id: APE.h,v 1.3 2006/09/13 17:58:40 russell Exp $
\end{verbatim}
\normalsize


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$\ast$$\ast$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. 

\subsection{Typedef Documentation}
\hypertarget{APE_8h_46e8b0bc5e870dab17b7cd543daf382a}{
\index{APE.h@{APE.h}!APE_etx@{APE\_\-etx}}
\index{APE_etx@{APE\_\-etx}!APE.h@{APE.h}}
\subsubsection{\setlength{\rightskip}{0pt plus 5cm}{\bf APE\_\-etx}}}
\label{APE_8h_46e8b0bc5e870dab17b7cd543daf382a}


Typedef for struct {\em \hyperlink{struct__APE__etx}{\_\-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. 

\subsection{Function Documentation}
\hypertarget{APE_8h_6e5bf225c4335dc77e5f03c69193a300}{
\index{APE.h@{APE.h}!APE_bcompress@{APE\_\-bcompress}}
\index{APE_bcompress@{APE\_\-bcompress}!APE.h@{APE.h}}
\subsubsection{\setlength{\rightskip}{0pt plus 5cm}unsigned int APE\_\-bcompress (unsigned char $\ast$ {\em out}, unsigned int {\em boff}, unsigned char $\ast$ {\em max}, const unsigned int $\ast$ {\em table}, const unsigned char $\ast$ {\em in}, int {\em cnt}, int $\ast$ {\em unencoded})}}
\label{APE_8h_6e5bf225c4335dc77e5f03c69193a300}


Convenience routine to compress a byte stream. 

\begin{Desc}
\item[Returns:]The number of bits needed to encoded the byte stream. If negative the all the symbols could not be encoded and {\em unencoded\/} should be checked for the count of those symbols not encoded.\end{Desc}
\begin{Desc}
\item[Parameters:]
\begin{description}
\item[{\em out}]The output buffer \item[{\em boff}]The current bit offset \item[{\em max}]The maximum output address (actually 1 byte past it) \item[{\em table}]The encoding table \item[{\em in}]The input buffer of symbols. \item[{\em cnt}]The number of input symbols. \item[{\em unencoded}]The number of input symbols left to encode. If successful this will be 0.\end{description}
\end{Desc}
This is a convenience routine, combining \hyperlink{APE_8c_88d2c574b45a8a27314fad84ca9f2eea}{APE\_\-start()}, \hyperlink{APE_8c_9c837ca41b6686cf90421d70a922c8d7}{APE\_\-encode()} and \hyperlink{APE_8c_cee5053cd7ae849f356e4c1eb8200b6f}{APE\_\-finish()}. It can be used iff the same table is used to encode all the symbols. \hypertarget{APE_8h_3876be55c4dccbd38ee28dcb28a14a82}{
\index{APE.h@{APE.h}!APE_bencode@{APE\_\-bencode}}
\index{APE_bencode@{APE\_\-bencode}!APE.h@{APE.h}}
\subsubsection{\setlength{\rightskip}{0pt plus 5cm}int APE\_\-bencode ({\bf APE\_\-etx} $\ast$ {\em etx}, const unsigned int $\ast$ {\em table}, const unsigned char $\ast$ {\em syms}, int {\em nsyms})}}
\label{APE_8h_3876be55c4dccbd38ee28dcb28a14a82}


Encodes an array of unsigned char symbols. 

\begin{Desc}
\item[Returns:]Number of symbols remaining to be encoded. If this is 0, all symbols where encoded.\end{Desc}
\begin{Desc}
\item[Parameters:]
\begin{description}
\item[{\em etx}]The encoding context \item[{\em table}]The encoding table \item[{\em syms}]The array of symbols to encode \item[{\em nsyms}]The number of symbols \end{description}
\end{Desc}
\hypertarget{APE_8h_7e9749f69a8ca2b4c167199a280d3a66}{
\index{APE.h@{APE.h}!APE_blencode@{APE\_\-blencode}}
\index{APE_blencode@{APE\_\-blencode}!APE.h@{APE.h}}
\subsubsection{\setlength{\rightskip}{0pt plus 5cm}int APE\_\-blencode ({\bf APE\_\-etx} $\ast$ {\em etx}, const unsigned int $\ast$$\ast$ {\em tables}, unsigned char const $\ast$ {\em syms}, int {\em nsyms})}}
\label{APE_8h_7e9749f69a8ca2b4c167199a280d3a66}


Encodes an array of unsigned char symbols. 

\begin{Desc}
\item[Returns:]Number of symbols remaining to be encoded. If this is 0, all symbols where encoded.\end{Desc}
\begin{Desc}
\item[Parameters:]
\begin{description}
\item[{\em etx}]The encoding context \item[{\em tables}]The encoding table \item[{\em syms}]The array of symbols to encode \item[{\em nsyms}]The number of symbols \end{description}
\end{Desc}
\hypertarget{APE_8h_9c837ca41b6686cf90421d70a922c8d7}{
\index{APE.h@{APE.h}!APE_encode@{APE\_\-encode}}
\index{APE_encode@{APE\_\-encode}!APE.h@{APE.h}}
\subsubsection{\setlength{\rightskip}{0pt plus 5cm}int APE\_\-encode ({\bf APE\_\-etx} $\ast$ {\em etx}, const unsigned int $\ast$ {\em table}, unsigned int {\em sym})}}
\label{APE_8h_9c837ca41b6686cf90421d70a922c8d7}


Encodes one symbol. 

\begin{Desc}
\item[Returns:]Number of symbols remaining to be encoded. If this is 0, the symbol was successfully encoded.\end{Desc}
\begin{Desc}
\item[Parameters:]
\begin{description}
\item[{\em etx}]The encoding context \item[{\em table}]The encoding table \item[{\em sym}]The symbol to encode \end{description}
\end{Desc}
\hypertarget{APE_8h_4959206e3623da947d475411633e8ccc}{
\index{APE.h@{APE.h}!APE_finish@{APE\_\-finish}}
\index{APE_finish@{APE\_\-finish}!APE.h@{APE.h}}
\subsubsection{\setlength{\rightskip}{0pt plus 5cm}int APE\_\-finish ({\bf APE\_\-etx} $\ast$ {\em etx})}}
\label{APE_8h_4959206e3623da947d475411633e8ccc}


Finishes the encoding by flushing out any currently buffered bits. 

\begin{Desc}
\item[Return values:]
\begin{description}
\item[{\em If}]$>$ 0, the number of encoded bits. If $<$ 0, the number of bits needed to encode the final piece\end{description}
\end{Desc}
\begin{Desc}
\item[Parameters:]
\begin{description}
\item[{\em etx}]The encoding context\end{description}
\end{Desc}
\begin{Desc}
\item[]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.\end{Desc}
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. \hypertarget{APE_8h_96d50e9d31bf7a651c77a21596863674}{
\index{APE.h@{APE.h}!APE_reset@{APE\_\-reset}}
\index{APE_reset@{APE\_\-reset}!APE.h@{APE.h}}
\subsubsection{\setlength{\rightskip}{0pt plus 5cm}int APE\_\-reset ({\bf APE\_\-etx} $\ast$ {\em etx}, unsigned char $\ast$ {\em out}, unsigned int {\em boff}, const unsigned char $\ast$ {\em max})}}
\label{APE_8h_96d50e9d31bf7a651c77a21596863674}


Resets the output context. 

\begin{Desc}
\item[Return values:]
\begin{description}
\item[{\em 0,If}]successful \item[{\em -1,If}]failed to provide at least 1 byte of memory.\end{description}
\end{Desc}
\begin{Desc}
\item[Parameters:]
\begin{description}
\item[{\em etx}]The encoding context to reset \item[{\em out}]The output buffer. \item[{\em boff}]The bit offset into the output buffer. \item[{\em max}]The maximum output address (actually 1 byte past it)\end{description}
\end{Desc}
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 \hypertarget{APE_8h_2f54e98eb1bf7b80b9385929e18c3218}{
\index{APE.h@{APE.h}!APE_sencode@{APE\_\-sencode}}
\index{APE_sencode@{APE\_\-sencode}!APE.h@{APE.h}}
\subsubsection{\setlength{\rightskip}{0pt plus 5cm}int APE\_\-sencode ({\bf APE\_\-etx} $\ast$ {\em etx}, const unsigned int $\ast$ {\em table}, const unsigned short $\ast$ {\em syms}, int {\em nsyms})}}
\label{APE_8h_2f54e98eb1bf7b80b9385929e18c3218}


Encodes an array of unsigned char symbols. 

\begin{Desc}
\item[Returns:]Number of symbols remaining to be encoded. If this is 0, all symbols where encoded.\end{Desc}
\begin{Desc}
\item[Parameters:]
\begin{description}
\item[{\em etx}]The encoding context \item[{\em table}]The encoding table \item[{\em syms}]The array of symbols to encode \item[{\em nsyms}]The number of symbols \end{description}
\end{Desc}
\hypertarget{APE_8h_762086e55ef44742cd9aedc2ccea9f3c}{
\index{APE.h@{APE.h}!APE_slencode@{APE\_\-slencode}}
\index{APE_slencode@{APE\_\-slencode}!APE.h@{APE.h}}
\subsubsection{\setlength{\rightskip}{0pt plus 5cm}int APE\_\-slencode ({\bf APE\_\-etx} $\ast$ {\em etx}, const unsigned int $\ast$$\ast$ {\em tables}, unsigned short const $\ast$ {\em syms}, int {\em nsyms})}}
\label{APE_8h_762086e55ef44742cd9aedc2ccea9f3c}


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

\begin{Desc}
\item[Returns:]Number of symbols remaining to be encoded. If this is 0, all symbols where encoded.\end{Desc}
\begin{Desc}
\item[Parameters:]
\begin{description}
\item[{\em etx}]The encoding context \item[{\em tables}]The encoding table \item[{\em syms}]The array of symbols to encode \item[{\em nsyms}]The number of symbols \end{description}
\end{Desc}
\hypertarget{APE_8h_88d2c574b45a8a27314fad84ca9f2eea}{
\index{APE.h@{APE.h}!APE_start@{APE\_\-start}}
\index{APE_start@{APE\_\-start}!APE.h@{APE.h}}
\subsubsection{\setlength{\rightskip}{0pt plus 5cm}int APE\_\-start ({\bf APE\_\-etx} $\ast$ {\em etx}, unsigned char $\ast$ {\em out}, unsigned int {\em boff}, const unsigned char $\ast$ {\em max})}}
\label{APE_8h_88d2c574b45a8a27314fad84ca9f2eea}


Initializes the encoding context. 

\begin{Desc}
\item[Return values:]
\begin{description}
\item[{\em 0,Currently,always}]0. This may expand to a status code if necessary\end{description}
\end{Desc}
\begin{Desc}
\item[Parameters:]
\begin{description}
\item[{\em etx}]The encoding context to initialize \item[{\em out}]The output buffer \item[{\em boff}]The bit offset into the output buffer \item[{\em max}]The maximum output address (actually 1 byte past it)\end{description}
\end{Desc}
Note that since the AWx routines are bit encoders/decoders, one needs to specify the offsets into the buffers as bit offsets.