\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. \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. \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. \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. \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. \end{DoxyCompactList}\item 
void {\bf th\-\_\-encode\-\_\-free} ({\bf th\-\_\-enc\-\_\-ctx} $\ast$\-\_\-enc)
\begin{DoxyCompactList}\small\item\em \-Frees an allocated encoder instance. \end{DoxyCompactList}\end{DoxyCompactItemize}


\subsection{\-Function \-Documentation}
\index{\-Functions for Encoding@{\-Functions for Encoding}!th\-\_\-encode\-\_\-alloc@{th\-\_\-encode\-\_\-alloc}}
\index{th\-\_\-encode\-\_\-alloc@{th\-\_\-encode\-\_\-alloc}!Functions for Encoding@{\-Functions for Encoding}}
\subsubsection[{th\-\_\-encode\-\_\-alloc}]{\setlength{\rightskip}{0pt plus 5cm}{\bf th\-\_\-enc\-\_\-ctx}$\ast$ {\bf th\-\_\-encode\-\_\-alloc} (
\begin{DoxyParamCaption}
\item[{const {\bf th\-\_\-info} $\ast$}]{\-\_\-info}
\end{DoxyParamCaption}
)}\label{group__encfuncs_gaa91e47bc9dd5f6ee52045bd7b815e5a7}


\-Allocates an encoder instance. 


\begin{DoxyParams}{\-Parameters}
{\em \-\_\-info} & \-A \doxyref{th\-\_\-info}{p.}{structth__info} struct filled with the desired encoding parameters. \\
\hline
\end{DoxyParams}
\begin{DoxyReturn}{\-Returns}
\-The initialized \doxyref{th\-\_\-enc\-\_\-ctx}{p.}{theoraenc_8h_af5cc40472b925456d42526a035d66edd} handle. 
\end{DoxyReturn}

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


\-Encoder control function. 

