theora_8h.tex

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

\item[{\em 0}]Success \end{description}
\end{Desc}
\index{theora.h@{theora.h}!theora_encode_packetout@{theora\_\-encode\_\-packetout}}
\index{theora_encode_packetout@{theora\_\-encode\_\-packetout}!theora.h@{theora.h}}
\subsubsection{\setlength{\rightskip}{0pt plus 5cm}int theora\_\-encode\_\-packetout ({\bf theora\_\-state} $\ast$ {\em t}, int {\em last\_\-p}, ogg\_\-packet $\ast$ {\em op})}\label{theora_8h_bd4b6f1eb80929ea318fbaa1d5d7fba3}


Request the next packet of encoded video. 

The encoded 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 last\_\-p}]whether this is the last packet the encoder should produce. \item[{\em op}]An ogg\_\-packet structure to fill. libtheora will set all elements of this structure, including a pointer to encoded data. The memory for the encoded data is owned by libtheora. \end{description}
\end{Desc}
\begin{Desc}
\item[Return values:]
\begin{description}
\item[{\em 0}]No internal storage exists OR no packet is ready \item[{\em -1}]The encoding process has completed \item[{\em 1}]Success \end{description}
\end{Desc}
\index{theora.h@{theora.h}!theora_encode_tables@{theora\_\-encode\_\-tables}}
\index{theora_encode_tables@{theora\_\-encode\_\-tables}!theora.h@{theora.h}}
\subsubsection{\setlength{\rightskip}{0pt plus 5cm}int theora\_\-encode\_\-tables ({\bf theora\_\-state} $\ast$ {\em t}, ogg\_\-packet $\ast$ {\em op})}\label{theora_8h_74fcaad3b21a9bfa643f0627ecba96d7}


Request a packet containing the codebook tables for the stream. 

A pointer to the codebook 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 codebook 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_YUVin@{theora\_\-encode\_\-YUVin}}
\index{theora_encode_YUVin@{theora\_\-encode\_\-YUVin}!theora.h@{theora.h}}
\subsubsection{\setlength{\rightskip}{0pt plus 5cm}int theora\_\-encode\_\-YUVin ({\bf theora\_\-state} $\ast$ {\em t}, {\bf yuv\_\-buffer} $\ast$ {\em yuv})}\label{theora_8h_21afcb28b49f5c775a4dbe6ab1d8b00e}


Submit a YUV buffer to the theora encoder. 

\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 yuv}]A buffer of YUV data to encode. \end{description}
\end{Desc}
\begin{Desc}
\item[Return values:]
\begin{description}
\item[{\em OC\_\-EINVAL}]Encoder is not ready, or is finished. \item[{\em -1}]The size of the given frame differs from those previously input \item[{\em 0}]Success \end{description}
\end{Desc}
\index{theora.h@{theora.h}!theora_granule_frame@{theora\_\-granule\_\-frame}}
\index{theora_granule_frame@{theora\_\-granule\_\-frame}!theora.h@{theora.h}}
\subsubsection{\setlength{\rightskip}{0pt plus 5cm}ogg\_\-int64\_\-t theora\_\-granule\_\-frame ({\bf theora\_\-state} $\ast$ {\em th}, ogg\_\-int64\_\-t {\em granulepos})}\label{theora_8h_072d4900733c1d0798b868dafb50847c}


Convert a granulepos to an absolute frame number. 

The granulepos is interpreted in the context of a given {\bf theora\_\-state}{\rm (p.\,\pageref{structtheora__state})} handle.

