\hypertarget{compress_8c}{
\section{compress.c File Reference}
\label{compress_8c}\index{compress.c@{compress.c}}
}
Routines acting upon the compression structure.  


{\tt \#include $<$compress.h$>$}\par
{\tt \#include $<$LSEC\_\-p.h$>$}\par
{\tt \#include $<$LSEC/LSEC\_\-msgs.h$>$}\par
{\tt \#include $<$LDT/APM.h$>$}\par
{\tt \#include $<$LDT/HDE.h$>$}\par
{\tt \#include $<$PBS/MBA.h$>$}\par
{\tt \#include $<$MSG/MSG\_\-pubdefs.h$>$}\par
{\tt \#include $<$string.h$>$}\par
\subsection*{Functions}
\begin{CompactItemize}
\item 
unsigned \hyperlink{compress_8c_4e30e2799924878b9d90e43e07bf43ab}{LSEC\_\-checkCompression} (\hyperlink{struct__LSEC__compression}{LSEC\_\-compression} $\ast$cpr)
\begin{CompactList}\small\item\em Check if there were errors during the histogram or encode operations. \item\end{CompactList}\item 
void \hyperlink{compress_8c_5b8711823ba4cdc678b9e36e73d7d69f}{LSEC\_\-clearCompression} (\hyperlink{struct__LSEC__compression}{LSEC\_\-compression} $\ast$cpr)
\begin{CompactList}\small\item\em Clear the compression structrure of any data from a previous cycle. \item\end{CompactList}\item 
void \hyperlink{compress_8c_7f15cada460e7ec8dbce47ad05626a91}{LSEC\_\-deleteCompression} (\hyperlink{struct__LSEC__compression}{LSEC\_\-compression} $\ast$cpr)
\begin{CompactList}\small\item\em Free the memory associated with the compression structure. \item\end{CompactList}\item 
unsigned int \hyperlink{compress_8c_e00495b47926f052ea308d7a961e1b71}{LSEC\_\-getBin} (\hyperlink{struct__LSEC__compression}{LSEC\_\-compression} $\ast$cpr, unsigned int bin)
\begin{CompactList}\small\item\em Return the contents of one bin of the histogram. \item\end{CompactList}\item 
unsigned int \hyperlink{compress_8c_336beb375c102af5777e40bf23da97a0}{LSEC\_\-getCount} (\hyperlink{struct__LSEC__compression}{LSEC\_\-compression} $\ast$cpr)
\begin{CompactList}\small\item\em Return the number of non-zero bins in the histogram. \item\end{CompactList}\item 
\hyperlink{struct__LSEC__compression}{LSEC\_\-compression} $\ast$ \hyperlink{compress_8c_e054d020b998d52290c930a49bacd810}{LSEC\_\-newCompression} (unsigned int nbits, const char $\ast$name)
\begin{CompactList}\small\item\em Allocate and initialise a new compression structure for APE encoding. \item\end{CompactList}\item 
\hyperlink{struct__LSEC__compression}{LSEC\_\-compression} $\ast$ \hyperlink{compress_8c_dbe62103d9fc4b3aa6d95608a1c4bdd8}{LSEC\_\-newCompressionH} (unsigned int nbits, const char $\ast$name)
\begin{CompactList}\small\item\em Allocate and initialise a new compression structure for Huffman encoding. \item\end{CompactList}\item 
unsigned $\ast$ \hyperlink{compress_8c_36d0e87844845da7d427ceb6dfb51a76}{LSEC\_\-pack} (\hyperlink{struct__LSEC__compression}{LSEC\_\-compression} $\ast$cpr, unsigned $\ast$buffer)
\begin{CompactList}\small\item\em Pack the tables of a compression structure into a buffer. \item\end{CompactList}\item 
unsigned int \hyperlink{compress_8c_8db296e748ac37ec50b8f2dbffb1658e}{LSEC\_\-packedSize32} (\hyperlink{struct__LSEC__compression}{LSEC\_\-compression} $\ast$cpr)
\begin{CompactList}\small\item\em Calculate the size of a packed compression structure. \item\end{CompactList}\item 
unsigned \hyperlink{compress_8c_fd634cbb818bc39bc847316e94029ef4}{LSEC\_\-process} (\hyperlink{struct__LSEC__compression}{LSEC\_\-compression} $\ast$cpr)
\begin{CompactList}\small\item\em Build the lookup, frequency and probability tables required by the APE. \item\end{CompactList}\item 
void \hyperlink{compress_8c_3a0649036e3f6f60f97c6eb8bcb8e80d}{LSEC\_\-reportCompression} (\hyperlink{struct__LSEC__compression}{LSEC\_\-compression} $\ast$cpr, FILE $\ast$fp)
\begin{CompactList}\small\item\em Describe the contents of a compression structure. \item\end{CompactList}\item 
void \hyperlink{compress_8c_e623d1692858d09fce861dc543a9487c}{LSEC\_\-zeroBin} (\hyperlink{struct__LSEC__compression}{LSEC\_\-compression} $\ast$cpr, unsigned int bin)
\begin{CompactList}\small\item\em Set the selected bin of the histogram to zero. \item\end{CompactList}\end{CompactItemize}


\subsection{Detailed Description}
Routines acting upon the compression structure. 

\begin{Desc}
\item[Author:]James Swain \& Owen Saxton\end{Desc}
{\bf \$Id:} \hyperlink{compress_8c}{compress.c},v 1.13 2011/03/27 17:44:40 saxton Exp \$ 

\subsection{Function Documentation}
\hypertarget{compress_8c_4e30e2799924878b9d90e43e07bf43ab}{
\index{compress.c@{compress.c}!LSEC\_\-checkCompression@{LSEC\_\-checkCompression}}
\index{LSEC\_\-checkCompression@{LSEC\_\-checkCompression}!compress.c@{compress.c}}
\subsubsection[{LSEC\_\-checkCompression}]{\setlength{\rightskip}{0pt plus 5cm}unsigned LSEC\_\-checkCompression ({\bf LSEC\_\-compression} $\ast$ {\em cpr})}}
\label{compress_8c_4e30e2799924878b9d90e43e07bf43ab}


Check if there were errors during the histogram or encode operations. 

\begin{Desc}
\item[Parameters:]
\begin{description}
\item[{\em cpr}]Pointer to a compression structure\end{description}
\end{Desc}
\begin{Desc}
\item[Return values:]
\begin{description}
\item[{\em LSEC\_\-SYMOOR}]If any of the symbols histogrammed or encoded by this compression structure were out of range \item[{\em LSEC\_\-AWEFAIL}]If there were any error during the encoding \item[{\em LSEC\_\-SUCCESS}]If there were no errors \end{description}
\end{Desc}


References \_\-LSEC\_\-compression::encerr, \_\-LSEC\_\-compression::name, and \_\-LSEC\_\-compression::ovrflw.

Referenced by LSEC\_\-checkCalCompaction().\hypertarget{compress_8c_5b8711823ba4cdc678b9e36e73d7d69f}{
\index{compress.c@{compress.c}!LSEC\_\-clearCompression@{LSEC\_\-clearCompression}}
\index{LSEC\_\-clearCompression@{LSEC\_\-clearCompression}!compress.c@{compress.c}}
\subsubsection[{LSEC\_\-clearCompression}]{\setlength{\rightskip}{0pt plus 5cm}void LSEC\_\-clearCompression ({\bf LSEC\_\-compression} $\ast$ {\em cpr})}}
\label{compress_8c_5b8711823ba4cdc678b9e36e73d7d69f}


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

\begin{Desc}
\item[Parameters:]
\begin{description}
\item[{\em cpr}]Pointer to an allocated, initialised, compression structure \end{description}
\end{Desc}


References LSEC\_\-compressionDesc::count, \_\-LSEC\_\-compression::desc, \_\-LSEC\_\-compression::encerr, LSEC\_\-compressionDesc::first\_\-bin, \_\-LSEC\_\-compression::hist, \_\-LSEC\_\-compression::last\_\-bin, \_\-LSEC\_\-compression::nbits, and \_\-LSEC\_\-compression::ovrflw.

Referenced by LSEC\_\-clearCalCompaction().\hypertarget{compress_8c_7f15cada460e7ec8dbce47ad05626a91}{
\index{compress.c@{compress.c}!LSEC\_\-deleteCompression@{LSEC\_\-deleteCompression}}
\index{LSEC\_\-deleteCompression@{LSEC\_\-deleteCompression}!compress.c@{compress.c}}
\subsubsection[{LSEC\_\-deleteCompression}]{\setlength{\rightskip}{0pt plus 5cm}void LSEC\_\-deleteCompression ({\bf LSEC\_\-compression} $\ast$ {\em cpr})}}
\label{compress_8c_7f15cada460e7ec8dbce47ad05626a91}


Free the memory associated with the compression structure. 

\begin{Desc}
\item[Parameters:]
\begin{description}
\item[{\em cpr}]Pointer to an allocated compression structure \end{description}
\end{Desc}


Referenced by LSEC\_\-deleteCompaction().\hypertarget{compress_8c_e00495b47926f052ea308d7a961e1b71}{
\index{compress.c@{compress.c}!LSEC\_\-getBin@{LSEC\_\-getBin}}
\index{LSEC\_\-getBin@{LSEC\_\-getBin}!compress.c@{compress.c}}
\subsubsection[{LSEC\_\-getBin}]{\setlength{\rightskip}{0pt plus 5cm}unsigned int LSEC\_\-getBin ({\bf LSEC\_\-compression} $\ast$ {\em cpr}, \/  unsigned int {\em bin})}}
\label{compress_8c_e00495b47926f052ea308d7a961e1b71}


Return the contents of one bin of the histogram. 

\begin{Desc}
\item[Parameters:]
\begin{description}
\item[{\em cpr}]Pointer to an allocated, initialised, populated, compression structure\item[{\em bin}]ID of one of the bins of the histogram\end{description}
\end{Desc}
\begin{Desc}
\item[Returns:]Contents of the bin \end{Desc}


References \_\-LSEC\_\-compression::hist, and \_\-LSEC\_\-compression::nbits.\hypertarget{compress_8c_336beb375c102af5777e40bf23da97a0}{
\index{compress.c@{compress.c}!LSEC\_\-getCount@{LSEC\_\-getCount}}
\index{LSEC\_\-getCount@{LSEC\_\-getCount}!compress.c@{compress.c}}
\subsubsection[{LSEC\_\-getCount}]{\setlength{\rightskip}{0pt plus 5cm}unsigned int LSEC\_\-getCount ({\bf LSEC\_\-compression} $\ast$ {\em cpr})}}
\label{compress_8c_336beb375c102af5777e40bf23da97a0}


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

\begin{Desc}
\item[Parameters:]
\begin{description}
\item[{\em cpr}]Pointer to a compression structure\end{description}
\end{Desc}
\begin{Desc}
\item[Returns:]Number of non-zero bins in the histogram \end{Desc}


References LSEC\_\-compressionDesc::count, and \_\-LSEC\_\-compression::desc.\hypertarget{compress_8c_e054d020b998d52290c930a49bacd810}{
\index{compress.c@{compress.c}!LSEC\_\-newCompression@{LSEC\_\-newCompression}}
\index{LSEC\_\-newCompression@{LSEC\_\-newCompression}!compress.c@{compress.c}}
\subsubsection[{LSEC\_\-newCompression}]{\setlength{\rightskip}{0pt plus 5cm}{\bf LSEC\_\-compression}$\ast$ LSEC\_\-newCompression (unsigned int {\em nbits}, \/  const char $\ast$ {\em name})}}
\label{compress_8c_e054d020b998d52290c930a49bacd810}


Allocate and initialise a new compression structure for APE encoding. 

\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\item[{\em name}]String used in the reporting of error to identify a compression structure\end{description}
\end{Desc}
\begin{Desc}
\item[Returns:]Pointer to an allocated and initialised LSEC\_\-compression structure\end{Desc}
The order of calling the functions presented here should be LSEC\_\-newCompression LSEC\_\-histogram - Repeat as necessary LSEC\_\-process LSEC\_\-pack LSEC\_\-compress - Repeat as necessary LSEC\_\-clearCompression : repeat as necessary : LSEC\_\-deleteCompression 

References \_\-LSEC\_\-compression::delta, \_\-LSEC\_\-compression::freq, \_\-LSEC\_\-compression::fwlu, \_\-LSEC\_\-compression::hist, \_\-LSEC\_\-compression::mask, \_\-LSEC\_\-compression::name, \_\-LSEC\_\-compression::nbits, and \_\-LSEC\_\-compression::table.

Referenced by LSEC\_\-newCompaction().\hypertarget{compress_8c_dbe62103d9fc4b3aa6d95608a1c4bdd8}{
\index{compress.c@{compress.c}!LSEC\_\-newCompressionH@{LSEC\_\-newCompressionH}}
\index{LSEC\_\-newCompressionH@{LSEC\_\-newCompressionH}!compress.c@{compress.c}}
\subsubsection[{LSEC\_\-newCompressionH}]{\setlength{\rightskip}{0pt plus 5cm}{\bf LSEC\_\-compression}$\ast$ LSEC\_\-newCompressionH (unsigned int {\em nbits}, \/  const char $\ast$ {\em name})}}
\label{compress_8c_dbe62103d9fc4b3aa6d95608a1c4bdd8}


Allocate and initialise a new compression structure for Huffman encoding. 

\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\item[{\em name}]String used in the reporting of error to identify a compression structure\end{description}
\end{Desc}
\begin{Desc}
\item[Returns:]Pointer to an allocated and initialised LSEC\_\-compression structure\end{Desc}
The order of calling the functions presented here should be LSEC\_\-newCompression LSEC\_\-histogram - Repeat as necessary LSEC\_\-process LSEC\_\-pack LSEC\_\-compress - Repeat as necessary LSEC\_\-clearCompression : repeat as necessary : LSEC\_\-deleteCompression 

References \_\-LSEC\_\-compression::hde, \_\-LSEC\_\-compression::hist, \_\-LSEC\_\-compression::hist0, \_\-LSEC\_\-compression::mask, \_\-LSEC\_\-compression::name, and \_\-LSEC\_\-compression::nbits.

Referenced by LSEC\_\-newCompaction().\hypertarget{compress_8c_36d0e87844845da7d427ceb6dfb51a76}{
\index{compress.c@{compress.c}!LSEC\_\-pack@{LSEC\_\-pack}}
\index{LSEC\_\-pack@{LSEC\_\-pack}!compress.c@{compress.c}}
\subsubsection[{LSEC\_\-pack}]{\setlength{\rightskip}{0pt plus 5cm}unsigned$\ast$ LSEC\_\-pack ({\bf LSEC\_\-compression} $\ast$ {\em cpr}, \/  unsigned $\ast$ {\em buffer})}}
\label{compress_8c_36d0e87844845da7d427ceb6dfb51a76}


Pack the tables of a compression structure into a buffer. 

This routine selects sufficient data from the tables of the compression structure to be able to recreate the tables required to decompress the data, and pack it into the consignment

\begin{Desc}
\item[Parameters:]
\begin{description}
\item[{\em buffer}]Pointer to the start of the buffer to place the packed structure\item[{\em cpr}]Pointer to an initialised, populated and processed compression structure\end{description}
\end{Desc}
\begin{Desc}
\item[Returns:]Pointer to the word after this compression structure after packing \end{Desc}


References LSEC\_\-compressionDesc::count, \_\-LSEC\_\-compression::delta, \_\-LSEC\_\-compression::desc, \_\-LSEC\_\-compression::freq, \_\-LSEC\_\-compression::hde, LSEC\_\-compressionDesc::n\_\-delta\_\-bits, and LSEC\_\-compressionDesc::n\_\-entry\_\-bits.\hypertarget{compress_8c_8db296e748ac37ec50b8f2dbffb1658e}{
\index{compress.c@{compress.c}!LSEC\_\-packedSize32@{LSEC\_\-packedSize32}}
\index{LSEC\_\-packedSize32@{LSEC\_\-packedSize32}!compress.c@{compress.c}}
\subsubsection[{LSEC\_\-packedSize32}]{\setlength{\rightskip}{0pt plus 5cm}unsigned int LSEC\_\-packedSize32 ({\bf LSEC\_\-compression} $\ast$ {\em cpr})}}
\label{compress_8c_8db296e748ac37ec50b8f2dbffb1658e}


Calculate the size of a packed compression structure. 

This routine calculates the number of 32-bit words required to hold the packed compression structure

\begin{Desc}
\item[Parameters:]
\begin{description}
\item[{\em cpr}]Pointer to a compression structure\end{description}
\end{Desc}
\begin{Desc}
\item[Returns:]Size of the packed compression structure \end{Desc}


References LSEC\_\-compressionDesc::count, \_\-LSEC\_\-compression::desc, \_\-LSEC\_\-compression::hde, LSEC\_\-compressionDesc::n\_\-delta\_\-bits, and LSEC\_\-compressionDesc::n\_\-entry\_\-bits.\hypertarget{compress_8c_fd634cbb818bc39bc847316e94029ef4}{
\index{compress.c@{compress.c}!LSEC\_\-process@{LSEC\_\-process}}
\index{LSEC\_\-process@{LSEC\_\-process}!compress.c@{compress.c}}
\subsubsection[{LSEC\_\-process}]{\setlength{\rightskip}{0pt plus 5cm}unsigned LSEC\_\-process ({\bf LSEC\_\-compression} $\ast$ {\em cpr})}}
\label{compress_8c_fd634cbb818bc39bc847316e94029ef4}


Build the lookup, frequency and probability tables required by the APE. 

\begin{Desc}
\item[Parameters:]
\begin{description}
\item[{\em cpr}]Pointer to an allocated, initialised, populated, compression structure\end{description}
\end{Desc}
\begin{Desc}
\item[Return values:]
\begin{description}
\item[{\em LSEC\_\-SUCCESS}]If the processing goes well \end{description}
\end{Desc}


References LSEC\_\-compressionDesc::count, \_\-LSEC\_\-compression::delta, \_\-LSEC\_\-compression::desc, LSEC\_\-compressionDesc::first\_\-bin, \_\-LSEC\_\-compression::freq, \_\-LSEC\_\-compression::fwlu, \_\-LSEC\_\-compression::hde, \_\-LSEC\_\-compression::hist, \_\-LSEC\_\-compression::hist0, \_\-LSEC\_\-compression::last\_\-bin, LSEC\_\-compressionDesc::n\_\-delta\_\-bits, LSEC\_\-compressionDesc::n\_\-entry\_\-bits, \_\-LSEC\_\-compression::nbits, and \_\-LSEC\_\-compression::table.

Referenced by LSEC\_\-processCal().\hypertarget{compress_8c_3a0649036e3f6f60f97c6eb8bcb8e80d}{
\index{compress.c@{compress.c}!LSEC\_\-reportCompression@{LSEC\_\-reportCompression}}
\index{LSEC\_\-reportCompression@{LSEC\_\-reportCompression}!compress.c@{compress.c}}
\subsubsection[{LSEC\_\-reportCompression}]{\setlength{\rightskip}{0pt plus 5cm}void LSEC\_\-reportCompression ({\bf LSEC\_\-compression} $\ast$ {\em cpr}, \/  FILE $\ast$ {\em fp})}}
\label{compress_8c_3a0649036e3f6f60f97c6eb8bcb8e80d}


Describe the contents of a compression structure. 

This routine formats the compression structure as ASCII text and writes it to the specified file

\begin{Desc}
\item[Parameters:]
\begin{description}
\item[{\em cpr}]Pointer to the compression structure\item[{\em fp}]Pointer to the file used as the destination \end{description}
\end{Desc}


References LSEC\_\-compressionDesc::count, \_\-LSEC\_\-compression::desc, \_\-LSEC\_\-compression::encerr, \_\-LSEC\_\-compression::freq, \_\-LSEC\_\-compression::hist, \_\-LSEC\_\-compression::name, \_\-LSEC\_\-compression::nbits, and \_\-LSEC\_\-compression::ovrflw.

Referenced by LSEC\_\-reportCalCompaction().\hypertarget{compress_8c_e623d1692858d09fce861dc543a9487c}{
\index{compress.c@{compress.c}!LSEC\_\-zeroBin@{LSEC\_\-zeroBin}}
\index{LSEC\_\-zeroBin@{LSEC\_\-zeroBin}!compress.c@{compress.c}}
\subsubsection[{LSEC\_\-zeroBin}]{\setlength{\rightskip}{0pt plus 5cm}void LSEC\_\-zeroBin ({\bf LSEC\_\-compression} $\ast$ {\em cpr}, \/  unsigned int {\em bin})}}
\label{compress_8c_e623d1692858d09fce861dc543a9487c}


Set the selected bin of the histogram to zero. 

This indicates that this symbol will be selectively removed from the uncompressed data stream before encoding

\begin{Desc}
\item[Parameters:]
\begin{description}
\item[{\em cpr}]Pointer to an allocated, initialised, populated, compression structure\item[{\em bin}]ID of one of the bins of the histogram \end{description}
\end{Desc}


References \_\-LSEC\_\-compression::hist, and \_\-LSEC\_\-compression::nbits.