diff options
Diffstat (limited to 'thirdparty/libtheora/theora')
| -rw-r--r-- | thirdparty/libtheora/theora/codec.h | 77 | ||||
| -rw-r--r-- | thirdparty/libtheora/theora/theora.h | 114 | ||||
| -rw-r--r-- | thirdparty/libtheora/theora/theoradec.h | 22 | ||||
| -rw-r--r-- | thirdparty/libtheora/theora/theoraenc.h | 112 |
4 files changed, 206 insertions, 119 deletions
diff --git a/thirdparty/libtheora/theora/codec.h b/thirdparty/libtheora/theora/codec.h index 5c2669630c..29b8602325 100644 --- a/thirdparty/libtheora/theora/codec.h +++ b/thirdparty/libtheora/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/thirdparty/libtheora/theora/theora.h b/thirdparty/libtheora/theora/theora.h index af6eb6f380..a729a76890 100644 --- a/thirdparty/libtheora/theora/theora.h +++ b/thirdparty/libtheora/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 @@ -179,14 +179,14 @@ typedef enum { OC_PF_420, /**< Chroma subsampling by 2 in each direction (4:2:0) */ OC_PF_RSVD, /**< Reserved value */ OC_PF_422, /**< Horizonatal chroma subsampling by 2 (4:2:2) */ - OC_PF_444, /**< No chroma subsampling at all (4:4:4) */ + OC_PF_444 /**< No chroma subsampling at all (4:4:4) */ } theora_pixelformat; /** * 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/thirdparty/libtheora/theora/theoradec.h b/thirdparty/libtheora/theora/theoradec.h index b20f0e3a64..77bef81909 100644 --- a/thirdparty/libtheora/theora/theoradec.h +++ b/thirdparty/libtheora/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. @@ -283,7 +290,8 @@ extern int th_decode_ctl(th_dec_ctx *_dec,int _req,void *_buf, * \retval 0 Success. * A new decoded frame can be retrieved by calling * th_decode_ycbcr_out(). - * \retval TH_DUPFRAME The packet represented a dropped (0-byte) frame. + * \retval TH_DUPFRAME The packet represented a dropped frame (either a + * 0-byte frame or an INTER frame with no coded blocks). * The player can skip the call to th_decode_ycbcr_out(), * as the contents of the decoded frame buffer have not * changed. diff --git a/thirdparty/libtheora/theora/theoraenc.h b/thirdparty/libtheora/theora/theoraenc.h index fdf2ab21e2..79b1c2b880 100644 --- a/thirdparty/libtheora/theora/theoraenc.h +++ b/thirdparty/libtheora/theora/theoraenc.h @@ -43,7 +43,7 @@ extern "C" { * <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_ctx is <tt>NULL</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 @@ -57,8 +57,8 @@ extern "C" { * <tt>NULL</tt> may be specified to revert to the default parameters. * * \param[in] _buf #th_quant_info - * \retval TH_EFAULT \a _enc_ctx is <tt>NULL</tt>. - * \retval TH_EINVAL Encoding has already begun, \a _buf is + * \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>. @@ -73,7 +73,7 @@ extern "C" { * \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_ctx or \a _buf is <tt>NULL</tt>. + * \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) @@ -101,7 +101,7 @@ extern "C" { * 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_ctx or \a _buf is <tt>NULL</tt>. + * \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) @@ -114,7 +114,7 @@ extern "C" { * 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_ctx or \a _buf is <tt>NULL</tt>. + * \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.*/ @@ -124,7 +124,7 @@ extern "C" { * * \param[in] _buf <tt>int</tt>: The new encoding speed level. * 0 is slowest, larger values use less CPU. - * \retval TH_EFAULT \a _enc_ctx or \a _buf is <tt>NULL</tt>. + * \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 @@ -142,7 +142,7 @@ extern "C" { * * \param[out] _buf <tt>int</tt>: The current encoding speed level. * 0 is slowest, larger values use less CPU. - * \retval TH_EFAULT \a _enc_ctx or \a _buf is <tt>NULL</tt>. + * \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.*/ @@ -162,7 +162,7 @@ extern "C" { * * \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_ctx or \a _buf is <tt>NULL</tt>. + * \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. @@ -187,7 +187,7 @@ extern "C" { * use. * - #TH_RATECTL_CAP_UNDERFLOW: Don't try to make up shortfalls * later. - * \retval TH_EFAULT \a _enc_ctx or \a _buf is <tt>NULL</tt>. + * \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 @@ -211,7 +211,7 @@ extern "C" { * \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_ctx or \a _buf is <tt>NULL</tt>. + * \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 @@ -243,7 +243,7 @@ extern "C" { * application. * \retval >=0 The number of bytes of metric data available in the * returned buffer. - * \retval TH_EFAULT \a _enc_ctx or \a _buf is <tt>NULL</tt>. + * \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. @@ -283,7 +283,7 @@ extern "C" { * 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_ctx is <tt>NULL</tt>. + * \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. @@ -306,7 +306,7 @@ extern "C" { * \param[in] _buf <tt>int</tt>: The new target quality, in the range 0...63, * inclusive. * \retval 0 Success. - * \retval TH_EFAULT \a _enc_ctx or \a _buf is <tt>NULL</tt>. + * \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.*/ @@ -328,10 +328,54 @@ extern "C" { * * \param[in] _buf <tt>long</tt>: The new target bitrate, in bits per second. * \retval 0 Success. - * \retval TH_EFAULT \a _enc_ctx or \a _buf is <tt>NULL</tt>. + * \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.*/ + * A future version of this library may allow passing 0 + * to disabled rate-controlled mode and return to a + * quality-based mode, in which case this function will + * not return an error for that value. + * \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) /*@}*/ @@ -342,7 +386,8 @@ extern "C" { /*@{*/ /**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.*/ + * bitrate targets are met at low rates during sudden bursts of activity. + * It is enabled by default.*/ #define TH_RATECTL_DROP_FRAMES (0x1) /**Ignore bitrate buffer overflows. * If the encoder uses so few bits that the reservoir of available bits @@ -350,14 +395,14 @@ extern "C" { * 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.*/ + * enabled, which is the default.*/ #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.*/ + * be disabled, which is the default.*/ #define TH_RATECTL_CAP_UNDERFLOW (0x4) /*@}*/ @@ -401,8 +446,8 @@ typedef struct th_enc_ctx th_enc_ctx; * 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. + * - 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. @@ -417,7 +462,10 @@ extern th_enc_ctx *th_encode_alloc(const th_info *_info); * 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.*/ + * \param _buf_sz The size of the parameter buffer. + * \return Possible return values depend on the control code used. + * See \ref encctlcodes "the list of control codes" for + * specific values. Generally 0 indicates success.*/ 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 @@ -441,11 +489,25 @@ extern int th_encode_flushheader(th_enc_ctx *_enc, /**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 does not match the frame size the encoder - * was initialized with, or encoding has already - * completed.*/ + * \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 |