\section{Functions for Encoding}
\label{group__encfuncs}\index{Functions for Encoding@{Functions for Encoding}}
\subsection*{Functions for encoding}
\label{_amgrpc58fb8743a7ca83eb895d57e29e032c8}
You must link to {\ttfamily libtheoraenc} and {\ttfamily libtheoradec} if you use any of the functions in this section.

The functions are listed in the order they are used in a typical encode. The basic steps are:
\begin{DoxyItemize}
\item Fill in a \doxyref{th\_\-info}{p.}{structth__info} structure with details on the format of the video you wish to encode.
\item Allocate a \doxyref{th\_\-enc\_\-ctx}{p.}{theoraenc_8h_af5cc40472b925456d42526a035d66edd} handle with \doxyref{th\_\-encode\_\-alloc()}{p.}{group__encfuncs_gaa91e47bc9dd5f6ee52045bd7b815e5a7}.
\item Perform any additional encoder configuration required with \doxyref{th\_\-encode\_\-ctl()}{p.}{group__encfuncs_ga3a427f6514dfdc01ea72172c469d51d9}.
\item Repeatedly call \doxyref{th\_\-encode\_\-flushheader()}{p.}{group__encfuncs_ga9439d61b566039d194ff782681fbc408} to retrieve all the header packets.
\item For each uncompressed frame:
\begin{DoxyItemize}
\item Submit the uncompressed frame via \doxyref{th\_\-encode\_\-ycbcr\_\-in()}{p.}{group__encfuncs_gadbe7dd66b411c2d61ab8153c15308750}
\item Repeatedly call \doxyref{th\_\-encode\_\-packetout()}{p.}{group__encfuncs_ga96d8ac1dda53187455352f99bbb5b04b} to retrieve any video data packets that are ready.
\end{DoxyItemize}
\item Call \doxyref{th\_\-encode\_\-free()}{p.}{group__encfuncs_ga36b23d216532231925c4107894204680} to release all encoder memory. 
\end{DoxyItemize}\begin{DoxyCompactItemize}
\item 
{\bf th\_\-enc\_\-ctx} $\ast$ {\bf th\_\-encode\_\-alloc} (const {\bf th\_\-info} $\ast$\_\-info)
\begin{DoxyCompactList}\small\item\em Allocates an encoder instance. \item\end{DoxyCompactList}\item 
int {\bf th\_\-encode\_\-ctl} ({\bf th\_\-enc\_\-ctx} $\ast$\_\-enc, int \_\-req, void $\ast$\_\-buf, size\_\-t \_\-buf\_\-sz)
\begin{DoxyCompactList}\small\item\em Encoder control function. \item\end{DoxyCompactList}\item 
int {\bf th\_\-encode\_\-flushheader} ({\bf th\_\-enc\_\-ctx} $\ast$\_\-enc, {\bf th\_\-comment} $\ast$\_\-comments, ogg\_\-packet $\ast$\_\-op)
\begin{DoxyCompactList}\small\item\em Outputs the next header packet. \item\end{DoxyCompactList}\item 
int {\bf th\_\-encode\_\-ycbcr\_\-in} ({\bf th\_\-enc\_\-ctx} $\ast$\_\-enc, {\bf th\_\-ycbcr\_\-buffer} \_\-ycbcr)
\begin{DoxyCompactList}\small\item\em Submits an uncompressed frame to the encoder. \item\end{DoxyCompactList}\item 
int {\bf th\_\-encode\_\-packetout} ({\bf th\_\-enc\_\-ctx} $\ast$\_\-enc, int \_\-last, ogg\_\-packet $\ast$\_\-op)
\begin{DoxyCompactList}\small\item\em Retrieves encoded video data packets. \item\end{DoxyCompactList}\item 
void {\bf th\_\-encode\_\-free} ({\bf th\_\-enc\_\-ctx} $\ast$\_\-enc)
\begin{DoxyCompactList}\small\item\em Frees an allocated encoder instance. \item\end{DoxyCompactList}\end{DoxyCompactItemize}


\subsection{Function Documentation}
\index{encfuncs@{encfuncs}!th\_\-encode\_\-alloc@{th\_\-encode\_\-alloc}}
\index{th\_\-encode\_\-alloc@{th\_\-encode\_\-alloc}!encfuncs@{encfuncs}}
\subsubsection[{th\_\-encode\_\-alloc}]{\setlength{\rightskip}{0pt plus 5cm}{\bf th\_\-enc\_\-ctx}$\ast$ th\_\-encode\_\-alloc (const {\bf th\_\-info} $\ast$ {\em \_\-info})}\label{group__encfuncs_gaa91e47bc9dd5f6ee52045bd7b815e5a7}