\begin{Desc}
\item[Parameters:]
\begin{description}
\item[{\em th}]A previously initialized {\bf theora\_\-state}{\rm (p.\,\pageref{structtheora__state})} handle (encode or decode) \item[{\em granulepos}]The granulepos to convert. \end{description}
\end{Desc}
\begin{Desc}
\item[Returns:]The frame number corresponding to {\em granulepos\/}. \end{Desc}
\begin{Desc}
\item[Return values:]
\begin{description}
\item[{\em -1}]The given granulepos is undefined (i.e. negative)\end{description}
\end{Desc}
Thus function was added in the 1.0alpha4 release. \index{theora.h@{theora.h}!theora_granule_shift@{theora\_\-granule\_\-shift}}
\index{theora_granule_shift@{theora\_\-granule\_\-shift}!theora.h@{theora.h}}
\subsubsection{\setlength{\rightskip}{0pt plus 5cm}int theora\_\-granule\_\-shift ({\bf theora\_\-info} $\ast$ {\em ti})}\label{theora_8h_3fd68eba5a134ac84d4db08dd8126991}


Report the granulepos shift radix. 

When embedded in Ogg, Theora uses a two-part granulepos, splitting the 64-bit field into two pieces. The more-significant section represents the frame count at the last keyframe, and the less-significant section represents the count of frames since the last keyframe. In this way the overall field is still non-decreasing with time, but usefully encodes a pointer to the last keyframe, which is necessary for correctly restarting decode after a seek.

This function reports the number of bits used to represent the distance to the last keyframe, and thus how the granulepos field must be shifted or masked to obtain the two parts.

Since libtheora returns compressed data in an ogg\_\-packet structure, this may be generally useful even if the Theora packets are not being used in an Ogg container.

\begin{Desc}
\item[Parameters:]
\begin{description}
\item[{\em ti}]A previously initialized {\bf theora\_\-info}{\rm (p.\,\pageref{structtheora__info})} struct \end{description}
\end{Desc}
\begin{Desc}
\item[Returns:]The bit shift dividing the two granulepos fields\end{Desc}
This function was added in the 1.0alpha5 release. \index{theora.h@{theora.h}!theora_granule_time@{theora\_\-granule\_\-time}}
\index{theora_granule_time@{theora\_\-granule\_\-time}!theora.h@{theora.h}}
\subsubsection{\setlength{\rightskip}{0pt plus 5cm}double theora\_\-granule\_\-time ({\bf theora\_\-state} $\ast$ {\em th}, ogg\_\-int64\_\-t {\em granulepos})}\label{theora_8h_56a89dbe9051fe6a3b7b31a6812df77d}


Convert a granulepos to absolute time in seconds. 

The granulepos is interpreted in the context of a given {\bf theora\_\-state}{\rm (p.\,\pageref{structtheora__state})} handle. \begin{Desc}
\item[Parameters:]
\begin{description}
\item[{\em th}]A previously initialized {\bf theora\_\-state}{\rm (p.\,\pageref{structtheora__state})} handle (encode or decode) \item[{\em granulepos}]The granulepos to convert. \end{description}
\end{Desc}
\begin{Desc}
\item[Returns:]The absolute time in seconds corresponding to {\em granulepos\/}. \end{Desc}
\begin{Desc}
\item[Return values:]
\begin{description}
\item[{\em -1.}]The given granulepos is undefined (i.e. negative), or \item[{\em -1.}]The function has been disabled because floating point support is not available. \end{description}
\end{Desc}
\index{theora.h@{theora.h}!theora_info_clear@{theora\_\-info\_\-clear}}
\index{theora_info_clear@{theora\_\-info\_\-clear}!theora.h@{theora.h}}
\subsubsection{\setlength{\rightskip}{0pt plus 5cm}void theora\_\-info\_\-clear ({\bf theora\_\-info} $\ast$ {\em c})}\label{theora_8h_c72b3f8c404d658d1e675e39a75b1931}


Clear a {\bf theora\_\-info}{\rm (p.\,\pageref{structtheora__info})} structure. 

