\section{theora.h File Reference}
\label{theora_8h}\index{theora.h@{theora.h}}
The libtheora C API. 

{\tt \#include $<$ogg/ogg.h$>$}\par
\subsection*{Data Structures}
\begin{CompactItemize}
\item 
struct {\bf yuv\_\-buffer}
\begin{CompactList}\small\item\em A YUV buffer for passing uncompressed frames to and from the codec. \item\end{CompactList}\item 
struct {\bf theora\_\-info}
\begin{CompactList}\small\item\em Theora bitstream info. \item\end{CompactList}\item 
struct {\bf theora\_\-state}
\begin{CompactList}\small\item\em Codec internal state and context. \item\end{CompactList}\item 
struct {\bf theora\_\-comment}
\begin{CompactList}\small\item\em Comment header metadata. \item\end{CompactList}\end{CompactItemize}
\subsection*{Defines}
\begin{CompactItemize}
\item 
\#define {\bf OC\_\-FAULT}\ -1\label{theora_8h_a0}

\begin{CompactList}\small\item\em general failure \item\end{CompactList}\item 
\#define {\bf OC\_\-EINVAL}\ -10\label{theora_8h_a1}

\begin{CompactList}\small\item\em library encountered invalid internal data \item\end{CompactList}\item 
\#define {\bf OC\_\-DISABLED}\ -11\label{theora_8h_a2}

\begin{CompactList}\small\item\em requested action is disabled \item\end{CompactList}\item 
\#define {\bf OC\_\-BADHEADER}\ -20\label{theora_8h_a3}

\begin{CompactList}\small\item\em header packet was corrupt/invalid \item\end{CompactList}\item 
\#define {\bf OC\_\-NOTFORMAT}\ -21\label{theora_8h_a4}

\begin{CompactList}\small\item\em packet is not a theora packet \item\end{CompactList}\item 
\#define {\bf OC\_\-VERSION}\ -22\label{theora_8h_a5}

\begin{CompactList}\small\item\em bitstream version is not handled \item\end{CompactList}\item 
\#define {\bf OC\_\-IMPL}\ -23\label{theora_8h_a6}

\begin{CompactList}\small\item\em feature or action not implemented \item\end{CompactList}\item 
\#define {\bf OC\_\-BADPACKET}\ -24\label{theora_8h_a7}

\begin{CompactList}\small\item\em packet is corrupt \item\end{CompactList}\item 
\#define {\bf OC\_\-NEWPACKET}\ -25\label{theora_8h_a8}

\begin{CompactList}\small\item\em packet is an (ignorable) unhandled extension \item\end{CompactList}\end{CompactItemize}
\subsection*{Typedefs}
\begin{CompactItemize}
\item 
typedef {\bf theora\_\-comment} {\bf theora\_\-comment}
\begin{CompactList}\small\item\em Comment header metadata. \item\end{CompactList}\end{CompactItemize}
\subsection*{Enumerations}
\begin{CompactItemize}
\item 
enum {\bf theora\_\-colorspace} \{ {\bf OC\_\-CS\_\-UNSPECIFIED}, 
{\bf OC\_\-CS\_\-ITU\_\-REC\_\-470M}, 
{\bf OC\_\-CS\_\-ITU\_\-REC\_\-470BG}
 \}
\begin{CompactList}\small\item\em A Colorspace. \item\end{CompactList}\end{CompactItemize}
\subsection*{Functions}
\begin{CompactItemize}
\item 
const char $\ast$ {\bf theora\_\-version\_\-string} (void)
\begin{CompactList}\small\item\em Retrieve a human-readable string to identify the encoder vendor and version. \item\end{CompactList}\item 
ogg\_\-uint32\_\-t {\bf theora\_\-version\_\-number} (void)
\begin{CompactList}\small\item\em Retrieve a 32-bit version number. \item\end{CompactList}\item 
int {\bf theora\_\-encode\_\-init} ({\bf theora\_\-state} $\ast$th, {\bf theora\_\-info} $\ast$c)
\begin{CompactList}\small\item\em Initialize the theora encoder. \item\end{CompactList}\item 
int {\bf theora\_\-encode\_\-YUVin} ({\bf theora\_\-state} $\ast$t, {\bf yuv\_\-buffer} $\ast$yuv)
\begin{CompactList}\small\item\em Submit a YUV buffer to the theora encoder. \item\end{CompactList}\item 
int {\bf theora\_\-encode\_\-packetout} ({\bf theora\_\-state} $\ast$t, int last\_\-p, ogg\_\-packet $\ast$op)
\begin{CompactList}\small\item\em Request the next packet of encoded video. \item\end{CompactList}\item 
int {\bf theora\_\-encode\_\-header} ({\bf theora\_\-state} $\ast$t, ogg\_\-packet $\ast$op)
\begin{CompactList}\small\item\em Request a packet containing the initial header. \item\end{CompactList}\item 
int {\bf theora\_\-encode\_\-comment} ({\bf theora\_\-comment} $\ast$tc, ogg\_\-packet $\ast$op)
\begin{CompactList}\small\item\em Request a comment header packet from provided metadata. \item\end{CompactList}\item 
int {\bf theora\_\-encode\_\-tables} ({\bf theora\_\-state} $\ast$t, ogg\_\-packet $\ast$op)
\begin{CompactList}\small\item\em Request a packet containing the codebook tables for the stream. \item\end{CompactList}\item 
int {\bf theora\_\-decode\_\-header} ({\bf theora\_\-info} $\ast$ci, {\bf theora\_\-comment} $\ast$cc, ogg\_\-packet $\ast$op)
\begin{CompactList}\small\item\em Decode an Ogg packet, with the expectation that the packet contains an initial header, comment data or codebook tables. \item\end{CompactList}\item 
int {\bf theora\_\-decode\_\-init} ({\bf theora\_\-state} $\ast$th, {\bf theora\_\-info} $\ast$c)
\begin{CompactList}\small\item\em Initialize a {\bf theora\_\-state}{\rm (p.\,\pageref{structtheora__state})} handle for decoding. \item\end{CompactList}\item 
int {\bf theora\_\-decode\_\-packetin} ({\bf theora\_\-state} $\ast$th, ogg\_\-packet $\ast$op)
\begin{CompactList}\small\item\em Input a packet containing encoded data into the theora decoder. \item\end{CompactList}\item 
int {\bf theora\_\-decode\_\-YUVout} ({\bf theora\_\-state} $\ast$th, {\bf yuv\_\-buffer} $\ast$yuv)
\begin{CompactList}\small\item\em Output the next available frame of decoded YUV data. \item\end{CompactList}\item 
int {\bf theora\_\-packet\_\-isheader} (ogg\_\-packet $\ast$op)
\begin{CompactList}\small\item\em Report whether a theora packet is a header or not This function does no verification beyond checking the header flag bit so it should not be used for bitstream identification; use {\bf theora\_\-decode\_\-header()}{\rm (p.\,\pageref{theora_8h_a21})} for that. \item\end{CompactList}\item 
int {\bf theora\_\-packet\_\-iskeyframe} (ogg\_\-packet $\ast$op)
\begin{CompactList}\small\item\em Report whether a theora packet is a keyframe or not. \item\end{CompactList}\item 
ogg\_\-int64\_\-t {\bf theora\_\-granule\_\-frame} ({\bf theora\_\-state} $\ast$th, ogg\_\-int64\_\-t granulepos)
\begin{CompactList}\small\item\em Convert a granulepos to an absolute frame number. \item\end{CompactList}\item 
double {\bf theora\_\-granule\_\-time} ({\bf theora\_\-state} $\ast$th, ogg\_\-int64\_\-t granulepos)
\begin{CompactList}\small\item\em Convert a granulepos to absolute time in seconds. \item\end{CompactList}\item 
void {\bf theora\_\-info\_\-init} ({\bf theora\_\-info} $\ast$c)
\begin{CompactList}\small\item\em Initialize a {\bf theora\_\-info}{\rm (p.\,\pageref{structtheora__info})} structure. \item\end{CompactList}\item 
void {\bf theora\_\-info\_\-clear} ({\bf theora\_\-info} $\ast$c)
\begin{CompactList}\small\item\em Clear a {\bf theora\_\-info}{\rm (p.\,\pageref{structtheora__info})} structure. \item\end{CompactList}\item 
void {\bf theora\_\-clear} ({\bf theora\_\-state} $\ast$t)
\begin{CompactList}\small\item\em Free all internal data associated with a {\bf theora\_\-state}{\rm (p.\,\pageref{structtheora__state})} handle. \item\end{CompactList}\item 
void {\bf theora\_\-comment\_\-init} ({\bf theora\_\-comment} $\ast$tc)\label{theora_8h_a32}

\begin{CompactList}\small\item\em Initialize an allocated {\bf theora\_\-comment}{\rm (p.\,\pageref{structtheora__comment})} structure. \item\end{CompactList}\item 
void {\bf theora\_\-comment\_\-add} ({\bf theora\_\-comment} $\ast$tc, char $\ast$comment)
\begin{CompactList}\small\item\em Add a comment to an initialized {\bf theora\_\-comment}{\rm (p.\,\pageref{structtheora__comment})} structure. \item\end{CompactList}\item 
void {\bf theora\_\-comment\_\-add\_\-tag} ({\bf theora\_\-comment} $\ast$tc, char $\ast$tag, char $\ast$value)
\begin{CompactList}\small\item\em Add a comment to an initialized {\bf theora\_\-comment}{\rm (p.\,\pageref{structtheora__comment})} structure. \item\end{CompactList}\item 
char $\ast$ {\bf theora\_\-comment\_\-query} ({\bf theora\_\-comment} $\ast$tc, char $\ast$tag, int count)
\begin{CompactList}\small\item\em look up a comment value by tag \item\end{CompactList}\item 
int {\bf theora\_\-comment\_\-query\_\-count} ({\bf theora\_\-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 theora\_\-comment\_\-clear} ({\bf theora\_\-comment} $\ast$tc)\label{theora_8h_a37}

\begin{CompactList}\small\item\em clears an allocated {\bf theora\_\-comment}{\rm (p.\,\pageref{structtheora__comment})} struct so that it can be freed. \item\end{CompactList}\end{CompactItemize}


\subsection{Detailed Description}
The libtheora C API. 



\subsection{Typedef Documentation}
\index{theora.h@{theora.h}!theora_comment@{theora\_\-comment}}
\index{theora_comment@{theora\_\-comment}!theora.h@{theora.h}}
\subsubsection{\setlength{\rightskip}{0pt plus 5cm}typedef struct {\bf theora\_\-comment}  {\bf theora\_\-comment}}\label{theora_8h_a9}


Comment header metadata. 

This structure holds the in-stream metadata corresponding to the 'comment' header packet.

Meta data is stored as a series of (tag, value) pairs, in length-encoded string vectors. The first occurence of the '=' character delimits the tag and value. A particular tag may occur more than once. The character set encoding for the strings is always utf-8, but the tag names are limited to case-insensitive ascii. See the spec for details.

In filling in this structure, {\bf theora\_\-decode\_\-header()}{\rm (p.\,\pageref{theora_8h_a21})} will null-terminate the user\_\-comment strings for safety. However, the bitstream format itself treats them as 8-bit clean, and so the length array should be treated as authoritative for their length. 

\subsection{Enumeration Type Documentation}
\index{theora.h@{theora.h}!theora_colorspace@{theora\_\-colorspace}}
\index{theora_colorspace@{theora\_\-colorspace}!theora.h@{theora.h}}
\subsubsection{\setlength{\rightskip}{0pt plus 5cm}enum {\bf theora\_\-colorspace}}\label{theora_8h_a38}


A Colorspace. 

\begin{Desc}
\item[Enumeration values: ]\par
\begin{description}
\index{OC_CS_UNSPECIFIED@{OC\_\-CS\_\-UNSPECIFIED}!theora.h@{theora.h}}\index{theora.h@{theora.h}!OC_CS_UNSPECIFIED@{OC\_\-CS\_\-UNSPECIFIED}}\item[{\em 
OC\_\-CS\_\-UNSPECIFIED\label{theora_8h_a38a10}
}]the colorspace is unknown or unspecified \index{OC_CS_ITU_REC_470M@{OC\_\-CS\_\-ITU\_\-REC\_\-470M}!theora.h@{theora.h}}\index{theora.h@{theora.h}!OC_CS_ITU_REC_470M@{OC\_\-CS\_\-ITU\_\-REC\_\-470M}}\item[{\em 
OC\_\-CS\_\-ITU\_\-REC\_\-470M\label{theora_8h_a38a11}
}]best option for 'NTSC' content \index{OC_CS_ITU_REC_470BG@{OC\_\-CS\_\-ITU\_\-REC\_\-470BG}!theora.h@{theora.h}}\index{theora.h@{theora.h}!OC_CS_ITU_REC_470BG@{OC\_\-CS\_\-ITU\_\-REC\_\-470BG}}\item[{\em 
OC\_\-CS\_\-ITU\_\-REC\_\-470BG\label{theora_8h_a38a12}
}]best option for 'PAL' content \end{description}
\end{Desc}



\subsection{Function Documentation}
\index{theora.h@{theora.h}!theora_clear@{theora\_\-clear}}
\index{theora_clear@{theora\_\-clear}!theora.h@{theora.h}}
\subsubsection{\setlength{\rightskip}{0pt plus 5cm}void theora\_\-clear ({\bf theora\_\-state} $\ast$ {\em t})}\label{theora_8h_a31}


Free all internal data associated with a {\bf theora\_\-state}{\rm (p.\,\pageref{structtheora__state})} handle. 

\begin{Desc}
\item[Parameters:]
\begin{description}
\item[{\em t}]A {\bf theora\_\-state}{\rm (p.\,\pageref{structtheora__state})} handle. \end{description}
\end{Desc}
\index{theora.h@{theora.h}!theora_comment_add@{theora\_\-comment\_\-add}}
\index{theora_comment_add@{theora\_\-comment\_\-add}!theora.h@{theora.h}}
\subsubsection{\setlength{\rightskip}{0pt plus 5cm}void theora\_\-comment\_\-add ({\bf theora\_\-comment} $\ast$ {\em tc}, char $\ast$ {\em comment})}\label{theora_8h_a33}


Add a comment to an initialized {\bf theora\_\-comment}{\rm (p.\,\pageref{structtheora__comment})} structure. 

\begin{Desc}
\item[Parameters:]
\begin{description}
\item[{\em comment}]must be a null-terminated string encoding the comment in \char`\"{}TAG=the value\char`\"{} form \end{description}
\end{Desc}
\index{theora.h@{theora.h}!theora_comment_add_tag@{theora\_\-comment\_\-add\_\-tag}}
\index{theora_comment_add_tag@{theora\_\-comment\_\-add\_\-tag}!theora.h@{theora.h}}
\subsubsection{\setlength{\rightskip}{0pt plus 5cm}void theora\_\-comment\_\-add\_\-tag ({\bf theora\_\-comment} $\ast$ {\em tc}, char $\ast$ {\em tag}, char $\ast$ {\em value})}\label{theora_8h_a34}


Add a comment to an initialized {\bf theora\_\-comment}{\rm (p.\,\pageref{structtheora__comment})} structure. 

\begin{Desc}
\item[Parameters:]
\begin{description}
\item[{\em tag}]a null-terminated string containing the tag associated with the comment. \item[{\em value}]the corresponding value as a null-terminated string Neither {\bf theora\_\-comment\_\-add()}{\rm (p.\,\pageref{theora_8h_a33})} nor {\bf theora\_\-comment\_\-add\_\-tag()}{\rm (p.\,\pageref{theora_8h_a34})} support comments containing null values, although the bitstream format supports this. To add such comments you will need to manipulate the {\bf theora\_\-comment}{\rm (p.\,\pageref{structtheora__comment})} structure directly \end{description}
\end{Desc}
\index{theora.h@{theora.h}!theora_comment_query@{theora\_\-comment\_\-query}}
\index{theora_comment_query@{theora\_\-comment\_\-query}!theora.h@{theora.h}}
\subsubsection{\setlength{\rightskip}{0pt plus 5cm}char$\ast$ theora\_\-comment\_\-query ({\bf theora\_\-comment} $\ast$ {\em tc}, char $\ast$ {\em tag}, int {\em count})}\label{theora_8h_a35}


look up a comment value by tag 

\begin{Desc}
\item[Parameters:]
\begin{description}
\item[{\em tc}]an initialized {\bf theora\_\-comment}{\rm (p.\,\pageref{structtheora__comment})} structure \item[{\em tag}]the tag to look up \item[{\em count}]the instance of the tag. The same tag can appear multiple times, each with a distinct and ordered value, so an index is required to retrieve them all. Use {\bf theora\_\-comment\_\-query\_\-count()}{\rm (p.\,\pageref{theora_8h_a36})} to get the legal range for the count parameter \end{description}
\end{Desc}
\begin{Desc}
\item[Returns:]a pointer to the queried tag's value \end{Desc}
\begin{Desc}
\item[Return values:]
\begin{description}
\item[{\em NULL}]if no matching tag is found \end{description}
\end{Desc}
\index{theora.h@{theora.h}!theora_comment_query_count@{theora\_\-comment\_\-query\_\-count}}
\index{theora_comment_query_count@{theora\_\-comment\_\-query\_\-count}!theora.h@{theora.h}}
\subsubsection{\setlength{\rightskip}{0pt plus 5cm}int theora\_\-comment\_\-query\_\-count ({\bf theora\_\-comment} $\ast$ {\em tc}, char $\ast$ {\em tag})}\label{theora_8h_a36}


look up the number of instances of a tag 

\begin{Desc}
\item[Parameters:]
\begin{description}
\item[{\em tc}]an initialized {\bf theora\_\-comment}{\rm (p.\,\pageref{structtheora__comment})} structure \item[{\em tag}]the tag to look up \end{description}
\end{Desc}
\begin{Desc}
\item[Returns:]the number on instances of a particular tag. Call this first when querying for a specific tag and then interate over the number of instances with separate calls to {\bf theora\_\-comment\_\-query()}{\rm (p.\,\pageref{theora_8h_a35})} to retrieve all instances in order. \end{Desc}
\index{theora.h@{theora.h}!theora_decode_header@{theora\_\-decode\_\-header}}
\index{theora_decode_header@{theora\_\-decode\_\-header}!theora.h@{theora.h}}
\subsubsection{\setlength{\rightskip}{0pt plus 5cm}int theora\_\-decode\_\-header ({\bf theora\_\-info} $\ast$ {\em ci}, {\bf theora\_\-comment} $\ast$ {\em cc}, ogg\_\-packet $\ast$ {\em op})}\label{theora_8h_a21}


Decode an Ogg packet, with the expectation that the packet contains an initial header, comment data or codebook tables. 

\begin{Desc}
\item[Parameters:]
\begin{description}
\item[{\em ci}]A {\bf theora\_\-info}{\rm (p.\,\pageref{structtheora__info})} structure to fill. This must have been previously initialized with {\bf theora\_\-info\_\-init()}{\rm (p.\,\pageref{theora_8h_a29})}. If {\em op\/} contains an initial header, {\bf theora\_\-decode\_\-header()}{\rm (p.\,\pageref{theora_8h_a21})} will fill {\em ci\/} with the parsed header values. If {\em op\/} contains codebook tables, {\bf theora\_\-decode\_\-header()}{\rm (p.\,\pageref{theora_8h_a21})} will parse these and attach an internal representation to {\em ci-$>$codec\_\-setup\/}. \item[{\em cc}]A {\bf theora\_\-comment}{\rm (p.\,\pageref{structtheora__comment})} structure to fill. If {\em op\/} contains comment data, {\bf theora\_\-decode\_\-header()}{\rm (p.\,\pageref{theora_8h_a21})} will fill {\em cc\/} with the parsed comments. \item[{\em op}]An ogg\_\-packet structure which you expect contains an initial header, comment data or codebook tables.\end{description}
\end{Desc}
\begin{Desc}
\item[Return values:]
\begin{description}
\item[{\em OC\_\-BADHEADER}]{\em op\/} is NULL; OR the first byte of {\em op-$>$packet\/} has the signature of an initial packet, but op is not a b\_\-o\_\-s packet; OR this packet has the signature of an initial header packet, but an initial header packet has already been seen; OR this packet has the signature of a comment packet, but the initial header has not yet been seen; OR this packet has the signature of a comment packet, but contains invalid data; OR this packet has the signature of codebook tables, but the initial header or comments have not yet been seen; OR this packet has the signature of codebook tables, but contains invalid data; OR the stream being decoded has a compatible version but this packet does not have the signature of a theora initial header, comments, or codebook packet \item[{\em OC\_\-VERSION}]The packet data of {\em op\/} is an initial header with a version which is incompatible with this version of libtheora. \item[{\em OC\_\-NEWPACKET}]the stream being decoded has an incompatible (future) version and contains an unknown signature. \item[{\em 0}]Success\end{description}
\end{Desc}
\begin{Desc}
\item[Note:]The normal usage is that {\bf theora\_\-decode\_\-header()}{\rm (p.\,\pageref{theora_8h_a21})} be called on the first three packets of a theora logical bitstream in succession. \end{Desc}
\index{theora.h@{theora.h}!theora_decode_init@{theora\_\-decode\_\-init}}
\index{theora_decode_init@{theora\_\-decode\_\-init}!theora.h@{theora.h}}
\subsubsection{\setlength{\rightskip}{0pt plus 5cm}int theora\_\-decode\_\-init ({\bf theora\_\-state} $\ast$ {\em th}, {\bf theora\_\-info} $\ast$ {\em c})}\label{theora_8h_a22}


Initialize a {\bf theora\_\-state}{\rm (p.\,\pageref{structtheora__state})} handle for decoding. 

\begin{Desc}
\item[Parameters:]
\begin{description}
\item[{\em th}]The {\bf theora\_\-state}{\rm (p.\,\pageref{structtheora__state})} handle to initialize. \item[{\em c}]A {\bf theora\_\-info}{\rm (p.\,\pageref{structtheora__info})} struct filled with the desired decoding parameters. This is of course usually obtained from a previous call to {\bf theora\_\-decode\_\-header()}{\rm (p.\,\pageref{theora_8h_a21})}. \end{description}
\end{Desc}
\begin{Desc}
\item[Returns:]0 Success \end{Desc}
\index{theora.h@{theora.h}!theora_decode_packetin@{theora\_\-decode\_\-packetin}}
\index{theora_decode_packetin@{theora\_\-decode\_\-packetin}!theora.h@{theora.h}}
\subsubsection{\setlength{\rightskip}{0pt plus 5cm}int theora\_\-decode\_\-packetin ({\bf theora\_\-state} $\ast$ {\em th}, ogg\_\-packet $\ast$ {\em op})}\label{theora_8h_a23}


Input a packet containing encoded data into the theora decoder. 

\begin{Desc}
\item[Parameters:]
\begin{description}
\item[{\em th}]A {\bf theora\_\-state}{\rm (p.\,\pageref{structtheora__state})} handle previously initialized for decoding. \item[{\em op}]An ogg\_\-packet containing encoded theora data. \end{description}
\end{Desc}
\begin{Desc}
\item[Return values:]
\begin{description}
\item[{\em OC\_\-BADPACKET}]{\em op\/} does not contain encoded video data \end{description}
\end{Desc}
\index{theora.h@{theora.h}!theora_decode_YUVout@{theora\_\-decode\_\-YUVout}}
\index{theora_decode_YUVout@{theora\_\-decode\_\-YUVout}!theora.h@{theora.h}}
\subsubsection{\setlength{\rightskip}{0pt plus 5cm}int theora\_\-decode\_\-YUVout ({\bf theora\_\-state} $\ast$ {\em th}, {\bf yuv\_\-buffer} $\ast$ {\em yuv})}\label{theora_8h_a24}


Output the next available frame of decoded YUV data. 

\begin{Desc}
\item[Parameters:]
\begin{description}
\item[{\em th}]A {\bf theora\_\-state}{\rm (p.\,\pageref{structtheora__state})} handle previously initialized for decoding. \item[{\em yuv}]A {\bf yuv\_\-buffer}{\rm (p.\,\pageref{structyuv__buffer})} in which libtheora should place the decoded data. \end{description}
\end{Desc}
\begin{Desc}
\item[Return values:]
\begin{description}
\item[{\em 0}]Success \end{description}
\end{Desc}
\index{theora.h@{theora.h}!theora_encode_comment@{theora\_\-encode\_\-comment}}
\index{theora_encode_comment@{theora\_\-encode\_\-comment}!theora.h@{theora.h}}
\subsubsection{\setlength{\rightskip}{0pt plus 5cm}int theora\_\-encode\_\-comment ({\bf theora\_\-comment} $\ast$ {\em tc}, ogg\_\-packet $\ast$ {\em op})}\label{theora_8h_a19}


Request a comment header packet from provided metadata. 

A pointer to the comment data is placed in a user-provided ogg\_\-packet structure. \begin{Desc}
\item[Parameters:]
\begin{description}
\item[{\em tc}]A {\bf theora\_\-comment}{\rm (p.\,\pageref{structtheora__comment})} structure filled with the desired metadata \item[{\em op}]An ogg\_\-packet structure to fill. libtheora will set all elements of this structure, including a pointer to the encoded comment data. The memory for the comment data is owned by libtheora. \end{description}
\end{Desc}
\begin{Desc}
\item[Return values:]
\begin{description}
\item[{\em 0}]Success \end{description}
\end{Desc}
\index{theora.h@{theora.h}!theora_encode_header@{theora\_\-encode\_\-header}}
\index{theora_encode_header@{theora\_\-encode\_\-header}!theora.h@{theora.h}}
\subsubsection{\setlength{\rightskip}{0pt plus 5cm}int theora\_\-encode\_\-header ({\bf theora\_\-state} $\ast$ {\em t}, ogg\_\-packet $\ast$ {\em op})}\label{theora_8h_a18}


Request a packet containing the initial header. 

A pointer to the header data is placed in a user-provided ogg\_\-packet structure. \begin{Desc}
\item[Parameters:]
\begin{description}
\item[{\em t}]A {\bf theora\_\-state}{\rm (p.\,\pageref{structtheora__state})} handle previously initialized for encoding. \item[{\em op}]An ogg\_\-packet structure to fill. libtheora will set all elements of this structure, including a pointer to the header data. The memory for the header data is owned by libtheora. \end{description}
\end{Desc}
\begin{Desc}
\item[Return values:]
\begin{description}
\item[{\em 0}]Success \end{description}
\end{Desc}
\index{theora.h@{theora.h}!theora_encode_init@{theora\_\-encode\_\-init}}
\index{theora_encode_init@{theora\_\-encode\_\-init}!theora.h@{theora.h}}
\subsubsection{\setlength{\rightskip}{0pt plus 5cm}int theora\_\-encode\_\-init ({\bf theora\_\-state} $\ast$ {\em th}, {\bf theora\_\-info} $\ast$ {\em c})}\label{theora_8h_a15}


Initialize the theora encoder. 

\begin{Desc}
\item[Parameters:]
\begin{description}
\item[{\em th}]The {\bf theora\_\-state}{\rm (p.\,\pageref{structtheora__state})} handle to initialize for encoding. \item[{\em ti}]A {\bf theora\_\-info}{\rm (p.\,\pageref{structtheora__info})} struct filled with the desired encoding parameters. \end{description}
\end{Desc}
\begin{Desc}
\item[Returns:]0 Success \end{Desc}
\index{theora.h@{theora.h}!theora_encode_packetout@{theora\_\-encode\_\-packetout}}
\index{theora_encode_packetout@{theora\_\-encode\_\-packetout}!theora.h@{theora.h}}
\subsubsection{\setlength{\rightskip}{0pt plus 5cm}int theora\_\-encode\_\-packetout ({\bf theora\_\-state} $\ast$ {\em t}, int {\em last\_\-p}, ogg\_\-packet $\ast$ {\em op})}\label{theora_8h_a17}


Request the next packet of encoded video. 

The encoded data is placed in a user-provided ogg\_\-packet structure. \begin{Desc}
\item[Parameters:]
\begin{description}
\item[{\em t}]A {\bf theora\_\-state}{\rm (p.\,\pageref{structtheora__state})} handle previously initialized for encoding. \item[{\em last\_\-p}]whether this is the last packet the encoder should produce. \item[{\em op}]An ogg\_\-packet structure to fill. libtheora will set all elements of this structure, including a pointer to encoded data. The memory for the encoded data is owned by libtheora. \end{description}
\end{Desc}
\begin{Desc}
\item[Return values:]
\begin{description}
\item[{\em 0}]No internal storage exists OR no packet is ready \item[{\em -1}]The encoding process has completed \item[{\em 1}]Success \end{description}
\end{Desc}
\index{theora.h@{theora.h}!theora_encode_tables@{theora\_\-encode\_\-tables}}
\index{theora_encode_tables@{theora\_\-encode\_\-tables}!theora.h@{theora.h}}
\subsubsection{\setlength{\rightskip}{0pt plus 5cm}int theora\_\-encode\_\-tables ({\bf theora\_\-state} $\ast$ {\em t}, ogg\_\-packet $\ast$ {\em op})}\label{theora_8h_a20}


Request a packet containing the codebook tables for the stream. 

A pointer to the codebook data is placed in a user-provided ogg\_\-packet structure. \begin{Desc}
\item[Parameters:]
\begin{description}
\item[{\em t}]A {\bf theora\_\-state}{\rm (p.\,\pageref{structtheora__state})} handle previously initialized for encoding. \item[{\em op}]An ogg\_\-packet structure to fill. libtheora will set all elements of this structure, including a pointer to the codebook data. The memory for the header data is owned by libtheora. \end{description}
\end{Desc}
\begin{Desc}
\item[Return values:]
\begin{description}
\item[{\em 0}]Success \end{description}
\end{Desc}
\index{theora.h@{theora.h}!theora_encode_YUVin@{theora\_\-encode\_\-YUVin}}
\index{theora_encode_YUVin@{theora\_\-encode\_\-YUVin}!theora.h@{theora.h}}
\subsubsection{\setlength{\rightskip}{0pt plus 5cm}int theora\_\-encode\_\-YUVin ({\bf theora\_\-state} $\ast$ {\em t}, {\bf yuv\_\-buffer} $\ast$ {\em yuv})}\label{theora_8h_a16}


Submit a YUV buffer to the theora encoder. 

\begin{Desc}
\item[Parameters:]
\begin{description}
\item[{\em t}]A {\bf theora\_\-state}{\rm (p.\,\pageref{structtheora__state})} handle previously initialized for encoding. \item[{\em yuv}]A buffer of YUV data to encode. \end{description}
\end{Desc}
\begin{Desc}
\item[Return values:]
\begin{description}
\item[{\em OC\_\-EINVAL}]Encoder is not ready, or is finished. \item[{\em -1}]The size of the given frame differs from those previously input \item[{\em 0}]Success \end{description}
\end{Desc}
\index{theora.h@{theora.h}!theora_granule_frame@{theora\_\-granule\_\-frame}}
\index{theora_granule_frame@{theora\_\-granule\_\-frame}!theora.h@{theora.h}}
\subsubsection{\setlength{\rightskip}{0pt plus 5cm}ogg\_\-int64\_\-t theora\_\-granule\_\-frame ({\bf theora\_\-state} $\ast$ {\em th}, ogg\_\-int64\_\-t {\em granulepos})}\label{theora_8h_a27}


Convert a granulepos to an absolute frame number. 

The granulepos is interpreted in the context of a given {\bf theora\_\-state}{\rm (p.\,\pageref{structtheora__state})} handle.

\begin{Desc}
\item[Parameters:]
\begin{description}
\item[{\em th}]A previously initialized {\bf theora\_\-state}{\rm (p.\,\pageref{structtheora__state})} handle (encode or decode) \item[{\em granulepos}]The granulepos to convert. \end{description}
\end{Desc}
\begin{Desc}
\item[Returns:]The frame number corresponding to {\em granulepos\/}. \end{Desc}
\begin{Desc}
\item[Return values:]
\begin{description}
\item[{\em -1}]The given granulepos is invalid (ie. negative)\end{description}
\end{Desc}
Thus function was added in the 1.0alpha4 release. \index{theora.h@{theora.h}!theora_granule_time@{theora\_\-granule\_\-time}}
\index{theora_granule_time@{theora\_\-granule\_\-time}!theora.h@{theora.h}}
\subsubsection{\setlength{\rightskip}{0pt plus 5cm}double theora\_\-granule\_\-time ({\bf theora\_\-state} $\ast$ {\em th}, ogg\_\-int64\_\-t {\em granulepos})}\label{theora_8h_a28}


Convert a granulepos to absolute time in seconds. 

The granulepos is interpreted in the context of a given {\bf theora\_\-state}{\rm (p.\,\pageref{structtheora__state})} handle. \begin{Desc}
\item[Parameters:]
\begin{description}
\item[{\em th}]A previously initialized {\bf theora\_\-state}{\rm (p.\,\pageref{structtheora__state})} handle (encode or decode) \item[{\em granulepos}]The granulepos to convert. \end{description}
\end{Desc}
\begin{Desc}
\item[Returns:]The absolute time in seconds corresponding to {\em granulepos\/}. \end{Desc}
\begin{Desc}
\item[Return values:]
\begin{description}
\item[{\em -1}]The given granulepos is invalid (ie. negative) \end{description}
\end{Desc}
\index{theora.h@{theora.h}!theora_info_clear@{theora\_\-info\_\-clear}}
\index{theora_info_clear@{theora\_\-info\_\-clear}!theora.h@{theora.h}}
\subsubsection{\setlength{\rightskip}{0pt plus 5cm}void theora\_\-info\_\-clear ({\bf theora\_\-info} $\ast$ {\em c})}\label{theora_8h_a30}


Clear a {\bf theora\_\-info}{\rm (p.\,\pageref{structtheora__info})} structure. 

All values within the given {\bf theora\_\-info}{\rm (p.\,\pageref{structtheora__info})} structure are cleared, and associated internal codec setup data is freed. \begin{Desc}
\item[Parameters:]
\begin{description}
\item[{\em c}]A {\bf theora\_\-info}{\rm (p.\,\pageref{structtheora__info})} struct to initialize. \end{description}
\end{Desc}
\index{theora.h@{theora.h}!theora_info_init@{theora\_\-info\_\-init}}
\index{theora_info_init@{theora\_\-info\_\-init}!theora.h@{theora.h}}
\subsubsection{\setlength{\rightskip}{0pt plus 5cm}void theora\_\-info\_\-init ({\bf theora\_\-info} $\ast$ {\em c})}\label{theora_8h_a29}


Initialize a {\bf theora\_\-info}{\rm (p.\,\pageref{structtheora__info})} structure. 

All values within the given {\bf theora\_\-info}{\rm (p.\,\pageref{structtheora__info})} structure are initialized, and space is allocated within libtheora for internal codec setup data. \begin{Desc}
\item[Parameters:]
\begin{description}
\item[{\em c}]A {\bf theora\_\-info}{\rm (p.\,\pageref{structtheora__info})} struct to initialize. \end{description}
\end{Desc}
\index{theora.h@{theora.h}!theora_packet_isheader@{theora\_\-packet\_\-isheader}}
\index{theora_packet_isheader@{theora\_\-packet\_\-isheader}!theora.h@{theora.h}}
\subsubsection{\setlength{\rightskip}{0pt plus 5cm}int theora\_\-packet\_\-isheader (ogg\_\-packet $\ast$ {\em op})}\label{theora_8h_a25}


Report whether a theora packet is a header or not This function does no verification beyond checking the header flag bit so it should not be used for bitstream identification; use {\bf theora\_\-decode\_\-header()}{\rm (p.\,\pageref{theora_8h_a21})} for that. 

\begin{Desc}
\item[Parameters:]
\begin{description}
\item[{\em op}]An ogg\_\-packet containing encoded theora data. \end{description}
\end{Desc}
\begin{Desc}
\item[Return values:]
\begin{description}
\item[{\em 1}]The packet is a header packet \item[{\em 0}]The packet is not a header packet (and so contains frame data)\end{description}
\end{Desc}
Thus function was added in the 1.0alpha4 release. \index{theora.h@{theora.h}!theora_packet_iskeyframe@{theora\_\-packet\_\-iskeyframe}}
\index{theora_packet_iskeyframe@{theora\_\-packet\_\-iskeyframe}!theora.h@{theora.h}}
\subsubsection{\setlength{\rightskip}{0pt plus 5cm}int theora\_\-packet\_\-iskeyframe (ogg\_\-packet $\ast$ {\em op})}\label{theora_8h_a26}


Report whether a theora packet is a keyframe or not. 

\begin{Desc}
\item[Parameters:]
\begin{description}
\item[{\em op}]An ogg\_\-packet containing encoded theora data. \end{description}
\end{Desc}
\begin{Desc}
\item[Return values:]
\begin{description}
\item[{\em 1}]The packet contains a keyframe image \item[{\em 0}]The packet is contains an interframe delta \item[{\em -1}]the packet is not an image data packet at all\end{description}
\end{Desc}
Thus function was added in the 1.0alpha4 release. \index{theora.h@{theora.h}!theora_version_number@{theora\_\-version\_\-number}}
\index{theora_version_number@{theora\_\-version\_\-number}!theora.h@{theora.h}}
\subsubsection{\setlength{\rightskip}{0pt plus 5cm}ogg\_\-uint32\_\-t theora\_\-version\_\-number (void)}\label{theora_8h_a14}


Retrieve a 32-bit version number. 

This number is composed of a 16-bit major version, 8-bit minor version and 8 bit sub-version, composed as follows: \small\begin{alltt}
   (VERSION\_MAJOR$<$$<$16) + (VERSION\_MINOR$<$$<$8) + (VERSION\_SUB)
\end{alltt}\normalsize 
 \begin{Desc}
\item[Returns:]the version number. \end{Desc}
\index{theora.h@{theora.h}!theora_version_string@{theora\_\-version\_\-string}}
\index{theora_version_string@{theora\_\-version\_\-string}!theora.h@{theora.h}}
\subsubsection{\setlength{\rightskip}{0pt plus 5cm}const char$\ast$ theora\_\-version\_\-string (void)}\label{theora_8h_a13}


Retrieve a human-readable string to identify the encoder vendor and version. 

\begin{Desc}
\item[Returns:]a version string. \end{Desc}
