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



This graph shows which files directly or indirectly include this file:\begin{figure}[H]
\begin{center}
\leavevmode
\includegraphics[width=87pt]{HDE_8h__dep__incl}
\end{center}
\end{figure}
\subsection*{Data Structures}
\begin{CompactItemize}
\item 
struct \hyperlink{struct__HDE__assay}{\_\-HDE\_\-assay}
\begin{CompactList}\small\item\em The result of the histogram assessment. \item\end{CompactList}\end{CompactItemize}
\subsection*{Typedefs}
\begin{CompactItemize}
\item 
\hypertarget{HDE_8h_a0}{
typedef \hyperlink{struct__HDE}{\_\-HDE} \hyperlink{HDE_8h_a0}{HDE}}
\label{HDE_8h_a0}

\begin{CompactList}\small\item\em Typedef for struct \hyperlink{struct__HDE}{\_\-HDE}. \item\end{CompactList}\item 
typedef \hyperlink{struct__HDE__assay}{\_\-HDE\_\-assay} \hyperlink{HDE_8h_a1}{HDE\_\-assay}
\begin{CompactList}\small\item\em Typedef for \_\-struct \hyperlink{struct__HDE__assay}{\_\-HDE\_\-assay}. \item\end{CompactList}\end{CompactItemize}
\subsection*{Functions}
\begin{CompactItemize}
\item 
void $\ast$ \hyperlink{HDE_8h_a2}{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_a3}{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_a4}{HDE\_\-encode\-SS} (\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_a5}{HDE\_\-assay\-Locate} (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_a6}{HDE\_\-hist\-Clear\-S} (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}\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.2 2006/11/01 21:23:34 russell Exp $
\end{verbatim}
\normalsize


\subsection{Typedef Documentation}
\hypertarget{HDE_8h_a1}{
\index{HDE.h@{HDE.h}!HDE_assay@{HDE\_\-assay}}
\index{HDE_assay@{HDE\_\-assay}!HDE.h@{HDE.h}}
\subsubsection[HDE\_\-assay]{\setlength{\rightskip}{0pt plus 5cm}\hyperlink{struct__HDE__assay}{HDE\_\-assay}}}
\label{HDE_8h_a1}


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\_\-assay\-Locate. 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_a5}{
\index{HDE.h@{HDE.h}!HDE_assayLocate@{HDE\_\-assayLocate}}
\index{HDE_assayLocate@{HDE\_\-assayLocate}!HDE.h@{HDE.h}}
\subsubsection[HDE\_\-assayLocate]{\setlength{\rightskip}{0pt plus 5cm}const \hyperlink{struct__HDE__assay}{HDE\_\-assay} $\ast$ HDE\_\-assay\-Locate (const \hyperlink{struct__HDE}{HDE} $\ast$ {\em hde})}}
\label{HDE_8h_a5}


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_a2}{
\index{HDE.h@{HDE.h}!HDE_construct@{HDE\_\-construct}}
\index{HDE_construct@{HDE\_\-construct}!HDE.h@{HDE.h}}
\subsubsection[HDE\_\-construct]{\setlength{\rightskip}{0pt plus 5cm}void HDE\_\-construct (\hyperlink{struct__HDE}{HDE} $\ast$ {\em hde}, unsigned int {\em nhuff})}}
\label{HDE_8h_a2}


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_a4}{
\index{HDE.h@{HDE.h}!HDE_encodeSS@{HDE\_\-encodeSS}}
\index{HDE_encodeSS@{HDE\_\-encodeSS}!HDE.h@{HDE.h}}
\subsubsection[HDE\_\-encodeSS]{\setlength{\rightskip}{0pt plus 5cm}unsigned int HDE\_\-encode\-SS (\hyperlink{struct__HDE}{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_a4}


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_a6}{
\index{HDE.h@{HDE.h}!HDE_histClearS@{HDE\_\-histClearS}}
\index{HDE_histClearS@{HDE\_\-histClearS}!HDE.h@{HDE.h}}
\subsubsection[HDE\_\-histClearS]{\setlength{\rightskip}{0pt plus 5cm}void HDE\_\-hist\-Clear\-S (const \hyperlink{struct__HDE}{HDE} $\ast$ {\em hde}, unsigned short int $\ast$ {\em hist})}}
\label{HDE_8h_a6}


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\_\-encode\-SS has been called, since it is that routine that sets up the HDE\_\-assay block\hypertarget{HDE_8h_a3}{
\index{HDE.h@{HDE.h}!HDE_sizeof@{HDE\_\-sizeof}}
\index{HDE_sizeof@{HDE\_\-sizeof}!HDE.h@{HDE.h}}
\subsubsection[HDE\_\-sizeof]{\setlength{\rightskip}{0pt plus 5cm}unsigned int HDE\_\-sizeof (unsigned int {\em nhuff})}}
\label{HDE_8h_a3}


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.