All values within the given {\bf theora\_\-info}{\rm (p.\,\pageref{structtheora__info})} structure are cleared, and associated internal codec setup data is freed. \begin{Desc}
\item[Parameters:]
\begin{description}
\item[{\em c}]A {\bf theora\_\-info}{\rm (p.\,\pageref{structtheora__info})} struct to initialize. \end{description}
\end{Desc}
\index{theora.h@{theora.h}!theora_info_init@{theora\_\-info\_\-init}}
\index{theora_info_init@{theora\_\-info\_\-init}!theora.h@{theora.h}}
\subsubsection{\setlength{\rightskip}{0pt plus 5cm}void theora\_\-info\_\-init ({\bf theora\_\-info} $\ast$ {\em c})}\label{theora_8h_f0f9fbb7e7bcce3c536e0b46d300c71e}


Initialize a {\bf theora\_\-info}{\rm (p.\,\pageref{structtheora__info})} structure. 

All values within the given {\bf theora\_\-info}{\rm (p.\,\pageref{structtheora__info})} structure are initialized, and space is allocated within libtheora for internal codec setup data. \begin{Desc}
\item[Parameters:]
\begin{description}
\item[{\em c}]A {\bf theora\_\-info}{\rm (p.\,\pageref{structtheora__info})} struct to initialize. \end{description}
\end{Desc}
\index{theora.h@{theora.h}!theora_packet_isheader@{theora\_\-packet\_\-isheader}}
\index{theora_packet_isheader@{theora\_\-packet\_\-isheader}!theora.h@{theora.h}}
\subsubsection{\setlength{\rightskip}{0pt plus 5cm}int theora\_\-packet\_\-isheader (ogg\_\-packet $\ast$ {\em op})}\label{theora_8h_b75731ff4e6a113430715dee160c1626}


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. 

\begin{Desc}
\item[Parameters:]
\begin{description}
\item[{\em op}]An 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 not a header packet (and so contains frame data)\end{description}
\end{Desc}
Thus function was added in the 1.0alpha4 release. \index{theora.h@{theora.h}!theora_packet_iskeyframe@{theora\_\-packet\_\-iskeyframe}}
\index{theora_packet_iskeyframe@{theora\_\-packet\_\-iskeyframe}!theora.h@{theora.h}}
\subsubsection{\setlength{\rightskip}{0pt plus 5cm}int theora\_\-packet\_\-iskeyframe (ogg\_\-packet $\ast$ {\em op})}\label{theora_8h_88a636ebe2e390aa0ca6bb547912814f}


Report whether a theora packet is a keyframe or not. 

\begin{Desc}
\item[Parameters:]
\begin{description}
\item[{\em op}]An ogg\_\-packet containing encoded theora data. \end{description}
\end{Desc}
\begin{Desc}
\item[Return values:]
\begin{description}
\item[{\em 1}]The packet contains a keyframe image \item[{\em 0}]The packet is contains an interframe delta \item[{\em -1}]The packet is not an image data packet at all\end{description}
\end{Desc}
Thus function was added in the 1.0alpha4 release. \index{theora.h@{theora.h}!theora_version_number@{theora\_\-version\_\-number}}
\index{theora_version_number@{theora\_\-version\_\-number}!theora.h@{theora.h}}
\subsubsection{\setlength{\rightskip}{0pt plus 5cm}ogg\_\-uint32\_\-t theora\_\-version\_\-number (void)}\label{theora_8h_d9cec696a9c830e9b3cb1bf4e372b23d}


Retrieve a 32-bit version number. 

This number is composed of a 16-bit major version, 8-bit minor version and 8 bit sub-version, composed as follows: \small\begin{alltt}
   (VERSION\_MAJOR<<16) + (VERSION\_MINOR<<8) + (VERSION\_SUB)
\end{alltt}\normalsize 
 \begin{Desc}
\item[Returns:]The version number. \end{Desc}
\index{theora.h@{theora.h}!theora_version_string@{theora\_\-version\_\-string}}
\index{theora_version_string@{theora\_\-version\_\-string}!theora.h@{theora.h}}
\subsubsection{\setlength{\rightskip}{0pt plus 5cm}const char$\ast$ theora\_\-version\_\-string (void)}\label{theora_8h_7682deb3e6612db562f54ea66b95584b}


Retrieve a human-readable string to identify the encoder vendor and version. 

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