1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
1.2 +++ b/media/libtheora/include/theora/theoraenc.h Wed Dec 31 06:09:35 2014 +0100
1.3 @@ -0,0 +1,540 @@
1.4 +/********************************************************************
1.5 + * *
1.6 + * THIS FILE IS PART OF THE OggTheora SOFTWARE CODEC SOURCE CODE. *
1.7 + * USE, DISTRIBUTION AND REPRODUCTION OF THIS LIBRARY SOURCE IS *
1.8 + * GOVERNED BY A BSD-STYLE SOURCE LICENSE INCLUDED WITH THIS SOURCE *
1.9 + * IN 'COPYING'. PLEASE READ THESE TERMS BEFORE DISTRIBUTING. *
1.10 + * *
1.11 + * THE Theora SOURCE CODE IS COPYRIGHT (C) 2002-2009 *
1.12 + * by the Xiph.Org Foundation http://www.xiph.org/ *
1.13 + * *
1.14 + ********************************************************************
1.15 +
1.16 + function:
1.17 + last mod: $Id: theora.h,v 1.8 2004/03/15 22:17:32 derf Exp $
1.18 +
1.19 + ********************************************************************/
1.20 +
1.21 +/**\file
1.22 + * The <tt>libtheoraenc</tt> C encoding API.*/
1.23 +
1.24 +#if !defined(_O_THEORA_THEORAENC_H_)
1.25 +# define _O_THEORA_THEORAENC_H_ (1)
1.26 +# include <stddef.h>
1.27 +# include <ogg/ogg.h>
1.28 +# include "codec.h"
1.29 +
1.30 +#if defined(__cplusplus)
1.31 +extern "C" {
1.32 +#endif
1.33 +
1.34 +
1.35 +
1.36 +/**\name th_encode_ctl() codes
1.37 + * \anchor encctlcodes
1.38 + * These are the available request codes for th_encode_ctl().
1.39 + * By convention, these are even, to distinguish them from the
1.40 + * \ref decctlcodes "decoder control codes".
1.41 + * Keep any experimental or vendor-specific values above \c 0x8000.*/
1.42 +/*@{*/
1.43 +/**Sets the Huffman tables to use.
1.44 + * The tables are copied, not stored by reference, so they can be freed after
1.45 + * this call.
1.46 + * <tt>NULL</tt> may be specified to revert to the default tables.
1.47 + *
1.48 + * \param[in] _buf <tt>#th_huff_code[#TH_NHUFFMAN_TABLES][#TH_NDCT_TOKENS]</tt>
1.49 + * \retval TH_EFAULT \a _enc is <tt>NULL</tt>.
1.50 + * \retval TH_EINVAL Encoding has already begun or one or more of the given
1.51 + * tables is not full or prefix-free, \a _buf is
1.52 + * <tt>NULL</tt> and \a _buf_sz is not zero, or \a _buf is
1.53 + * non-<tt>NULL</tt> and \a _buf_sz is not
1.54 + * <tt>sizeof(#th_huff_code)*#TH_NHUFFMAN_TABLES*#TH_NDCT_TOKENS</tt>.
1.55 + * \retval TH_EIMPL Not supported by this implementation.*/
1.56 +#define TH_ENCCTL_SET_HUFFMAN_CODES (0)
1.57 +/**Sets the quantization parameters to use.
1.58 + * The parameters are copied, not stored by reference, so they can be freed
1.59 + * after this call.
1.60 + * <tt>NULL</tt> may be specified to revert to the default parameters.
1.61 + *
1.62 + * \param[in] _buf #th_quant_info
1.63 + * \retval TH_EFAULT \a _enc is <tt>NULL</tt>.
1.64 + * \retval TH_EINVAL Encoding has already begun, \a _buf is
1.65 + * <tt>NULL</tt> and \a _buf_sz is not zero,
1.66 + * or \a _buf is non-<tt>NULL</tt> and
1.67 + * \a _buf_sz is not <tt>sizeof(#th_quant_info)</tt>.
1.68 + * \retval TH_EIMPL Not supported by this implementation.*/
1.69 +#define TH_ENCCTL_SET_QUANT_PARAMS (2)
1.70 +/**Sets the maximum distance between key frames.
1.71 + * This can be changed during an encode, but will be bounded by
1.72 + * <tt>1<<th_info#keyframe_granule_shift</tt>.
1.73 + * If it is set before encoding begins, th_info#keyframe_granule_shift will
1.74 + * be enlarged appropriately.
1.75 + *
1.76 + * \param[in] _buf <tt>ogg_uint32_t</tt>: The maximum distance between key
1.77 + * frames.
1.78 + * \param[out] _buf <tt>ogg_uint32_t</tt>: The actual maximum distance set.
1.79 + * \retval TH_EFAULT \a _enc or \a _buf is <tt>NULL</tt>.
1.80 + * \retval TH_EINVAL \a _buf_sz is not <tt>sizeof(ogg_uint32_t)</tt>.
1.81 + * \retval TH_EIMPL Not supported by this implementation.*/
1.82 +#define TH_ENCCTL_SET_KEYFRAME_FREQUENCY_FORCE (4)
1.83 +/**Disables any encoder features that would prevent lossless transcoding back
1.84 + * to VP3.
1.85 + * This primarily means disabling block-adaptive quantization and always coding
1.86 + * all four luma blocks in a macro block when 4MV is used.
1.87 + * It also includes using the VP3 quantization tables and Huffman codes; if you
1.88 + * set them explicitly after calling this function, the resulting stream will
1.89 + * not be VP3-compatible.
1.90 + * If you enable VP3-compatibility when encoding 4:2:2 or 4:4:4 source
1.91 + * material, or when using a picture region smaller than the full frame (e.g.
1.92 + * a non-multiple-of-16 width or height), then non-VP3 bitstream features will
1.93 + * still be disabled, but the stream will still not be VP3-compatible, as VP3
1.94 + * was not capable of encoding such formats.
1.95 + * If you call this after encoding has already begun, then the quantization
1.96 + * tables and codebooks cannot be changed, but the frame-level features will
1.97 + * be enabled or disabled as requested.
1.98 + *
1.99 + * \param[in] _buf <tt>int</tt>: a non-zero value to enable VP3 compatibility,
1.100 + * or 0 to disable it (the default).
1.101 + * \param[out] _buf <tt>int</tt>: 1 if all bitstream features required for
1.102 + * VP3-compatibility could be set, and 0 otherwise.
1.103 + * The latter will be returned if the pixel format is not
1.104 + * 4:2:0, the picture region is smaller than the full frame,
1.105 + * or if encoding has begun, preventing the quantization
1.106 + * tables and codebooks from being set.
1.107 + * \retval TH_EFAULT \a _enc or \a _buf is <tt>NULL</tt>.
1.108 + * \retval TH_EINVAL \a _buf_sz is not <tt>sizeof(int)</tt>.
1.109 + * \retval TH_EIMPL Not supported by this implementation.*/
1.110 +#define TH_ENCCTL_SET_VP3_COMPATIBLE (10)
1.111 +/**Gets the maximum speed level.
1.112 + * Higher speed levels favor quicker encoding over better quality per bit.
1.113 + * Depending on the encoding mode, and the internal algorithms used, quality
1.114 + * may actually improve, but in this case bitrate will also likely increase.
1.115 + * In any case, overall rate/distortion performance will probably decrease.
1.116 + * The maximum value, and the meaning of each value, may change depending on
1.117 + * the current encoding mode (VBR vs. constant quality, etc.).
1.118 + *
1.119 + * \param[out] _buf <tt>int</tt>: The maximum encoding speed level.
1.120 + * \retval TH_EFAULT \a _enc or \a _buf is <tt>NULL</tt>.
1.121 + * \retval TH_EINVAL \a _buf_sz is not <tt>sizeof(int)</tt>.
1.122 + * \retval TH_EIMPL Not supported by this implementation in the current
1.123 + * encoding mode.*/
1.124 +#define TH_ENCCTL_GET_SPLEVEL_MAX (12)
1.125 +/**Sets the speed level.
1.126 + * The current speed level may be retrieved using #TH_ENCCTL_GET_SPLEVEL.
1.127 + *
1.128 + * \param[in] _buf <tt>int</tt>: The new encoding speed level.
1.129 + * 0 is slowest, larger values use less CPU.
1.130 + * \retval TH_EFAULT \a _enc or \a _buf is <tt>NULL</tt>.
1.131 + * \retval TH_EINVAL \a _buf_sz is not <tt>sizeof(int)</tt>, or the
1.132 + * encoding speed level is out of bounds.
1.133 + * The maximum encoding speed level may be
1.134 + * implementation- and encoding mode-specific, and can be
1.135 + * obtained via #TH_ENCCTL_GET_SPLEVEL_MAX.
1.136 + * \retval TH_EIMPL Not supported by this implementation in the current
1.137 + * encoding mode.*/
1.138 +#define TH_ENCCTL_SET_SPLEVEL (14)
1.139 +/**Gets the current speed level.
1.140 + * The default speed level may vary according to encoder implementation, but if
1.141 + * this control code is not supported (it returns #TH_EIMPL), the default may
1.142 + * be assumed to be the slowest available speed (0).
1.143 + * The maximum encoding speed level may be implementation- and encoding
1.144 + * mode-specific, and can be obtained via #TH_ENCCTL_GET_SPLEVEL_MAX.
1.145 + *
1.146 + * \param[out] _buf <tt>int</tt>: The current encoding speed level.
1.147 + * 0 is slowest, larger values use less CPU.
1.148 + * \retval TH_EFAULT \a _enc or \a _buf is <tt>NULL</tt>.
1.149 + * \retval TH_EINVAL \a _buf_sz is not <tt>sizeof(int)</tt>.
1.150 + * \retval TH_EIMPL Not supported by this implementation in the current
1.151 + * encoding mode.*/
1.152 +#define TH_ENCCTL_GET_SPLEVEL (16)
1.153 +/**Sets the number of duplicates of the next frame to produce.
1.154 + * Although libtheora can encode duplicate frames very cheaply, it costs some
1.155 + * amount of CPU to detect them, and a run of duplicates cannot span a
1.156 + * keyframe boundary.
1.157 + * This control code tells the encoder to produce the specified number of extra
1.158 + * duplicates of the next frame.
1.159 + * This allows the encoder to make smarter keyframe placement decisions and
1.160 + * rate control decisions, and reduces CPU usage as well, when compared to
1.161 + * just submitting the same frame for encoding multiple times.
1.162 + * This setting only applies to the next frame submitted for encoding.
1.163 + * You MUST call th_encode_packetout() repeatedly until it returns 0, or the
1.164 + * extra duplicate frames will be lost.
1.165 + *
1.166 + * \param[in] _buf <tt>int</tt>: The number of duplicates to produce.
1.167 + * If this is negative or zero, no duplicates will be produced.
1.168 + * \retval TH_EFAULT \a _enc or \a _buf is <tt>NULL</tt>.
1.169 + * \retval TH_EINVAL \a _buf_sz is not <tt>sizeof(int)</tt>, or the
1.170 + * number of duplicates is greater than or equal to the
1.171 + * maximum keyframe interval.
1.172 + * In the latter case, NO duplicate frames will be produced.
1.173 + * You must ensure that the maximum keyframe interval is set
1.174 + * larger than the maximum number of duplicates you will
1.175 + * ever wish to insert prior to encoding.
1.176 + * \retval TH_EIMPL Not supported by this implementation in the current
1.177 + * encoding mode.*/
1.178 +#define TH_ENCCTL_SET_DUP_COUNT (18)
1.179 +/**Modifies the default bitrate management behavior.
1.180 + * Use to allow or disallow frame dropping, and to enable or disable capping
1.181 + * bit reservoir overflows and underflows.
1.182 + * See \ref encctlcodes "the list of available flags".
1.183 + * The flags are set by default to
1.184 + * <tt>#TH_RATECTL_DROP_FRAMES|#TH_RATECTL_CAP_OVERFLOW</tt>.
1.185 + *
1.186 + * \param[in] _buf <tt>int</tt>: Any combination of
1.187 + * \ref ratectlflags "the available flags":
1.188 + * - #TH_RATECTL_DROP_FRAMES: Enable frame dropping.
1.189 + * - #TH_RATECTL_CAP_OVERFLOW: Don't bank excess bits for later
1.190 + * use.
1.191 + * - #TH_RATECTL_CAP_UNDERFLOW: Don't try to make up shortfalls
1.192 + * later.
1.193 + * \retval TH_EFAULT \a _enc or \a _buf is <tt>NULL</tt>.
1.194 + * \retval TH_EINVAL \a _buf_sz is not <tt>sizeof(int)</tt> or rate control
1.195 + * is not enabled.
1.196 + * \retval TH_EIMPL Not supported by this implementation in the current
1.197 + * encoding mode.*/
1.198 +#define TH_ENCCTL_SET_RATE_FLAGS (20)
1.199 +/**Sets the size of the bitrate management bit reservoir as a function
1.200 + * of number of frames.
1.201 + * The reservoir size affects how quickly bitrate management reacts to
1.202 + * instantaneous changes in the video complexity.
1.203 + * Larger reservoirs react more slowly, and provide better overall quality, but
1.204 + * require more buffering by a client, adding more latency to live streams.
1.205 + * By default, libtheora sets the reservoir to the maximum distance between
1.206 + * keyframes, subject to a minimum and maximum limit.
1.207 + * This call may be used to increase or decrease the reservoir, increasing or
1.208 + * decreasing the allowed temporary variance in bitrate.
1.209 + * An implementation may impose some limits on the size of a reservoir it can
1.210 + * handle, in which case the actual reservoir size may not be exactly what was
1.211 + * requested.
1.212 + * The actual value set will be returned.
1.213 + *
1.214 + * \param[in] _buf <tt>int</tt>: Requested size of the reservoir measured in
1.215 + * frames.
1.216 + * \param[out] _buf <tt>int</tt>: The actual size of the reservoir set.
1.217 + * \retval TH_EFAULT \a _enc or \a _buf is <tt>NULL</tt>.
1.218 + * \retval TH_EINVAL \a _buf_sz is not <tt>sizeof(int)</tt>, or rate control
1.219 + * is not enabled. The buffer has an implementation
1.220 + * defined minimum and maximum size and the value in _buf
1.221 + * will be adjusted to match the actual value set.
1.222 + * \retval TH_EIMPL Not supported by this implementation in the current
1.223 + * encoding mode.*/
1.224 +#define TH_ENCCTL_SET_RATE_BUFFER (22)
1.225 +/**Enable pass 1 of two-pass encoding mode and retrieve the first pass metrics.
1.226 + * Pass 1 mode must be enabled before the first frame is encoded, and a target
1.227 + * bitrate must have already been specified to the encoder.
1.228 + * Although this does not have to be the exact rate that will be used in the
1.229 + * second pass, closer values may produce better results.
1.230 + * The first call returns the size of the two-pass header data, along with some
1.231 + * placeholder content, and sets the encoder into pass 1 mode implicitly.
1.232 + * This call sets the encoder to pass 1 mode implicitly.
1.233 + * Then, a subsequent call must be made after each call to
1.234 + * th_encode_ycbcr_in() to retrieve the metrics for that frame.
1.235 + * An additional, final call must be made to retrieve the summary data,
1.236 + * containing such information as the total number of frames, etc.
1.237 + * This must be stored in place of the placeholder data that was returned
1.238 + * in the first call, before the frame metrics data.
1.239 + * All of this data must be presented back to the encoder during pass 2 using
1.240 + * #TH_ENCCTL_2PASS_IN.
1.241 + *
1.242 + * \param[out] <tt>char *</tt>_buf: Returns a pointer to internal storage
1.243 + * containing the two pass metrics data.
1.244 + * This storage is only valid until the next call, or until the
1.245 + * encoder context is freed, and must be copied by the
1.246 + * application.
1.247 + * \retval >=0 The number of bytes of metric data available in the
1.248 + * returned buffer.
1.249 + * \retval TH_EFAULT \a _enc or \a _buf is <tt>NULL</tt>.
1.250 + * \retval TH_EINVAL \a _buf_sz is not <tt>sizeof(char *)</tt>, no target
1.251 + * bitrate has been set, or the first call was made after
1.252 + * the first frame was submitted for encoding.
1.253 + * \retval TH_EIMPL Not supported by this implementation.*/
1.254 +#define TH_ENCCTL_2PASS_OUT (24)
1.255 +/**Submits two-pass encoding metric data collected the first encoding pass to
1.256 + * the second pass.
1.257 + * The first call must be made before the first frame is encoded, and a target
1.258 + * bitrate must have already been specified to the encoder.
1.259 + * It sets the encoder to pass 2 mode implicitly; this cannot be disabled.
1.260 + * The encoder may require reading data from some or all of the frames in
1.261 + * advance, depending on, e.g., the reservoir size used in the second pass.
1.262 + * You must call this function repeatedly before each frame to provide data
1.263 + * until either a) it fails to consume all of the data presented or b) all of
1.264 + * the pass 1 data has been consumed.
1.265 + * In the first case, you must save the remaining data to be presented after
1.266 + * the next frame.
1.267 + * You can call this function with a NULL argument to get an upper bound on
1.268 + * the number of bytes that will be required before the next frame.
1.269 + *
1.270 + * When pass 2 is first enabled, the default bit reservoir is set to the entire
1.271 + * file; this gives maximum flexibility but can lead to very high peak rates.
1.272 + * You can subsequently set it to another value with #TH_ENCCTL_SET_RATE_BUFFER
1.273 + * (e.g., to set it to the keyframe interval for non-live streaming), however,
1.274 + * you may then need to provide more data before the next frame.
1.275 + *
1.276 + * \param[in] _buf <tt>char[]</tt>: A buffer containing the data returned by
1.277 + * #TH_ENCCTL_2PASS_OUT in pass 1.
1.278 + * You may pass <tt>NULL</tt> for \a _buf to return an upper
1.279 + * bound on the number of additional bytes needed before the
1.280 + * next frame.
1.281 + * The summary data returned at the end of pass 1 must be at
1.282 + * the head of the buffer on the first call with a
1.283 + * non-<tt>NULL</tt> \a _buf, and the placeholder data
1.284 + * returned at the start of pass 1 should be omitted.
1.285 + * After each call you should advance this buffer by the number
1.286 + * of bytes consumed.
1.287 + * \retval >0 The number of bytes of metric data required/consumed.
1.288 + * \retval 0 No more data is required before the next frame.
1.289 + * \retval TH_EFAULT \a _enc is <tt>NULL</tt>.
1.290 + * \retval TH_EINVAL No target bitrate has been set, or the first call was
1.291 + * made after the first frame was submitted for
1.292 + * encoding.
1.293 + * \retval TH_ENOTFORMAT The data did not appear to be pass 1 from a compatible
1.294 + * implementation of this library.
1.295 + * \retval TH_EBADHEADER The data was invalid; this may be returned when
1.296 + * attempting to read an aborted pass 1 file that still
1.297 + * has the placeholder data in place of the summary
1.298 + * data.
1.299 + * \retval TH_EIMPL Not supported by this implementation.*/
1.300 +#define TH_ENCCTL_2PASS_IN (26)
1.301 +/**Sets the current encoding quality.
1.302 + * This is only valid so long as no bitrate has been specified, either through
1.303 + * the #th_info struct used to initialize the encoder or through
1.304 + * #TH_ENCCTL_SET_BITRATE (this restriction may be relaxed in a future
1.305 + * version).
1.306 + * If it is set before the headers are emitted, the target quality encoded in
1.307 + * them will be updated.
1.308 + *
1.309 + * \param[in] _buf <tt>int</tt>: The new target quality, in the range 0...63,
1.310 + * inclusive.
1.311 + * \retval 0 Success.
1.312 + * \retval TH_EFAULT \a _enc or \a _buf is <tt>NULL</tt>.
1.313 + * \retval TH_EINVAL A target bitrate has already been specified, or the
1.314 + * quality index was not in the range 0...63.
1.315 + * \retval TH_EIMPL Not supported by this implementation.*/
1.316 +#define TH_ENCCTL_SET_QUALITY (28)
1.317 +/**Sets the current encoding bitrate.
1.318 + * Once a bitrate is set, the encoder must use a rate-controlled mode for all
1.319 + * future frames (this restriction may be relaxed in a future version).
1.320 + * If it is set before the headers are emitted, the target bitrate encoded in
1.321 + * them will be updated.
1.322 + * Due to the buffer delay, the exact bitrate of each section of the encode is
1.323 + * not guaranteed.
1.324 + * The encoder may have already used more bits than allowed for the frames it
1.325 + * has encoded, expecting to make them up in future frames, or it may have
1.326 + * used fewer, holding the excess in reserve.
1.327 + * The exact transition between the two bitrates is not well-defined by this
1.328 + * API, but may be affected by flags set with #TH_ENCCTL_SET_RATE_FLAGS.
1.329 + * After a number of frames equal to the buffer delay, one may expect further
1.330 + * output to average at the target bitrate.
1.331 + *
1.332 + * \param[in] _buf <tt>long</tt>: The new target bitrate, in bits per second.
1.333 + * \retval 0 Success.
1.334 + * \retval TH_EFAULT \a _enc or \a _buf is <tt>NULL</tt>.
1.335 + * \retval TH_EINVAL The target bitrate was not positive.
1.336 + * \retval TH_EIMPL Not supported by this implementation.*/
1.337 +#define TH_ENCCTL_SET_BITRATE (30)
1.338 +/**Sets the configuration to be compatible with that from the given setup
1.339 + * header.
1.340 + * This sets the Huffman codebooks and quantization parameters to match those
1.341 + * found in the given setup header.
1.342 + * This guarantees that packets encoded by this encoder will be decodable using
1.343 + * a decoder configured with the passed-in setup header.
1.344 + * It does <em>not</em> guarantee that th_encode_flushheader() will produce a
1.345 + * bit-identical setup header, only that they will be compatible.
1.346 + * If you need a bit-identical setup header, then use the one you passed into
1.347 + * this command, and not the one returned by th_encode_flushheader().
1.348 + *
1.349 + * This also does <em>not</em> enable or disable VP3 compatibility; that is not
1.350 + * signaled in the setup header (or anywhere else in the encoded stream), and
1.351 + * is controlled independently by the #TH_ENCCTL_SET_VP3_COMPATIBLE function.
1.352 + * If you wish to enable VP3 compatibility mode <em>and</em> want the codebooks
1.353 + * and quantization parameters to match the given setup header, you should
1.354 + * enable VP3 compatibility before invoking this command, otherwise the
1.355 + * codebooks and quantization parameters will be reset to the VP3 defaults.
1.356 + *
1.357 + * The current encoder does not support Huffman codebooks which do not contain
1.358 + * codewords for all 32 tokens.
1.359 + * Such codebooks are legal, according to the specification, but cannot be
1.360 + * configured with this function.
1.361 + *
1.362 + * \param[in] _buf <tt>unsigned char[]</tt>: The encoded setup header to copy
1.363 + * the configuration from.
1.364 + * This should be the original,
1.365 + * undecoded setup header packet,
1.366 + * and <em>not</em> a #th_setup_info
1.367 + * structure filled in by
1.368 + * th_decode_headerin().
1.369 + * \retval TH_EFAULT \a _enc or \a _buf is <tt>NULL</tt>.
1.370 + * \retval TH_EINVAL Encoding has already begun, so the codebooks and
1.371 + * quantization parameters cannot be changed, or the
1.372 + * data in the setup header was not supported by this
1.373 + * encoder.
1.374 + * \retval TH_EBADHEADER \a _buf did not contain a valid setup header packet.
1.375 + * \retval TH_ENOTFORMAT \a _buf did not contain a Theora header at all.
1.376 + * \retval TH_EIMPL Not supported by this implementation.*/
1.377 +#define TH_ENCCTL_SET_COMPAT_CONFIG (32)
1.378 +
1.379 +/*@}*/
1.380 +
1.381 +
1.382 +/**\name TH_ENCCTL_SET_RATE_FLAGS flags
1.383 + * \anchor ratectlflags
1.384 + * These are the flags available for use with #TH_ENCCTL_SET_RATE_FLAGS.*/
1.385 +/*@{*/
1.386 +/**Drop frames to keep within bitrate buffer constraints.
1.387 + * This can have a severe impact on quality, but is the only way to ensure that
1.388 + * bitrate targets are met at low rates during sudden bursts of activity.*/
1.389 +#define TH_RATECTL_DROP_FRAMES (0x1)
1.390 +/**Ignore bitrate buffer overflows.
1.391 + * If the encoder uses so few bits that the reservoir of available bits
1.392 + * overflows, ignore the excess.
1.393 + * The encoder will not try to use these extra bits in future frames.
1.394 + * At high rates this may cause the result to be undersized, but allows a
1.395 + * client to play the stream using a finite buffer; it should normally be
1.396 + * enabled.*/
1.397 +#define TH_RATECTL_CAP_OVERFLOW (0x2)
1.398 +/**Ignore bitrate buffer underflows.
1.399 + * If the encoder uses so many bits that the reservoir of available bits
1.400 + * underflows, ignore the deficit.
1.401 + * The encoder will not try to make up these extra bits in future frames.
1.402 + * At low rates this may cause the result to be oversized; it should normally
1.403 + * be disabled.*/
1.404 +#define TH_RATECTL_CAP_UNDERFLOW (0x4)
1.405 +/*@}*/
1.406 +
1.407 +
1.408 +
1.409 +/**The quantization parameters used by VP3.*/
1.410 +extern const th_quant_info TH_VP31_QUANT_INFO;
1.411 +
1.412 +/**The Huffman tables used by VP3.*/
1.413 +extern const th_huff_code
1.414 + TH_VP31_HUFF_CODES[TH_NHUFFMAN_TABLES][TH_NDCT_TOKENS];
1.415 +
1.416 +
1.417 +
1.418 +/**\name Encoder state
1.419 + The following data structure is opaque, and its contents are not publicly
1.420 + defined by this API.
1.421 + Referring to its internals directly is unsupported, and may break without
1.422 + warning.*/
1.423 +/*@{*/
1.424 +/**The encoder context.*/
1.425 +typedef struct th_enc_ctx th_enc_ctx;
1.426 +/*@}*/
1.427 +
1.428 +
1.429 +
1.430 +/**\defgroup encfuncs Functions for Encoding*/
1.431 +/*@{*/
1.432 +/**\name Functions for encoding
1.433 + * You must link to <tt>libtheoraenc</tt> and <tt>libtheoradec</tt>
1.434 + * if you use any of the functions in this section.
1.435 + *
1.436 + * The functions are listed in the order they are used in a typical encode.
1.437 + * The basic steps are:
1.438 + * - Fill in a #th_info structure with details on the format of the video you
1.439 + * wish to encode.
1.440 + * - Allocate a #th_enc_ctx handle with th_encode_alloc().
1.441 + * - Perform any additional encoder configuration required with
1.442 + * th_encode_ctl().
1.443 + * - Repeatedly call th_encode_flushheader() to retrieve all the header
1.444 + * packets.
1.445 + * - For each uncompressed frame:
1.446 + * - Submit the uncompressed frame via th_encode_ycbcr_in()
1.447 + * - Repeatedly call th_encode_packetout() to retrieve any video data packets
1.448 + * that are ready.
1.449 + * - Call th_encode_free() to release all encoder memory.*/
1.450 +/*@{*/
1.451 +/**Allocates an encoder instance.
1.452 + * \param _info A #th_info struct filled with the desired encoding parameters.
1.453 + * \return The initialized #th_enc_ctx handle.
1.454 + * \retval NULL If the encoding parameters were invalid.*/
1.455 +extern th_enc_ctx *th_encode_alloc(const th_info *_info);
1.456 +/**Encoder control function.
1.457 + * This is used to provide advanced control the encoding process.
1.458 + * \param _enc A #th_enc_ctx handle.
1.459 + * \param _req The control code to process.
1.460 + * See \ref encctlcodes "the list of available control codes"
1.461 + * for details.
1.462 + * \param _buf The parameters for this control code.
1.463 + * \param _buf_sz The size of the parameter buffer.*/
1.464 +extern int th_encode_ctl(th_enc_ctx *_enc,int _req,void *_buf,size_t _buf_sz);
1.465 +/**Outputs the next header packet.
1.466 + * This should be called repeatedly after encoder initialization until it
1.467 + * returns 0 in order to get all of the header packets, in order, before
1.468 + * encoding actual video data.
1.469 + * \param _enc A #th_enc_ctx handle.
1.470 + * \param _comments The metadata to place in the comment header, when it is
1.471 + * encoded.
1.472 + * \param _op An <tt>ogg_packet</tt> structure to fill.
1.473 + * All of the elements of this structure will be set,
1.474 + * including a pointer to the header data.
1.475 + * The memory for the header data is owned by
1.476 + * <tt>libtheoraenc</tt>, and may be invalidated when the
1.477 + * next encoder function is called.
1.478 + * \return A positive value indicates that a header packet was successfully
1.479 + * produced.
1.480 + * \retval 0 No packet was produced, and no more header packets remain.
1.481 + * \retval TH_EFAULT \a _enc, \a _comments, or \a _op was <tt>NULL</tt>.*/
1.482 +extern int th_encode_flushheader(th_enc_ctx *_enc,
1.483 + th_comment *_comments,ogg_packet *_op);
1.484 +/**Submits an uncompressed frame to the encoder.
1.485 + * \param _enc A #th_enc_ctx handle.
1.486 + * \param _ycbcr A buffer of Y'CbCr data to encode.
1.487 + * If the width and height of the buffer matches the frame size
1.488 + * the encoder was initialized with, the encoder will only
1.489 + * reference the portion inside the picture region.
1.490 + * Any data outside this region will be ignored, and need not map
1.491 + * to a valid address.
1.492 + * Alternatively, you can pass a buffer equal to the size of the
1.493 + * picture region, if this is less than the full frame size.
1.494 + * When using subsampled chroma planes, odd picture sizes or odd
1.495 + * picture offsets may require an unexpected chroma plane size,
1.496 + * and their use is generally discouraged, as they will not be
1.497 + * well-supported by players and other media frameworks.
1.498 + * See Section 4.4 of
1.499 + * <a href="http://www.theora.org/doc/Theora.pdf">the Theora
1.500 + * specification</a> for details if you wish to use them anyway.
1.501 + * \retval 0 Success.
1.502 + * \retval TH_EFAULT \a _enc or \a _ycbcr is <tt>NULL</tt>.
1.503 + * \retval TH_EINVAL The buffer size matches neither the frame size nor the
1.504 + * picture size the encoder was initialized with, or
1.505 + * encoding has already completed.*/
1.506 +extern int th_encode_ycbcr_in(th_enc_ctx *_enc,th_ycbcr_buffer _ycbcr);
1.507 +/**Retrieves encoded video data packets.
1.508 + * This should be called repeatedly after each frame is submitted to flush any
1.509 + * encoded packets, until it returns 0.
1.510 + * The encoder will not buffer these packets as subsequent frames are
1.511 + * compressed, so a failure to do so will result in lost video data.
1.512 + * \note Currently the encoder operates in a one-frame-in, one-packet-out
1.513 + * manner.
1.514 + * However, this may be changed in the future.
1.515 + * \param _enc A #th_enc_ctx handle.
1.516 + * \param _last Set this flag to a non-zero value if no more uncompressed
1.517 + * frames will be submitted.
1.518 + * This ensures that a proper EOS flag is set on the last packet.
1.519 + * \param _op An <tt>ogg_packet</tt> structure to fill.
1.520 + * All of the elements of this structure will be set, including a
1.521 + * pointer to the video data.
1.522 + * The memory for the video data is owned by
1.523 + * <tt>libtheoraenc</tt>, and may be invalidated when the next
1.524 + * encoder function is called.
1.525 + * \return A positive value indicates that a video data packet was successfully
1.526 + * produced.
1.527 + * \retval 0 No packet was produced, and no more encoded video data
1.528 + * remains.
1.529 + * \retval TH_EFAULT \a _enc or \a _op was <tt>NULL</tt>.*/
1.530 +extern int th_encode_packetout(th_enc_ctx *_enc,int _last,ogg_packet *_op);
1.531 +/**Frees an allocated encoder instance.
1.532 + * \param _enc A #th_enc_ctx handle.*/
1.533 +extern void th_encode_free(th_enc_ctx *_enc);
1.534 +/*@}*/
1.535 +/*@}*/
1.536 +
1.537 +
1.538 +
1.539 +#if defined(__cplusplus)
1.540 +}
1.541 +#endif
1.542 +
1.543 +#endif
