Stowage/godot
2
0
Fork 0
mirror of https://github.com/godotengine/godot.git synced 2025-12-08 06:09:55 +00:00
Code Issues Projects Releases Packages Wiki Activity

Update libtheora to GIT (2020.10)

Browse source
This commit is contained in:
DeeJayLSP 2022-09-27 21:18:11 -03:00
parent 92bcd3c01d
commit b87584a070
82 changed files with 11069 additions and 9212 deletions
Download patch file Download diff file Expand all files Collapse all files

77
thirdparty/libtheora/theora/codec.h vendored
View file

@ -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 <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.
* New code should link to \c libtheoradec. If using encoder
* features, it must also link to \c libtheoraenc.
*
* 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.
* 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.
*
* 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.

114
thirdparty/libtheora/theora/theora.h vendored
View file

@ -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.*/

22
thirdparty/libtheora/theora/theoradec.h vendored
View file

@ -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.

112
thirdparty/libtheora/theora/theoraenc.h vendored
View file

@ -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