Allocates an encoder instance. 
\begin{DoxyParams}{Parameters}
\item[{\em \_\-info}]A \doxyref{th\_\-info}{p.}{structth__info} struct filled with the desired encoding parameters. \end{DoxyParams}
\begin{DoxyReturn}{Returns}
The initialized \doxyref{th\_\-enc\_\-ctx}{p.}{theoraenc_8h_af5cc40472b925456d42526a035d66edd} handle. 
\end{DoxyReturn}

\begin{DoxyRetVals}{Return values}
\item[{\em NULL}]If the encoding parameters were invalid. \end{DoxyRetVals}
\index{encfuncs@{encfuncs}!th\_\-encode\_\-ctl@{th\_\-encode\_\-ctl}}
\index{th\_\-encode\_\-ctl@{th\_\-encode\_\-ctl}!encfuncs@{encfuncs}}
\subsubsection[{th\_\-encode\_\-ctl}]{\setlength{\rightskip}{0pt plus 5cm}int th\_\-encode\_\-ctl ({\bf th\_\-enc\_\-ctx} $\ast$ {\em \_\-enc}, \/  int {\em \_\-req}, \/  void $\ast$ {\em \_\-buf}, \/  size\_\-t {\em \_\-buf\_\-sz})}\label{group__encfuncs_ga3a427f6514dfdc01ea72172c469d51d9}


Encoder control function. This is used to provide advanced control the encoding process. 
\begin{DoxyParams}{Parameters}
\item[{\em \_\-enc}]A \doxyref{th\_\-enc\_\-ctx}{p.}{theoraenc_8h_af5cc40472b925456d42526a035d66edd} handle. \item[{\em \_\-req}]The control code to process. See \doxyref{the list of available control codes}{p.}{theoraenc_8h_encctlcodes} for details. \item[{\em \_\-buf}]The parameters for this control code. \item[{\em \_\-buf\_\-sz}]The size of the parameter buffer. \end{DoxyParams}
\index{encfuncs@{encfuncs}!th\_\-encode\_\-flushheader@{th\_\-encode\_\-flushheader}}
\index{th\_\-encode\_\-flushheader@{th\_\-encode\_\-flushheader}!encfuncs@{encfuncs}}
\subsubsection[{th\_\-encode\_\-flushheader}]{\setlength{\rightskip}{0pt plus 5cm}int th\_\-encode\_\-flushheader ({\bf th\_\-enc\_\-ctx} $\ast$ {\em \_\-enc}, \/  {\bf th\_\-comment} $\ast$ {\em \_\-comments}, \/  ogg\_\-packet $\ast$ {\em \_\-op})}\label{group__encfuncs_ga9439d61b566039d194ff782681fbc408}


Outputs the next header packet. This should be called repeatedly after encoder initialization until it returns 0 in order to get all of the header packets, in order, before encoding actual video data. 
\begin{DoxyParams}{Parameters}
\item[{\em \_\-enc}]A \doxyref{th\_\-enc\_\-ctx}{p.}{theoraenc_8h_af5cc40472b925456d42526a035d66edd} handle. \item[{\em \_\-comments}]The metadata to place in the comment header, when it is encoded. \item[{\em \_\-op}]An {\ttfamily ogg\_\-packet} structure to fill. All of the elements of this structure will be set, including a pointer to the header data. The memory for the header data is owned by {\ttfamily libtheoraenc}, and may be invalidated when the next encoder function is called. \end{DoxyParams}
\begin{DoxyReturn}{Returns}
A positive value indicates that a header packet was successfully produced. 
\end{DoxyReturn}

\begin{DoxyRetVals}{Return values}
\item[{\em 0}]No packet was produced, and no more header packets remain. \item[{\em TH\_\-EFAULT}]{\itshape \_\-enc\/}, {\itshape \_\-comments\/}, or {\itshape \_\-op\/} was {\ttfamily NULL}. \end{DoxyRetVals}
\index{encfuncs@{encfuncs}!th\_\-encode\_\-free@{th\_\-encode\_\-free}}
\index{th\_\-encode\_\-free@{th\_\-encode\_\-free}!encfuncs@{encfuncs}}
\subsubsection[{th\_\-encode\_\-free}]{\setlength{\rightskip}{0pt plus 5cm}void th\_\-encode\_\-free ({\bf th\_\-enc\_\-ctx} $\ast$ {\em \_\-enc})}\label{group__encfuncs_ga36b23d216532231925c4107894204680}


