theora_8h.tex

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

\begin{description}
\item[{\em tc}]A previously initialized theora comment structure \item[{\em comment}]A null-terminated string encoding the comment in the form \char`\"{}TAG=the value\char`\"{}\end{description}
\end{Desc}
Neither {\bf theora\_\-comment\_\-add()}{\rm (p.\,\pageref{theora_8h_795da8fab8fe137dea276d6bf20bf5f2})} nor {\bf theora\_\-comment\_\-add\_\-tag()}{\rm (p.\,\pageref{theora_8h_adc406fcdc1d2192ae2a9adfb3bd4e6f})} 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. \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_adc406fcdc1d2192ae2a9adfb3bd4e6f}


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

\begin{Desc}
\item[Parameters:]
\begin{description}
\item[{\em tc}]A previously initialized theora comment structure \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\end{description}
\end{Desc}
Neither {\bf theora\_\-comment\_\-add()}{\rm (p.\,\pageref{theora_8h_795da8fab8fe137dea276d6bf20bf5f2})} nor {\bf theora\_\-comment\_\-add\_\-tag()}{\rm (p.\,\pageref{theora_8h_adc406fcdc1d2192ae2a9adfb3bd4e6f})} 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. \index{theora.h@{theora.h}!theora_comment_clear@{theora\_\-comment\_\-clear}}
\index{theora_comment_clear@{theora\_\-comment\_\-clear}!theora.h@{theora.h}}
\subsubsection{\setlength{\rightskip}{0pt plus 5cm}void theora\_\-comment\_\-clear ({\bf theora\_\-comment} $\ast$ {\em tc})}\label{theora_8h_7cabfa586d5e0ecae1dedd7c05d6a1fe}


Clear an allocated {\bf theora\_\-comment}{\rm (p.\,\pageref{structtheora__comment})} struct so that it can be freed. 

\begin{Desc}
\item[Parameters:]
\begin{description}
\item[{\em tc}]An allocated {\bf theora\_\-comment}{\rm (p.\,\pageref{structtheora__comment})} structure. \end{description}
\end{Desc}
\index{theora.h@{theora.h}!theora_comment_init@{theora\_\-comment\_\-init}}
\index{theora_comment_init@{theora\_\-comment\_\-init}!theora.h@{theora.h}}
\subsubsection{\setlength{\rightskip}{0pt plus 5cm}void theora\_\-comment\_\-init ({\bf theora\_\-comment} $\ast$ {\em tc})}\label{theora_8h_531adee5230be7d45af1dede0e82c79a}


Initialize an allocated {\bf theora\_\-comment}{\rm (p.\,\pageref{structtheora__comment})} structure. 

\begin{Desc}
\item[Parameters:]
\begin{description}
\item[{\em tc}]An allocated {\bf theora\_\-comment}{\rm (p.\,\pageref{structtheora__comment})} structure \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_0071768c54009941f50d7c738a33340d}


Look up a comment value by tag. 

\begin{Desc}
\item[Parameters:]
\begin{description}
\item[{\em tc}]Tn 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. \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}]No matching tag is found\end{description}
\end{Desc}
\begin{Desc}
\item[Note:]Use {\bf theora\_\-comment\_\-query\_\-count()}{\rm (p.\,\pageref{theora_8h_d0ee4a15b96518d5d8ab38df814c0b27})} to get the legal range for the count parameter. \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_d0ee4a15b96518d5d8ab38df814c0b27}


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.\end{Desc}
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_0071768c54009941f50d7c738a33340d})} to retrieve all instances in order. \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_41a60c67649c41ae88278d777f89ee3f}


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_f0f9fbb7e7bcce3c536e0b46d300c71e})}. If {\em op\/} contains an initial header, {\bf theora\_\-decode\_\-header()}{\rm (p.\,\pageref{theora_8h_41a60c67649c41ae88278d777f89ee3f})} will fill {\em ci\/} with the parsed header values. If {\em op\/} contains codebook tables, {\bf theora\_\-decode\_\-header()}{\rm (p.\,\pageref{theora_8h_41a60c67649c41ae88278d777f89ee3f})} 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_41a60c67649c41ae88278d777f89ee3f})} 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_41a60c67649c41ae88278d777f89ee3f})} 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_a9f81159ae039353cac6076a59fba871}


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_41a60c67649c41ae88278d777f89ee3f})}. \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_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_a67cbe3cc458aad10904c0cc78044fc5}


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 0}]Success \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_38049cd76f6f1d30906344dcc747782c}


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


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


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 ti})}\label{theora_8h_9544a8feccd8a25e6336a57eac2c411e}


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[Return values:]
\begin{description}