\-This is used to provide advanced control the encoding process. 
\begin{DoxyParams}{\-Parameters}
{\em \-\_\-enc} & \-A \doxyref{th\-\_\-enc\-\_\-ctx}{p.}{theoraenc_8h_af5cc40472b925456d42526a035d66edd} handle. \\
\hline
{\em \-\_\-req} & \-The control code to process. \-See \doxyref{the list of available control codes}{p.}{theoraenc_8h_encctlcodes} for details. \\
\hline
{\em \-\_\-buf} & \-The parameters for this control code. \\
\hline
{\em \-\_\-buf\-\_\-sz} & \-The size of the parameter buffer. \\
\hline
\end{DoxyParams}
\index{\-Functions for Encoding@{\-Functions for Encoding}!th\-\_\-encode\-\_\-flushheader@{th\-\_\-encode\-\_\-flushheader}}
\index{th\-\_\-encode\-\_\-flushheader@{th\-\_\-encode\-\_\-flushheader}!Functions for Encoding@{\-Functions for Encoding}}
\subsubsection[{th\-\_\-encode\-\_\-flushheader}]{\setlength{\rightskip}{0pt plus 5cm}int {\bf th\-\_\-encode\-\_\-flushheader} (
\begin{DoxyParamCaption}
\item[{{\bf th\-\_\-enc\-\_\-ctx} $\ast$}]{\-\_\-enc, }
\item[{{\bf th\-\_\-comment} $\ast$}]{\-\_\-comments, }
\item[{ogg\-\_\-packet $\ast$}]{\-\_\-op}
\end{DoxyParamCaption}
)}\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}
{\em \-\_\-enc} & \-A \doxyref{th\-\_\-enc\-\_\-ctx}{p.}{theoraenc_8h_af5cc40472b925456d42526a035d66edd} handle. \\
\hline
{\em \-\_\-comments} & \-The metadata to place in the comment header, when it is encoded. \\
\hline
{\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. \\
\hline
\end{DoxyParams}
\begin{DoxyReturn}{\-Returns}
\-A positive value indicates that a header packet was successfully produced. 
\end{DoxyReturn}

\begin{DoxyRetVals}{\-Return values}
{\em 0} & \-No packet was produced, and no more header packets remain. \\
\hline
{\em \-T\-H\-\_\-\-E\-F\-A\-U\-L\-T} & {\itshape \-\_\-enc\/}, {\itshape \-\_\-comments\/}, or {\itshape \-\_\-op\/} was {\ttfamily \-N\-U\-L\-L}. \\
\hline
\end{DoxyRetVals}
\index{\-Functions for Encoding@{\-Functions for Encoding}!th\-\_\-encode\-\_\-free@{th\-\_\-encode\-\_\-free}}
\index{th\-\_\-encode\-\_\-free@{th\-\_\-encode\-\_\-free}!Functions for Encoding@{\-Functions for Encoding}}
\subsubsection[{th\-\_\-encode\-\_\-free}]{\setlength{\rightskip}{0pt plus 5cm}void {\bf th\-\_\-encode\-\_\-free} (
\begin{DoxyParamCaption}
\item[{{\bf th\-\_\-enc\-\_\-ctx} $\ast$}]{\-\_\-enc}
\end{DoxyParamCaption}
)}\label{group__encfuncs_ga36b23d216532231925c4107894204680}


\-Frees an allocated encoder instance. 


\begin{DoxyParams}{\-Parameters}
{\em \-\_\-enc} & \-A \doxyref{th\-\_\-enc\-\_\-ctx}{p.}{theoraenc_8h_af5cc40472b925456d42526a035d66edd} handle. \\
\hline
\end{DoxyParams}
\index{\-Functions for Encoding@{\-Functions for Encoding}!th\-\_\-encode\-\_\-packetout@{th\-\_\-encode\-\_\-packetout}}
\index{th\-\_\-encode\-\_\-packetout@{th\-\_\-encode\-\_\-packetout}!Functions for Encoding@{\-Functions for Encoding}}
\subsubsection[{th\-\_\-encode\-\_\-packetout}]{\setlength{\rightskip}{0pt plus 5cm}int {\bf th\-\_\-encode\-\_\-packetout} (
\begin{DoxyParamCaption}
\item[{{\bf th\-\_\-enc\-\_\-ctx} $\ast$}]{\-\_\-enc, }
\item[{int}]{\-\_\-last, }
\item[{ogg\-\_\-packet $\ast$}]{\-\_\-op}
\end{DoxyParamCaption}
)}\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}
{\em \-\_\-enc} & \-A \doxyref{th\-\_\-enc\-\_\-ctx}{p.}{theoraenc_8h_af5cc40472b925456d42526a035d66edd} handle. \\
\hline
{\em \-\_\-last} & \-Set this flag to a non-\/zero value if no more uncompressed frames will be submitted. \-This ensures that a proper \-E\-O\-S flag is set on the last packet. \\
\hline
{\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. \\
\hline
\end{DoxyParams}
\begin{DoxyReturn}{\-Returns}
\-A positive value indicates that a video data packet was successfully produced. 
\end{DoxyReturn}

\begin{DoxyRetVals}{\-Return values}
{\em 0} & \-No packet was produced, and no more encoded video data remains. \\
\hline
{\em \-T\-H\-\_\-\-E\-F\-A\-U\-L\-T} & {\itshape \-\_\-enc\/} or {\itshape \-\_\-op\/} was {\ttfamily \-N\-U\-L\-L}. \\
\hline
\end{DoxyRetVals}
\index{\-Functions for Encoding@{\-Functions for Encoding}!th\-\_\-encode\-\_\-ycbcr\-\_\-in@{th\-\_\-encode\-\_\-ycbcr\-\_\-in}}
\index{th\-\_\-encode\-\_\-ycbcr\-\_\-in@{th\-\_\-encode\-\_\-ycbcr\-\_\-in}!Functions for Encoding@{\-Functions for Encoding}}
\subsubsection[{th\-\_\-encode\-\_\-ycbcr\-\_\-in}]{\setlength{\rightskip}{0pt plus 5cm}int {\bf th\-\_\-encode\-\_\-ycbcr\-\_\-in} (
\begin{DoxyParamCaption}
\item[{{\bf th\-\_\-enc\-\_\-ctx} $\ast$}]{\-\_\-enc, }
\item[{{\bf th\-\_\-ycbcr\-\_\-buffer}}]{\-\_\-ycbcr}
\end{DoxyParamCaption}
)}\label{group__encfuncs_gadbe7dd66b411c2d61ab8153c15308750}


\-Submits an uncompressed frame to the encoder. 


\begin{DoxyParams}{\-Parameters}
{\em \-\_\-enc} & \-A \doxyref{th\-\_\-enc\-\_\-ctx}{p.}{theoraenc_8h_af5cc40472b925456d42526a035d66edd} handle. \\
\hline
{\em \-\_\-ycbcr} & \-A buffer of \-Y'\-Cb\-Cr data to encode. \\
\hline
\end{DoxyParams}

\begin{DoxyRetVals}{\-Return values}
{\em 0} & \-Success. \\
\hline
{\em \-T\-H\-\_\-\-E\-F\-A\-U\-L\-T} & {\itshape \-\_\-enc\/} or {\itshape \-\_\-ycbcr\/} is {\ttfamily \-N\-U\-L\-L}. \\
\hline
{\em \-T\-H\-\_\-\-E\-I\-N\-V\-A\-L} & \-The buffer size does not match the frame size the encoder was initialized with, or encoding has already completed. \\
\hline
\end{DoxyRetVals}