theora_8h.tex

mediastreamer2是开源的网络传输媒体流的库

\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_95aff598c4af451822e7e836b3886cbf}

\begin{CompactList}\small\item\em General failure. \item\end{CompactList}\item 
\#define {\bf OC\_\-EINVAL}~-10\label{theora_8h_06a281a54a00da88abf1a3b29ec11e4a}

\begin{CompactList}\small\item\em Library encountered invalid internal data. \item\end{CompactList}\item 
\#define {\bf OC\_\-DISABLED}~-11\label{theora_8h_b2bc670dc664c72ea6fcbaf9deda3476}

\begin{CompactList}\small\item\em Requested action is disabled. \item\end{CompactList}\item 
\#define {\bf OC\_\-BADHEADER}~-20\label{theora_8h_9d583a6c9a30e48ec7d4ea937f769614}

\begin{CompactList}\small\item\em Header packet was corrupt/invalid. \item\end{CompactList}\item 
\#define {\bf OC\_\-NOTFORMAT}~-21\label{theora_8h_ed82978e76177264a6b8fc3278697c33}

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

\begin{CompactList}\small\item\em Bitstream version is not handled. \item\end{CompactList}\item 
\#define {\bf OC\_\-IMPL}~-23\label{theora_8h_5d58ee606f97079e94c30549584fd7c8}

\begin{CompactList}\small\item\em Feature or action not implemented. \item\end{CompactList}\item 
\#define {\bf OC\_\-BADPACKET}~-24\label{theora_8h_36091b71b428f52454e363463ef6e445}

\begin{CompactList}\small\item\em Packet is corrupt. \item\end{CompactList}\item 
\#define {\bf OC\_\-NEWPACKET}~-25\label{theora_8h_efea777076ff2a9004b418415edba208}

\begin{CompactList}\small\item\em Packet is an (ignorable) unhandled extension. \item\end{CompactList}\item 
\#define {\bf OC\_\-DUPFRAME}~1\label{theora_8h_a4e82ad9e3a51af2f9659f2eb353170e}

\begin{CompactList}\small\item\em Packet is a dropped frame. \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}, 
{\bf OC\_\-CS\_\-NSPACES}
 \}
\begin{CompactList}\small\item\em A Colorspace. \item\end{CompactList}\item 
enum {\bf theora\_\-pixelformat} \{ {\bf OC\_\-PF\_\-420}, 
{\bf OC\_\-PF\_\-RSVD}, 
{\bf OC\_\-PF\_\-422}, 
{\bf OC\_\-PF\_\-444}
 \}
\begin{CompactList}\small\item\em A Chroma subsampling. \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$ti)
\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_41a60c67649c41ae88278d777f89ee3f})} 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 
int {\bf theora\_\-granule\_\-shift} ({\bf theora\_\-info} $\ast$ti)
\begin{CompactList}\small\item\em Report the granulepos shift radix. \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)
\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)
\begin{CompactList}\small\item\em Clear 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{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_fdb3ecc6cbb1a6c346281db5c972d52d}


A Colorspace. 

\begin{Desc}
\item[Enumerator: ]\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_fdb3ecc6cbb1a6c346281db5c972d52d98594a87da35091a8baa4643bd8904ef}
}]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_fdb3ecc6cbb1a6c346281db5c972d52d91b8497a22276b56b62cbec714c6365f}
}]This is the 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_fdb3ecc6cbb1a6c346281db5c972d52d3d957a2abfb9f9b11912eddb564365d3}
}]This is the best option for 'PAL' content. \index{OC_CS_NSPACES@{OC\_\-CS\_\-NSPACES}!theora.h@{theora.h}}\index{theora.h@{theora.h}!OC_CS_NSPACES@{OC\_\-CS\_\-NSPACES}}\item[{\em 
OC\_\-CS\_\-NSPACES\label{theora_8h_fdb3ecc6cbb1a6c346281db5c972d52d171c884c1c919c2c264f8bf6224d758f}
}]This marks the end of the defined colorspaces. \end{description}
\end{Desc}

\index{theora.h@{theora.h}!theora_pixelformat@{theora\_\-pixelformat}}
\index{theora_pixelformat@{theora\_\-pixelformat}!theora.h@{theora.h}}
\subsubsection{\setlength{\rightskip}{0pt plus 5cm}enum {\bf theora\_\-pixelformat}}\label{theora_8h_e6d5fa4a952719a002d8df5ba19fd7d3}


A Chroma subsampling. 

These enumerate the available chroma subsampling options supported by the theora format. See Section 4.4 of the specification for exact definitions. \begin{Desc}
\item[Enumerator: ]\par
\begin{description}
\index{OC_PF_420@{OC\_\-PF\_\-420}!theora.h@{theora.h}}\index{theora.h@{theora.h}!OC_PF_420@{OC\_\-PF\_\-420}}\item[{\em 
OC\_\-PF\_\-420\label{theora_8h_e6d5fa4a952719a002d8df5ba19fd7d3ba38f832e52748c1df744683c15fe05b}
}]Chroma subsampling by 2 in each direction (4:2:0). \index{OC_PF_RSVD@{OC\_\-PF\_\-RSVD}!theora.h@{theora.h}}\index{theora.h@{theora.h}!OC_PF_RSVD@{OC\_\-PF\_\-RSVD}}\item[{\em 
OC\_\-PF\_\-RSVD\label{theora_8h_e6d5fa4a952719a002d8df5ba19fd7d317351a1b9c53cd886ad34c3b1d3bd7b3}
}]Reserved value. \index{OC_PF_422@{OC\_\-PF\_\-422}!theora.h@{theora.h}}\index{theora.h@{theora.h}!OC_PF_422@{OC\_\-PF\_\-422}}\item[{\em 
OC\_\-PF\_\-422\label{theora_8h_e6d5fa4a952719a002d8df5ba19fd7d3c841320c974a9704f146d52d08f31cb0}
}]Horizonatal chroma subsampling by 2 (4:2:2). \index{OC_PF_444@{OC\_\-PF\_\-444}!theora.h@{theora.h}}\index{theora.h@{theora.h}!OC_PF_444@{OC\_\-PF\_\-444}}\item[{\em 
OC\_\-PF\_\-444\label{theora_8h_e6d5fa4a952719a002d8df5ba19fd7d3a2c8a52c7c2e20fac7b0182579e89144}
}]No chroma subsampling at all (4:4:4). \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_c3d872f1cbe57918661471cf41fe2949}


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_795da8fab8fe137dea276d6bf20bf5f2}


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

\begin{Desc}
\item[Parameters:]