diff options
Diffstat (limited to 'media/libtheora/include')
| -rw-r--r-- | media/libtheora/include/theora/codec.h | 77 | ||||
| -rw-r--r-- | media/libtheora/include/theora/theora.h | 112 | ||||
| -rw-r--r-- | media/libtheora/include/theora/theoradec.h | 19 | ||||
| -rw-r--r-- | media/libtheora/include/theora/theoraenc.h | 540 |
4 files changed, 116 insertions, 632 deletions
diff --git a/media/libtheora/include/theora/codec.h b/media/libtheora/include/theora/codec.h index 5c2669630c..29b8602325 100644 --- a/media/libtheora/include/theora/codec.h +++ b/media/libtheora/include/theora/codec.h @@ -16,11 +16,12 @@ ********************************************************************/ /**\mainpage - * + * * \section intro Introduction * - * This is the documentation for <tt>libtheora</tt> C API. - * The current reference + * This is the documentation for the <tt>libtheora</tt> C API. + * + * The \c libtheora package is the current reference * implementation for <a href="http://www.theora.org/">Theora</a>, a free, * patent-unencumbered video codec. * Theora is derived from On2's VP3 codec with additional features and @@ -30,29 +31,31 @@ * <a href="http://www.theora.org/doc/Theora.pdf">the Theora * specification</a>. * - * \subsection Organization + * \section Organization * - * The functions documented here are actually subdivided into three + * The functions documented here are divided between two * separate libraries: - * - <tt>libtheoraenc</tt> contains the encoder interface, + * - \c libtheoraenc contains the encoder interface, * described in \ref encfuncs. - * - <tt>libtheoradec</tt> contains the decoder interface and - * routines shared with the encoder. - * You must also link to this if you link to <tt>libtheoraenc</tt>. - * The routines in this library are described in \ref decfuncs and - * \ref basefuncs. - * - <tt>libtheora</tt> contains the \ref oldfuncs. + * - \c libtheoradec contains the decoder interface, + * described in \ref decfuncs, \n + * and additional \ref basefuncs. + * + * New code should link to \c libtheoradec. If using encoder + * features, it must also link to \c libtheoraenc. * - * New code should link to <tt>libtheoradec</tt> and, if using encoder - * features, <tt>libtheoraenc</tt>. Together these two export both - * the standard and the legacy API, so this is all that is needed by - * any code. The older <tt>libtheora</tt> library is provided just for - * compatibility with older build configurations. + * During initial development, prior to the 1.0 release, + * \c libtheora exported a different \ref oldfuncs which + * combined both encode and decode functions. + * In general, legacy API symbols can be indentified + * by their \c theora_ or \c OC_ namespace prefixes. + * The current API uses \c th_ or \c TH_ instead. * - * In general the recommended 1.x API symbols can be distinguished - * by their <tt>th_</tt> or <tt>TH_</tt> namespace prefix. - * The older, legacy API uses <tt>theora_</tt> or <tt>OC_</tt> - * prefixes instead. + * While deprecated, \c libtheoraenc and \c libtheoradec + * together export the legacy api as well at the one documented above. + * Likewise, the legacy \c libtheora included with this package + * exports the new 1.x API. Older code and build scripts can therefore + * but updated independently to the current scheme. */ /**\file @@ -168,7 +171,7 @@ typedef struct{ typedef th_img_plane th_ycbcr_buffer[3]; /**Theora bitstream information. - * This contains the basic playback parameters for a stream, and corresponds to + * This contains the basic playback parameters for a stream, and corresponds to * the initial 'info' header packet. * To initialize an encoder, the application fills in this structure and * passes it to th_encode_alloc(). @@ -317,7 +320,7 @@ typedef struct{ * In filling in this structure, th_decode_headerin() will null-terminate * the user_comment strings for safety. * However, the bitstream format itself treats them as 8-bit clean vectors, - * possibly containing null characters, and so the length array should be + * possibly containing null characters, so the length array should be * treated as their authoritative length. */ typedef struct th_comment{ @@ -448,7 +451,13 @@ typedef struct{ /**\defgroup basefuncs Functions Shared by Encode and Decode*/ /*@{*/ -/**\name Basic shared functions*/ +/**\name Basic shared functions + * These functions return information about the library itself, + * or provide high-level information about codec state + * and packet type. + * + * You must link to \c libtheoradec if you use any of the + * functions in this section.*/ /*@{*/ /**Retrieves a human-readable string to identify the library vendor and * version. @@ -510,7 +519,12 @@ extern int th_packet_iskeyframe(ogg_packet *_op); /*@}*/ -/**\name Functions for manipulating header data*/ +/**\name Functions for manipulating header data + * These functions manipulate the #th_info and #th_comment structures + * which describe video parameters and key-value metadata, respectively. + * + * You must link to \c libtheoradec if you use any of the + * functions in this section.*/ /*@{*/ /**Initializes a th_info structure. * This should be called on a freshly allocated #th_info structure before @@ -537,7 +551,7 @@ extern void th_comment_init(th_comment *_tc); * \param _tc The #th_comment struct to add the comment to. * \param _comment Must be a null-terminated UTF-8 string containing the * comment in "TAG=the value" form.*/ -extern void th_comment_add(th_comment *_tc, char *_comment); +extern void th_comment_add(th_comment *_tc,const char *_comment); /**Add a comment to an initialized #th_comment structure. * \note Neither th_comment_add() nor th_comment_add_tag() support * comments containing null values, although the bitstream format does @@ -545,10 +559,11 @@ extern void th_comment_add(th_comment *_tc, char *_comment); * To add such comments you will need to manipulate the #th_comment * structure directly. * \param _tc The #th_comment struct to add the comment to. - * \param _tag A null-terminated string containing the tag associated with + * \param _tag A null-terminated string containing the tag associated with * the comment. * \param _val The corresponding value as a null-terminated string.*/ -extern void th_comment_add_tag(th_comment *_tc,char *_tag,char *_val); +extern void th_comment_add_tag(th_comment *_tc,const char *_tag, + const char *_val); /**Look up a comment value by its tag. * \param _tc An initialized #th_comment structure. * \param _tag The tag to look up. @@ -564,15 +579,15 @@ extern void th_comment_add_tag(th_comment *_tc,char *_tag,char *_val); * It should not be modified or freed by the application, and * modifications to the structure may invalidate the pointer. * \retval NULL If no matching tag is found.*/ -extern char *th_comment_query(th_comment *_tc,char *_tag,int _count); +extern char *th_comment_query(th_comment *_tc,const char *_tag,int _count); /**Look up the number of instances of a tag. * Call this first when querying for a specific tag and then iterate over the * number of instances with separate calls to th_comment_query() to * retrieve all the values for that tag in order. * \param _tc An initialized #th_comment structure. * \param _tag The tag to look up. - * \return The number on instances of this particular tag.*/ -extern int th_comment_query_count(th_comment *_tc,char *_tag); + * \return The number of instances of this particular tag.*/ +extern int th_comment_query_count(th_comment *_tc,const char *_tag); /**Clears a #th_comment structure. * This should be called on a #th_comment structure after it is no longer * needed. diff --git a/media/libtheora/include/theora/theora.h b/media/libtheora/include/theora/theora.h index 575a889b71..a729a76890 100644 --- a/media/libtheora/include/theora/theora.h +++ b/media/libtheora/include/theora/theora.h @@ -34,41 +34,41 @@ extern "C" * * \section intro Introduction * - * This is the documentation for the libtheora legacy C API, declared in + * This is the documentation for the libtheora legacy C API, declared in * the theora.h header, which describes the old interface used before * the 1.0 release. This API was widely deployed for several years and - * remains supported, but for new code we recommend the cleaner API + * remains supported, but for new code we recommend the cleaner API * declared in theoradec.h and theoraenc.h. * * libtheora is the reference implementation for * <a href="http://www.theora.org/">Theora</a>, a free video codec. * Theora is derived from On2's VP3 codec with improved integration with * Ogg multimedia formats by <a href="http://www.xiph.org/">Xiph.Org</a>. - * + * * \section overview Overview * - * This library will both decode and encode theora packets to/from raw YUV + * This library will both decode and encode theora packets to/from raw YUV * frames. In either case, the packets will most likely either come from or - * need to be embedded in an Ogg stream. Use - * <a href="http://xiph.org/ogg/">libogg</a> or + * need to be embedded in an Ogg stream. Use + * <a href="http://xiph.org/ogg/">libogg</a> or * <a href="http://www.annodex.net/software/liboggz/index.html">liboggz</a> * to extract/package these packets. * * \section decoding Decoding Process * * Decoding can be separated into the following steps: - * -# initialise theora_info and theora_comment structures using + * -# initialise theora_info and theora_comment structures using * theora_info_init() and theora_comment_init(): \verbatim theora_info info; theora_comment comment; - + theora_info_init(&info); theora_comment_init(&comment); \endverbatim - * -# retrieve header packets from Ogg stream (there should be 3) and decode - * into theora_info and theora_comment structures using - * theora_decode_header(). See \ref identification for more information on + * -# retrieve header packets from Ogg stream (there should be 3) and decode + * into theora_info and theora_comment structures using + * theora_decode_header(). See \ref identification for more information on * identifying which packets are theora packets. \verbatim int i; @@ -79,14 +79,14 @@ extern "C" } \endverbatim * -# initialise the decoder based on the information retrieved into the - * theora_info struct by theora_decode_header(). You will need a + * theora_info struct by theora_decode_header(). You will need a * theora_state struct. \verbatim theora_state state; - + theora_decode_init(&state, &info); \endverbatim - * -# pass in packets and retrieve decoded frames! See the yuv_buffer + * -# pass in packets and retrieve decoded frames! See the yuv_buffer * documentation for information on how to retrieve raw YUV data. \verbatim yuf_buffer buffer; @@ -96,20 +96,20 @@ extern "C" theora_decode_YUVout(&state, &buffer); } \endverbatim - * + * * * \subsection identification Identifying Theora Packets * - * All streams inside an Ogg file have a unique serial_no attached to the - * stream. Typically, you will want to - * - retrieve the serial_no for each b_o_s (beginning of stream) page - * encountered within the Ogg file; - * - test the first (only) packet on that page to determine if it is a theora + * All streams inside an Ogg file have a unique serial_no attached to the + * stream. Typically, you will want to + * - retrieve the serial_no for each b_o_s (beginning of stream) page + * encountered within the Ogg file; + * - test the first (only) packet on that page to determine if it is a theora * packet; - * - once you have found a theora b_o_s page then use the retrieved serial_no + * - once you have found a theora b_o_s page then use the retrieved serial_no * to identify future packets belonging to the same theora stream. - * - * Note that you \e cannot use theora_packet_isheader() to determine if a + * + * Note that you \e cannot use theora_packet_isheader() to determine if a * packet is a theora packet or not, as this function does not perform any * checking beyond whether a header bit is present. Instead, use the * theora_decode_header() function and check the return value; or examine the @@ -124,9 +124,9 @@ extern "C" * A YUV buffer for passing uncompressed frames to and from the codec. * This holds a Y'CbCr frame in planar format. The CbCr planes can be * subsampled and have their own separate dimensions and row stride - * offsets. Note that the strides may be negative in some + * offsets. Note that the strides may be negative in some * configurations. For theora the width and height of the largest plane - * must be a multiple of 16. The actual meaningful picture size and + * must be a multiple of 16. The actual meaningful picture size and * offset are stored in the theora_info structure; frames returned by * the decoder may need to be cropped for display. * @@ -135,8 +135,8 @@ extern "C" * are ordered from left to right. * * During decode, the yuv_buffer struct is allocated by the user, but all - * fields (including luma and chroma pointers) are filled by the library. - * These pointers address library-internal memory and their contents should + * fields (including luma and chroma pointers) are filled by the library. + * These pointers address library-internal memory and their contents should * not be modified. * * Conversely, during encode the user allocates the struct and fills out all @@ -186,7 +186,7 @@ typedef enum { * Theora bitstream info. * Contains the basic playback parameters for a stream, * corresponding to the initial 'info' header packet. - * + * * Encoded theora frames must be a multiple of 16 in width and height. * To handle other frame sizes, a crop rectangle is specified in * frame_height and frame_width, offset_x and * offset_y. The offset @@ -198,10 +198,10 @@ typedef enum { * fraction. Aspect ratio is also stored as a rational fraction, and * refers to the aspect ratio of the frame pixels, not of the * overall frame itself. - * + * * See <a href="http://svn.xiph.org/trunk/theora/examples/encoder_example.c"> * examples/encoder_example.c</a> for usage examples of the - * other paramters and good default settings for the encoder parameters. + * other parameters and good default settings for the encoder parameters. */ typedef struct { ogg_uint32_t width; /**< encoded frame width */ @@ -253,14 +253,14 @@ typedef struct{ } theora_state; -/** +/** * Comment header metadata. * * This structure holds the in-stream metadata corresponding to * the 'comment' header packet. * * Meta data is stored as a series of (tag, value) pairs, in - * length-encoded string vectors. The first occurence of the + * length-encoded string vectors. The first occurence of the * '=' character delimits the tag and value. A particular tag * may occur more than once. The character set encoding for * the strings is always UTF-8, but the tag names are limited @@ -285,7 +285,7 @@ typedef struct theora_comment{ /* \anchor decctlcodes_old * These are the available request codes for theora_control() * when called with a decoder instance. - * By convention decoder control codes are odd, to distinguish + * By convention decoder control codes are odd, to distinguish * them from \ref encctlcodes_old "encoder control codes" which * are even. * @@ -306,7 +306,7 @@ typedef struct theora_comment{ #define TH_DECCTL_GET_PPLEVEL_MAX (1) /**Set the post-processing level. - * Sets the level of post-processing to use when decoding the + * Sets the level of post-processing to use when decoding the * compressed stream. This must be a value between zero (off) * and the maximum returned by TH_DECCTL_GET_PPLEVEL_MAX. */ @@ -345,9 +345,9 @@ typedef struct theora_comment{ * \param[in] buf #th_quant_info * \retval OC_FAULT \a theora_state is <tt>NULL</tt>. * \retval OC_EINVAL Encoding has already begun, the quantization parameters - * are not acceptable to this version of the encoder, - * \a buf is <tt>NULL</tt> and \a buf_sz is not zero, - * or \a buf is non-<tt>NULL</tt> and \a buf_sz is + * are not acceptable to this version of the encoder, + * \a buf is <tt>NULL</tt> and \a buf_sz is not zero, + * or \a buf is non-<tt>NULL</tt> and \a buf_sz is * not <tt>sizeof(#th_quant_info)</tt>. * \retval OC_IMPL Not supported by this implementation.*/ #define TH_ENCCTL_SET_QUANT_PARAMS (2) @@ -424,7 +424,7 @@ typedef struct theora_comment{ #define OC_NEWPACKET -25 /**< Packet is an (ignorable) unhandled extension */ #define OC_DUPFRAME 1 /**< Packet is a dropped frame */ -/** +/** * Retrieve a human-readable string to identify the encoder vendor and version. * \returns A version string. */ @@ -462,7 +462,7 @@ extern int theora_encode_init(theora_state *th, theora_info *ti); extern int theora_encode_YUVin(theora_state *t, yuv_buffer *yuv); /** - * Request the next packet of encoded video. + * Request the next packet of encoded video. * The encoded data is placed in a user-provided ogg_packet structure. * \param t A theora_state handle previously initialized for encoding. * \param last_p whether this is the last packet the encoder should produce. @@ -496,7 +496,11 @@ extern int theora_encode_header(theora_state *t, ogg_packet *op); * \param 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. + * the application, and must be freed by it using _ogg_free(). + * On some systems (such as Windows when using dynamic linking), this + * may mean the free is executed in a different module from the + * malloc, which will crash; there is no way to free this memory on + * such systems. * \retval 0 Success */ extern int theora_encode_comment(theora_comment *tc, ogg_packet *op); @@ -581,8 +585,8 @@ extern int theora_decode_packetin(theora_state *th,ogg_packet *op); * \param th A theora_state handle previously initialized for decoding. * \param yuv A yuv_buffer in which libtheora should place the decoded data. * Note that the buffer struct itself is allocated by the user, but - * that the luma and chroma pointers will be filled in by the - * library. Also note that these luma and chroma regions should be + * that the luma and chroma pointers will be filled in by the + * library. Also note that these luma and chroma regions should be * considered read-only by the user. * \retval 0 Success */ @@ -617,22 +621,22 @@ extern int theora_packet_iskeyframe(ogg_packet *op); /** * Report the granulepos shift radix * - * When embedded in Ogg, Theora uses a two-part granulepos, + * 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. + * 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. + * packets are not being used in an Ogg container. * * \param ti A previously initialized theora_info struct * \returns The bit shift dividing the two granulepos fields @@ -644,7 +648,7 @@ int theora_granule_shift(theora_info *ti); /** * Convert a granulepos to an absolute frame index, starting at 0. * The granulepos is interpreted in the context of a given theora_state handle. - * + * * Note that while the granulepos encodes the frame count (i.e. starting * from 1) this call returns the frame index, starting from zero. Thus * One can calculate the presentation time by multiplying the index by @@ -670,9 +674,7 @@ extern ogg_int64_t theora_granule_frame(theora_state *th,ogg_int64_t granulepos) * This is the "end time" for the frame, or the latest time it should * be displayed. * It is not the presentation time. - * \retval -1. The given granulepos is undefined (i.e. negative), or - * \retval -1. The function has been disabled because floating - * point support is not available. + * \retval -1. The given granulepos is undefined (i.e. negative). */ extern double theora_granule_time(theora_state *th,ogg_int64_t granulepos); @@ -699,7 +701,7 @@ extern void theora_clear(theora_state *t); /** * Initialize an allocated theora_comment structure - * \param tc An allocated theora_comment structure + * \param tc An allocated theora_comment structure **/ extern void theora_comment_init(theora_comment *tc); @@ -720,7 +722,7 @@ extern void theora_comment_add(theora_comment *tc, char *comment); /** * Add a comment to an initialized theora_comment structure. * \param tc A previously initialized theora comment structure - * \param tag A null-terminated string containing the tag + * \param tag A null-terminated string containing the tag * associated with the comment. * \param value The corresponding value as a null-terminated string * @@ -752,9 +754,9 @@ extern char *theora_comment_query(theora_comment *tc, char *tag, int count); * \param tc An initialized theora_comment structure * \param tag The tag to look up * \returns The number on instances of a particular tag. - * + * * Call this first when querying for a specific tag and then interate - * over the number of instances with separate calls to + * over the number of instances with separate calls to * theora_comment_query() to retrieve all instances in order. **/ extern int theora_comment_query_count(theora_comment *tc, char *tag); @@ -769,7 +771,7 @@ extern void theora_comment_clear(theora_comment *tc); * This is used to provide advanced control the encoding process. * \param th A #theora_state handle. * \param req The control code to process. - * See \ref encctlcodes_old "the list of available + * See \ref encctlcodes_old "the list of available * control codes" for details. * \param buf The parameters for this control code. * \param buf_sz The size of the parameter buffer.*/ diff --git a/media/libtheora/include/theora/theoradec.h b/media/libtheora/include/theora/theoradec.h index 6177af3216..77bef81909 100644 --- a/media/libtheora/include/theora/theoradec.h +++ b/media/libtheora/include/theora/theoradec.h @@ -92,13 +92,17 @@ extern "C" { * <tt>sizeof(th_stripe_callback)</tt>.*/ #define TH_DECCTL_SET_STRIPE_CB (7) -/**Enables telemetry and sets the macroblock display mode */ +/**Sets the macroblock display mode. Set to 0 to disable displaying + * macroblocks.*/ #define TH_DECCTL_SET_TELEMETRY_MBMODE (9) -/**Enables telemetry and sets the motion vector display mode */ +/**Sets the motion vector display mode. Set to 0 to disable displaying motion + * vectors.*/ #define TH_DECCTL_SET_TELEMETRY_MV (11) -/**Enables telemetry and sets the adaptive quantization display mode */ +/**Sets the adaptive quantization display mode. Set to 0 to disable displaying + * adaptive quantization. */ #define TH_DECCTL_SET_TELEMETRY_QI (13) -/**Enables telemetry and sets the bitstream breakdown visualization mode */ +/**Sets the bitstream breakdown visualization mode. Set to 0 to disable + * displaying bitstream breakdown.*/ #define TH_DECCTL_SET_TELEMETRY_BITS (15) /*@}*/ @@ -171,7 +175,7 @@ typedef struct th_setup_info th_setup_info; /**\defgroup decfuncs Functions for Decoding*/ /*@{*/ /**\name Functions for decoding - * You must link to <tt>libtheoradec</tt> if you use any of the + * You must link to <tt>libtheoradec</tt> if you use any of the * functions in this section. * * The functions are listed in the order they are used in a typical decode. @@ -267,7 +271,10 @@ extern void th_setup_free(th_setup_info *_setup); * See \ref decctlcodes "the list of available control codes" * for details. * \param _buf The parameters for this control code. - * \param _buf_sz The size of the parameter buffer.*/ + * \param _buf_sz The size of the parameter buffer. + * \return Possible return values depend on the control code used. + * See \ref decctlcodes "the list of control codes" for + * specific values. Generally 0 indicates success.*/ extern int th_decode_ctl(th_dec_ctx *_dec,int _req,void *_buf, size_t _buf_sz); /**Submits a packet containing encoded video data to the decoder. diff --git a/media/libtheora/include/theora/theoraenc.h b/media/libtheora/include/theora/theoraenc.h deleted file mode 100644 index 721ea89b9d..0000000000 --- a/media/libtheora/include/theora/theoraenc.h +++ /dev/null @@ -1,540 +0,0 @@ -/******************************************************************** - * * - * THIS FILE IS PART OF THE OggTheora SOFTWARE CODEC SOURCE CODE. * - * USE, DISTRIBUTION AND REPRODUCTION OF THIS LIBRARY SOURCE IS * - * GOVERNED BY A BSD-STYLE SOURCE LICENSE INCLUDED WITH THIS SOURCE * - * IN 'COPYING'. PLEASE READ THESE TERMS BEFORE DISTRIBUTING. * - * * - * THE Theora SOURCE CODE IS COPYRIGHT (C) 2002-2009 * - * by the Xiph.Org Foundation http://www.xiph.org/ * - * * - ******************************************************************** - - function: - last mod: $Id: theora.h,v 1.8 2004/03/15 22:17:32 derf Exp $ - - ********************************************************************/ - -/**\file - * The <tt>libtheoraenc</tt> C encoding API.*/ - -#if !defined(_O_THEORA_THEORAENC_H_) -# define _O_THEORA_THEORAENC_H_ (1) -# include <stddef.h> -# include <ogg/ogg.h> -# include "codec.h" - -#if defined(__cplusplus) -extern "C" { -#endif - - - -/**\name th_encode_ctl() codes - * \anchor encctlcodes - * These are the available request codes for th_encode_ctl(). - * By convention, these are even, to distinguish them from the - * \ref decctlcodes "decoder control codes". - * Keep any experimental or vendor-specific values above \c 0x8000.*/ -/*@{*/ -/**Sets the Huffman tables to use. - * The tables are copied, not stored by reference, so they can be freed after - * this call. - * <tt>NULL</tt> may be specified to revert to the default tables. - * - * \param[in] _buf <tt>#th_huff_code[#TH_NHUFFMAN_TABLES][#TH_NDCT_TOKENS]</tt> - * \retval TH_EFAULT \a _enc is <tt>NULL</tt>. - * \retval TH_EINVAL Encoding has already begun or one or more of the given - * tables is not full or prefix-free, \a _buf is - * <tt>NULL</tt> and \a _buf_sz is not zero, or \a _buf is - * non-<tt>NULL</tt> and \a _buf_sz is not - * <tt>sizeof(#th_huff_code)*#TH_NHUFFMAN_TABLES*#TH_NDCT_TOKENS</tt>. - * \retval TH_EIMPL Not supported by this implementation.*/ -#define TH_ENCCTL_SET_HUFFMAN_CODES (0) -/**Sets the quantization parameters to use. - * The parameters are copied, not stored by reference, so they can be freed - * after this call. - * <tt>NULL</tt> may be specified to revert to the default parameters. - * - * \param[in] _buf #th_quant_info - * \retval TH_EFAULT \a _enc is <tt>NULL</tt>. - * \retval TH_EINVAL Encoding has already begun, \a _buf is - * <tt>NULL</tt> and \a _buf_sz is not zero, - * or \a _buf is non-<tt>NULL</tt> and - * \a _buf_sz is not <tt>sizeof(#th_quant_info)</tt>. - * \retval TH_EIMPL Not supported by this implementation.*/ -#define TH_ENCCTL_SET_QUANT_PARAMS (2) -/**Sets the maximum distance between key frames. - * This can be changed during an encode, but will be bounded by - * <tt>1<<th_info#keyframe_granule_shift</tt>. - * If it is set before encoding begins, th_info#keyframe_granule_shift will - * be enlarged appropriately. - * - * \param[in] _buf <tt>ogg_uint32_t</tt>: The maximum distance between key - * frames. - * \param[out] _buf <tt>ogg_uint32_t</tt>: The actual maximum distance set. - * \retval TH_EFAULT \a _enc or \a _buf is <tt>NULL</tt>. - * \retval TH_EINVAL \a _buf_sz is not <tt>sizeof(ogg_uint32_t)</tt>. - * \retval TH_EIMPL Not supported by this implementation.*/ -#define TH_ENCCTL_SET_KEYFRAME_FREQUENCY_FORCE (4) -/**Disables any encoder features that would prevent lossless transcoding back - * to VP3. - * This primarily means disabling block-adaptive quantization and always coding - * all four luma blocks in a macro block when 4MV is used. - * It also includes using the VP3 quantization tables and Huffman codes; if you - * set them explicitly after calling this function, the resulting stream will - * not be VP3-compatible. - * If you enable VP3-compatibility when encoding 4:2:2 or 4:4:4 source - * material, or when using a picture region smaller than the full frame (e.g. - * a non-multiple-of-16 width or height), then non-VP3 bitstream features will - * still be disabled, but the stream will still not be VP3-compatible, as VP3 - * was not capable of encoding such formats. - * If you call this after encoding has already begun, then the quantization - * tables and codebooks cannot be changed, but the frame-level features will - * be enabled or disabled as requested. - * - * \param[in] _buf <tt>int</tt>: a non-zero value to enable VP3 compatibility, - * or 0 to disable it (the default). - * \param[out] _buf <tt>int</tt>: 1 if all bitstream features required for - * VP3-compatibility could be set, and 0 otherwise. - * The latter will be returned if the pixel format is not - * 4:2:0, the picture region is smaller than the full frame, - * or if encoding has begun, preventing the quantization - * tables and codebooks from being set. - * \retval TH_EFAULT \a _enc or \a _buf is <tt>NULL</tt>. - * \retval TH_EINVAL \a _buf_sz is not <tt>sizeof(int)</tt>. - * \retval TH_EIMPL Not supported by this implementation.*/ -#define TH_ENCCTL_SET_VP3_COMPATIBLE (10) -/**Gets the maximum speed level. - * Higher speed levels favor quicker encoding over better quality per bit. - * Depending on the encoding mode, and the internal algorithms used, quality - * may actually improve, but in this case bitrate will also likely increase. - * In any case, overall rate/distortion performance will probably decrease. - * The maximum value, and the meaning of each value, may change depending on - * the current encoding mode (VBR vs. constant quality, etc.). - * - * \param[out] _buf <tt>int</tt>: The maximum encoding speed level. - * \retval TH_EFAULT \a _enc or \a _buf is <tt>NULL</tt>. - * \retval TH_EINVAL \a _buf_sz is not <tt>sizeof(int)</tt>. - * \retval TH_EIMPL Not supported by this implementation in the current - * encoding mode.*/ -#define TH_ENCCTL_GET_SPLEVEL_MAX (12) -/**Sets the speed level. - * The current speed level may be retrieved using #TH_ENCCTL_GET_SPLEVEL. - * - * \param[in] _buf <tt>int</tt>: The new encoding speed level. - * 0 is slowest, larger values use less CPU. - * \retval TH_EFAULT \a _enc or \a _buf is <tt>NULL</tt>. - * \retval TH_EINVAL \a _buf_sz is not <tt>sizeof(int)</tt>, or the - * encoding speed level is out of bounds. - * The maximum encoding speed level may be - * implementation- and encoding mode-specific, and can be - * obtained via #TH_ENCCTL_GET_SPLEVEL_MAX. - * \retval TH_EIMPL Not supported by this implementation in the current - * encoding mode.*/ -#define TH_ENCCTL_SET_SPLEVEL (14) -/**Gets the current speed level. - * The default speed level may vary according to encoder implementation, but if - * this control code is not supported (it returns #TH_EIMPL), the default may - * be assumed to be the slowest available speed (0). - * The maximum encoding speed level may be implementation- and encoding - * mode-specific, and can be obtained via #TH_ENCCTL_GET_SPLEVEL_MAX. - * - * \param[out] _buf <tt>int</tt>: The current encoding speed level. - * 0 is slowest, larger values use less CPU. - * \retval TH_EFAULT \a _enc or \a _buf is <tt>NULL</tt>. - * \retval TH_EINVAL \a _buf_sz is not <tt>sizeof(int)</tt>. - * \retval TH_EIMPL Not supported by this implementation in the current - * encoding mode.*/ -#define TH_ENCCTL_GET_SPLEVEL (16) -/**Sets the number of duplicates of the next frame to produce. - * Although libtheora can encode duplicate frames very cheaply, it costs some - * amount of CPU to detect them, and a run of duplicates cannot span a - * keyframe boundary. - * This control code tells the encoder to produce the specified number of extra - * duplicates of the next frame. - * This allows the encoder to make smarter keyframe placement decisions and - * rate control decisions, and reduces CPU usage as well, when compared to - * just submitting the same frame for encoding multiple times. - * This setting only applies to the next frame submitted for encoding. - * You MUST call th_encode_packetout() repeatedly until it returns 0, or the - * extra duplicate frames will be lost. - * - * \param[in] _buf <tt>int</tt>: The number of duplicates to produce. - * If this is negative or zero, no duplicates will be produced. - * \retval TH_EFAULT \a _enc or \a _buf is <tt>NULL</tt>. - * \retval TH_EINVAL \a _buf_sz is not <tt>sizeof(int)</tt>, or the - * number of duplicates is greater than or equal to the - * maximum keyframe interval. - * In the latter case, NO duplicate frames will be produced. - * You must ensure that the maximum keyframe interval is set - * larger than the maximum number of duplicates you will - * ever wish to insert prior to encoding. - * \retval TH_EIMPL Not supported by this implementation in the current - * encoding mode.*/ -#define TH_ENCCTL_SET_DUP_COUNT (18) -/**Modifies the default bitrate management behavior. - * Use to allow or disallow frame dropping, and to enable or disable capping - * bit reservoir overflows and underflows. - * See \ref encctlcodes "the list of available flags". - * The flags are set by default to - * <tt>#TH_RATECTL_DROP_FRAMES|#TH_RATECTL_CAP_OVERFLOW</tt>. - * - * \param[in] _buf <tt>int</tt>: Any combination of - * \ref ratectlflags "the available flags": - * - #TH_RATECTL_DROP_FRAMES: Enable frame dropping. - * - #TH_RATECTL_CAP_OVERFLOW: Don't bank excess bits for later - * use. - * - #TH_RATECTL_CAP_UNDERFLOW: Don't try to make up shortfalls - * later. - * \retval TH_EFAULT \a _enc or \a _buf is <tt>NULL</tt>. - * \retval TH_EINVAL \a _buf_sz is not <tt>sizeof(int)</tt> or rate control - * is not enabled. - * \retval TH_EIMPL Not supported by this implementation in the current - * encoding mode.*/ -#define TH_ENCCTL_SET_RATE_FLAGS (20) -/**Sets the size of the bitrate management bit reservoir as a function - * of number of frames. - * The reservoir size affects how quickly bitrate management reacts to - * instantaneous changes in the video complexity. - * Larger reservoirs react more slowly, and provide better overall quality, but - * require more buffering by a client, adding more latency to live streams. - * By default, libtheora sets the reservoir to the maximum distance between - * keyframes, subject to a minimum and maximum limit. - * This call may be used to increase or decrease the reservoir, increasing or - * decreasing the allowed temporary variance in bitrate. - * An implementation may impose some limits on the size of a reservoir it can - * handle, in which case the actual reservoir size may not be exactly what was - * requested. - * The actual value set will be returned. - * - * \param[in] _buf <tt>int</tt>: Requested size of the reservoir measured in - * frames. - * \param[out] _buf <tt>int</tt>: The actual size of the reservoir set. - * \retval TH_EFAULT \a _enc or \a _buf is <tt>NULL</tt>. - * \retval TH_EINVAL \a _buf_sz is not <tt>sizeof(int)</tt>, or rate control - * is not enabled. The buffer has an implementation - * defined minimum and maximum size and the value in _buf - * will be adjusted to match the actual value set. - * \retval TH_EIMPL Not supported by this implementation in the current - * encoding mode.*/ -#define TH_ENCCTL_SET_RATE_BUFFER (22) -/**Enable pass 1 of two-pass encoding mode and retrieve the first pass metrics. - * Pass 1 mode must be enabled before the first frame is encoded, and a target - * bitrate must have already been specified to the encoder. - * Although this does not have to be the exact rate that will be used in the - * second pass, closer values may produce better results. - * The first call returns the size of the two-pass header data, along with some - * placeholder content, and sets the encoder into pass 1 mode implicitly. - * This call sets the encoder to pass 1 mode implicitly. - * Then, a subsequent call must be made after each call to - * th_encode_ycbcr_in() to retrieve the metrics for that frame. - * An additional, final call must be made to retrieve the summary data, - * containing such information as the total number of frames, etc. - * This must be stored in place of the placeholder data that was returned - * in the first call, before the frame metrics data. - * All of this data must be presented back to the encoder during pass 2 using - * #TH_ENCCTL_2PASS_IN. - * - * \param[out] <tt>char *</tt>_buf: Returns a pointer to internal storage - * containing the two pass metrics data. - * This storage is only valid until the next call, or until the - * encoder context is freed, and must be copied by the - * application. - * \retval >=0 The number of bytes of metric data available in the - * returned buffer. - * \retval TH_EFAULT \a _enc or \a _buf is <tt>NULL</tt>. - * \retval TH_EINVAL \a _buf_sz is not <tt>sizeof(char *)</tt>, no target - * bitrate has been set, or the first call was made after - * the first frame was submitted for encoding. - * \retval TH_EIMPL Not supported by this implementation.*/ -#define TH_ENCCTL_2PASS_OUT (24) -/**Submits two-pass encoding metric data collected the first encoding pass to - * the second pass. - * The first call must be made before the first frame is encoded, and a target - * bitrate must have already been specified to the encoder. - * It sets the encoder to pass 2 mode implicitly; this cannot be disabled. - * The encoder may require reading data from some or all of the frames in - * advance, depending on, e.g., the reservoir size used in the second pass. - * You must call this function repeatedly before each frame to provide data - * until either a) it fails to consume all of the data presented or b) all of - * the pass 1 data has been consumed. - * In the first case, you must save the remaining data to be presented after - * the next frame. - * You can call this function with a NULL argument to get an upper bound on - * the number of bytes that will be required before the next frame. - * - * When pass 2 is first enabled, the default bit reservoir is set to the entire - * file; this gives maximum flexibility but can lead to very high peak rates. - * You can subsequently set it to another value with #TH_ENCCTL_SET_RATE_BUFFER - * (e.g., to set it to the keyframe interval for non-live streaming), however, - * you may then need to provide more data before the next frame. - * - * \param[in] _buf <tt>char[]</tt>: A buffer containing the data returned by - * #TH_ENCCTL_2PASS_OUT in pass 1. - * You may pass <tt>NULL</tt> for \a _buf to return an upper - * bound on the number of additional bytes needed before the - * next frame. - * The summary data returned at the end of pass 1 must be at - * the head of the buffer on the first call with a - * non-<tt>NULL</tt> \a _buf, and the placeholder data - * returned at the start of pass 1 should be omitted. - * After each call you should advance this buffer by the number - * of bytes consumed. - * \retval >0 The number of bytes of metric data required/consumed. - * \retval 0 No more data is required before the next frame. - * \retval TH_EFAULT \a _enc is <tt>NULL</tt>. - * \retval TH_EINVAL No target bitrate has been set, or the first call was - * made after the first frame was submitted for - * encoding. - * \retval TH_ENOTFORMAT The data did not appear to be pass 1 from a compatible - * implementation of this library. - * \retval TH_EBADHEADER The data was invalid; this may be returned when - * attempting to read an aborted pass 1 file that still - * has the placeholder data in place of the summary - * data. - * \retval TH_EIMPL Not supported by this implementation.*/ -#define TH_ENCCTL_2PASS_IN (26) -/**Sets the current encoding quality. - * This is only valid so long as no bitrate has been specified, either through - * the #th_info struct used to initialize the encoder or through - * #TH_ENCCTL_SET_BITRATE (this restriction may be relaxed in a future - * version). - * If it is set before the headers are emitted, the target quality encoded in - * them will be updated. - * - * \param[in] _buf <tt>int</tt>: The new target quality, in the range 0...63, - * inclusive. - * \retval 0 Success. - * \retval TH_EFAULT \a _enc or \a _buf is <tt>NULL</tt>. - * \retval TH_EINVAL A target bitrate has already been specified, or the - * quality index was not in the range 0...63. - * \retval TH_EIMPL Not supported by this implementation.*/ -#define TH_ENCCTL_SET_QUALITY (28) -/**Sets the current encoding bitrate. - * Once a bitrate is set, the encoder must use a rate-controlled mode for all - * future frames (this restriction may be relaxed in a future version). - * If it is set before the headers are emitted, the target bitrate encoded in - * them will be updated. - * Due to the buffer delay, the exact bitrate of each section of the encode is - * not guaranteed. - * The encoder may have already used more bits than allowed for the frames it - * has encoded, expecting to make them up in future frames, or it may have - * used fewer, holding the excess in reserve. - * The exact transition between the two bitrates is not well-defined by this - * API, but may be affected by flags set with #TH_ENCCTL_SET_RATE_FLAGS. - * After a number of frames equal to the buffer delay, one may expect further - * output to average at the target bitrate. - * - * \param[in] _buf <tt>long</tt>: The new target bitrate, in bits per second. - * \retval 0 Success. - * \retval TH_EFAULT \a _enc or \a _buf is <tt>NULL</tt>. - * \retval TH_EINVAL The target bitrate was not positive. - * \retval TH_EIMPL Not supported by this implementation.*/ -#define TH_ENCCTL_SET_BITRATE (30) -/**Sets the configuration to be compatible with that from the given setup - * header. - * This sets the Huffman codebooks and quantization parameters to match those - * found in the given setup header. - * This guarantees that packets encoded by this encoder will be decodable using - * a decoder configured with the passed-in setup header. - * It does <em>not</em> guarantee that th_encode_flushheader() will produce a - * bit-identical setup header, only that they will be compatible. - * If you need a bit-identical setup header, then use the one you passed into - * this command, and not the one returned by th_encode_flushheader(). - * - * This also does <em>not</em> enable or disable VP3 compatibility; that is not - * signaled in the setup header (or anywhere else in the encoded stream), and - * is controlled independently by the #TH_ENCCTL_SET_VP3_COMPATIBLE function. - * If you wish to enable VP3 compatibility mode <em>and</em> want the codebooks - * and quantization parameters to match the given setup header, you should - * enable VP3 compatibility before invoking this command, otherwise the - * codebooks and quantization parameters will be reset to the VP3 defaults. - * - * The current encoder does not support Huffman codebooks which do not contain - * codewords for all 32 tokens. - * Such codebooks are legal, according to the specification, but cannot be - * configured with this function. - * - * \param[in] _buf <tt>unsigned char[]</tt>: The encoded setup header to copy - * the configuration from. - * This should be the original, - * undecoded setup header packet, - * and <em>not</em> a #th_setup_info - * structure filled in by - * th_decode_headerin(). - * \retval TH_EFAULT \a _enc or \a _buf is <tt>NULL</tt>. - * \retval TH_EINVAL Encoding has already begun, so the codebooks and - * quantization parameters cannot be changed, or the - * data in the setup header was not supported by this - * encoder. - * \retval TH_EBADHEADER \a _buf did not contain a valid setup header packet. - * \retval TH_ENOTFORMAT \a _buf did not contain a Theora header at all. - * \retval TH_EIMPL Not supported by this implementation.*/ -#define TH_ENCCTL_SET_COMPAT_CONFIG (32) - -/*@}*/ - - -/**\name TH_ENCCTL_SET_RATE_FLAGS flags - * \anchor ratectlflags - * These are the flags available for use with #TH_ENCCTL_SET_RATE_FLAGS.*/ -/*@{*/ -/**Drop frames to keep within bitrate buffer constraints. - * This can have a severe impact on quality, but is the only way to ensure that - * bitrate targets are met at low rates during sudden bursts of activity.*/ -#define TH_RATECTL_DROP_FRAMES (0x1) -/**Ignore bitrate buffer overflows. - * If the encoder uses so few bits that the reservoir of available bits - * overflows, ignore the excess. - * The encoder will not try to use these extra bits in future frames. - * At high rates this may cause the result to be undersized, but allows a - * client to play the stream using a finite buffer; it should normally be - * enabled.*/ -#define TH_RATECTL_CAP_OVERFLOW (0x2) -/**Ignore bitrate buffer underflows. - * If the encoder uses so many bits that the reservoir of available bits - * underflows, ignore the deficit. - * The encoder will not try to make up these extra bits in future frames. - * At low rates this may cause the result to be oversized; it should normally - * be disabled.*/ -#define TH_RATECTL_CAP_UNDERFLOW (0x4) -/*@}*/ - - - -/**The quantization parameters used by VP3.*/ -extern const th_quant_info TH_VP31_QUANT_INFO; - -/**The Huffman tables used by VP3.*/ -extern const th_huff_code - TH_VP31_HUFF_CODES[TH_NHUFFMAN_TABLES][TH_NDCT_TOKENS]; - - - -/**\name Encoder state - The following data structure is opaque, and its contents are not publicly - defined by this API. - Referring to its internals directly is unsupported, and may break without - warning.*/ -/*@{*/ -/**The encoder context.*/ -typedef struct th_enc_ctx th_enc_ctx; -/*@}*/ - - - -/**\defgroup encfuncs Functions for Encoding*/ -/*@{*/ -/**\name Functions for encoding - * You must link to <tt>libtheoraenc</tt> and <tt>libtheoradec</tt> - * 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: - * - Fill in a #th_info structure with details on the format of the video you - * wish to encode. - * - Allocate a #th_enc_ctx handle with th_encode_alloc(). - * - Perform any additional encoder configuration required with - * th_encode_ctl(). - * - Repeatedly call th_encode_flushheader() to retrieve all the header - * packets. - * - For each uncompressed frame: - * - Submit the uncompressed frame via th_encode_ycbcr_in() - * - Repeatedly call th_encode_packetout() to retrieve any video data packets - * that are ready. - * - Call th_encode_free() to release all encoder memory.*/ -/*@{*/ -/**Allocates an encoder instance. - * \param _info A #th_info struct filled with the desired encoding parameters. - * \return The initialized #th_enc_ctx handle. - * \retval NULL If the encoding parameters were invalid.*/ -extern th_enc_ctx *th_encode_alloc(const th_info *_info); -/**Encoder control function. - * This is used to provide advanced control the encoding process. - * \param _enc A #th_enc_ctx handle. - * \param _req The control code to process. - * See \ref encctlcodes "the list of available control codes" - * for details. - * \param _buf The parameters for this control code. - * \param _buf_sz The size of the parameter buffer.*/ -extern int th_encode_ctl(th_enc_ctx *_enc,int _req,void *_buf,size_t _buf_sz); -/**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. - * \param _enc A #th_enc_ctx handle. - * \param _comments The metadata to place in the comment header, when it is - * encoded. - * \param _op An <tt>ogg_packet</tt> 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 - * <tt>libtheoraenc</tt>, and may be invalidated when the - * next encoder function is called. - * \return A positive value indicates that a header packet was successfully - * produced. - * \retval 0 No packet was produced, and no more header packets remain. - * \retval TH_EFAULT \a _enc, \a _comments, or \a _op was <tt>NULL</tt>.*/ -extern int th_encode_flushheader(th_enc_ctx *_enc, - th_comment *_comments,ogg_packet *_op); -/**Submits an uncompressed frame to the encoder. - * \param _enc A #th_enc_ctx handle. - * \param _ycbcr A buffer of Y'CbCr data to encode. - * If the width and height of the buffer matches the frame size - * the encoder was initialized with, the encoder will only - * reference the portion inside the picture region. - * Any data outside this region will be ignored, and need not map - * to a valid address. - * Alternatively, you can pass a buffer equal to the size of the - * picture region, if this is less than the full frame size. - * When using subsampled chroma planes, odd picture sizes or odd - * picture offsets may require an unexpected chroma plane size, - * and their use is generally discouraged, as they will not be - * well-supported by players and other media frameworks. - * See Section 4.4 of - * <a href="http://www.theora.org/doc/Theora.pdf">the Theora - * specification</a> for details if you wish to use them anyway. - * \retval 0 Success. - * \retval TH_EFAULT \a _enc or \a _ycbcr is <tt>NULL</tt>. - * \retval TH_EINVAL The buffer size matches neither the frame size nor the - * picture size the encoder was initialized with, or - * encoding has already completed.*/ -extern int th_encode_ycbcr_in(th_enc_ctx *_enc,th_ycbcr_buffer _ycbcr); -/**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. - * \note Currently the encoder operates in a one-frame-in, one-packet-out - * manner. - * However, this may be changed in the future. - * \param _enc A #th_enc_ctx handle. - * \param _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. - * \param _op An <tt>ogg_packet</tt> 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 - * <tt>libtheoraenc</tt>, and may be invalidated when the next - * encoder function is called. - * \return A positive value indicates that a video data packet was successfully - * produced. - * \retval 0 No packet was produced, and no more encoded video data - * remains. - * \retval TH_EFAULT \a _enc or \a _op was <tt>NULL</tt>.*/ -extern int th_encode_packetout(th_enc_ctx *_enc,int _last,ogg_packet *_op); -/**Frees an allocated encoder instance. - * \param _enc A #th_enc_ctx handle.*/ -extern void th_encode_free(th_enc_ctx *_enc); -/*@}*/ -/*@}*/ - - - -#if defined(__cplusplus) -} -#endif - -#endif |