\section{Functions Shared by Encode and Decode}
\label{group__basefuncs}\index{Functions Shared by Encode and Decode@{Functions Shared by Encode and Decode}}
\subsection*{Basic shared functions}
\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}
\subsection*{Functions for manipulating header data}
\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}


\subsection{Function Documentation}
\index{basefuncs@{basefuncs}!th_comment_add@{th\_\-comment\_\-add}}
\index{th_comment_add@{th\_\-comment\_\-add}!basefuncs@{basefuncs}}
\subsubsection{\setlength{\rightskip}{0pt plus 5cm}void th\_\-comment\_\-add ({\bf th\_\-comment} $\ast$ {\em \_\-tc}, char $\ast$ {\em \_\-comment})}\label{group__basefuncs_gca822d55513190861d6186f1a1ac3a72}


Add a comment to an initialized \doxyref{th\_\-comment}{p.}{structth__comment} structure. 

\begin{Desc}
\item[Note:]Neither \doxyref{th\_\-comment\_\-add()}{p.}{group__basefuncs_gca822d55513190861d6186f1a1ac3a72} nor \doxyref{th\_\-comment\_\-add\_\-tag()}{p.}{group__basefuncs_g00a42f948c70db8512de5bfdbec114c5} support comments containing null values, although the bitstream format does support them. To add such comments you will need to manipulate the \doxyref{th\_\-comment}{p.}{structth__comment} structure directly. \end{Desc}
\begin{Desc}
\item[Parameters:]
\begin{description}
\item[{\em \_\-tc}]The \doxyref{th\_\-comment}{p.}{structth__comment} struct to add the comment to. \item[{\em \_\-comment}]Must be a null-terminated UTF-8 string containing the comment in \char`\"{}TAG=the value\char`\"{} form. \end{description}
\end{Desc}
\index{basefuncs@{basefuncs}!th_comment_add_tag@{th\_\-comment\_\-add\_\-tag}}
\index{th_comment_add_tag@{th\_\-comment\_\-add\_\-tag}!basefuncs@{basefuncs}}
\subsubsection{\setlength{\rightskip}{0pt plus 5cm}void th\_\-comment\_\-add\_\-tag ({\bf th\_\-comment} $\ast$ {\em \_\-tc}, char $\ast$ {\em \_\-tag}, char $\ast$ {\em \_\-val})}\label{group__basefuncs_g00a42f948c70db8512de5bfdbec114c5}


Add a comment to an initialized \doxyref{th\_\-comment}{p.}{structth__comment} structure. 

\begin{Desc}
\item[Note:]Neither \doxyref{th\_\-comment\_\-add()}{p.}{group__basefuncs_gca822d55513190861d6186f1a1ac3a72} nor \doxyref{th\_\-comment\_\-add\_\-tag()}{p.}{group__basefuncs_g00a42f948c70db8512de5bfdbec114c5} support comments containing null values, although the bitstream format does support them. To add such comments you will need to manipulate the \doxyref{th\_\-comment}{p.}{structth__comment} structure directly. \end{Desc}
\begin{Desc}
\item[Parameters:]
\begin{description}
\item[{\em \_\-tc}]The \doxyref{th\_\-comment}{p.}{structth__comment} struct to add the comment to. \item[{\em \_\-tag}]A null-terminated string containing the tag associated with the comment. \item[{\em \_\-val}]The corresponding value as a null-terminated string. \end{description}
\end{Desc}
\index{basefuncs@{basefuncs}!th_comment_clear@{th\_\-comment\_\-clear}}
\index{th_comment_clear@{th\_\-comment\_\-clear}!basefuncs@{basefuncs}}
\subsubsection{\setlength{\rightskip}{0pt plus 5cm}void th\_\-comment\_\-clear ({\bf th\_\-comment} $\ast$ {\em \_\-tc})}\label{group__basefuncs_gc6fa7d58af72644989d858f258622af0}


Clears a \doxyref{th\_\-comment}{p.}{structth__comment} structure. 

