love2d.megasource/libs/libtheora-1.1.1/doc/libtheora/latex/codec_8h.tex

\section{codec.h File Reference}
\label{codec_8h}\index{codec.h@{codec.h}}


The shared {\ttfamily libtheoradec} and {\ttfamily libtheoraenc} C API.  
{\ttfamily \#include $<$ogg/ogg.h$>$}\par
\subsection*{Data Structures}
\begin{DoxyCompactItemize}
\item 
struct {\bf th\_\-img\_\-plane}
\begin{DoxyCompactList}\small\item\em A buffer for a single color plane in an uncompressed image. \item\end{DoxyCompactList}\item 
struct {\bf th\_\-info}
\begin{DoxyCompactList}\small\item\em Theora bitstream information. \item\end{DoxyCompactList}\item 
struct {\bf th\_\-comment}
\begin{DoxyCompactList}\small\item\em The comment information. \item\end{DoxyCompactList}\item 
struct {\bf th\_\-quant\_\-ranges}
\begin{DoxyCompactList}\small\item\em A set of {\itshape qi\/} ranges. \item\end{DoxyCompactList}\item 
struct {\bf th\_\-quant\_\-info}
\begin{DoxyCompactList}\small\item\em A complete set of quantization parameters. \item\end{DoxyCompactList}\item 
struct {\bf th\_\-huff\_\-code}
\begin{DoxyCompactList}\small\item\em A Huffman code for a Theora DCT token. \item\end{DoxyCompactList}\end{DoxyCompactItemize}
\subsection*{Defines}
\begin{DoxyCompactItemize}
\item 
\#define {\bf \_\-O\_\-THEORA\_\-CODEC\_\-H\_\-}~(1)
\item 
\#define {\bf TH\_\-NHUFFMAN\_\-TABLES}~(80)
\begin{DoxyCompactList}\small\item\em The number of Huffman tables used by Theora. \item\end{DoxyCompactList}\item 
\#define {\bf TH\_\-NDCT\_\-TOKENS}~(32)
\begin{DoxyCompactList}\small\item\em The number of DCT token values in each table. \item\end{DoxyCompactList}\end{DoxyCompactItemize}
\begin{Indent}{\bf Return codes}\par
{\em \label{_amgrp800007e5fae550658ee577ca16693452}
 }\begin{DoxyCompactItemize}
\item 
\#define {\bf TH\_\-EFAULT}~(-\/1)
\begin{DoxyCompactList}\small\item\em An invalid pointer was provided. \item\end{DoxyCompactList}\item 
\#define {\bf TH\_\-EINVAL}~(-\/10)
\begin{DoxyCompactList}\small\item\em An invalid argument was provided. \item\end{DoxyCompactList}\item 
\#define {\bf TH\_\-EBADHEADER}~(-\/20)
\begin{DoxyCompactList}\small\item\em The contents of the header were incomplete, invalid, or unexpected. \item\end{DoxyCompactList}\item 
\#define {\bf TH\_\-ENOTFORMAT}~(-\/21)
\begin{DoxyCompactList}\small\item\em The header does not belong to a Theora stream. \item\end{DoxyCompactList}\item 
\#define {\bf TH\_\-EVERSION}~(-\/22)
\begin{DoxyCompactList}\small\item\em The bitstream version is too high. \item\end{DoxyCompactList}\item 
\#define {\bf TH\_\-EIMPL}~(-\/23)
\begin{DoxyCompactList}\small\item\em The specified function is not implemented. \item\end{DoxyCompactList}\item 
\#define {\bf TH\_\-EBADPACKET}~(-\/24)
\begin{DoxyCompactList}\small\item\em There were errors in the video data packet. \item\end{DoxyCompactList}\item 
\#define {\bf TH\_\-DUPFRAME}~(1)
\begin{DoxyCompactList}\small\item\em The decoded packet represented a dropped frame. \item\end{DoxyCompactList}\end{DoxyCompactItemize}
\end{Indent}
\subsection*{Typedefs}
\begin{DoxyCompactItemize}
\item 
typedef {\bf th\_\-img\_\-plane} {\bf th\_\-ycbcr\_\-buffer} [3]
\begin{DoxyCompactList}\small\item\em A complete image buffer for an uncompressed frame. \item\end{DoxyCompactList}\item 
typedef unsigned char {\bf th\_\-quant\_\-base} [64]
\begin{DoxyCompactList}\small\item\em A single base matrix. \item\end{DoxyCompactList}\end{DoxyCompactItemize}
\subsection*{Enumerations}
\begin{DoxyCompactItemize}
\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{DoxyCompactList}\small\item\em The currently defined color space tags. \item\end{DoxyCompactList}\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{DoxyCompactList}\small\item\em The currently defined pixel format tags. \item\end{DoxyCompactList}\end{DoxyCompactItemize}
\subsection*{Functions}
\begin{Indent}{\bf Basic shared functions}\par
{\em \label{_amgrpb625c22fa07613c734f71c378fe32d7a}
 }\begin{DoxyCompactItemize}
\item 
const char $\ast$ {\bf th\_\-version\_\-string} (void)
\begin{DoxyCompactList}\small\item\em Retrieves a human-\/readable string to identify the library vendor and version. \item\end{DoxyCompactList}\item 
ogg\_\-uint32\_\-t {\bf th\_\-version\_\-number} (void)
\begin{DoxyCompactList}\small\item\em Retrieves the library version number. \item\end{DoxyCompactList}\item 
ogg\_\-int64\_\-t {\bf th\_\-granule\_\-frame} (void $\ast$\_\-encdec, ogg\_\-int64\_\-t \_\-granpos)
\begin{DoxyCompactList}\small\item\em Converts a granule position to an absolute frame index, starting at {\ttfamily 0}. \item\end{DoxyCompactList}\item 
double {\bf th\_\-granule\_\-time} (void $\ast$\_\-encdec, ogg\_\-int64\_\-t \_\-granpos)
\begin{DoxyCompactList}\small\item\em Converts a granule position to an absolute time in seconds. \item\end{DoxyCompactList}\item 
int {\bf th\_\-packet\_\-isheader} (ogg\_\-packet $\ast$\_\-op)
\begin{DoxyCompactList}\small\item\em Determines whether a Theora packet is a header or not. \item\end{DoxyCompactList}\item 
int {\bf th\_\-packet\_\-iskeyframe} (ogg\_\-packet $\ast$\_\-op)
\begin{DoxyCompactList}\small\item\em Determines whether a theora packet is a key frame or not. \item\end{DoxyCompactList}\end{DoxyCompactItemize}
\end{Indent}
\begin{Indent}{\bf Functions for manipulating header data}\par
{\em \label{_amgrp14ef5f819e97c870c128539ed1f334e3}
 }\begin{DoxyCompactItemize}
\item 
void {\bf th\_\-info\_\-init} ({\bf th\_\-info} $\ast$\_\-info)
\begin{DoxyCompactList}\small\item\em Initializes a \doxyref{th\_\-info}{p.}{structth__info} structure. \item\end{DoxyCompactList}\item 
void {\bf th\_\-info\_\-clear} ({\bf th\_\-info} $\ast$\_\-info)
\begin{DoxyCompactList}\small\item\em Clears a \doxyref{th\_\-info}{p.}{structth__info} structure. \item\end{DoxyCompactList}\item 
void {\bf th\_\-comment\_\-init} ({\bf th\_\-comment} $\ast$\_\-tc)
\begin{DoxyCompactList}\small\item\em Initialize a \doxyref{th\_\-comment}{p.}{structth__comment} structure. \item\end{DoxyCompactList}\item 
void {\bf th\_\-comment\_\-add} ({\bf th\_\-comment} $\ast$\_\-tc, char $\ast$\_\-comment)
\begin{DoxyCompactList}\small\item\em Add a comment to an initialized \doxyref{th\_\-comment}{p.}{structth__comment} structure. \item\end{DoxyCompactList}\item 
void {\bf th\_\-comment\_\-add\_\-tag} ({\bf th\_\-comment} $\ast$\_\-tc, char $\ast$\_\-tag, char $\ast$\_\-val)
\begin{DoxyCompactList}\small\item\em Add a comment to an initialized \doxyref{th\_\-comment}{p.}{structth__comment} structure. \item\end{DoxyCompactList}\item 
char $\ast$ {\bf th\_\-comment\_\-query} ({\bf th\_\-comment} $\ast$\_\-tc, char $\ast$\_\-tag, int \_\-count)
\begin{DoxyCompactList}\small\item\em Look up a comment value by its tag. \item\end{DoxyCompactList}\item 
int {\bf th\_\-comment\_\-query\_\-count} ({\bf th\_\-comment} $\ast$\_\-tc, char $\ast$\_\-tag)
\begin{DoxyCompactList}\small\item\em Look up the number of instances of a tag. \item\end{DoxyCompactList}\item 
void {\bf th\_\-comment\_\-clear} ({\bf th\_\-comment} $\ast$\_\-tc)
\begin{DoxyCompactList}\small\item\em Clears a \doxyref{th\_\-comment}{p.}{structth__comment} structure. \item\end{DoxyCompactList}\end{DoxyCompactItemize}
\end{Indent}


\subsection{Detailed Description}
The shared {\ttfamily libtheoradec} and {\ttfamily libtheoraenc} C API. You don't need to include this directly. 

\subsection{Define Documentation}
\index{codec.h@{codec.h}!\_\-O\_\-THEORA\_\-CODEC\_\-H\_\-@{\_\-O\_\-THEORA\_\-CODEC\_\-H\_\-}}
\index{\_\-O\_\-THEORA\_\-CODEC\_\-H\_\-@{\_\-O\_\-THEORA\_\-CODEC\_\-H\_\-}!codec.h@{codec.h}}
\subsubsection[{\_\-O\_\-THEORA\_\-CODEC\_\-H\_\-}]{\setlength{\rightskip}{0pt plus 5cm}\#define \_\-O\_\-THEORA\_\-CODEC\_\-H\_\-~(1)}\label{codec_8h_a15352a6a862d25ab00a8f06ea65ee75b}
\index{codec.h@{codec.h}!TH\_\-DUPFRAME@{TH\_\-DUPFRAME}}
\index{TH\_\-DUPFRAME@{TH\_\-DUPFRAME}!codec.h@{codec.h}}
\subsubsection[{TH\_\-DUPFRAME}]{\setlength{\rightskip}{0pt plus 5cm}\#define TH\_\-DUPFRAME~(1)}\label{codec_8h_ab10e7b64f17a02707fc9348ea9832d09}


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. \index{codec.h@{codec.h}!TH\_\-EBADHEADER@{TH\_\-EBADHEADER}}
\index{TH\_\-EBADHEADER@{TH\_\-EBADHEADER}!codec.h@{codec.h}}
\subsubsection[{TH\_\-EBADHEADER}]{\setlength{\rightskip}{0pt plus 5cm}\#define TH\_\-EBADHEADER~(-\/20)}\label{codec_8h_af00f7ecc5242d12a717202537324a510}


The contents of the header were incomplete, invalid, or unexpected. \index{codec.h@{codec.h}!TH\_\-EBADPACKET@{TH\_\-EBADPACKET}}
\index{TH\_\-EBADPACKET@{TH\_\-EBADPACKET}!codec.h@{codec.h}}
\subsubsection[{TH\_\-EBADPACKET}]{\setlength{\rightskip}{0pt plus 5cm}\#define TH\_\-EBADPACKET~(-\/24)}\label{codec_8h_a6efb84e9c2213a8840003eee2847b27f}


There were errors in the video data packet. \index{codec.h@{codec.h}!TH\_\-EFAULT@{TH\_\-EFAULT}}
\index{TH\_\-EFAULT@{TH\_\-EFAULT}!codec.h@{codec.h}}
\subsubsection[{TH\_\-EFAULT}]{\setlength{\rightskip}{0pt plus 5cm}\#define TH\_\-EFAULT~(-\/1)}\label{codec_8h_a4d8d8e34fc5ec39ffa05d61a310a0407}


An invalid pointer was provided. \index{codec.h@{codec.h}!TH\_\-EIMPL@{TH\_\-EIMPL}}
\index{TH\_\-EIMPL@{TH\_\-EIMPL}!codec.h@{codec.h}}
\subsubsection[{TH\_\-EIMPL}]{\setlength{\rightskip}{0pt plus 5cm}\#define TH\_\-EIMPL~(-\/23)}\label{codec_8h_a921c47accc17841f220af5a6afb79efe}


The specified function is not implemented. \index{codec.h@{codec.h}!TH\_\-EINVAL@{TH\_\-EINVAL}}
\index{TH\_\-EINVAL@{TH\_\-EINVAL}!codec.h@{codec.h}}
\subsubsection[{TH\_\-EINVAL}]{\setlength{\rightskip}{0pt plus 5cm}\#define TH\_\-EINVAL~(-\/10)}\label{codec_8h_afbbd9f19fbf292aeb62a37792cecb870}


An invalid argument was provided. \index{codec.h@{codec.h}!TH\_\-ENOTFORMAT@{TH\_\-ENOTFORMAT}}
\index{TH\_\-ENOTFORMAT@{TH\_\-ENOTFORMAT}!codec.h@{codec.h}}
\subsubsection[{TH\_\-ENOTFORMAT}]{\setlength{\rightskip}{0pt plus 5cm}\#define TH\_\-ENOTFORMAT~(-\/21)}\label{codec_8h_a3dc08a00a9aba231be398f3e31726d9c}


The header does not belong to a Theora stream. \index{codec.h@{codec.h}!TH\_\-EVERSION@{TH\_\-EVERSION}}
\index{TH\_\-EVERSION@{TH\_\-EVERSION}!codec.h@{codec.h}}
\subsubsection[{TH\_\-EVERSION}]{\setlength{\rightskip}{0pt plus 5cm}\#define TH\_\-EVERSION~(-\/22)}\label{codec_8h_ac3a45ef2b24f75259258edc481e3a122}


The bitstream version is too high. \index{codec.h@{codec.h}!TH\_\-NDCT\_\-TOKENS@{TH\_\-NDCT\_\-TOKENS}}
\index{TH\_\-NDCT\_\-TOKENS@{TH\_\-NDCT\_\-TOKENS}!codec.h@{codec.h}}
\subsubsection[{TH\_\-NDCT\_\-TOKENS}]{\setlength{\rightskip}{0pt plus 5cm}\#define TH\_\-NDCT\_\-TOKENS~(32)}\label{codec_8h_a2a44f48084e76a58cae48fb5d47cd422}


The number of DCT token values in each table. \index{codec.h@{codec.h}!TH\_\-NHUFFMAN\_\-TABLES@{TH\_\-NHUFFMAN\_\-TABLES}}
\index{TH\_\-NHUFFMAN\_\-TABLES@{TH\_\-NHUFFMAN\_\-TABLES}!codec.h@{codec.h}}
\subsubsection[{TH\_\-NHUFFMAN\_\-TABLES}]{\setlength{\rightskip}{0pt plus 5cm}\#define TH\_\-NHUFFMAN\_\-TABLES~(80)}\label{codec_8h_a49bf449eae33c5320f0c308f32c6ae42}


The number of Huffman tables used by Theora. 

\subsection{Typedef Documentation}
\index{codec.h@{codec.h}!th\_\-quant\_\-base@{th\_\-quant\_\-base}}
\index{th\_\-quant\_\-base@{th\_\-quant\_\-base}!codec.h@{codec.h}}
\subsubsection[{th\_\-quant\_\-base}]{\setlength{\rightskip}{0pt plus 5cm}typedef unsigned char {\bf th\_\-quant\_\-base}[64]}\label{codec_8h_a6a1426d16beef8a311d7f0e9d2e96326}


A single base matrix. \index{codec.h@{codec.h}!th\_\-ycbcr\_\-buffer@{th\_\-ycbcr\_\-buffer}}
\index{th\_\-ycbcr\_\-buffer@{th\_\-ycbcr\_\-buffer}!codec.h@{codec.h}}
\subsubsection[{th\_\-ycbcr\_\-buffer}]{\setlength{\rightskip}{0pt plus 5cm}typedef {\bf th\_\-img\_\-plane} {\bf th\_\-ycbcr\_\-buffer}[3]}\label{codec_8h_a343f7cfabad179cc4fe527cf06873f45}


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_a2301388ef3755c41ab12fd144c1fc54e}. 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_a5b3f834bcf141564e7bb14f49101870f}, \doxyref{th\_\-info::pic\_\-y}{p.}{structth__info_a8aacc575cab2dfe3735001c2ad32aa14}, \doxyref{th\_\-info::pic\_\-width}{p.}{structth__info_a5048edf77b141dd3e9a92ca85e317345}, and \doxyref{th\_\-info::pic\_\-height}{p.}{structth__info_a775178474283c5990ba73f9ba7f6b88b}. All samples are 8 bits. \begin{DoxyNote}{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'CbCr, 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{DoxyNote}


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


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_a4ce7a695ce353b1582d29b6c1ddf31a0adb9a17a3283c8d490652e507db2427cf}
}]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_a4ce7a695ce353b1582d29b6c1ddf31a0a1a19346bbfb8192baa4c185df73d3397}
}]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_a4ce7a695ce353b1582d29b6c1ddf31a0a009021d50836ddb0ec6004a2803775fe}
}]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_a4ce7a695ce353b1582d29b6c1ddf31a0a0fa8ea07f583ee57943520ddb2f6e62e}
}]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[{th\_\-pixel\_\-fmt}]{\setlength{\rightskip}{0pt plus 5cm}enum {\bf th\_\-pixel\_\-fmt}}\label{codec_8h_a5c9e7f2f0c7ed209c9ca3ed0abd328bc}


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_a5c9e7f2f0c7ed209c9ca3ed0abd328bcafed7ad7ee4345930255827bff6055162}
}]Chroma decimation by 2 in both the X and Y directions (4:2:0). The Cb and Cr chroma planes are half the width and half the height of the luma plane. \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_a5c9e7f2f0c7ed209c9ca3ed0abd328bca9e60af0159d42b20806d7eb4a8b833e6}
}]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_a5c9e7f2f0c7ed209c9ca3ed0abd328bca0271d01babf2f51512479f4a6245b9fa}
}]Chroma decimation by 2 in the X direction (4:2:2). The Cb and Cr chroma planes are half the width of the luma plane, but full height. \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_a5c9e7f2f0c7ed209c9ca3ed0abd328bca2ac50ac048ea75501a5e0f99a63c8c86}
}]No chroma decimation (4:4:4). The Cb and Cr chroma planes are full width and full height. \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_a5c9e7f2f0c7ed209c9ca3ed0abd328bca2d6d78b9df1df086bb60f32f963a31eb}
}]The total number of currently defined pixel formats. \end{description}
\end{Desc}