Frees an allocated encoder instance. 
\begin{DoxyParams}{Parameters}
\item[{\em \_\-enc}]A \doxyref{th\_\-enc\_\-ctx}{p.}{theoraenc_8h_af5cc40472b925456d42526a035d66edd} handle. \end{DoxyParams}
\index{encfuncs@{encfuncs}!th\_\-encode\_\-packetout@{th\_\-encode\_\-packetout}}
\index{th\_\-encode\_\-packetout@{th\_\-encode\_\-packetout}!encfuncs@{encfuncs}}
\subsubsection[{th\_\-encode\_\-packetout}]{\setlength{\rightskip}{0pt plus 5cm}int th\_\-encode\_\-packetout ({\bf th\_\-enc\_\-ctx} $\ast$ {\em \_\-enc}, \/  int {\em \_\-last}, \/  ogg\_\-packet $\ast$ {\em \_\-op})}\label{group__encfuncs_ga96d8ac1dda53187455352f99bbb5b04b}


Retrieves encoded video data packets. This should be called repeatedly after each frame is submitted to flush any encoded packets, until it returns 0. The encoder will not buffer these packets as subsequent frames are compressed, so a failure to do so will result in lost video data. \begin{DoxyNote}{Note}
Currently the encoder operates in a one-\/frame-\/in, one-\/packet-\/out manner. However, this may be changed in the future. 
\end{DoxyNote}

\begin{DoxyParams}{Parameters}
\item[{\em \_\-enc}]A \doxyref{th\_\-enc\_\-ctx}{p.}{theoraenc_8h_af5cc40472b925456d42526a035d66edd} handle. \item[{\em \_\-last}]Set this flag to a non-\/zero value if no more uncompressed frames will be submitted. This ensures that a proper EOS flag is set on the last packet. \item[{\em \_\-op}]An {\ttfamily ogg\_\-packet} structure to fill. All of the elements of this structure will be set, including a pointer to the video data. The memory for the video data is owned by {\ttfamily libtheoraenc}, and may be invalidated when the next encoder function is called. \end{DoxyParams}
\begin{DoxyReturn}{Returns}
A positive value indicates that a video data packet was successfully produced. 
\end{DoxyReturn}

\begin{DoxyRetVals}{Return values}
\item[{\em 0}]No packet was produced, and no more encoded video data remains. \item[{\em TH\_\-EFAULT}]{\itshape \_\-enc\/} or {\itshape \_\-op\/} was {\ttfamily NULL}. \end{DoxyRetVals}
\index{encfuncs@{encfuncs}!th\_\-encode\_\-ycbcr\_\-in@{th\_\-encode\_\-ycbcr\_\-in}}
\index{th\_\-encode\_\-ycbcr\_\-in@{th\_\-encode\_\-ycbcr\_\-in}!encfuncs@{encfuncs}}
\subsubsection[{th\_\-encode\_\-ycbcr\_\-in}]{\setlength{\rightskip}{0pt plus 5cm}int th\_\-encode\_\-ycbcr\_\-in ({\bf th\_\-enc\_\-ctx} $\ast$ {\em \_\-enc}, \/  {\bf th\_\-ycbcr\_\-buffer} {\em \_\-ycbcr})}\label{group__encfuncs_gadbe7dd66b411c2d61ab8153c15308750}


Submits an uncompressed frame to the encoder. 
\begin{DoxyParams}{Parameters}
\item[{\em \_\-enc}]A \doxyref{th\_\-enc\_\-ctx}{p.}{theoraenc_8h_af5cc40472b925456d42526a035d66edd} handle. \item[{\em \_\-ycbcr}]A buffer of Y'CbCr data to encode. \end{DoxyParams}

\begin{DoxyRetVals}{Return values}
\item[{\em 0}]Success. \item[{\em TH\_\-EFAULT}]{\itshape \_\-enc\/} or {\itshape \_\-ycbcr\/} is {\ttfamily NULL}. \item[{\em TH\_\-EINVAL}]The buffer size does not match the frame size the encoder was initialized with, or encoding has already completed. \end{DoxyRetVals}