This should be called on a \doxyref{th\_\-comment}{p.}{structth__comment} structure after it is no longer needed. It will free all memory used by the structure members. \begin{Desc}
\item[Parameters:]
\begin{description}
\item[{\em \_\-tc}]The \doxyref{th\_\-comment}{p.}{structth__comment} struct to clear. \end{description}
\end{Desc}
\index{basefuncs@{basefuncs}!th_comment_init@{th\_\-comment\_\-init}}
\index{th_comment_init@{th\_\-comment\_\-init}!basefuncs@{basefuncs}}
\subsubsection{\setlength{\rightskip}{0pt plus 5cm}void th\_\-comment\_\-init ({\bf th\_\-comment} $\ast$ {\em \_\-tc})}\label{group__basefuncs_g67828854bfe8d853239bd300cf236578}


Initialize a \doxyref{th\_\-comment}{p.}{structth__comment} structure. 

This should be called on a freshly allocated \doxyref{th\_\-comment}{p.}{structth__comment} structure before attempting to use it. \begin{Desc}
\item[Parameters:]
\begin{description}
\item[{\em \_\-tc}]The \doxyref{th\_\-comment}{p.}{structth__comment} struct to initialize. \end{description}
\end{Desc}
\index{basefuncs@{basefuncs}!th_comment_query@{th\_\-comment\_\-query}}
\index{th_comment_query@{th\_\-comment\_\-query}!basefuncs@{basefuncs}}
\subsubsection{\setlength{\rightskip}{0pt plus 5cm}char$\ast$ th\_\-comment\_\-query ({\bf th\_\-comment} $\ast$ {\em \_\-tc}, char $\ast$ {\em \_\-tag}, int {\em \_\-count})}\label{group__basefuncs_g0f57e329036722d57505fa4413629c49}


Look up a comment value by its tag. 

