michael@0: /********************************************************************
michael@0: * *
michael@0: * THIS FILE IS PART OF THE OggTheora SOFTWARE CODEC SOURCE CODE. *
michael@0: * USE, DISTRIBUTION AND REPRODUCTION OF THIS LIBRARY SOURCE IS *
michael@0: * GOVERNED BY A BSD-STYLE SOURCE LICENSE INCLUDED WITH THIS SOURCE *
michael@0: * IN 'COPYING'. PLEASE READ THESE TERMS BEFORE DISTRIBUTING. *
michael@0: * *
michael@0: * THE Theora SOURCE CODE IS COPYRIGHT (C) 2002-2009 *
michael@0: * by the Xiph.Org Foundation http://www.xiph.org/ *
michael@0: * *
michael@0: ********************************************************************
michael@0:
michael@0: function:
michael@0: last mod: $Id: theora.h,v 1.8 2004/03/15 22:17:32 derf Exp $
michael@0:
michael@0: ********************************************************************/
michael@0:
michael@0: /**\file
michael@0: * The libtheoraenc C encoding API.*/
michael@0:
michael@0: #if !defined(_O_THEORA_THEORAENC_H_)
michael@0: # define _O_THEORA_THEORAENC_H_ (1)
michael@0: # include
michael@0: # include
michael@0: # include "codec.h"
michael@0:
michael@0: #if defined(__cplusplus)
michael@0: extern "C" {
michael@0: #endif
michael@0:
michael@0:
michael@0:
michael@0: /**\name th_encode_ctl() codes
michael@0: * \anchor encctlcodes
michael@0: * These are the available request codes for th_encode_ctl().
michael@0: * By convention, these are even, to distinguish them from the
michael@0: * \ref decctlcodes "decoder control codes".
michael@0: * Keep any experimental or vendor-specific values above \c 0x8000.*/
michael@0: /*@{*/
michael@0: /**Sets the Huffman tables to use.
michael@0: * The tables are copied, not stored by reference, so they can be freed after
michael@0: * this call.
michael@0: * NULL may be specified to revert to the default tables.
michael@0: *
michael@0: * \param[in] _buf #th_huff_code[#TH_NHUFFMAN_TABLES][#TH_NDCT_TOKENS]
michael@0: * \retval TH_EFAULT \a _enc is NULL.
michael@0: * \retval TH_EINVAL Encoding has already begun or one or more of the given
michael@0: * tables is not full or prefix-free, \a _buf is
michael@0: * NULL and \a _buf_sz is not zero, or \a _buf is
michael@0: * non-NULL and \a _buf_sz is not
michael@0: * sizeof(#th_huff_code)*#TH_NHUFFMAN_TABLES*#TH_NDCT_TOKENS.
michael@0: * \retval TH_EIMPL Not supported by this implementation.*/
michael@0: #define TH_ENCCTL_SET_HUFFMAN_CODES (0)
michael@0: /**Sets the quantization parameters to use.
michael@0: * The parameters are copied, not stored by reference, so they can be freed
michael@0: * after this call.
michael@0: * NULL may be specified to revert to the default parameters.
michael@0: *
michael@0: * \param[in] _buf #th_quant_info
michael@0: * \retval TH_EFAULT \a _enc is NULL.
michael@0: * \retval TH_EINVAL Encoding has already begun, \a _buf is
michael@0: * NULL and \a _buf_sz is not zero,
michael@0: * or \a _buf is non-NULL and
michael@0: * \a _buf_sz is not sizeof(#th_quant_info).
michael@0: * \retval TH_EIMPL Not supported by this implementation.*/
michael@0: #define TH_ENCCTL_SET_QUANT_PARAMS (2)
michael@0: /**Sets the maximum distance between key frames.
michael@0: * This can be changed during an encode, but will be bounded by
michael@0: * 1<.
michael@0: * If it is set before encoding begins, th_info#keyframe_granule_shift will
michael@0: * be enlarged appropriately.
michael@0: *
michael@0: * \param[in] _buf ogg_uint32_t: The maximum distance between key
michael@0: * frames.
michael@0: * \param[out] _buf ogg_uint32_t: The actual maximum distance set.
michael@0: * \retval TH_EFAULT \a _enc or \a _buf is NULL.
michael@0: * \retval TH_EINVAL \a _buf_sz is not sizeof(ogg_uint32_t).
michael@0: * \retval TH_EIMPL Not supported by this implementation.*/
michael@0: #define TH_ENCCTL_SET_KEYFRAME_FREQUENCY_FORCE (4)
michael@0: /**Disables any encoder features that would prevent lossless transcoding back
michael@0: * to VP3.
michael@0: * This primarily means disabling block-adaptive quantization and always coding
michael@0: * all four luma blocks in a macro block when 4MV is used.
michael@0: * It also includes using the VP3 quantization tables and Huffman codes; if you
michael@0: * set them explicitly after calling this function, the resulting stream will
michael@0: * not be VP3-compatible.
michael@0: * If you enable VP3-compatibility when encoding 4:2:2 or 4:4:4 source
michael@0: * material, or when using a picture region smaller than the full frame (e.g.
michael@0: * a non-multiple-of-16 width or height), then non-VP3 bitstream features will
michael@0: * still be disabled, but the stream will still not be VP3-compatible, as VP3
michael@0: * was not capable of encoding such formats.
michael@0: * If you call this after encoding has already begun, then the quantization
michael@0: * tables and codebooks cannot be changed, but the frame-level features will
michael@0: * be enabled or disabled as requested.
michael@0: *
michael@0: * \param[in] _buf int: a non-zero value to enable VP3 compatibility,
michael@0: * or 0 to disable it (the default).
michael@0: * \param[out] _buf int: 1 if all bitstream features required for
michael@0: * VP3-compatibility could be set, and 0 otherwise.
michael@0: * The latter will be returned if the pixel format is not
michael@0: * 4:2:0, the picture region is smaller than the full frame,
michael@0: * or if encoding has begun, preventing the quantization
michael@0: * tables and codebooks from being set.
michael@0: * \retval TH_EFAULT \a _enc or \a _buf is NULL.
michael@0: * \retval TH_EINVAL \a _buf_sz is not sizeof(int).
michael@0: * \retval TH_EIMPL Not supported by this implementation.*/
michael@0: #define TH_ENCCTL_SET_VP3_COMPATIBLE (10)
michael@0: /**Gets the maximum speed level.
michael@0: * Higher speed levels favor quicker encoding over better quality per bit.
michael@0: * Depending on the encoding mode, and the internal algorithms used, quality
michael@0: * may actually improve, but in this case bitrate will also likely increase.
michael@0: * In any case, overall rate/distortion performance will probably decrease.
michael@0: * The maximum value, and the meaning of each value, may change depending on
michael@0: * the current encoding mode (VBR vs. constant quality, etc.).
michael@0: *
michael@0: * \param[out] _buf int: The maximum encoding speed level.
michael@0: * \retval TH_EFAULT \a _enc or \a _buf is NULL.
michael@0: * \retval TH_EINVAL \a _buf_sz is not sizeof(int).
michael@0: * \retval TH_EIMPL Not supported by this implementation in the current
michael@0: * encoding mode.*/
michael@0: #define TH_ENCCTL_GET_SPLEVEL_MAX (12)
michael@0: /**Sets the speed level.
michael@0: * The current speed level may be retrieved using #TH_ENCCTL_GET_SPLEVEL.
michael@0: *
michael@0: * \param[in] _buf int: The new encoding speed level.
michael@0: * 0 is slowest, larger values use less CPU.
michael@0: * \retval TH_EFAULT \a _enc or \a _buf is NULL.
michael@0: * \retval TH_EINVAL \a _buf_sz is not sizeof(int), or the
michael@0: * encoding speed level is out of bounds.
michael@0: * The maximum encoding speed level may be
michael@0: * implementation- and encoding mode-specific, and can be
michael@0: * obtained via #TH_ENCCTL_GET_SPLEVEL_MAX.
michael@0: * \retval TH_EIMPL Not supported by this implementation in the current
michael@0: * encoding mode.*/
michael@0: #define TH_ENCCTL_SET_SPLEVEL (14)
michael@0: /**Gets the current speed level.
michael@0: * The default speed level may vary according to encoder implementation, but if
michael@0: * this control code is not supported (it returns #TH_EIMPL), the default may
michael@0: * be assumed to be the slowest available speed (0).
michael@0: * The maximum encoding speed level may be implementation- and encoding
michael@0: * mode-specific, and can be obtained via #TH_ENCCTL_GET_SPLEVEL_MAX.
michael@0: *
michael@0: * \param[out] _buf int: The current encoding speed level.
michael@0: * 0 is slowest, larger values use less CPU.
michael@0: * \retval TH_EFAULT \a _enc or \a _buf is NULL.
michael@0: * \retval TH_EINVAL \a _buf_sz is not sizeof(int).
michael@0: * \retval TH_EIMPL Not supported by this implementation in the current
michael@0: * encoding mode.*/
michael@0: #define TH_ENCCTL_GET_SPLEVEL (16)
michael@0: /**Sets the number of duplicates of the next frame to produce.
michael@0: * Although libtheora can encode duplicate frames very cheaply, it costs some
michael@0: * amount of CPU to detect them, and a run of duplicates cannot span a
michael@0: * keyframe boundary.
michael@0: * This control code tells the encoder to produce the specified number of extra
michael@0: * duplicates of the next frame.
michael@0: * This allows the encoder to make smarter keyframe placement decisions and
michael@0: * rate control decisions, and reduces CPU usage as well, when compared to
michael@0: * just submitting the same frame for encoding multiple times.
michael@0: * This setting only applies to the next frame submitted for encoding.
michael@0: * You MUST call th_encode_packetout() repeatedly until it returns 0, or the
michael@0: * extra duplicate frames will be lost.
michael@0: *
michael@0: * \param[in] _buf int: The number of duplicates to produce.
michael@0: * If this is negative or zero, no duplicates will be produced.
michael@0: * \retval TH_EFAULT \a _enc or \a _buf is NULL.
michael@0: * \retval TH_EINVAL \a _buf_sz is not sizeof(int), or the
michael@0: * number of duplicates is greater than or equal to the
michael@0: * maximum keyframe interval.
michael@0: * In the latter case, NO duplicate frames will be produced.
michael@0: * You must ensure that the maximum keyframe interval is set
michael@0: * larger than the maximum number of duplicates you will
michael@0: * ever wish to insert prior to encoding.
michael@0: * \retval TH_EIMPL Not supported by this implementation in the current
michael@0: * encoding mode.*/
michael@0: #define TH_ENCCTL_SET_DUP_COUNT (18)
michael@0: /**Modifies the default bitrate management behavior.
michael@0: * Use to allow or disallow frame dropping, and to enable or disable capping
michael@0: * bit reservoir overflows and underflows.
michael@0: * See \ref encctlcodes "the list of available flags".
michael@0: * The flags are set by default to
michael@0: * #TH_RATECTL_DROP_FRAMES|#TH_RATECTL_CAP_OVERFLOW.
michael@0: *
michael@0: * \param[in] _buf int: Any combination of
michael@0: * \ref ratectlflags "the available flags":
michael@0: * - #TH_RATECTL_DROP_FRAMES: Enable frame dropping.
michael@0: * - #TH_RATECTL_CAP_OVERFLOW: Don't bank excess bits for later
michael@0: * use.
michael@0: * - #TH_RATECTL_CAP_UNDERFLOW: Don't try to make up shortfalls
michael@0: * later.
michael@0: * \retval TH_EFAULT \a _enc or \a _buf is NULL.
michael@0: * \retval TH_EINVAL \a _buf_sz is not sizeof(int) or rate control
michael@0: * is not enabled.
michael@0: * \retval TH_EIMPL Not supported by this implementation in the current
michael@0: * encoding mode.*/
michael@0: #define TH_ENCCTL_SET_RATE_FLAGS (20)
michael@0: /**Sets the size of the bitrate management bit reservoir as a function
michael@0: * of number of frames.
michael@0: * The reservoir size affects how quickly bitrate management reacts to
michael@0: * instantaneous changes in the video complexity.
michael@0: * Larger reservoirs react more slowly, and provide better overall quality, but
michael@0: * require more buffering by a client, adding more latency to live streams.
michael@0: * By default, libtheora sets the reservoir to the maximum distance between
michael@0: * keyframes, subject to a minimum and maximum limit.
michael@0: * This call may be used to increase or decrease the reservoir, increasing or
michael@0: * decreasing the allowed temporary variance in bitrate.
michael@0: * An implementation may impose some limits on the size of a reservoir it can
michael@0: * handle, in which case the actual reservoir size may not be exactly what was
michael@0: * requested.
michael@0: * The actual value set will be returned.
michael@0: *
michael@0: * \param[in] _buf int: Requested size of the reservoir measured in
michael@0: * frames.
michael@0: * \param[out] _buf int: The actual size of the reservoir set.
michael@0: * \retval TH_EFAULT \a _enc or \a _buf is NULL.
michael@0: * \retval TH_EINVAL \a _buf_sz is not sizeof(int), or rate control
michael@0: * is not enabled. The buffer has an implementation
michael@0: * defined minimum and maximum size and the value in _buf
michael@0: * will be adjusted to match the actual value set.
michael@0: * \retval TH_EIMPL Not supported by this implementation in the current
michael@0: * encoding mode.*/
michael@0: #define TH_ENCCTL_SET_RATE_BUFFER (22)
michael@0: /**Enable pass 1 of two-pass encoding mode and retrieve the first pass metrics.
michael@0: * Pass 1 mode must be enabled before the first frame is encoded, and a target
michael@0: * bitrate must have already been specified to the encoder.
michael@0: * Although this does not have to be the exact rate that will be used in the
michael@0: * second pass, closer values may produce better results.
michael@0: * The first call returns the size of the two-pass header data, along with some
michael@0: * placeholder content, and sets the encoder into pass 1 mode implicitly.
michael@0: * This call sets the encoder to pass 1 mode implicitly.
michael@0: * Then, a subsequent call must be made after each call to
michael@0: * th_encode_ycbcr_in() to retrieve the metrics for that frame.
michael@0: * An additional, final call must be made to retrieve the summary data,
michael@0: * containing such information as the total number of frames, etc.
michael@0: * This must be stored in place of the placeholder data that was returned
michael@0: * in the first call, before the frame metrics data.
michael@0: * All of this data must be presented back to the encoder during pass 2 using
michael@0: * #TH_ENCCTL_2PASS_IN.
michael@0: *
michael@0: * \param[out] char *_buf: Returns a pointer to internal storage
michael@0: * containing the two pass metrics data.
michael@0: * This storage is only valid until the next call, or until the
michael@0: * encoder context is freed, and must be copied by the
michael@0: * application.
michael@0: * \retval >=0 The number of bytes of metric data available in the
michael@0: * returned buffer.
michael@0: * \retval TH_EFAULT \a _enc or \a _buf is NULL.
michael@0: * \retval TH_EINVAL \a _buf_sz is not sizeof(char *), no target
michael@0: * bitrate has been set, or the first call was made after
michael@0: * the first frame was submitted for encoding.
michael@0: * \retval TH_EIMPL Not supported by this implementation.*/
michael@0: #define TH_ENCCTL_2PASS_OUT (24)
michael@0: /**Submits two-pass encoding metric data collected the first encoding pass to
michael@0: * the second pass.
michael@0: * The first call must be made before the first frame is encoded, and a target
michael@0: * bitrate must have already been specified to the encoder.
michael@0: * It sets the encoder to pass 2 mode implicitly; this cannot be disabled.
michael@0: * The encoder may require reading data from some or all of the frames in
michael@0: * advance, depending on, e.g., the reservoir size used in the second pass.
michael@0: * You must call this function repeatedly before each frame to provide data
michael@0: * until either a) it fails to consume all of the data presented or b) all of
michael@0: * the pass 1 data has been consumed.
michael@0: * In the first case, you must save the remaining data to be presented after
michael@0: * the next frame.
michael@0: * You can call this function with a NULL argument to get an upper bound on
michael@0: * the number of bytes that will be required before the next frame.
michael@0: *
michael@0: * When pass 2 is first enabled, the default bit reservoir is set to the entire
michael@0: * file; this gives maximum flexibility but can lead to very high peak rates.
michael@0: * You can subsequently set it to another value with #TH_ENCCTL_SET_RATE_BUFFER
michael@0: * (e.g., to set it to the keyframe interval for non-live streaming), however,
michael@0: * you may then need to provide more data before the next frame.
michael@0: *
michael@0: * \param[in] _buf char[]: A buffer containing the data returned by
michael@0: * #TH_ENCCTL_2PASS_OUT in pass 1.
michael@0: * You may pass NULL for \a _buf to return an upper
michael@0: * bound on the number of additional bytes needed before the
michael@0: * next frame.
michael@0: * The summary data returned at the end of pass 1 must be at
michael@0: * the head of the buffer on the first call with a
michael@0: * non-NULL \a _buf, and the placeholder data
michael@0: * returned at the start of pass 1 should be omitted.
michael@0: * After each call you should advance this buffer by the number
michael@0: * of bytes consumed.
michael@0: * \retval >0 The number of bytes of metric data required/consumed.
michael@0: * \retval 0 No more data is required before the next frame.
michael@0: * \retval TH_EFAULT \a _enc is NULL.
michael@0: * \retval TH_EINVAL No target bitrate has been set, or the first call was
michael@0: * made after the first frame was submitted for
michael@0: * encoding.
michael@0: * \retval TH_ENOTFORMAT The data did not appear to be pass 1 from a compatible
michael@0: * implementation of this library.
michael@0: * \retval TH_EBADHEADER The data was invalid; this may be returned when
michael@0: * attempting to read an aborted pass 1 file that still
michael@0: * has the placeholder data in place of the summary
michael@0: * data.
michael@0: * \retval TH_EIMPL Not supported by this implementation.*/
michael@0: #define TH_ENCCTL_2PASS_IN (26)
michael@0: /**Sets the current encoding quality.
michael@0: * This is only valid so long as no bitrate has been specified, either through
michael@0: * the #th_info struct used to initialize the encoder or through
michael@0: * #TH_ENCCTL_SET_BITRATE (this restriction may be relaxed in a future
michael@0: * version).
michael@0: * If it is set before the headers are emitted, the target quality encoded in
michael@0: * them will be updated.
michael@0: *
michael@0: * \param[in] _buf int: The new target quality, in the range 0...63,
michael@0: * inclusive.
michael@0: * \retval 0 Success.
michael@0: * \retval TH_EFAULT \a _enc or \a _buf is NULL.
michael@0: * \retval TH_EINVAL A target bitrate has already been specified, or the
michael@0: * quality index was not in the range 0...63.
michael@0: * \retval TH_EIMPL Not supported by this implementation.*/
michael@0: #define TH_ENCCTL_SET_QUALITY (28)
michael@0: /**Sets the current encoding bitrate.
michael@0: * Once a bitrate is set, the encoder must use a rate-controlled mode for all
michael@0: * future frames (this restriction may be relaxed in a future version).
michael@0: * If it is set before the headers are emitted, the target bitrate encoded in
michael@0: * them will be updated.
michael@0: * Due to the buffer delay, the exact bitrate of each section of the encode is
michael@0: * not guaranteed.
michael@0: * The encoder may have already used more bits than allowed for the frames it
michael@0: * has encoded, expecting to make them up in future frames, or it may have
michael@0: * used fewer, holding the excess in reserve.
michael@0: * The exact transition between the two bitrates is not well-defined by this
michael@0: * API, but may be affected by flags set with #TH_ENCCTL_SET_RATE_FLAGS.
michael@0: * After a number of frames equal to the buffer delay, one may expect further
michael@0: * output to average at the target bitrate.
michael@0: *
michael@0: * \param[in] _buf long: The new target bitrate, in bits per second.
michael@0: * \retval 0 Success.
michael@0: * \retval TH_EFAULT \a _enc or \a _buf is NULL.
michael@0: * \retval TH_EINVAL The target bitrate was not positive.
michael@0: * \retval TH_EIMPL Not supported by this implementation.*/
michael@0: #define TH_ENCCTL_SET_BITRATE (30)
michael@0: /**Sets the configuration to be compatible with that from the given setup
michael@0: * header.
michael@0: * This sets the Huffman codebooks and quantization parameters to match those
michael@0: * found in the given setup header.
michael@0: * This guarantees that packets encoded by this encoder will be decodable using
michael@0: * a decoder configured with the passed-in setup header.
michael@0: * It does not guarantee that th_encode_flushheader() will produce a
michael@0: * bit-identical setup header, only that they will be compatible.
michael@0: * If you need a bit-identical setup header, then use the one you passed into
michael@0: * this command, and not the one returned by th_encode_flushheader().
michael@0: *
michael@0: * This also does not enable or disable VP3 compatibility; that is not
michael@0: * signaled in the setup header (or anywhere else in the encoded stream), and
michael@0: * is controlled independently by the #TH_ENCCTL_SET_VP3_COMPATIBLE function.
michael@0: * If you wish to enable VP3 compatibility mode and want the codebooks
michael@0: * and quantization parameters to match the given setup header, you should
michael@0: * enable VP3 compatibility before invoking this command, otherwise the
michael@0: * codebooks and quantization parameters will be reset to the VP3 defaults.
michael@0: *
michael@0: * The current encoder does not support Huffman codebooks which do not contain
michael@0: * codewords for all 32 tokens.
michael@0: * Such codebooks are legal, according to the specification, but cannot be
michael@0: * configured with this function.
michael@0: *
michael@0: * \param[in] _buf unsigned char[]: The encoded setup header to copy
michael@0: * the configuration from.
michael@0: * This should be the original,
michael@0: * undecoded setup header packet,
michael@0: * and not a #th_setup_info
michael@0: * structure filled in by
michael@0: * th_decode_headerin().
michael@0: * \retval TH_EFAULT \a _enc or \a _buf is NULL.
michael@0: * \retval TH_EINVAL Encoding has already begun, so the codebooks and
michael@0: * quantization parameters cannot be changed, or the
michael@0: * data in the setup header was not supported by this
michael@0: * encoder.
michael@0: * \retval TH_EBADHEADER \a _buf did not contain a valid setup header packet.
michael@0: * \retval TH_ENOTFORMAT \a _buf did not contain a Theora header at all.
michael@0: * \retval TH_EIMPL Not supported by this implementation.*/
michael@0: #define TH_ENCCTL_SET_COMPAT_CONFIG (32)
michael@0:
michael@0: /*@}*/
michael@0:
michael@0:
michael@0: /**\name TH_ENCCTL_SET_RATE_FLAGS flags
michael@0: * \anchor ratectlflags
michael@0: * These are the flags available for use with #TH_ENCCTL_SET_RATE_FLAGS.*/
michael@0: /*@{*/
michael@0: /**Drop frames to keep within bitrate buffer constraints.
michael@0: * This can have a severe impact on quality, but is the only way to ensure that
michael@0: * bitrate targets are met at low rates during sudden bursts of activity.*/
michael@0: #define TH_RATECTL_DROP_FRAMES (0x1)
michael@0: /**Ignore bitrate buffer overflows.
michael@0: * If the encoder uses so few bits that the reservoir of available bits
michael@0: * overflows, ignore the excess.
michael@0: * The encoder will not try to use these extra bits in future frames.
michael@0: * At high rates this may cause the result to be undersized, but allows a
michael@0: * client to play the stream using a finite buffer; it should normally be
michael@0: * enabled.*/
michael@0: #define TH_RATECTL_CAP_OVERFLOW (0x2)
michael@0: /**Ignore bitrate buffer underflows.
michael@0: * If the encoder uses so many bits that the reservoir of available bits
michael@0: * underflows, ignore the deficit.
michael@0: * The encoder will not try to make up these extra bits in future frames.
michael@0: * At low rates this may cause the result to be oversized; it should normally
michael@0: * be disabled.*/
michael@0: #define TH_RATECTL_CAP_UNDERFLOW (0x4)
michael@0: /*@}*/
michael@0:
michael@0:
michael@0:
michael@0: /**The quantization parameters used by VP3.*/
michael@0: extern const th_quant_info TH_VP31_QUANT_INFO;
michael@0:
michael@0: /**The Huffman tables used by VP3.*/
michael@0: extern const th_huff_code
michael@0: TH_VP31_HUFF_CODES[TH_NHUFFMAN_TABLES][TH_NDCT_TOKENS];
michael@0:
michael@0:
michael@0:
michael@0: /**\name Encoder state
michael@0: The following data structure is opaque, and its contents are not publicly
michael@0: defined by this API.
michael@0: Referring to its internals directly is unsupported, and may break without
michael@0: warning.*/
michael@0: /*@{*/
michael@0: /**The encoder context.*/
michael@0: typedef struct th_enc_ctx th_enc_ctx;
michael@0: /*@}*/
michael@0:
michael@0:
michael@0:
michael@0: /**\defgroup encfuncs Functions for Encoding*/
michael@0: /*@{*/
michael@0: /**\name Functions for encoding
michael@0: * You must link to libtheoraenc and libtheoradec
michael@0: * if you use any of the functions in this section.
michael@0: *
michael@0: * The functions are listed in the order they are used in a typical encode.
michael@0: * The basic steps are:
michael@0: * - Fill in a #th_info structure with details on the format of the video you
michael@0: * wish to encode.
michael@0: * - Allocate a #th_enc_ctx handle with th_encode_alloc().
michael@0: * - Perform any additional encoder configuration required with
michael@0: * th_encode_ctl().
michael@0: * - Repeatedly call th_encode_flushheader() to retrieve all the header
michael@0: * packets.
michael@0: * - For each uncompressed frame:
michael@0: * - Submit the uncompressed frame via th_encode_ycbcr_in()
michael@0: * - Repeatedly call th_encode_packetout() to retrieve any video data packets
michael@0: * that are ready.
michael@0: * - Call th_encode_free() to release all encoder memory.*/
michael@0: /*@{*/
michael@0: /**Allocates an encoder instance.
michael@0: * \param _info A #th_info struct filled with the desired encoding parameters.
michael@0: * \return The initialized #th_enc_ctx handle.
michael@0: * \retval NULL If the encoding parameters were invalid.*/
michael@0: extern th_enc_ctx *th_encode_alloc(const th_info *_info);
michael@0: /**Encoder control function.
michael@0: * This is used to provide advanced control the encoding process.
michael@0: * \param _enc A #th_enc_ctx handle.
michael@0: * \param _req The control code to process.
michael@0: * See \ref encctlcodes "the list of available control codes"
michael@0: * for details.
michael@0: * \param _buf The parameters for this control code.
michael@0: * \param _buf_sz The size of the parameter buffer.*/
michael@0: extern int th_encode_ctl(th_enc_ctx *_enc,int _req,void *_buf,size_t _buf_sz);
michael@0: /**Outputs the next header packet.
michael@0: * This should be called repeatedly after encoder initialization until it
michael@0: * returns 0 in order to get all of the header packets, in order, before
michael@0: * encoding actual video data.
michael@0: * \param _enc A #th_enc_ctx handle.
michael@0: * \param _comments The metadata to place in the comment header, when it is
michael@0: * encoded.
michael@0: * \param _op An ogg_packet structure to fill.
michael@0: * All of the elements of this structure will be set,
michael@0: * including a pointer to the header data.
michael@0: * The memory for the header data is owned by
michael@0: * libtheoraenc, and may be invalidated when the
michael@0: * next encoder function is called.
michael@0: * \return A positive value indicates that a header packet was successfully
michael@0: * produced.
michael@0: * \retval 0 No packet was produced, and no more header packets remain.
michael@0: * \retval TH_EFAULT \a _enc, \a _comments, or \a _op was NULL.*/
michael@0: extern int th_encode_flushheader(th_enc_ctx *_enc,
michael@0: th_comment *_comments,ogg_packet *_op);
michael@0: /**Submits an uncompressed frame to the encoder.
michael@0: * \param _enc A #th_enc_ctx handle.
michael@0: * \param _ycbcr A buffer of Y'CbCr data to encode.
michael@0: * If the width and height of the buffer matches the frame size
michael@0: * the encoder was initialized with, the encoder will only
michael@0: * reference the portion inside the picture region.
michael@0: * Any data outside this region will be ignored, and need not map
michael@0: * to a valid address.
michael@0: * Alternatively, you can pass a buffer equal to the size of the
michael@0: * picture region, if this is less than the full frame size.
michael@0: * When using subsampled chroma planes, odd picture sizes or odd
michael@0: * picture offsets may require an unexpected chroma plane size,
michael@0: * and their use is generally discouraged, as they will not be
michael@0: * well-supported by players and other media frameworks.
michael@0: * See Section 4.4 of
michael@0: * the Theora
michael@0: * specification for details if you wish to use them anyway.
michael@0: * \retval 0 Success.
michael@0: * \retval TH_EFAULT \a _enc or \a _ycbcr is NULL.
michael@0: * \retval TH_EINVAL The buffer size matches neither the frame size nor the
michael@0: * picture size the encoder was initialized with, or
michael@0: * encoding has already completed.*/
michael@0: extern int th_encode_ycbcr_in(th_enc_ctx *_enc,th_ycbcr_buffer _ycbcr);
michael@0: /**Retrieves encoded video data packets.
michael@0: * This should be called repeatedly after each frame is submitted to flush any
michael@0: * encoded packets, until it returns 0.
michael@0: * The encoder will not buffer these packets as subsequent frames are
michael@0: * compressed, so a failure to do so will result in lost video data.
michael@0: * \note Currently the encoder operates in a one-frame-in, one-packet-out
michael@0: * manner.
michael@0: * However, this may be changed in the future.
michael@0: * \param _enc A #th_enc_ctx handle.
michael@0: * \param _last Set this flag to a non-zero value if no more uncompressed
michael@0: * frames will be submitted.
michael@0: * This ensures that a proper EOS flag is set on the last packet.
michael@0: * \param _op An ogg_packet structure to fill.
michael@0: * All of the elements of this structure will be set, including a
michael@0: * pointer to the video data.
michael@0: * The memory for the video data is owned by
michael@0: * libtheoraenc, and may be invalidated when the next
michael@0: * encoder function is called.
michael@0: * \return A positive value indicates that a video data packet was successfully
michael@0: * produced.
michael@0: * \retval 0 No packet was produced, and no more encoded video data
michael@0: * remains.
michael@0: * \retval TH_EFAULT \a _enc or \a _op was NULL.*/
michael@0: extern int th_encode_packetout(th_enc_ctx *_enc,int _last,ogg_packet *_op);
michael@0: /**Frees an allocated encoder instance.
michael@0: * \param _enc A #th_enc_ctx handle.*/
michael@0: extern void th_encode_free(th_enc_ctx *_enc);
michael@0: /*@}*/
michael@0: /*@}*/
michael@0:
michael@0:
michael@0:
michael@0: #if defined(__cplusplus)
michael@0: }
michael@0: #endif
michael@0:
michael@0: #endif