\hypertarget{RLE_8h}{
\section{RLE.h File Reference}
\label{RLE_8h}\index{RLE.h@{RLE.h}}
}
Run Length Encoding interface file. 

\subsection*{Functions}
\begin{CompactItemize}
\item 
unsigned int \hyperlink{RLE_8h_4eb6c36cc18a1a8c08fb9ae43433ebfb}{RLE\_\-encode} (unsigned int $\ast$buf, unsigned int pos, unsigned int w, int nbits)
\begin{CompactList}\small\item\em Uses a run length encoding method to encode the bits in the specified word. \item\end{CompactList}\item 
int \hyperlink{RLE_8h_8b5cf9cec3c68d3e7a14650ad5539443}{RLE\_\-compare} (unsigned int w, int nbits, int max)
\begin{CompactList}\small\item\em Compares the size of the {\em max\/} with run length method and returns (almost) rle\_\-size - max. \item\end{CompactList}\item 
unsigned int \hyperlink{RLE_8h_26e02a160fab8b8f8c4e6797ecae0b37}{RLE\_\-size} (unsigned int w, int nbits)
\begin{CompactList}\small\item\em Returns the size of the run length encoding method. \item\end{CompactList}\end{CompactItemize}


\subsection{Detailed Description}
Run Length Encoding 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: RLE.h,v 1.1 2009/04/30 00:31:28 russell Exp $
\end{verbatim}
\normalsize


\begin{Desc}
\item[Overview]Interface specification for routines to encode bit strings using a run length encoding method. The only twist added to the straight-forward encoding, is that only the necessary number of bits needed to encode the bit address are used. For example, when encoding a 32-bit value, the straight-forward run-length encoding would use a 5-bit address (representing the bit number) and a 1 bit stop/continue bit. However, when the number of bits left to encode is less than 16, one only needs 4 bits. Similarly, when the number of bits left to encode is less tha 8, one only needs 3 bits, etc, etc.\end{Desc}
\begin{Desc}
\item[Warning:]As is usual in these encoding routines, encoding 0 is the user's responsibility. This is because many times a value of 0 has already been encoded as a side-effect of some larger encoding scheme.\end{Desc}
\begin{Desc}
\item[Summary]The set of run length encoding routines is\begin{itemize}
\item RLE\_\-encode, encodes an n-bit number. While {\em n\/} can be any number from 1-32, practically speaking, only powers of 2 will affect the result (1,2,4,8,16,32)\item RLE\_\-exceeds, can be used to determine whether the size of the encoded pattern exceeds a maximum value. This can be useful when choosing between competing encoding methods, without actually encoding the data. This routine is somewhat faster than calling RLE\_\-size, since RLE\_\-exceeds can stop once the size exceeds the maximum value.\item RLE\_\-size, returns the size, in bits, needed to encode an n-bit number. \end{itemize}
\end{Desc}


\subsection{Function Documentation}
\hypertarget{RLE_8h_8b5cf9cec3c68d3e7a14650ad5539443}{
\index{RLE.h@{RLE.h}!RLE_compare@{RLE\_\-compare}}
\index{RLE_compare@{RLE\_\-compare}!RLE.h@{RLE.h}}
\subsubsection{\setlength{\rightskip}{0pt plus 5cm}int RLE\_\-compare (unsigned int {\em word}, int {\em cnt}, int {\em max})}}
\label{RLE_8h_8b5cf9cec3c68d3e7a14650ad5539443}


Compares the size of the {\em max\/} with run length method and returns (almost) rle\_\-size - max. 

\begin{Desc}
\item[Return values:]
\begin{description}
\item[{\em $>$0}]Indicates RLE encoding is larger than {\em max\/}. How much larger is not encoded, only that it is larger. \item[{\em =0}]The number of bits needed by the RLE\_\-encode is the same as max \item[{\em $<$0}]The number of bits needed by the RLE\_\-compare is less than max. In this case, {\em max\/} + return value = size of RLE encoding.\end{description}
\end{Desc}
\begin{Desc}
\item[Parameters:]
\begin{description}
\item[{\em word}]The word to encode \item[{\em cnt}]The maximum bit number + 1 (LSB = 0) that can be set. For example, if all 32 bits can be set, then this is 32, if only 16 bits (right-jusified) then 16. This must be a value between 1 and 32. \item[{\em max}]The maximum number of bits.\end{description}
\end{Desc}
This routine can be used to judge whether some other encoding method is better than the run length method.

\begin{Desc}
\item[Example]If one wishes to use an {\em asis\/} encoding on a 16-bit value if the run length encoding method exceeds 16 bits 

\begin{Code}\begin{verbatim}      / * Check if the run length encoding size is greater than or equal 16 * /
      if (RLE_compare (word, 16, 16) >= 0)
      {
          / * Yes, RLE method is greater than or equal to 16 bits 
              use asis encoding                                    * /
          pos = BFP_wordB (buf, pos, 1);
          pos = BFP_wordR (buf, pos, word, 16);
      }
      else
     {
          / * No, RLE_method is less than 16 bits * /
          pos = BFP_wordB  (buf, pos, 0);
          pos = RLE_encode (buf, pos, word, 16);
      }
\end{verbatim}
\end{Code}

 \end{Desc}
\hypertarget{RLE_8h_4eb6c36cc18a1a8c08fb9ae43433ebfb}{
\index{RLE.h@{RLE.h}!RLE_encode@{RLE\_\-encode}}
\index{RLE_encode@{RLE\_\-encode}!RLE.h@{RLE.h}}
\subsubsection{\setlength{\rightskip}{0pt plus 5cm}unsigned int RLE\_\-encode (unsigned int $\ast$ {\em buf}, unsigned int {\em pos}, unsigned int {\em word}, int {\em cnt})}}
\label{RLE_8h_4eb6c36cc18a1a8c08fb9ae43433ebfb}


Uses a run length encoding method to encode the bits in the specified word. 

\begin{Desc}
\item[Returns:]The updated bit position\end{Desc}
\begin{Desc}
\item[Parameters:]
\begin{description}
\item[{\em buf}]The output buffer \item[{\em pos}]The current bit position \item[{\em word}]The word to encode \item[{\em cnt}]The maximum bit number + 1 (LSB = 0) that can be set. For example, if all 32 bits can be set, then this is 32, if only 16 bits (right-jusified) then 16. This must be a value between 1 and 32. \end{description}
\end{Desc}
\hypertarget{RLE_8h_26e02a160fab8b8f8c4e6797ecae0b37}{
\index{RLE.h@{RLE.h}!RLE_size@{RLE\_\-size}}
\index{RLE_size@{RLE\_\-size}!RLE.h@{RLE.h}}
\subsubsection{\setlength{\rightskip}{0pt plus 5cm}unsigned int RLE\_\-size (unsigned int {\em word}, int {\em cnt})}}
\label{RLE_8h_26e02a160fab8b8f8c4e6797ecae0b37}


Returns the size of the run length encoding method. 

\begin{Desc}
\item[Returns:]The number of bits needed by the RLE\_\-encode\end{Desc}
\begin{Desc}
\item[Parameters:]
\begin{description}
\item[{\em word}]The word to encode \item[{\em cnt}]The maximum bit number + 1 (LSB = 0) that can be set. For example, if all 32 bits can be set, then this is 32, if only 16 bits (right-jusified) then 16. This must be a value between 1 and 32. \end{description}
\end{Desc}