\begin{Desc}
\item[Parameters:]
\begin{description}
\item[{\em \_\-tc}]An initialized \doxyref{th\_\-comment}{p.}{structth__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 value, so an index is required to retrieve them all. The order in which these values appear is significant and should be preserved. Use \doxyref{th\_\-comment\_\-query\_\-count()}{p.}{group__basefuncs_gf6715b961d7b235254e622d5c18e41ac} to get the legal range for the {\em \_\-count\/} parameter. \end{description}
\end{Desc}
\begin{Desc}
\item[Returns:]A pointer to the queried tag's value. This points directly to data in the \doxyref{th\_\-comment}{p.}{structth__comment} structure. It should not be modified or freed by the application, and modifications to the structure may invalidate the pointer. \end{Desc}
\begin{Desc}
\item[Return values:]
\begin{description}
\item[{\em NULL}]If no matching tag is found. \end{description}
\end{Desc}
\index{basefuncs@{basefuncs}!th_comment_query_count@{th\_\-comment\_\-query\_\-count}}
\index{th_comment_query_count@{th\_\-comment\_\-query\_\-count}!basefuncs@{basefuncs}}
\subsubsection{\setlength{\rightskip}{0pt plus 5cm}int th\_\-comment\_\-query\_\-count ({\bf th\_\-comment} $\ast$ {\em \_\-tc}, char $\ast$ {\em \_\-tag})}\label{group__basefuncs_gf6715b961d7b235254e622d5c18e41ac}


Look up the number of instances of a tag. 

Call this first when querying for a specific tag and then iterate over the number of instances with separate calls to \doxyref{th\_\-comment\_\-query()}{p.}{group__basefuncs_g0f57e329036722d57505fa4413629c49} to retrieve all the values for that tag in order. \begin{Desc}
\item[Parameters:]
\begin{description}
\item[{\em \_\-tc}]An initialized \doxyref{th\_\-comment}{p.}{structth__comment} structure. \item[{\em \_\-tag}]The tag to look up. \end{description}
\end{Desc}
\begin{Desc}
\item[Returns:]The number on instances of this particular tag. \end{Desc}
\index{basefuncs@{basefuncs}!th_granule_frame@{th\_\-granule\_\-frame}}
\index{th_granule_frame@{th\_\-granule\_\-frame}!basefuncs@{basefuncs}}
\subsubsection{\setlength{\rightskip}{0pt plus 5cm}ogg\_\-int64\_\-t th\_\-granule\_\-frame (void $\ast$ {\em \_\-encdec}, ogg\_\-int64\_\-t {\em \_\-granpos})}\label{group__basefuncs_g74ec9d46721a87821093894c55b48de6}


Converts a granule position to an absolute frame number. 

The granule position is interpreted in the context of a given th\_\-enc\_\-ctx or \doxyref{th\_\-dec\_\-ctx}{p.}{theoradec_8h_e57d28984ca7a50fa99faaff751e433f} handle (either will suffice). \begin{Desc}
\item[Parameters:]
\begin{description}
\item[{\em \_\-encdec}]A previously allocated th\_\-enc\_\-ctx or \doxyref{th\_\-dec\_\-ctx}{p.}{theoradec_8h_e57d28984ca7a50fa99faaff751e433f} handle. \item[{\em \_\-granpos}]The granule position to convert. \end{description}
\end{Desc}
\begin{Desc}
\item[Returns:]The absolute frame number corresponding to {\em \_\-granpos\/}. \end{Desc}
\begin{Desc}
\item[Return values:]
\begin{description}
\item[{\em -1}]The given granule position was invalid (i.e. negative). \end{description}
\end{Desc}
\index{basefuncs@{basefuncs}!th_granule_time@{th\_\-granule\_\-time}}
\index{th_granule_time@{th\_\-granule\_\-time}!basefuncs@{basefuncs}}
\subsubsection{\setlength{\rightskip}{0pt plus 5cm}double th\_\-granule\_\-time (void $\ast$ {\em \_\-encdec}, ogg\_\-int64\_\-t {\em \_\-granpos})}\label{group__basefuncs_gc9fd7464bb9e061c2a351157f7d9351f}


Converts a granule position to an absolute time in seconds. 

The granule position is interpreted in the context of a given th\_\-enc\_\-ctx or \doxyref{th\_\-dec\_\-ctx}{p.}{theoradec_8h_e57d28984ca7a50fa99faaff751e433f} handle (either will suffice). \begin{Desc}
\item[Parameters:]
\begin{description}
\item[{\em \_\-encdec}]A previously allocated th\_\-enc\_\-ctx or \doxyref{th\_\-dec\_\-ctx}{p.}{theoradec_8h_e57d28984ca7a50fa99faaff751e433f} handle. \item[{\em \_\-granpos}]The granule position to convert. \end{description}
\end{Desc}
\begin{Desc}
\item[Returns:]The absolute time in seconds corresponding to {\em \_\-granpos\/}. \end{Desc}
\begin{Desc}
\item[Return values:]
\begin{description}
\item[{\em -1}]The given granule position was invalid (i.e. negative). \end{description}
\end{Desc}
\index{basefuncs@{basefuncs}!th_info_clear@{th\_\-info\_\-clear}}
\index{th_info_clear@{th\_\-info\_\-clear}!basefuncs@{basefuncs}}
\subsubsection{\setlength{\rightskip}{0pt plus 5cm}void th\_\-info\_\-clear ({\bf th\_\-info} $\ast$ {\em \_\-info})}\label{group__basefuncs_gcac12d219c844d930e23f38e7dcff8c9}


Clears a \doxyref{th\_\-info}{p.}{structth__info} structure. 

This should be called on a \doxyref{th\_\-info}{p.}{structth__info} structure after it is no longer needed. \begin{Desc}
\item[Parameters:]
\begin{description}
\item[{\em \_\-info}]The \doxyref{th\_\-info}{p.}{structth__info} struct to clear. \end{description}
\end{Desc}
\index{basefuncs@{basefuncs}!th_info_init@{th\_\-info\_\-init}}
\index{th_info_init@{th\_\-info\_\-init}!basefuncs@{basefuncs}}
\subsubsection{\setlength{\rightskip}{0pt plus 5cm}void th\_\-info\_\-init ({\bf th\_\-info} $\ast$ {\em \_\-info})}\label{group__basefuncs_g47dd4fd90382e1fcf11f27c8b8eeb860}


Initializes a \doxyref{th\_\-info}{p.}{structth__info} structure. 

This should be called on a freshly allocated \doxyref{th\_\-info}{p.}{structth__info} structure before attempting to use it. \begin{Desc}
\item[Parameters:]
\begin{description}
\item[{\em \_\-info}]The \doxyref{th\_\-info}{p.}{structth__info} struct to initialize. \end{description}
\end{Desc}
\index{basefuncs@{basefuncs}!th_packet_isheader@{th\_\-packet\_\-isheader}}
\index{th_packet_isheader@{th\_\-packet\_\-isheader}!basefuncs@{basefuncs}}
\subsubsection{\setlength{\rightskip}{0pt plus 5cm}int th\_\-packet\_\-isheader (ogg\_\-packet $\ast$ {\em \_\-op})}\label{group__basefuncs_ga46b8bc31ea34ff976c3ed4ba47a2e29}


Determines whether a Theora packet is a header or not. 

This function does no verification beyond checking the packet type bit, so it should not be used for bitstream identification; use \doxyref{th\_\-decode\_\-headerin()}{p.}{group__decfuncs_gb6616614374d049781bf883f995b43d8} for that. As per the Theora specification, an empty (0-byte) packet is treated as a data packet (a delta frame with no coded blocks). \begin{Desc}
\item[Parameters:]
\begin{description}
\item[{\em \_\-op}]An {\tt 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 a video data packet. \end{description}
\end{Desc}
\index{basefuncs@{basefuncs}!th_packet_iskeyframe@{th\_\-packet\_\-iskeyframe}}
\index{th_packet_iskeyframe@{th\_\-packet\_\-iskeyframe}!basefuncs@{basefuncs}}
\subsubsection{\setlength{\rightskip}{0pt plus 5cm}int th\_\-packet\_\-iskeyframe (ogg\_\-packet $\ast$ {\em \_\-op})}\label{group__basefuncs_g02319add6374b9a7ff8a868a3fdc3184}


Determines whether a theora packet is a key frame or not. 

This function does no verification beyond checking the packet type and key frame bits, so it should not be used for bitstream identification; use \doxyref{th\_\-decode\_\-headerin()}{p.}{group__decfuncs_gb6616614374d049781bf883f995b43d8} for that. As per the Theora specification, an empty (0-byte) packet is treated as a delta frame (with no coded blocks). \begin{Desc}
\item[Parameters:]
\begin{description}
\item[{\em \_\-op}]An {\tt ogg\_\-packet} containing encoded Theora data. \end{description}
\end{Desc}
\begin{Desc}
\item[Return values:]
\begin{description}
\item[{\em 1}]The packet contains a key frame. \item[{\em 0}]The packet contains a delta frame. \item[{\em -1}]The packet is not a video data packet. \end{description}
\end{Desc}
\index{basefuncs@{basefuncs}!th_version_number@{th\_\-version\_\-number}}
\index{th_version_number@{th\_\-version\_\-number}!basefuncs@{basefuncs}}
\subsubsection{\setlength{\rightskip}{0pt plus 5cm}ogg\_\-uint32\_\-t th\_\-version\_\-number (void)}\label{group__basefuncs_gf8f6423ebbb784d9eccd94b2ad24115f}


Retrieves the library version number. 

This is the highest bitstream version that the encoder library will produce, or that the decoder library can decode. This number is composed of a 16-bit major version, 8-bit minor version and 8 bit sub-version, composed as follows: 

\begin{Code}\begin{verbatim} (VERSION_MAJOR<<16)+(VERSION_MINOR<<8)+(VERSION_SUBMINOR)
\end{verbatim}\end{Code}

 \begin{Desc}
\item[Returns:]the version number. \end{Desc}
\index{basefuncs@{basefuncs}!th_version_string@{th\_\-version\_\-string}}
\index{th_version_string@{th\_\-version\_\-string}!basefuncs@{basefuncs}}
\subsubsection{\setlength{\rightskip}{0pt plus 5cm}const char$\ast$ th\_\-version\_\-string (void)}\label{group__basefuncs_g40e2ccb7966eca0d2e25c5d363d9615f}


Retrieves a human-readable string to identify the library vendor and version. 

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