\hypertarget{decompress_8c}{
\section{decompress.c File Reference}
\label{decompress_8c}\index{decompress.c@{decompress.c}}
}
Routines used to manipulate the tables used to decode the compressed events. 

{\tt \#include \char`\"{}decompress\_\-p.h\char`\"{}}\par
{\tt \#include \char`\"{}LDT/APM.h\char`\"{}}\par
{\tt \#include $<$string.h$>$}\par
{\tt \#include $<$math.h$>$}\par


Include dependency graph for decompress.c:\begin{figure}[H]
\begin{center}
\leavevmode
\includegraphics[width=244pt]{decompress_8c__incl}
\end{center}
\end{figure}
\subsection*{Functions}
\begin{CompactItemize}
\item 
static const unsigned $\ast$ \hyperlink{decompress_8c_a0}{getwrd} (const unsigned $\ast$buffer, unsigned $\ast$bcnt, unsigned $\ast$word, unsigned nbits)
\begin{CompactList}\small\item\em Get bits from a buffer. \item\end{CompactList}\item 
double \hyperlink{decompress_8c_a1}{calc\_\-nbits} (const int $\ast$f, int cnt, int tot)
\begin{CompactList}\small\item\em Calculate the number of bits need to encode a sample with the specified frequency distribution. \item\end{CompactList}\item 
size\_\-t \hyperlink{decompress_8c_a2}{QSEC\_\-sizeof\-Decompression} (unsigned int nbits)
\begin{CompactList}\small\item\em Calculate the total size required to accomodate a decompression structure. \item\end{CompactList}\item 
\hyperlink{structQSEC__decompression__}{QSEC\_\-decompression} $\ast$ \hyperlink{decompress_8c_a3}{QSEC\_\-construct\-Decompression} (void $\ast$buffer, unsigned int nbits, const char $\ast$name)
\begin{CompactList}\small\item\em Initialise the buffer as a decompression structure. \item\end{CompactList}\item 
\hyperlink{structQSEC__decompression__}{QSEC\_\-decompression} $\ast$ \hyperlink{decompress_8c_a4}{QSEC\_\-new\-Decompression} (unsigned int nbits, const char $\ast$name)
\begin{CompactList}\small\item\em Allocate and initialise a new decompression structure. \item\end{CompactList}\item 
void \hyperlink{decompress_8c_a5}{QSEC\_\-delete\-Decompression} (\hyperlink{structQSEC__decompression__}{QSEC\_\-decompression} $\ast$dcm)
\begin{CompactList}\small\item\em Free the memory associated with the decompression structure. \item\end{CompactList}\item 
void \hyperlink{decompress_8c_a6}{QSEC\_\-clear\-Decompression} (\hyperlink{structQSEC__decompression__}{QSEC\_\-decompression} $\ast$dcm)
\begin{CompactList}\small\item\em Clear the decompression structrure of any data from a previous cycle. \item\end{CompactList}\item 
unsigned int \hyperlink{decompress_8c_a7}{QSEC\_\-get\-Count} (\hyperlink{structQSEC__decompression__}{QSEC\_\-decompression} $\ast$dcm)
\begin{CompactList}\small\item\em Return the number of non-zero bins in the histogram. \item\end{CompactList}\item 
const unsigned int $\ast$ \hyperlink{decompress_8c_a8}{QSEC\_\-unpack} (\hyperlink{structQSEC__decompression__}{QSEC\_\-decompression} $\ast$dcm, const unsigned int $\ast$buffer)
\begin{CompactList}\small\item\em Build the lookup and freqency tables by retrieving and unpacking data from the consignment. \item\end{CompactList}\item 
unsigned \hyperlink{decompress_8c_a9}{QSEC\_\-decompress} (\hyperlink{structQSEC__decompression__}{QSEC\_\-decompression} $\ast$dcm, APD\_\-dtx $\ast$dtx)
\begin{CompactList}\small\item\em Decode the next symbol. \item\end{CompactList}\item 
void \hyperlink{decompress_8c_a10}{QSEC\_\-report\-Decompression} (\hyperlink{structQSEC__decompression__}{QSEC\_\-decompression} $\ast$dcm, FILE $\ast$fp)
\begin{CompactList}\small\item\em Describe the contents of the decompression structure in formatted ASCII send to the file {\em fp\/}. \item\end{CompactList}\end{CompactItemize}


\subsection{Detailed Description}
Routines used to manipulate the tables used to decode the compressed events. 

\begin{Desc}
\item[Author:]James Swain \& Owen Saxton\end{Desc}
\begin{Desc}
\item[Id]\hyperlink{decompress_8c}{decompress.c},v 1.8 2007/04/05 23:05:17 saxton Exp \end{Desc}


\subsection{Function Documentation}
\hypertarget{decompress_8c_a1}{
\index{decompress.c@{decompress.c}!calc_nbits@{calc\_\-nbits}}
\index{calc_nbits@{calc\_\-nbits}!decompress.c@{decompress.c}}
\subsubsection[calc\_\-nbits]{\setlength{\rightskip}{0pt plus 5cm}double calc\_\-nbits (const int $\ast$ {\em f}, int {\em cnt}, int {\em tot})}}
\label{decompress_8c_a1}


Calculate the number of bits need to encode a sample with the specified frequency distribution. 

This is based on the following formula

nbits = - TOT $\ast$ SUM \mbox{[} f\mbox{[}i\mbox{]} / TOT $\ast$ ln (f\mbox{[}i\mbox{]} / TOT) \mbox{]} = - TOT/TOT $\ast$ SUM \mbox{[} f\mbox{[}i\mbox{]} $\ast$ (ln (f\mbox{[}i\mbox{]}) - ln (TOT)) \mbox{]} = - SUM \mbox{[} f\mbox{[}i\mbox{]} $\ast$ ln (f\mbox{[}i\mbox{]} \mbox{]} + SUM \mbox{[} f\mbox{[}i\mbox{]} $\ast$ ln (TOT) \mbox{]} = - SUM \mbox{[} f\mbox{[}i\mbox{]} $\ast$ ln (f\mbox{[}i\mbox{]} \mbox{]} + TOT $\ast$ ln (TOT) \mbox{]}

\begin{Desc}
\item[Parameters:]
\begin{description}
\item[{\em f}]The frequency distribution\item[{\em cnt}]The count of entries in the frequency distribution\item[{\em tot}]The total number of entries in the frequency distribution\end{description}
\end{Desc}
\hypertarget{decompress_8c_a0}{
\index{decompress.c@{decompress.c}!getwrd@{getwrd}}
\index{getwrd@{getwrd}!decompress.c@{decompress.c}}
\subsubsection[getwrd]{\setlength{\rightskip}{0pt plus 5cm}const unsigned $\ast$ getwrd (const unsigned $\ast$ {\em buffer}, unsigned $\ast$ {\em bcnt}, unsigned $\ast$ {\em word}, unsigned {\em nbits})\hspace{0.3cm}{\tt  \mbox{[}inline, static\mbox{]}}}}
\label{decompress_8c_a0}


Get bits from a buffer. 

\begin{Desc}
\item[Parameters:]
\begin{description}
\item[{\em buffer}]Pointer to the current word in the buffer\item[{\em bcnt}]Number of bits already used in the current word\item[{\em word}]Word to add to the buffer\item[{\em nbits}]Number of bits from the word to add to the buffer\end{description}
\end{Desc}
\begin{Desc}
\item[Returns:]Pointer to the next word to use in the buffer\end{Desc}
\hypertarget{decompress_8c_a6}{
\index{decompress.c@{decompress.c}!QSEC_clearDecompression@{QSEC\_\-clearDecompression}}
\index{QSEC_clearDecompression@{QSEC\_\-clearDecompression}!decompress.c@{decompress.c}}
\subsubsection[QSEC\_\-clearDecompression]{\setlength{\rightskip}{0pt plus 5cm}void QSEC\_\-clear\-Decompression (\hyperlink{structQSEC__decompression__}{QSEC\_\-decompression} $\ast$ {\em dcm})}}
\label{decompress_8c_a6}


Clear the decompression structrure of any data from a previous cycle. 

\begin{Desc}
\item[Parameters:]
\begin{description}
\item[{\em dcm}]Pointer to an allocated, initialised, decompression structure\end{description}
\end{Desc}
\hypertarget{decompress_8c_a3}{
\index{decompress.c@{decompress.c}!QSEC_constructDecompression@{QSEC\_\-constructDecompression}}
\index{QSEC_constructDecompression@{QSEC\_\-constructDecompression}!decompress.c@{decompress.c}}
\subsubsection[QSEC\_\-constructDecompression]{\setlength{\rightskip}{0pt plus 5cm}\hyperlink{structQSEC__decompression__}{QSEC\_\-decompression}$\ast$ QSEC\_\-construct\-Decompression (void $\ast$ {\em buffer}, unsigned int {\em nbits}, const char $\ast$ {\em name})}}
\label{decompress_8c_a3}


Initialise the buffer as a decompression structure. 

\begin{Desc}
\item[Parameters:]
\begin{description}
\item[{\em buffer}]Pointer to the uninitialised memory to use for this decompression structure\item[{\em nbits}]Number of bits in the symbols to be handled by this decompression strcuture\item[{\em name}]String identifying this structure\end{description}
\end{Desc}
\begin{Desc}
\item[Returns:]Pointer to an initialised decompression structure\end{Desc}
\hypertarget{decompress_8c_a9}{
\index{decompress.c@{decompress.c}!QSEC_decompress@{QSEC\_\-decompress}}
\index{QSEC_decompress@{QSEC\_\-decompress}!decompress.c@{decompress.c}}
\subsubsection[QSEC\_\-decompress]{\setlength{\rightskip}{0pt plus 5cm}unsigned QSEC\_\-decompress (\hyperlink{structQSEC__decompression__}{QSEC\_\-decompression} $\ast$ {\em dcm}, APD\_\-dtx $\ast$ {\em dtx})}}
\label{decompress_8c_a9}


Decode the next symbol. 

\begin{Desc}
\item[Parameters:]
\begin{description}
\item[{\em dcm}]Pointer to an initialsed, populated and processed decompression structure\item[{\em dtx}]Pointer to the arithmetic encoder context\end{description}
\end{Desc}
\begin{Desc}
\item[Returns:]The next symbol\end{Desc}
\hypertarget{decompress_8c_a5}{
\index{decompress.c@{decompress.c}!QSEC_deleteDecompression@{QSEC\_\-deleteDecompression}}
\index{QSEC_deleteDecompression@{QSEC\_\-deleteDecompression}!decompress.c@{decompress.c}}
\subsubsection[QSEC\_\-deleteDecompression]{\setlength{\rightskip}{0pt plus 5cm}void QSEC\_\-delete\-Decompression (\hyperlink{structQSEC__decompression__}{QSEC\_\-decompression} $\ast$ {\em dcm})}}
\label{decompress_8c_a5}


Free the memory associated with the decompression structure. 

\begin{Desc}
\item[Parameters:]
\begin{description}
\item[{\em dcm}]Pointer to an allocated decompression structure\end{description}
\end{Desc}
\hypertarget{decompress_8c_a7}{
\index{decompress.c@{decompress.c}!QSEC_getCount@{QSEC\_\-getCount}}
\index{QSEC_getCount@{QSEC\_\-getCount}!decompress.c@{decompress.c}}
\subsubsection[QSEC\_\-getCount]{\setlength{\rightskip}{0pt plus 5cm}unsigned int QSEC\_\-get\-Count (\hyperlink{structQSEC__decompression__}{QSEC\_\-decompression} $\ast$ {\em dcm})}}
\label{decompress_8c_a7}


Return the number of non-zero bins in the histogram. 

\begin{Desc}
\item[Parameters:]
\begin{description}
\item[{\em dcm}]Pointer to a decompression structure\end{description}
\end{Desc}
\begin{Desc}
\item[Returns:]Number of non-zero bins in the histogram\end{Desc}
\hypertarget{decompress_8c_a4}{
\index{decompress.c@{decompress.c}!QSEC_newDecompression@{QSEC\_\-newDecompression}}
\index{QSEC_newDecompression@{QSEC\_\-newDecompression}!decompress.c@{decompress.c}}
\subsubsection[QSEC\_\-newDecompression]{\setlength{\rightskip}{0pt plus 5cm}\hyperlink{structQSEC__decompression__}{QSEC\_\-decompression}$\ast$ QSEC\_\-new\-Decompression (unsigned int {\em nbits}, const char $\ast$ {\em name})}}
\label{decompress_8c_a4}


Allocate and initialise a new decompression structure. 

\begin{Desc}
\item[Parameters:]
\begin{description}
\item[{\em name}]String used in the reporting of error to identify a decompression structure\item[{\em nbits}]Number of symbols in the complete range of possible symbols (including excluded internal sub-ranges), hence the number of bins in the histogram and frequency tables\end{description}
\end{Desc}
\begin{Desc}
\item[Returns:]Pointer to an allocated and initialised QSEC\_\-decompression structure\end{Desc}
\hypertarget{decompress_8c_a10}{
\index{decompress.c@{decompress.c}!QSEC_reportDecompression@{QSEC\_\-reportDecompression}}
\index{QSEC_reportDecompression@{QSEC\_\-reportDecompression}!decompress.c@{decompress.c}}
\subsubsection[QSEC\_\-reportDecompression]{\setlength{\rightskip}{0pt plus 5cm}void QSEC\_\-report\-Decompression (\hyperlink{structQSEC__decompression__}{QSEC\_\-decompression} $\ast$ {\em dcm}, FILE $\ast$ {\em fp})}}
\label{decompress_8c_a10}


Describe the contents of the decompression structure in formatted ASCII send to the file {\em fp\/}. 

\begin{Desc}
\item[Parameters:]
\begin{description}
\item[{\em dcm}]Pointer to the decompression structure\item[{\em fp}]Pointer to the file used as the destination\end{description}
\end{Desc}
\hypertarget{decompress_8c_a2}{
\index{decompress.c@{decompress.c}!QSEC_sizeofDecompression@{QSEC\_\-sizeofDecompression}}
\index{QSEC_sizeofDecompression@{QSEC\_\-sizeofDecompression}!decompress.c@{decompress.c}}
\subsubsection[QSEC\_\-sizeofDecompression]{\setlength{\rightskip}{0pt plus 5cm}size\_\-t QSEC\_\-sizeof\-Decompression (unsigned int {\em nbits})}}
\label{decompress_8c_a2}


Calculate the total size required to accomodate a decompression structure. 

\begin{Desc}
\item[Parameters:]
\begin{description}
\item[{\em nbits}]Number of symbols in the complete range of possible symbols (including excluded internal sub-ranges), hence the number of bins in the histogram and frequency tables\end{description}
\end{Desc}
\begin{Desc}
\item[Returns:]Size of memory block required to accomodate a decompression structure\end{Desc}
\hypertarget{decompress_8c_a8}{
\index{decompress.c@{decompress.c}!QSEC_unpack@{QSEC\_\-unpack}}
\index{QSEC_unpack@{QSEC\_\-unpack}!decompress.c@{decompress.c}}
\subsubsection[QSEC\_\-unpack]{\setlength{\rightskip}{0pt plus 5cm}const unsigned int$\ast$ QSEC\_\-unpack (\hyperlink{structQSEC__decompression__}{QSEC\_\-decompression} $\ast$ {\em dcm}, const unsigned int $\ast$ {\em buffer})}}
\label{decompress_8c_a8}


Build the lookup and freqency tables by retrieving and unpacking data from the consignment. 

\begin{Desc}
\item[Parameters:]
\begin{description}
\item[{\em dcm}]Pointer to an initialsed decompression structure\item[{\em buffer}]Pointer to the start of the buffer holding the packed structure\end{description}
\end{Desc}
\begin{Desc}
\item[Returns:]Pointer to the next input location or NULL if there is an error in the unpacking\end{Desc}