\hypertarget{HDE_8h}{
\section{HDE.h File Reference}
\label{HDE_8h}\index{HDE.h@{HDE.h}}
}
Interface to the routines to encodes a distribution of symbols using a Huffman encoding technique. Routines are available to encode both the distribution itself and the resulting Huffman table. 

{\tt \#include \char`\"{}LDT/HUFF.h\char`\"{}}\par
{\tt \#include \char`\"{}LDT/BA.h\char`\"{}}\par
{\tt \#include \char`\"{}PBS/FFS.ih\char`\"{}}\par
\subsection*{Classes}
\begin{CompactItemize}
\item 
struct \hyperlink{struct__HDE__assay}{\_\-HDE\_\-assay}
\begin{CompactList}\small\item\em The result of the histogram assessment. \item\end{CompactList}\item 
struct \hyperlink{struct__HDE}{\_\-HDE}
\begin{CompactList}\small\item\em The control structure for the HDE facility. \item\end{CompactList}\end{CompactItemize}
\subsection*{Typedefs}
\begin{CompactItemize}
\item 
typedef struct \hyperlink{struct__HDE__assay}{\_\-HDE\_\-assay} \hyperlink{HDE_8h_9e8558d8ce1358d5655e505a81f86b39}{HDE\_\-assay}
\begin{CompactList}\small\item\em Typedef for \_\-struct \hyperlink{struct__HDE__assay}{\_\-HDE\_\-assay}. \item\end{CompactList}\item 
\hypertarget{HDE_8h_004ed02bdc5c50cd4cc3754c94d93470}{
typedef struct \hyperlink{struct__HDE}{\_\-HDE} \hyperlink{HDE_8h_004ed02bdc5c50cd4cc3754c94d93470}{HDE}}
\label{HDE_8h_004ed02bdc5c50cd4cc3754c94d93470}

\begin{CompactList}\small\item\em Typedef for struct \hyperlink{struct__HDE}{\_\-HDE}. \item\end{CompactList}\end{CompactItemize}
\subsection*{Functions}
\begin{CompactItemize}
\item 
static \_\-\_\-inline \hyperlink{struct__HUFF__code}{HUFF\_\-code} \hyperlink{HDE_8h_9f027d6e8558148e6c82f337da789e52}{\_\-HDE\_\-codeS} (\hyperlink{struct__HDE}{HDE} $\ast$hde, short int symbol)
\begin{CompactList}\small\item\em Encodes a symbol using the encoding information in {\em hde\/}. This encoding information must have been previously setup using HDE\_\-encodeTable. \item\end{CompactList}\item 
static \_\-\_\-inline unsigned int \hyperlink{HDE_8h_1d423e301822f42dfcf4e0d731c3631d}{\_\-HDE\_\-symbolEncodeS} (\hyperlink{struct__HDE}{HDE} $\ast$hde, unsigned int $\ast$buf, unsigned int pos, short int symbol)
\begin{CompactList}\small\item\em Encodes a symbol using the encoding information in {\em hde\/}. This encoding information must have been previously setup using HDE\_\-encodeTable. \item\end{CompactList}\item 
void $\ast$ \hyperlink{HDE_8h_a9a74343d50b34a82b0433ff12acf8af}{HDE\_\-construct} (\hyperlink{struct__HDE}{HDE} $\ast$hde, unsigned int huffman\_\-nbins)
\begin{CompactList}\small\item\em Constructs (initializes) the specified HDE structure. \item\end{CompactList}\item 
unsigned int \hyperlink{HDE_8h_e69c53983ad9a1eaf66742f17095c7a7}{HDE\_\-sizeof} (unsigned int huffman\_\-nbins)
\begin{CompactList}\small\item\em Returns the size, in bytes, for a handle to hold a Huffman distribution of {\em huffman\_\-bins\/}. \item\end{CompactList}\item 
unsigned int \hyperlink{HDE_8h_cb2bd668c734a177c2289123f4cfce47}{HDE\_\-encodeSS} (\hyperlink{struct__HDE}{HDE} $\ast$hde, unsigned int $\ast$buf, unsigned int pos, unsigned int huffman\_\-bins, const unsigned short int $\ast$hist, int nbins, const short int $\ast$symbols, int nsymbols)
\begin{CompactList}\small\item\em Encodes the specified symbols {\em symbols\/} using the specified histogram of frequencies. Both the symbols and the histogram are presented as 16-bit values. \item\end{CompactList}\item 
const \hyperlink{struct__HDE__assay}{HDE\_\-assay} $\ast$ \hyperlink{HDE_8h_e4860342ea88bbf9b001f30bdff40615}{HDE\_\-assayLocate} (const \hyperlink{struct__HDE}{HDE} $\ast$hde)
\begin{CompactList}\small\item\em Returns a pointer to the publically defined piece of this structure. This can be a one-time call, i.e. for any given HDE structure, this routine always returns the same value. \item\end{CompactList}\item 
void \hyperlink{HDE_8h_f8abcce9ddab452adee90afb81ca4bd1}{HDE\_\-histClearS} (const \hyperlink{struct__HDE}{HDE} $\ast$hde, unsigned short int $\ast$hist)
\begin{CompactList}\small\item\em Clears the histogram using the active bin range stored in the HDE\_\-assay block of the HDE structure. \item\end{CompactList}\item 
void \hyperlink{HDE_8h_5ab4a5dccce0788e92054994730f53dc}{HDE\_\-histClearL} (const \hyperlink{struct__HDE}{HDE} $\ast$hde, unsigned int $\ast$hist)
\begin{CompactList}\small\item\em Clears the histogram using the active bin range stored in the HDE\_\-assay block of the HDE structure. \item\end{CompactList}\item 
void \hyperlink{HDE_8h_bdeab01b8fa2c20070c09a8a69c6db09}{HDE\_\-tableConstructL} (\hyperlink{struct__HDE}{HDE} $\ast$hde, unsigned int nhuff, const unsigned int $\ast$hist, int nbins, int nentries)
\begin{CompactList}\small\item\em Constructs HDE Huffman Table associated with the specified distribution. \item\end{CompactList}\item 
unsigned int \hyperlink{HDE_8h_2b7ea12756d6fd067b55c7075ded8be3}{HDE\_\-tableEncode} (\hyperlink{struct__HDE}{HDE} $\ast$hde, unsigned int $\ast$buf, unsigned int pos)
\begin{CompactList}\small\item\em Encodes a previously constructed table. \item\end{CompactList}\item 
unsigned int \hyperlink{HDE_8h_67b6e04a702dafe4cba2751d314d182e}{HDE\_\-symbolsEncodeS} (\hyperlink{struct__HDE}{HDE} $\ast$hde, unsigned int $\ast$buf, unsigned int pos, const short int $\ast$symbols, int nsymbols)
\begin{CompactList}\small\item\em Encodes the set of symbols using the encoding information in {\em hde\/}. This encoding information must have been previously setup using HDE\_\-encodeTable. \item\end{CompactList}\item 
\hypertarget{HDE_8h_4265d553e503f61608a7c581ec487fc9}{
unsigned int \textbf{HDE\_\-symbolEncodeS} (\hyperlink{struct__HDE}{HDE} $\ast$hde, unsigned int $\ast$buf, unsigned int pos, short int symbol)}
\label{HDE_8h_4265d553e503f61608a7c581ec487fc9}

\end{CompactItemize}


\subsection{Detailed Description}
Interface to the routines to encodes a distribution of symbols using a Huffman encoding technique. Routines are available to encode both the distribution itself and the resulting Huffman table. 

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


\footnotesize\begin{verbatim}

   CVS $Id: HDE.h,v 1.4 2010/08/06 19:00:29 saxton Exp $
\end{verbatim}
\normalsize
 

\subsection{Typedef Documentation}
\hypertarget{HDE_8h_9e8558d8ce1358d5655e505a81f86b39}{
\index{HDE.h@{HDE.h}!HDE_assay@{HDE\_\-assay}}
\index{HDE_assay@{HDE\_\-assay}!HDE.h@{HDE.h}}
\subsubsection{\setlength{\rightskip}{0pt plus 5cm}{\bf HDE\_\-assay}}}
\label{HDE_8h_9e8558d8ce1358d5655e505a81f86b39}


Typedef for \_\-struct \hyperlink{struct__HDE__assay}{\_\-HDE\_\-assay}. 

\begin{Desc}
\item[Warning:]The user should never allocate this structure. It should only be assessed via a pointer returned from HDE\_\-assayLocate. The information in here is mainly for diagnostic purposes, allowing those outside the package to gain some insight or monitor the HDE's inner workings.\end{Desc}
The one exception is that the field members {\em min\/} and {\em cnt\/} can be used to clear the histogram. This allows one to only zero those entries that have non-zero bins. Given that the size of the histogram may be large and that the number of incremented bins may be small, this is a big gain in efficiency. Consider histogramming an 12 bit ADC. A pedestal subtracted histogram could be out to 8192 bins, whereas the actual distribution may be $<$ 100 bins 

\subsection{Function Documentation}
\hypertarget{HDE_8h_9f027d6e8558148e6c82f337da789e52}{
\index{HDE.h@{HDE.h}!_HDE_codeS@{\_\-HDE\_\-codeS}}
\index{_HDE_codeS@{\_\-HDE\_\-codeS}!HDE.h@{HDE.h}}
\subsubsection{\setlength{\rightskip}{0pt plus 5cm}{\bf HUFF\_\-code} \_\-HDE\_\-codeS ({\bf HDE} $\ast$ {\em hde}, short int {\em symbol})\hspace{0.3cm}{\tt  \mbox{[}static\mbox{]}}}}
\label{HDE_8h_9f027d6e8558148e6c82f337da789e52}


Encodes a symbol using the encoding information in {\em hde\/}. This encoding information must have been previously setup using HDE\_\-encodeTable. 

\begin{Desc}
\item[Returns:]The encoded value\end{Desc}
\begin{Desc}
\item[Parameters:]
\begin{description}
\item[{\em hde}]The HDE control structure \item[{\em symbol}]The symbol \end{description}
\end{Desc}
\hypertarget{HDE_8h_1d423e301822f42dfcf4e0d731c3631d}{
\index{HDE.h@{HDE.h}!_HDE_symbolEncodeS@{\_\-HDE\_\-symbolEncodeS}}
\index{_HDE_symbolEncodeS@{\_\-HDE\_\-symbolEncodeS}!HDE.h@{HDE.h}}
\subsubsection{\setlength{\rightskip}{0pt plus 5cm}unsigned int \_\-HDE\_\-symbolEncodeS ({\bf HDE} $\ast$ {\em hde}, unsigned int $\ast$ {\em buf}, unsigned int {\em pos}, short int {\em symbol})\hspace{0.3cm}{\tt  \mbox{[}static\mbox{]}}}}
\label{HDE_8h_1d423e301822f42dfcf4e0d731c3631d}


Encodes a symbol using the encoding information in {\em hde\/}. This encoding information must have been previously setup using HDE\_\-encodeTable. 

\begin{Desc}
\item[Returns:]The updated bit write position\end{Desc}
\begin{Desc}
\item[Parameters:]
\begin{description}
\item[{\em hde}]The HDE control structure \item[{\em symbol}]The symbol \item[{\em buf}]The output buffer address \item[{\em pos}]The current write bit offset \end{description}
\end{Desc}
\hypertarget{HDE_8h_e4860342ea88bbf9b001f30bdff40615}{
\index{HDE.h@{HDE.h}!HDE_assayLocate@{HDE\_\-assayLocate}}
\index{HDE_assayLocate@{HDE\_\-assayLocate}!HDE.h@{HDE.h}}
\subsubsection{\setlength{\rightskip}{0pt plus 5cm}const {\bf HDE\_\-assay} $\ast$ HDE\_\-assayLocate (const {\bf HDE} $\ast$ {\em hde})}}
\label{HDE_8h_e4860342ea88bbf9b001f30bdff40615}


Returns a pointer to the publically defined piece of this structure. This can be a one-time call, i.e. for any given HDE structure, this routine always returns the same value. 

\begin{Desc}
\item[Returns:]Pointer to the HDE\_\-assay structure\end{Desc}
\begin{Desc}
\item[Parameters:]
\begin{description}
\item[{\em hde}]The HDE control structure\end{description}
\end{Desc}
The information returned is mainly of diagnostic use. However, knowing the min and max bin entry allows one to efficiently clear a previously used histogram. \hypertarget{HDE_8h_a9a74343d50b34a82b0433ff12acf8af}{
\index{HDE.h@{HDE.h}!HDE_construct@{HDE\_\-construct}}
\index{HDE_construct@{HDE\_\-construct}!HDE.h@{HDE.h}}
\subsubsection{\setlength{\rightskip}{0pt plus 5cm}void HDE\_\-construct ({\bf HDE} $\ast$ {\em hde}, unsigned int {\em nhuff})}}
\label{HDE_8h_a9a74343d50b34a82b0433ff12acf8af}


Constructs (initializes) the specified HDE structure. 

\begin{Desc}
\item[Returns:]The next address after this structure.\end{Desc}
\begin{Desc}
\item[Parameters:]
\begin{description}
\item[{\em hde}]The HDE control structure to construct \item[{\em nhuff}]The maximum number of Huffman encoding bins that this control structure is meant to support.\end{description}
\end{Desc}
The size of this structure should be acquired by a call to HDE\_\-sizeof. The parameter {\em huffman\_\-nbins\/} must be the same in the call to HDE\_\-sizeof and HDE\_\-construct. \hypertarget{HDE_8h_cb2bd668c734a177c2289123f4cfce47}{
\index{HDE.h@{HDE.h}!HDE_encodeSS@{HDE\_\-encodeSS}}
\index{HDE_encodeSS@{HDE\_\-encodeSS}!HDE.h@{HDE.h}}
\subsubsection{\setlength{\rightskip}{0pt plus 5cm}unsigned int HDE\_\-encodeSS ({\bf HDE} $\ast$ {\em hde}, unsigned int $\ast$ {\em buf}, unsigned int {\em pos}, unsigned int {\em nhuff}, const unsigned short int $\ast$ {\em hist}, int {\em nbins}, const short int $\ast$ {\em symbols}, int {\em nsymbols})}}
\label{HDE_8h_cb2bd668c734a177c2289123f4cfce47}


Encodes the specified symbols {\em symbols\/} using the specified histogram of frequencies. Both the symbols and the histogram are presented as 16-bit values. 

\begin{Desc}
\item[Returns:]The updated bit write position\end{Desc}
\begin{Desc}
\item[Parameters:]
\begin{description}
\item[{\em hde}]The HDE control structure \item[{\em buf}]The output buffer address \item[{\em pos}]The current write bit offset \item[{\em nhuff}]Provides a means to limit the size of the huffman encoding region to a region that is smaller than what was specified during the HDE construction (i.e. the {\em nhuff\/} parameter) The construction value is used, if this value is 0 or larger. \item[{\em hist}]The frequency histogram. The histogram is such that it extends -/+ nbins from this pointer. That is, this is the center of the histogram. \item[{\em nbins}]The half width of the histogram \item[{\em symbols}]The array of symbols \item[{\em nsymbols}]The number of symbols \end{description}
\end{Desc}
\hypertarget{HDE_8h_5ab4a5dccce0788e92054994730f53dc}{
\index{HDE.h@{HDE.h}!HDE_histClearL@{HDE\_\-histClearL}}
\index{HDE_histClearL@{HDE\_\-histClearL}!HDE.h@{HDE.h}}
\subsubsection{\setlength{\rightskip}{0pt plus 5cm}void HDE\_\-histClearL (const {\bf HDE} $\ast$ {\em hde}, unsigned int $\ast$ {\em hist})}}
\label{HDE_8h_5ab4a5dccce0788e92054994730f53dc}


Clears the histogram using the active bin range stored in the HDE\_\-assay block of the HDE structure. 

\begin{Desc}
\item[Parameters:]
\begin{description}
\item[{\em hde}]The HDE control handle \item[{\em hist}]The histogram to clear\end{description}
\end{Desc}
This routine must be called after HDE\_\-encodeSS has been called, since it is that routine that sets up the HDE\_\-assay block \hypertarget{HDE_8h_f8abcce9ddab452adee90afb81ca4bd1}{
\index{HDE.h@{HDE.h}!HDE_histClearS@{HDE\_\-histClearS}}
\index{HDE_histClearS@{HDE\_\-histClearS}!HDE.h@{HDE.h}}
\subsubsection{\setlength{\rightskip}{0pt plus 5cm}void HDE\_\-histClearS (const {\bf HDE} $\ast$ {\em hde}, unsigned short int $\ast$ {\em hist})}}
\label{HDE_8h_f8abcce9ddab452adee90afb81ca4bd1}


Clears the histogram using the active bin range stored in the HDE\_\-assay block of the HDE structure. 

\begin{Desc}
\item[Parameters:]
\begin{description}
\item[{\em hde}]The HDE control handle \item[{\em hist}]The histogram to clear\end{description}
\end{Desc}
This routine must be called after HDE\_\-encodeSS has been called, since it is that routine that sets up the HDE\_\-assay block \hypertarget{HDE_8h_e69c53983ad9a1eaf66742f17095c7a7}{
\index{HDE.h@{HDE.h}!HDE_sizeof@{HDE\_\-sizeof}}
\index{HDE_sizeof@{HDE\_\-sizeof}!HDE.h@{HDE.h}}
\subsubsection{\setlength{\rightskip}{0pt plus 5cm}unsigned int HDE\_\-sizeof (unsigned int {\em nhuff})}}
\label{HDE_8h_e69c53983ad9a1eaf66742f17095c7a7}


Returns the size, in bytes, for a handle to hold a Huffman distribution of {\em huffman\_\-bins\/}. 

\begin{Desc}
\item[Parameters:]
\begin{description}
\item[{\em nhuff}]The maximum size of the Huffman encoding area Suggested values are small powers of 2 like 32, 64, 128. Note also up to 3 bins may be used to hold describe the underflow, overflow and exception areas. Currently these 3 are mapped into 1 bin, but this may change in a future implementation\end{description}
\end{Desc}
For the most part, this only provides a working area. On host-based workstations with expandable stacks, this memory would go on the stack, but, it is too large to do this for embedded systems. \hypertarget{HDE_8h_67b6e04a702dafe4cba2751d314d182e}{
\index{HDE.h@{HDE.h}!HDE_symbolsEncodeS@{HDE\_\-symbolsEncodeS}}
\index{HDE_symbolsEncodeS@{HDE\_\-symbolsEncodeS}!HDE.h@{HDE.h}}
\subsubsection{\setlength{\rightskip}{0pt plus 5cm}unsigned int HDE\_\-symbolsEncodeS ({\bf HDE} $\ast$ {\em hde}, unsigned int $\ast$ {\em buf}, unsigned int {\em pos}, const short int $\ast$ {\em symbols}, int {\em nsymbols})}}
\label{HDE_8h_67b6e04a702dafe4cba2751d314d182e}


Encodes the set of symbols using the encoding information in {\em hde\/}. This encoding information must have been previously setup using HDE\_\-encodeTable. 

\begin{Desc}
\item[Returns:]The updated bit write position\end{Desc}
\begin{Desc}
\item[Parameters:]
\begin{description}
\item[{\em hde}]The HDE control structure \item[{\em symbols}]The array of symbols \item[{\em nsymbols}]The number of symbols \item[{\em buf}]The output buffer address \item[{\em pos}]The current write bit offset \end{description}
\end{Desc}
\hypertarget{HDE_8h_bdeab01b8fa2c20070c09a8a69c6db09}{
\index{HDE.h@{HDE.h}!HDE_tableConstructL@{HDE\_\-tableConstructL}}
\index{HDE_tableConstructL@{HDE\_\-tableConstructL}!HDE.h@{HDE.h}}
\subsubsection{\setlength{\rightskip}{0pt plus 5cm}void HDE\_\-tableConstructL ({\bf HDE} $\ast$ {\em hde}, unsigned int {\em nhuff}, const unsigned int $\ast$ {\em hist}, int {\em nbins}, int {\em nentries})}}
\label{HDE_8h_bdeab01b8fa2c20070c09a8a69c6db09}


Constructs HDE Huffman Table associated with the specified distribution. 

\begin{Desc}
\item[Returns:]The updated bit write position\end{Desc}
\begin{Desc}
\item[Parameters:]
\begin{description}
\item[{\em hde}]The HDE control structure \item[{\em nhuff}]Provides a means to limit the size of the huffman encoding region to a region that is smaller than what was specified during the HDE construction (i.e. the {\em nhuff\/} parameter) The construction value is used, if this value is 0 or larger. \item[{\em hist}]The frequency histogram. The histogram is such that it extends -/+ nbins from this pointer. That is, this is the center of the histogram. \item[{\em nbins}]The half width of the histogram \item[{\em nentries}]The number of entries in the histogram \end{description}
\end{Desc}
\hypertarget{HDE_8h_2b7ea12756d6fd067b55c7075ded8be3}{
\index{HDE.h@{HDE.h}!HDE_tableEncode@{HDE\_\-tableEncode}}
\index{HDE_tableEncode@{HDE\_\-tableEncode}!HDE.h@{HDE.h}}
\subsubsection{\setlength{\rightskip}{0pt plus 5cm}unsigned int HDE\_\-tableEncode ({\bf HDE} $\ast$ {\em hde}, unsigned int $\ast$ {\em buf}, unsigned int {\em pos})}}
\label{HDE_8h_2b7ea12756d6fd067b55c7075ded8be3}


Encodes a previously constructed table. 

\begin{Desc}
\item[Returns:]The updated bit write position\end{Desc}
\begin{Desc}
\item[Parameters:]
\begin{description}
\item[{\em hde}]The HDE control structure \item[{\em buf}]The output buffer address \item[{\em pos}]The current write bit offset \end{description}
\end{Desc}