\section{codec.h File Reference}
\label{codec_8h}\index{codec.h@{codec.h}}
The shared {\tt libtheoradec} and {\tt libtheoraenc} C API. 

{\tt \#include $<$ogg/ogg.h$>$}\par
\subsection*{Data Structures}
\begin{CompactItemize}
\item 
struct {\bf th\_\-img\_\-plane}
\begin{CompactList}\small\item\em A buffer for a single color plane in an uncompressed image. \item\end{CompactList}\item 
struct {\bf th\_\-info}
\begin{CompactList}\small\item\em Theora bitstream information. \item\end{CompactList}\item 
struct {\bf th\_\-comment}
\begin{CompactList}\small\item\em The comment information. \item\end{CompactList}\item 
struct {\bf th\_\-quant\_\-ranges}
\begin{CompactList}\small\item\em A set of {\em qi\/} ranges. \item\end{CompactList}\item 
struct {\bf th\_\-quant\_\-info}
\begin{CompactList}\small\item\em A complete set of quantization parameters. \item\end{CompactList}\item 
struct {\bf th\_\-huff\_\-code}
\begin{CompactList}\small\item\em A Huffman code for a Theora DCT token. \item\end{CompactList}\end{CompactItemize}
\subsection*{Defines}
\begin{CompactItemize}
\item 
\#define \textbf{\_\-O\_\-THEORA\_\-CODEC\_\-H\_\-}~(1)\label{codec_8h_efaeaf2a9c6b40e8a0d272f250c9eccf}

\item 
\#define {\bf TH\_\-NHUFFMAN\_\-TABLES}~(80)\label{codec_8h_941d3dbb961fa6f9741a0fe41d0cba5f}

\begin{CompactList}\small\item\em The number of Huffman tables used by Theora. \item\end{CompactList}\item 
\#define {\bf TH\_\-NDCT\_\-TOKENS}~(32)\label{codec_8h_6a531d13df95e68929af5033b54109b3}

\begin{CompactList}\small\item\em The number of DCT token values in each table. \item\end{CompactList}\end{CompactItemize}
\begin{Indent}{\bf Return codes}\par
\begin{CompactItemize}
\item 
\#define {\bf TH\_\-EFAULT}~(-1)\label{codec_8h_60049ec6651ddcf3a41be0d20cd4c25e}

\begin{CompactList}\small\item\em An invalid pointer was provided. \item\end{CompactList}\item 
\#define {\bf TH\_\-EINVAL}~(-10)\label{codec_8h_c5f9d492efbfe7b8f8451a72d029c2fa}

\begin{CompactList}\small\item\em An invalid argument was provided. \item\end{CompactList}\item 
\#define {\bf TH\_\-EBADHEADER}~(-20)\label{codec_8h_c66132e83e895129da3f67121ce71e91}

\begin{CompactList}\small\item\em The contents of the header were incomplete, invalid, or unexpected. \item\end{CompactList}\item 
\#define {\bf TH\_\-ENOTFORMAT}~(-21)\label{codec_8h_b9fecb27ea3f98e9cb47bd53fa0b82cc}

\begin{CompactList}\small\item\em The header does not belong to a Theora stream. \item\end{CompactList}\item 
\#define {\bf TH\_\-EVERSION}~(-22)\label{codec_8h_64c063b91c1f61d8765bda03c76c309e}

\begin{CompactList}\small\item\em The bitstream version is too high. \item\end{CompactList}\item 
\#define {\bf TH\_\-EIMPL}~(-23)\label{codec_8h_0ff34f3723fb69ec0cb7e85739a43cd8}

\begin{CompactList}\small\item\em The specified function is not implemented. \item\end{CompactList}\item 
\#define {\bf TH\_\-EBADPACKET}~(-24)\label{codec_8h_1a0b02a5cac53a079373e9b917296939}

\begin{CompactList}\small\item\em There were errors in the video data packet. \item\end{CompactList}\item 
\#define {\bf TH\_\-DUPFRAME}~(1)
\begin{CompactList}\small\item\em The decoded packet represented a dropped frame. \item\end{CompactList}\end{CompactItemize}
\end{Indent}
\subsection*{Typedefs}
\begin{CompactItemize}
\item 
typedef {\bf th\_\-img\_\-plane} {\bf th\_\-ycbcr\_\-buffer} [3]
\begin{CompactList}\small\item\em A complete image buffer for an uncompressed frame. \item\end{CompactList}\item 
typedef unsigned char {\bf th\_\-quant\_\-base} [64]\label{codec_8h_de2e393eb13fc6093b2471b71d6b4244}

\begin{CompactList}\small\item\em A single base matrix. \item\end{CompactList}\end{CompactItemize}
\subsection*{Enumerations}
\begin{CompactItemize}
\item 
enum {\bf th\_\-colorspace} \{ {\bf TH\_\-CS\_\-UNSPECIFIED}, 
{\bf TH\_\-CS\_\-ITU\_\-REC\_\-470M}, 
{\bf TH\_\-CS\_\-ITU\_\-REC\_\-470BG}, 
{\bf TH\_\-CS\_\-NSPACES}
 \}
\begin{CompactList}\small\item\em The currently defined color space tags. \item\end{CompactList}\item 
enum {\bf th\_\-pixel\_\-fmt} \{ \par
{\bf TH\_\-PF\_\-420}, 
{\bf TH\_\-PF\_\-RSVD}, 
{\bf TH\_\-PF\_\-422}, 
{\bf TH\_\-PF\_\-444}, 
\par
{\bf TH\_\-PF\_\-NFORMATS}
 \}
\begin{CompactList}\small\item\em The currently defined pixel format tags. \item\end{CompactList}\end{CompactItemize}
\subsection*{Functions}
\begin{Indent}{\bf Basic shared functions}\par
\begin{CompactItemize}
\item 
const char $\ast$ {\bf th\_\-version\_\-string} (void)
\begin{CompactList}\small\item\em Retrieves a human-readable string to identify the library vendor and version. \item\end{CompactList}\item 
ogg\_\-uint32\_\-t {\bf th\_\-version\_\-number} (void)
\begin{CompactList}\small\item\em Retrieves the library version number. \item\end{CompactList}\item 
ogg\_\-int64\_\-t {\bf th\_\-granule\_\-frame} (void $\ast$\_\-encdec, ogg\_\-int64\_\-t \_\-granpos)
\begin{CompactList}\small\item\em Converts a granule position to an absolute frame number. \item\end{CompactList}\item 
double {\bf th\_\-granule\_\-time} (void $\ast$\_\-encdec, ogg\_\-int64\_\-t \_\-granpos)
\begin{CompactList}\small\item\em Converts a granule position to an absolute time in seconds. \item\end{CompactList}\item 
int {\bf th\_\-packet\_\-isheader} (ogg\_\-packet $\ast$\_\-op)
\begin{CompactList}\small\item\em Determines whether a Theora packet is a header or not. \item\end{CompactList}\item 
int {\bf th\_\-packet\_\-iskeyframe} (ogg\_\-packet $\ast$\_\-op)
\begin{CompactList}\small\item\em Determines whether a theora packet is a key frame or not. \item\end{CompactList}\end{CompactItemize}
\end{Indent}
\begin{Indent}{\bf Functions for manipulating header data}\par
\begin{CompactItemize}
\item 
void {\bf th\_\-info\_\-init} ({\bf th\_\-info} $\ast$\_\-info)
\begin{CompactList}\small\item\em Initializes a \doxyref{th\_\-info}{p.}{structth__info} structure. \item\end{CompactList}\item 
void {\bf th\_\-info\_\-clear} ({\bf th\_\-info} $\ast$\_\-info)
\begin{CompactList}\small\item\em Clears a \doxyref{th\_\-info}{p.}{structth__info} structure. \item\end{CompactList}\item 
void {\bf th\_\-comment\_\-init} ({\bf th\_\-comment} $\ast$\_\-tc)
\begin{CompactList}\small\item\em Initialize a \doxyref{th\_\-comment}{p.}{structth__comment} structure. \item\end{CompactList}\item 
void {\bf th\_\-comment\_\-add} ({\bf th\_\-comment} $\ast$\_\-tc, char $\ast$\_\-comment)
\begin{CompactList}\small\item\em Add a comment to an initialized \doxyref{th\_\-comment}{p.}{structth__comment} structure. \item\end{CompactList}\item 
void {\bf th\_\-comment\_\-add\_\-tag} ({\bf th\_\-comment} $\ast$\_\-tc, char $\ast$\_\-tag, char $\ast$\_\-val)
\begin{CompactList}\small\item\em Add a comment to an initialized \doxyref{th\_\-comment}{p.}{structth__comment} structure. \item\end{CompactList}\item 
char $\ast$ {\bf th\_\-comment\_\-query} ({\bf th\_\-comment} $\ast$\_\-tc, char $\ast$\_\-tag, int \_\-count)
\begin{CompactList}\small\item\em Look up a comment value by its tag. \item\end{CompactList}\item 
int {\bf th\_\-comment\_\-query\_\-count} ({\bf th\_\-comment} $\ast$\_\-tc, char $\ast$\_\-tag)
\begin{CompactList}\small\item\em Look up the number of instances of a tag. \item\end{CompactList}\item 
void {\bf th\_\-comment\_\-clear} ({\bf th\_\-comment} $\ast$\_\-tc)
\begin{CompactList}\small\item\em Clears a \doxyref{th\_\-comment}{p.}{structth__comment} structure. \item\end{CompactList}\end{CompactItemize}
\end{Indent}


\subsection{Detailed Description}
The shared {\tt libtheoradec} and {\tt libtheoraenc} C API. 



\subsection{Define Documentation}
\index{codec.h@{codec.h}!TH_DUPFRAME@{TH\_\-DUPFRAME}}
\index{TH_DUPFRAME@{TH\_\-DUPFRAME}!codec.h@{codec.h}}
\subsubsection{\setlength{\rightskip}{0pt plus 5cm}\#define TH\_\-DUPFRAME~(1)}\label{codec_8h_08a81fa97b24fc08bcc911b46a48cad1}


The decoded packet represented a dropped frame. 

The player can continue to display the current frame, as the contents of the decoded frame buffer have not changed. 

\subsection{Typedef Documentation}
\index{codec.h@{codec.h}!th_ycbcr_buffer@{th\_\-ycbcr\_\-buffer}}
\index{th_ycbcr_buffer@{th\_\-ycbcr\_\-buffer}!codec.h@{codec.h}}
\subsubsection{\setlength{\rightskip}{0pt plus 5cm}typedef {\bf th\_\-img\_\-plane} {\bf th\_\-ycbcr\_\-buffer}[3]}\label{codec_8h_044188211a7e8856b80c890fc7aa329a}


A complete image buffer for an uncompressed frame. 

The chroma planes may be decimated by a factor of two in either direction, as indicated by \doxyref{th\_\-info::pixel\_\-fmt}{p.}{structth__info_b1966565a00135ddd50fa196ff45310e}. The width and height of the Y' plane must be multiples of 16. They may need to be cropped for display, using the rectangle specified by \doxyref{th\_\-info::pic\_\-x}{p.}{structth__info_61f578d14183bb428525e84b9c07dedd}, \doxyref{th\_\-info::pic\_\-y}{p.}{structth__info_a768fdac6fd834588be82823b56fd9a5}, \doxyref{th\_\-info::pic\_\-width}{p.}{structth__info_65159959b98e3df2e759fccc6e468671}, and \doxyref{th\_\-info::pic\_\-height}{p.}{structth__info_5ac85f41e0b49e387d26422210f23ae2}. All samples are 8 bits. \begin{Desc}
\item[Note:]The term YUV often used to describe a colorspace is ambiguous. The exact parameters of the RGB to YUV conversion process aside, in many contexts the U and V channels actually have opposite meanings. To avoid this confusion, we are explicit: the name of the color channels are Y'Cb\-Cr, and they appear in that order, always. The prime symbol denotes that the Y channel is non-linear. Cb and Cr stand for \char`\"{}Chroma blue\char`\"{} and \char`\"{}Chroma red\char`\"{}, respectively. \end{Desc}


\subsection{Enumeration Type Documentation}
\index{codec.h@{codec.h}!th_colorspace@{th\_\-colorspace}}
\index{th_colorspace@{th\_\-colorspace}!codec.h@{codec.h}}
\subsubsection{\setlength{\rightskip}{0pt plus 5cm}enum {\bf th\_\-colorspace}}\label{codec_8h_d506e7b8f6bbf30a9f71183cf1097359}


The currently defined color space tags. 

See {\tt the Theora specification}, Chapter 4, for exact details on the meaning of each of these color spaces. \begin{Desc}
\item[Enumerator: ]\par
\begin{description}
\index{TH_CS_UNSPECIFIED@{TH\_\-CS\_\-UNSPECIFIED}!codec.h@{codec.h}}\index{codec.h@{codec.h}!TH_CS_UNSPECIFIED@{TH\_\-CS\_\-UNSPECIFIED}}\item[{\em 
TH\_\-CS\_\-UNSPECIFIED\label{codec_8h_d506e7b8f6bbf30a9f71183cf1097359b495f0e7787cd4e18fc8c49c209abd55}
}]The color space was not specified at the encoder. 

It may be conveyed by an external means. \index{TH_CS_ITU_REC_470M@{TH\_\-CS\_\-ITU\_\-REC\_\-470M}!codec.h@{codec.h}}\index{codec.h@{codec.h}!TH_CS_ITU_REC_470M@{TH\_\-CS\_\-ITU\_\-REC\_\-470M}}\item[{\em 
TH\_\-CS\_\-ITU\_\-REC\_\-470M\label{codec_8h_d506e7b8f6bbf30a9f71183cf1097359dcf0d6efd2f51539d2eb73ff7d91f396}
}]A color space designed for NTSC content. \index{TH_CS_ITU_REC_470BG@{TH\_\-CS\_\-ITU\_\-REC\_\-470BG}!codec.h@{codec.h}}\index{codec.h@{codec.h}!TH_CS_ITU_REC_470BG@{TH\_\-CS\_\-ITU\_\-REC\_\-470BG}}\item[{\em 
TH\_\-CS\_\-ITU\_\-REC\_\-470BG\label{codec_8h_d506e7b8f6bbf30a9f71183cf1097359796a45a21605e81e3e2935108c59b189}
}]A color space designed for PAL/SECAM content. \index{TH_CS_NSPACES@{TH\_\-CS\_\-NSPACES}!codec.h@{codec.h}}\index{codec.h@{codec.h}!TH_CS_NSPACES@{TH\_\-CS\_\-NSPACES}}\item[{\em 
TH\_\-CS\_\-NSPACES\label{codec_8h_d506e7b8f6bbf30a9f71183cf10973593832e79cb2e2ac073dd038336760d02c}
}]The total number of currently defined color spaces. \end{description}
\end{Desc}

\index{codec.h@{codec.h}!th_pixel_fmt@{th\_\-pixel\_\-fmt}}
\index{th_pixel_fmt@{th\_\-pixel\_\-fmt}!codec.h@{codec.h}}
\subsubsection{\setlength{\rightskip}{0pt plus 5cm}enum {\bf th\_\-pixel\_\-fmt}}\label{codec_8h_14abb3d1a139c721a81611dd79ba9f78}


The currently defined pixel format tags. 

See {\tt the Theora specification}, Section 4.4, for details on the precise sample locations. \begin{Desc}
\item[Enumerator: ]\par
\begin{description}
\index{TH_PF_420@{TH\_\-PF\_\-420}!codec.h@{codec.h}}\index{codec.h@{codec.h}!TH_PF_420@{TH\_\-PF\_\-420}}\item[{\em 
TH\_\-PF\_\-420\label{codec_8h_14abb3d1a139c721a81611dd79ba9f787aeb9ad8128f043e3e0fd0e7eafc4771}
}]Chroma decimation by 2 in both the X and Y directions (4:2:0). \index{TH_PF_RSVD@{TH\_\-PF\_\-RSVD}!codec.h@{codec.h}}\index{codec.h@{codec.h}!TH_PF_RSVD@{TH\_\-PF\_\-RSVD}}\item[{\em 
TH\_\-PF\_\-RSVD\label{codec_8h_14abb3d1a139c721a81611dd79ba9f78a73e80fd96c5fcb950b7f36a00300d66}
}]Currently reserved. \index{TH_PF_422@{TH\_\-PF\_\-422}!codec.h@{codec.h}}\index{codec.h@{codec.h}!TH_PF_422@{TH\_\-PF\_\-422}}\item[{\em 
TH\_\-PF\_\-422\label{codec_8h_14abb3d1a139c721a81611dd79ba9f7844ea86b7a5a2cafdd741dda86bf96a60}
}]Chroma decimation by 2 in the X direction (4:2:2). \index{TH_PF_444@{TH\_\-PF\_\-444}!codec.h@{codec.h}}\index{codec.h@{codec.h}!TH_PF_444@{TH\_\-PF\_\-444}}\item[{\em 
TH\_\-PF\_\-444\label{codec_8h_14abb3d1a139c721a81611dd79ba9f78efc9250eacdd5374b78a4f3f7d7ae136}
}]No chroma decimation (4:4:4). \index{TH_PF_NFORMATS@{TH\_\-PF\_\-NFORMATS}!codec.h@{codec.h}}\index{codec.h@{codec.h}!TH_PF_NFORMATS@{TH\_\-PF\_\-NFORMATS}}\item[{\em 
TH\_\-PF\_\-NFORMATS\label{codec_8h_14abb3d1a139c721a81611dd79ba9f78cfd67ab067c95a854c5dceb0ed846659}
}]The total number of currently defined pixel formats. \end{description}
\end{Desc}

