1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
1.2 +++ b/media/libtheora/include/theora/theora.h Wed Dec 31 06:09:35 2014 +0100
1.3 @@ -0,0 +1,784 @@
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.17 2003/12/06 18:06:19 arc Exp $
1.18 +
1.19 + ********************************************************************/
1.20 +
1.21 +#ifndef _O_THEORA_H_
1.22 +#define _O_THEORA_H_
1.23 +
1.24 +#ifdef __cplusplus
1.25 +extern "C"
1.26 +{
1.27 +#endif /* __cplusplus */
1.28 +
1.29 +#include <stddef.h> /* for size_t */
1.30 +
1.31 +#include <ogg/ogg.h>
1.32 +
1.33 +/** \file
1.34 + * The libtheora pre-1.0 legacy C API.
1.35 + *
1.36 + * \ingroup oldfuncs
1.37 + *
1.38 + * \section intro Introduction
1.39 + *
1.40 + * This is the documentation for the libtheora legacy C API, declared in
1.41 + * the theora.h header, which describes the old interface used before
1.42 + * the 1.0 release. This API was widely deployed for several years and
1.43 + * remains supported, but for new code we recommend the cleaner API
1.44 + * declared in theoradec.h and theoraenc.h.
1.45 + *
1.46 + * libtheora is the reference implementation for
1.47 + * <a href="http://www.theora.org/">Theora</a>, a free video codec.
1.48 + * Theora is derived from On2's VP3 codec with improved integration with
1.49 + * Ogg multimedia formats by <a href="http://www.xiph.org/">Xiph.Org</a>.
1.50 + *
1.51 + * \section overview Overview
1.52 + *
1.53 + * This library will both decode and encode theora packets to/from raw YUV
1.54 + * frames. In either case, the packets will most likely either come from or
1.55 + * need to be embedded in an Ogg stream. Use
1.56 + * <a href="http://xiph.org/ogg/">libogg</a> or
1.57 + * <a href="http://www.annodex.net/software/liboggz/index.html">liboggz</a>
1.58 + * to extract/package these packets.
1.59 + *
1.60 + * \section decoding Decoding Process
1.61 + *
1.62 + * Decoding can be separated into the following steps:
1.63 + * -# initialise theora_info and theora_comment structures using
1.64 + * theora_info_init() and theora_comment_init():
1.65 + \verbatim
1.66 + theora_info info;
1.67 + theora_comment comment;
1.68 +
1.69 + theora_info_init(&info);
1.70 + theora_comment_init(&comment);
1.71 + \endverbatim
1.72 + * -# retrieve header packets from Ogg stream (there should be 3) and decode
1.73 + * into theora_info and theora_comment structures using
1.74 + * theora_decode_header(). See \ref identification for more information on
1.75 + * identifying which packets are theora packets.
1.76 + \verbatim
1.77 + int i;
1.78 + for (i = 0; i < 3; i++)
1.79 + {
1.80 + (get a theora packet "op" from the Ogg stream)
1.81 + theora_decode_header(&info, &comment, op);
1.82 + }
1.83 + \endverbatim
1.84 + * -# initialise the decoder based on the information retrieved into the
1.85 + * theora_info struct by theora_decode_header(). You will need a
1.86 + * theora_state struct.
1.87 + \verbatim
1.88 + theora_state state;
1.89 +
1.90 + theora_decode_init(&state, &info);
1.91 + \endverbatim
1.92 + * -# pass in packets and retrieve decoded frames! See the yuv_buffer
1.93 + * documentation for information on how to retrieve raw YUV data.
1.94 + \verbatim
1.95 + yuf_buffer buffer;
1.96 + while (last packet was not e_o_s) {
1.97 + (get a theora packet "op" from the Ogg stream)
1.98 + theora_decode_packetin(&state, op);
1.99 + theora_decode_YUVout(&state, &buffer);
1.100 + }
1.101 + \endverbatim
1.102 + *
1.103 + *
1.104 + * \subsection identification Identifying Theora Packets
1.105 + *
1.106 + * All streams inside an Ogg file have a unique serial_no attached to the
1.107 + * stream. Typically, you will want to
1.108 + * - retrieve the serial_no for each b_o_s (beginning of stream) page
1.109 + * encountered within the Ogg file;
1.110 + * - test the first (only) packet on that page to determine if it is a theora
1.111 + * packet;
1.112 + * - once you have found a theora b_o_s page then use the retrieved serial_no
1.113 + * to identify future packets belonging to the same theora stream.
1.114 + *
1.115 + * Note that you \e cannot use theora_packet_isheader() to determine if a
1.116 + * packet is a theora packet or not, as this function does not perform any
1.117 + * checking beyond whether a header bit is present. Instead, use the
1.118 + * theora_decode_header() function and check the return value; or examine the
1.119 + * header bytes at the beginning of the Ogg page.
1.120 + */
1.121 +
1.122 +
1.123 +/** \defgroup oldfuncs Legacy pre-1.0 C API */
1.124 +/* @{ */
1.125 +
1.126 +/**
1.127 + * A YUV buffer for passing uncompressed frames to and from the codec.
1.128 + * This holds a Y'CbCr frame in planar format. The CbCr planes can be
1.129 + * subsampled and have their own separate dimensions and row stride
1.130 + * offsets. Note that the strides may be negative in some
1.131 + * configurations. For theora the width and height of the largest plane
1.132 + * must be a multiple of 16. The actual meaningful picture size and
1.133 + * offset are stored in the theora_info structure; frames returned by
1.134 + * the decoder may need to be cropped for display.
1.135 + *
1.136 + * All samples are 8 bits. Within each plane samples are ordered by
1.137 + * row from the top of the frame to the bottom. Within each row samples
1.138 + * are ordered from left to right.
1.139 + *
1.140 + * During decode, the yuv_buffer struct is allocated by the user, but all
1.141 + * fields (including luma and chroma pointers) are filled by the library.
1.142 + * These pointers address library-internal memory and their contents should
1.143 + * not be modified.
1.144 + *
1.145 + * Conversely, during encode the user allocates the struct and fills out all
1.146 + * fields. The user also manages the data addressed by the luma and chroma
1.147 + * pointers. See the encoder_example.c and dump_video.c example files in
1.148 + * theora/examples/ for more information.
1.149 + */
1.150 +typedef struct {
1.151 + int y_width; /**< Width of the Y' luminance plane */
1.152 + int y_height; /**< Height of the luminance plane */
1.153 + int y_stride; /**< Offset in bytes between successive rows */
1.154 +
1.155 + int uv_width; /**< Width of the Cb and Cr chroma planes */
1.156 + int uv_height; /**< Height of the chroma planes */
1.157 + int uv_stride; /**< Offset between successive chroma rows */
1.158 + unsigned char *y; /**< Pointer to start of luminance data */
1.159 + unsigned char *u; /**< Pointer to start of Cb data */
1.160 + unsigned char *v; /**< Pointer to start of Cr data */
1.161 +
1.162 +} yuv_buffer;
1.163 +
1.164 +/**
1.165 + * A Colorspace.
1.166 + */
1.167 +typedef enum {
1.168 + OC_CS_UNSPECIFIED, /**< The colorspace is unknown or unspecified */
1.169 + OC_CS_ITU_REC_470M, /**< This is the best option for 'NTSC' content */
1.170 + OC_CS_ITU_REC_470BG, /**< This is the best option for 'PAL' content */
1.171 + OC_CS_NSPACES /**< This marks the end of the defined colorspaces */
1.172 +} theora_colorspace;
1.173 +
1.174 +/**
1.175 + * A Chroma subsampling
1.176 + *
1.177 + * These enumerate the available chroma subsampling options supported
1.178 + * by the theora format. See Section 4.4 of the specification for
1.179 + * exact definitions.
1.180 + */
1.181 +typedef enum {
1.182 + OC_PF_420, /**< Chroma subsampling by 2 in each direction (4:2:0) */
1.183 + OC_PF_RSVD, /**< Reserved value */
1.184 + OC_PF_422, /**< Horizonatal chroma subsampling by 2 (4:2:2) */
1.185 + OC_PF_444 /**< No chroma subsampling at all (4:4:4) */
1.186 +} theora_pixelformat;
1.187 +
1.188 +/**
1.189 + * Theora bitstream info.
1.190 + * Contains the basic playback parameters for a stream,
1.191 + * corresponding to the initial 'info' header packet.
1.192 + *
1.193 + * Encoded theora frames must be a multiple of 16 in width and height.
1.194 + * To handle other frame sizes, a crop rectangle is specified in
1.195 + * frame_height and frame_width, offset_x and * offset_y. The offset
1.196 + * and size should still be a multiple of 2 to avoid chroma sampling
1.197 + * shifts. Offset values in this structure are measured from the
1.198 + * upper left of the image.
1.199 + *
1.200 + * Frame rate, in frames per second, is stored as a rational
1.201 + * fraction. Aspect ratio is also stored as a rational fraction, and
1.202 + * refers to the aspect ratio of the frame pixels, not of the
1.203 + * overall frame itself.
1.204 + *
1.205 + * See <a href="http://svn.xiph.org/trunk/theora/examples/encoder_example.c">
1.206 + * examples/encoder_example.c</a> for usage examples of the
1.207 + * other paramters and good default settings for the encoder parameters.
1.208 + */
1.209 +typedef struct {
1.210 + ogg_uint32_t width; /**< encoded frame width */
1.211 + ogg_uint32_t height; /**< encoded frame height */
1.212 + ogg_uint32_t frame_width; /**< display frame width */
1.213 + ogg_uint32_t frame_height; /**< display frame height */
1.214 + ogg_uint32_t offset_x; /**< horizontal offset of the displayed frame */
1.215 + ogg_uint32_t offset_y; /**< vertical offset of the displayed frame */
1.216 + ogg_uint32_t fps_numerator; /**< frame rate numerator **/
1.217 + ogg_uint32_t fps_denominator; /**< frame rate denominator **/
1.218 + ogg_uint32_t aspect_numerator; /**< pixel aspect ratio numerator */
1.219 + ogg_uint32_t aspect_denominator; /**< pixel aspect ratio denominator */
1.220 + theora_colorspace colorspace; /**< colorspace */
1.221 + int target_bitrate; /**< nominal bitrate in bits per second */
1.222 + int quality; /**< Nominal quality setting, 0-63 */
1.223 + int quick_p; /**< Quick encode/decode */
1.224 +
1.225 + /* decode only */
1.226 + unsigned char version_major;
1.227 + unsigned char version_minor;
1.228 + unsigned char version_subminor;
1.229 +
1.230 + void *codec_setup;
1.231 +
1.232 + /* encode only */
1.233 + int dropframes_p;
1.234 + int keyframe_auto_p;
1.235 + ogg_uint32_t keyframe_frequency;
1.236 + ogg_uint32_t keyframe_frequency_force; /* also used for decode init to
1.237 + get granpos shift correct */
1.238 + ogg_uint32_t keyframe_data_target_bitrate;
1.239 + ogg_int32_t keyframe_auto_threshold;
1.240 + ogg_uint32_t keyframe_mindistance;
1.241 + ogg_int32_t noise_sensitivity;
1.242 + ogg_int32_t sharpness;
1.243 +
1.244 + theora_pixelformat pixelformat; /**< chroma subsampling mode to expect */
1.245 +
1.246 +} theora_info;
1.247 +
1.248 +/** Codec internal state and context.
1.249 + */
1.250 +typedef struct{
1.251 + theora_info *i;
1.252 + ogg_int64_t granulepos;
1.253 +
1.254 + void *internal_encode;
1.255 + void *internal_decode;
1.256 +
1.257 +} theora_state;
1.258 +
1.259 +/**
1.260 + * Comment header metadata.
1.261 + *
1.262 + * This structure holds the in-stream metadata corresponding to
1.263 + * the 'comment' header packet.
1.264 + *
1.265 + * Meta data is stored as a series of (tag, value) pairs, in
1.266 + * length-encoded string vectors. The first occurence of the
1.267 + * '=' character delimits the tag and value. A particular tag
1.268 + * may occur more than once. The character set encoding for
1.269 + * the strings is always UTF-8, but the tag names are limited
1.270 + * to case-insensitive ASCII. See the spec for details.
1.271 + *
1.272 + * In filling in this structure, theora_decode_header() will
1.273 + * null-terminate the user_comment strings for safety. However,
1.274 + * the bitstream format itself treats them as 8-bit clean,
1.275 + * and so the length array should be treated as authoritative
1.276 + * for their length.
1.277 + */
1.278 +typedef struct theora_comment{
1.279 + char **user_comments; /**< An array of comment string vectors */
1.280 + int *comment_lengths; /**< An array of corresponding string vector lengths in bytes */
1.281 + int comments; /**< The total number of comment string vectors */
1.282 + char *vendor; /**< The vendor string identifying the encoder, null terminated */
1.283 +
1.284 +} theora_comment;
1.285 +
1.286 +
1.287 +/**\name theora_control() codes */
1.288 +/* \anchor decctlcodes_old
1.289 + * These are the available request codes for theora_control()
1.290 + * when called with a decoder instance.
1.291 + * By convention decoder control codes are odd, to distinguish
1.292 + * them from \ref encctlcodes_old "encoder control codes" which
1.293 + * are even.
1.294 + *
1.295 + * Note that since the 1.0 release, both the legacy and the final
1.296 + * implementation accept all the same control codes, but only the
1.297 + * final API declares the newer codes.
1.298 + *
1.299 + * Keep any experimental or vendor-specific values above \c 0x8000.*/
1.300 +
1.301 +/*@{*/
1.302 +
1.303 +/**Get the maximum post-processing level.
1.304 + * The decoder supports a post-processing filter that can improve
1.305 + * the appearance of the decoded images. This returns the highest
1.306 + * level setting for this post-processor, corresponding to maximum
1.307 + * improvement and computational expense.
1.308 + */
1.309 +#define TH_DECCTL_GET_PPLEVEL_MAX (1)
1.310 +
1.311 +/**Set the post-processing level.
1.312 + * Sets the level of post-processing to use when decoding the
1.313 + * compressed stream. This must be a value between zero (off)
1.314 + * and the maximum returned by TH_DECCTL_GET_PPLEVEL_MAX.
1.315 + */
1.316 +#define TH_DECCTL_SET_PPLEVEL (3)
1.317 +
1.318 +/**Sets the maximum distance between key frames.
1.319 + * This can be changed during an encode, but will be bounded by
1.320 + * <tt>1<<th_info#keyframe_granule_shift</tt>.
1.321 + * If it is set before encoding begins, th_info#keyframe_granule_shift will
1.322 + * be enlarged appropriately.
1.323 + *
1.324 + * \param[in] buf <tt>ogg_uint32_t</tt>: The maximum distance between key
1.325 + * frames.
1.326 + * \param[out] buf <tt>ogg_uint32_t</tt>: The actual maximum distance set.
1.327 + * \retval OC_FAULT \a theora_state or \a buf is <tt>NULL</tt>.
1.328 + * \retval OC_EINVAL \a buf_sz is not <tt>sizeof(ogg_uint32_t)</tt>.
1.329 + * \retval OC_IMPL Not supported by this implementation.*/
1.330 +#define TH_ENCCTL_SET_KEYFRAME_FREQUENCY_FORCE (4)
1.331 +
1.332 +/**Set the granule position.
1.333 + * Call this after a seek, to update the internal granulepos
1.334 + * in the decoder, to insure that subsequent frames are marked
1.335 + * properly. If you track timestamps yourself and do not use
1.336 + * the granule postion returned by the decoder, then you do
1.337 + * not need to use this control.
1.338 + */
1.339 +#define TH_DECCTL_SET_GRANPOS (5)
1.340 +
1.341 +/**\anchor encctlcodes_old */
1.342 +
1.343 +/**Sets the quantization parameters to use.
1.344 + * The parameters are copied, not stored by reference, so they can be freed
1.345 + * after this call.
1.346 + * <tt>NULL</tt> may be specified to revert to the default parameters.
1.347 + *
1.348 + * \param[in] buf #th_quant_info
1.349 + * \retval OC_FAULT \a theora_state is <tt>NULL</tt>.
1.350 + * \retval OC_EINVAL Encoding has already begun, the quantization parameters
1.351 + * are not acceptable to this version of the encoder,
1.352 + * \a buf is <tt>NULL</tt> and \a buf_sz is not zero,
1.353 + * or \a buf is non-<tt>NULL</tt> and \a buf_sz is
1.354 + * not <tt>sizeof(#th_quant_info)</tt>.
1.355 + * \retval OC_IMPL Not supported by this implementation.*/
1.356 +#define TH_ENCCTL_SET_QUANT_PARAMS (2)
1.357 +
1.358 +/**Disables any encoder features that would prevent lossless transcoding back
1.359 + * to VP3.
1.360 + * This primarily means disabling block-level QI values and not using 4MV mode
1.361 + * when any of the luma blocks in a macro block are not coded.
1.362 + * It also includes using the VP3 quantization tables and Huffman codes; if you
1.363 + * set them explicitly after calling this function, the resulting stream will
1.364 + * not be VP3-compatible.
1.365 + * If you enable VP3-compatibility when encoding 4:2:2 or 4:4:4 source
1.366 + * material, or when using a picture region smaller than the full frame (e.g.
1.367 + * a non-multiple-of-16 width or height), then non-VP3 bitstream features will
1.368 + * still be disabled, but the stream will still not be VP3-compatible, as VP3
1.369 + * was not capable of encoding such formats.
1.370 + * If you call this after encoding has already begun, then the quantization
1.371 + * tables and codebooks cannot be changed, but the frame-level features will
1.372 + * be enabled or disabled as requested.
1.373 + *
1.374 + * \param[in] buf <tt>int</tt>: a non-zero value to enable VP3 compatibility,
1.375 + * or 0 to disable it (the default).
1.376 + * \param[out] buf <tt>int</tt>: 1 if all bitstream features required for
1.377 + * VP3-compatibility could be set, and 0 otherwise.
1.378 + * The latter will be returned if the pixel format is not
1.379 + * 4:2:0, the picture region is smaller than the full frame,
1.380 + * or if encoding has begun, preventing the quantization
1.381 + * tables and codebooks from being set.
1.382 + * \retval OC_FAULT \a theora_state or \a buf is <tt>NULL</tt>.
1.383 + * \retval OC_EINVAL \a buf_sz is not <tt>sizeof(int)</tt>.
1.384 + * \retval OC_IMPL Not supported by this implementation.*/
1.385 +#define TH_ENCCTL_SET_VP3_COMPATIBLE (10)
1.386 +
1.387 +/**Gets the maximum speed level.
1.388 + * Higher speed levels favor quicker encoding over better quality per bit.
1.389 + * Depending on the encoding mode, and the internal algorithms used, quality
1.390 + * may actually improve, but in this case bitrate will also likely increase.
1.391 + * In any case, overall rate/distortion performance will probably decrease.
1.392 + * The maximum value, and the meaning of each value, may change depending on
1.393 + * the current encoding mode (VBR vs. CQI, etc.).
1.394 + *
1.395 + * \param[out] buf int: The maximum encoding speed level.
1.396 + * \retval OC_FAULT \a theora_state or \a buf is <tt>NULL</tt>.
1.397 + * \retval OC_EINVAL \a buf_sz is not <tt>sizeof(int)</tt>.
1.398 + * \retval OC_IMPL Not supported by this implementation in the current
1.399 + * encoding mode.*/
1.400 +#define TH_ENCCTL_GET_SPLEVEL_MAX (12)
1.401 +
1.402 +/**Sets the speed level.
1.403 + * By default a speed value of 1 is used.
1.404 + *
1.405 + * \param[in] buf int: The new encoding speed level.
1.406 + * 0 is slowest, larger values use less CPU.
1.407 + * \retval OC_FAULT \a theora_state or \a buf is <tt>NULL</tt>.
1.408 + * \retval OC_EINVAL \a buf_sz is not <tt>sizeof(int)</tt>, or the
1.409 + * encoding speed level is out of bounds.
1.410 + * The maximum encoding speed level may be
1.411 + * implementation- and encoding mode-specific, and can be
1.412 + * obtained via #TH_ENCCTL_GET_SPLEVEL_MAX.
1.413 + * \retval OC_IMPL Not supported by this implementation in the current
1.414 + * encoding mode.*/
1.415 +#define TH_ENCCTL_SET_SPLEVEL (14)
1.416 +
1.417 +/*@}*/
1.418 +
1.419 +#define OC_FAULT -1 /**< General failure */
1.420 +#define OC_EINVAL -10 /**< Library encountered invalid internal data */
1.421 +#define OC_DISABLED -11 /**< Requested action is disabled */
1.422 +#define OC_BADHEADER -20 /**< Header packet was corrupt/invalid */
1.423 +#define OC_NOTFORMAT -21 /**< Packet is not a theora packet */
1.424 +#define OC_VERSION -22 /**< Bitstream version is not handled */
1.425 +#define OC_IMPL -23 /**< Feature or action not implemented */
1.426 +#define OC_BADPACKET -24 /**< Packet is corrupt */
1.427 +#define OC_NEWPACKET -25 /**< Packet is an (ignorable) unhandled extension */
1.428 +#define OC_DUPFRAME 1 /**< Packet is a dropped frame */
1.429 +
1.430 +/**
1.431 + * Retrieve a human-readable string to identify the encoder vendor and version.
1.432 + * \returns A version string.
1.433 + */
1.434 +extern const char *theora_version_string(void);
1.435 +
1.436 +/**
1.437 + * Retrieve a 32-bit version number.
1.438 + * This number is composed of a 16-bit major version, 8-bit minor version
1.439 + * and 8 bit sub-version, composed as follows:
1.440 +<pre>
1.441 + (VERSION_MAJOR<<16) + (VERSION_MINOR<<8) + (VERSION_SUB)
1.442 +</pre>
1.443 +* \returns The version number.
1.444 +*/
1.445 +extern ogg_uint32_t theora_version_number(void);
1.446 +
1.447 +/**
1.448 + * Initialize the theora encoder.
1.449 + * \param th The theora_state handle to initialize for encoding.
1.450 + * \param ti A theora_info struct filled with the desired encoding parameters.
1.451 + * \retval 0 Success
1.452 + */
1.453 +extern int theora_encode_init(theora_state *th, theora_info *ti);
1.454 +
1.455 +/**
1.456 + * Submit a YUV buffer to the theora encoder.
1.457 + * \param t A theora_state handle previously initialized for encoding.
1.458 + * \param yuv A buffer of YUV data to encode. Note that both the yuv_buffer
1.459 + * struct and the luma/chroma buffers within should be allocated by
1.460 + * the user.
1.461 + * \retval OC_EINVAL Encoder is not ready, or is finished.
1.462 + * \retval -1 The size of the given frame differs from those previously input
1.463 + * \retval 0 Success
1.464 + */
1.465 +extern int theora_encode_YUVin(theora_state *t, yuv_buffer *yuv);
1.466 +
1.467 +/**
1.468 + * Request the next packet of encoded video.
1.469 + * The encoded data is placed in a user-provided ogg_packet structure.
1.470 + * \param t A theora_state handle previously initialized for encoding.
1.471 + * \param last_p whether this is the last packet the encoder should produce.
1.472 + * \param op An ogg_packet structure to fill. libtheora will set all
1.473 + * elements of this structure, including a pointer to encoded
1.474 + * data. The memory for the encoded data is owned by libtheora.
1.475 + * \retval 0 No internal storage exists OR no packet is ready
1.476 + * \retval -1 The encoding process has completed
1.477 + * \retval 1 Success
1.478 + */
1.479 +extern int theora_encode_packetout( theora_state *t, int last_p,
1.480 + ogg_packet *op);
1.481 +
1.482 +/**
1.483 + * Request a packet containing the initial header.
1.484 + * A pointer to the header data is placed in a user-provided ogg_packet
1.485 + * structure.
1.486 + * \param t A theora_state handle previously initialized for encoding.
1.487 + * \param op An ogg_packet structure to fill. libtheora will set all
1.488 + * elements of this structure, including a pointer to the header
1.489 + * data. The memory for the header data is owned by libtheora.
1.490 + * \retval 0 Success
1.491 + */
1.492 +extern int theora_encode_header(theora_state *t, ogg_packet *op);
1.493 +
1.494 +/**
1.495 + * Request a comment header packet from provided metadata.
1.496 + * A pointer to the comment data is placed in a user-provided ogg_packet
1.497 + * structure.
1.498 + * \param tc A theora_comment structure filled with the desired metadata
1.499 + * \param op An ogg_packet structure to fill. libtheora will set all
1.500 + * elements of this structure, including a pointer to the encoded
1.501 + * comment data. The memory for the comment data is owned by
1.502 + * libtheora.
1.503 + * \retval 0 Success
1.504 + */
1.505 +extern int theora_encode_comment(theora_comment *tc, ogg_packet *op);
1.506 +
1.507 +/**
1.508 + * Request a packet containing the codebook tables for the stream.
1.509 + * A pointer to the codebook data is placed in a user-provided ogg_packet
1.510 + * structure.
1.511 + * \param t A theora_state handle previously initialized for encoding.
1.512 + * \param op An ogg_packet structure to fill. libtheora will set all
1.513 + * elements of this structure, including a pointer to the codebook
1.514 + * data. The memory for the header data is owned by libtheora.
1.515 + * \retval 0 Success
1.516 + */
1.517 +extern int theora_encode_tables(theora_state *t, ogg_packet *op);
1.518 +
1.519 +/**
1.520 + * Decode an Ogg packet, with the expectation that the packet contains
1.521 + * an initial header, comment data or codebook tables.
1.522 + *
1.523 + * \param ci A theora_info structure to fill. This must have been previously
1.524 + * initialized with theora_info_init(). If \a op contains an initial
1.525 + * header, theora_decode_header() will fill \a ci with the
1.526 + * parsed header values. If \a op contains codebook tables,
1.527 + * theora_decode_header() will parse these and attach an internal
1.528 + * representation to \a ci->codec_setup.
1.529 + * \param cc A theora_comment structure to fill. If \a op contains comment
1.530 + * data, theora_decode_header() will fill \a cc with the parsed
1.531 + * comments.
1.532 + * \param op An ogg_packet structure which you expect contains an initial
1.533 + * header, comment data or codebook tables.
1.534 + *
1.535 + * \retval OC_BADHEADER \a op is NULL; OR the first byte of \a op->packet
1.536 + * has the signature of an initial packet, but op is
1.537 + * not a b_o_s packet; OR this packet has the signature
1.538 + * of an initial header packet, but an initial header
1.539 + * packet has already been seen; OR this packet has the
1.540 + * signature of a comment packet, but the initial header
1.541 + * has not yet been seen; OR this packet has the signature
1.542 + * of a comment packet, but contains invalid data; OR
1.543 + * this packet has the signature of codebook tables,
1.544 + * but the initial header or comments have not yet
1.545 + * been seen; OR this packet has the signature of codebook
1.546 + * tables, but contains invalid data;
1.547 + * OR the stream being decoded has a compatible version
1.548 + * but this packet does not have the signature of a
1.549 + * theora initial header, comments, or codebook packet
1.550 + * \retval OC_VERSION The packet data of \a op is an initial header with
1.551 + * a version which is incompatible with this version of
1.552 + * libtheora.
1.553 + * \retval OC_NEWPACKET the stream being decoded has an incompatible (future)
1.554 + * version and contains an unknown signature.
1.555 + * \retval 0 Success
1.556 + *
1.557 + * \note The normal usage is that theora_decode_header() be called on the
1.558 + * first three packets of a theora logical bitstream in succession.
1.559 + */
1.560 +extern int theora_decode_header(theora_info *ci, theora_comment *cc,
1.561 + ogg_packet *op);
1.562 +
1.563 +/**
1.564 + * Initialize a theora_state handle for decoding.
1.565 + * \param th The theora_state handle to initialize.
1.566 + * \param c A theora_info struct filled with the desired decoding parameters.
1.567 + * This is of course usually obtained from a previous call to
1.568 + * theora_decode_header().
1.569 + * \retval 0 Success
1.570 + */
1.571 +extern int theora_decode_init(theora_state *th, theora_info *c);
1.572 +
1.573 +/**
1.574 + * Input a packet containing encoded data into the theora decoder.
1.575 + * \param th A theora_state handle previously initialized for decoding.
1.576 + * \param op An ogg_packet containing encoded theora data.
1.577 + * \retval 0 Success
1.578 + * \retval OC_BADPACKET \a op does not contain encoded video data
1.579 + */
1.580 +extern int theora_decode_packetin(theora_state *th,ogg_packet *op);
1.581 +
1.582 +/**
1.583 + * Output the next available frame of decoded YUV data.
1.584 + * \param th A theora_state handle previously initialized for decoding.
1.585 + * \param yuv A yuv_buffer in which libtheora should place the decoded data.
1.586 + * Note that the buffer struct itself is allocated by the user, but
1.587 + * that the luma and chroma pointers will be filled in by the
1.588 + * library. Also note that these luma and chroma regions should be
1.589 + * considered read-only by the user.
1.590 + * \retval 0 Success
1.591 + */
1.592 +extern int theora_decode_YUVout(theora_state *th,yuv_buffer *yuv);
1.593 +
1.594 +/**
1.595 + * Report whether a theora packet is a header or not
1.596 + * This function does no verification beyond checking the header
1.597 + * flag bit so it should not be used for bitstream identification;
1.598 + * use theora_decode_header() for that.
1.599 + *
1.600 + * \param op An ogg_packet containing encoded theora data.
1.601 + * \retval 1 The packet is a header packet
1.602 + * \retval 0 The packet is not a header packet (and so contains frame data)
1.603 + *
1.604 + * Thus function was added in the 1.0alpha4 release.
1.605 + */
1.606 +extern int theora_packet_isheader(ogg_packet *op);
1.607 +
1.608 +/**
1.609 + * Report whether a theora packet is a keyframe or not
1.610 + *
1.611 + * \param op An ogg_packet containing encoded theora data.
1.612 + * \retval 1 The packet contains a keyframe image
1.613 + * \retval 0 The packet is contains an interframe delta
1.614 + * \retval -1 The packet is not an image data packet at all
1.615 + *
1.616 + * Thus function was added in the 1.0alpha4 release.
1.617 + */
1.618 +extern int theora_packet_iskeyframe(ogg_packet *op);
1.619 +
1.620 +/**
1.621 + * Report the granulepos shift radix
1.622 + *
1.623 + * When embedded in Ogg, Theora uses a two-part granulepos,
1.624 + * splitting the 64-bit field into two pieces. The more-significant
1.625 + * section represents the frame count at the last keyframe,
1.626 + * and the less-significant section represents the count of
1.627 + * frames since the last keyframe. In this way the overall
1.628 + * field is still non-decreasing with time, but usefully encodes
1.629 + * a pointer to the last keyframe, which is necessary for
1.630 + * correctly restarting decode after a seek.
1.631 + *
1.632 + * This function reports the number of bits used to represent
1.633 + * the distance to the last keyframe, and thus how the granulepos
1.634 + * field must be shifted or masked to obtain the two parts.
1.635 + *
1.636 + * Since libtheora returns compressed data in an ogg_packet
1.637 + * structure, this may be generally useful even if the Theora
1.638 + * packets are not being used in an Ogg container.
1.639 + *
1.640 + * \param ti A previously initialized theora_info struct
1.641 + * \returns The bit shift dividing the two granulepos fields
1.642 + *
1.643 + * This function was added in the 1.0alpha5 release.
1.644 + */
1.645 +int theora_granule_shift(theora_info *ti);
1.646 +
1.647 +/**
1.648 + * Convert a granulepos to an absolute frame index, starting at 0.
1.649 + * The granulepos is interpreted in the context of a given theora_state handle.
1.650 + *
1.651 + * Note that while the granulepos encodes the frame count (i.e. starting
1.652 + * from 1) this call returns the frame index, starting from zero. Thus
1.653 + * One can calculate the presentation time by multiplying the index by
1.654 + * the rate.
1.655 + *
1.656 + * \param th A previously initialized theora_state handle (encode or decode)
1.657 + * \param granulepos The granulepos to convert.
1.658 + * \returns The frame index corresponding to \a granulepos.
1.659 + * \retval -1 The given granulepos is undefined (i.e. negative)
1.660 + *
1.661 + * Thus function was added in the 1.0alpha4 release.
1.662 + */
1.663 +extern ogg_int64_t theora_granule_frame(theora_state *th,ogg_int64_t granulepos);
1.664 +
1.665 +/**
1.666 + * Convert a granulepos to absolute time in seconds. The granulepos is
1.667 + * interpreted in the context of a given theora_state handle, and gives
1.668 + * the end time of a frame's presentation as used in Ogg mux ordering.
1.669 + *
1.670 + * \param th A previously initialized theora_state handle (encode or decode)
1.671 + * \param granulepos The granulepos to convert.
1.672 + * \returns The absolute time in seconds corresponding to \a granulepos.
1.673 + * This is the "end time" for the frame, or the latest time it should
1.674 + * be displayed.
1.675 + * It is not the presentation time.
1.676 + * \retval -1. The given granulepos is undefined (i.e. negative), or
1.677 + * \retval -1. The function has been disabled because floating
1.678 + * point support is not available.
1.679 + */
1.680 +extern double theora_granule_time(theora_state *th,ogg_int64_t granulepos);
1.681 +
1.682 +/**
1.683 + * Initialize a theora_info structure. All values within the given theora_info
1.684 + * structure are initialized, and space is allocated within libtheora for
1.685 + * internal codec setup data.
1.686 + * \param c A theora_info struct to initialize.
1.687 + */
1.688 +extern void theora_info_init(theora_info *c);
1.689 +
1.690 +/**
1.691 + * Clear a theora_info structure. All values within the given theora_info
1.692 + * structure are cleared, and associated internal codec setup data is freed.
1.693 + * \param c A theora_info struct to initialize.
1.694 + */
1.695 +extern void theora_info_clear(theora_info *c);
1.696 +
1.697 +/**
1.698 + * Free all internal data associated with a theora_state handle.
1.699 + * \param t A theora_state handle.
1.700 + */
1.701 +extern void theora_clear(theora_state *t);
1.702 +
1.703 +/**
1.704 + * Initialize an allocated theora_comment structure
1.705 + * \param tc An allocated theora_comment structure
1.706 + **/
1.707 +extern void theora_comment_init(theora_comment *tc);
1.708 +
1.709 +/**
1.710 + * Add a comment to an initialized theora_comment structure
1.711 + * \param tc A previously initialized theora comment structure
1.712 + * \param comment A null-terminated string encoding the comment in the form
1.713 + * "TAG=the value"
1.714 + *
1.715 + * Neither theora_comment_add() nor theora_comment_add_tag() support
1.716 + * comments containing null values, although the bitstream format
1.717 + * supports this. To add such comments you will need to manipulate
1.718 + * the theora_comment structure directly.
1.719 + **/
1.720 +
1.721 +extern void theora_comment_add(theora_comment *tc, char *comment);
1.722 +
1.723 +/**
1.724 + * Add a comment to an initialized theora_comment structure.
1.725 + * \param tc A previously initialized theora comment structure
1.726 + * \param tag A null-terminated string containing the tag
1.727 + * associated with the comment.
1.728 + * \param value The corresponding value as a null-terminated string
1.729 + *
1.730 + * Neither theora_comment_add() nor theora_comment_add_tag() support
1.731 + * comments containing null values, although the bitstream format
1.732 + * supports this. To add such comments you will need to manipulate
1.733 + * the theora_comment structure directly.
1.734 + **/
1.735 +extern void theora_comment_add_tag(theora_comment *tc,
1.736 + char *tag, char *value);
1.737 +
1.738 +/**
1.739 + * Look up a comment value by tag.
1.740 + * \param tc Tn initialized theora_comment structure
1.741 + * \param tag The tag to look up
1.742 + * \param count The instance of the tag. The same tag can appear multiple
1.743 + * times, each with a distinct and ordered value, so an index
1.744 + * is required to retrieve them all.
1.745 + * \returns A pointer to the queried tag's value
1.746 + * \retval NULL No matching tag is found
1.747 + *
1.748 + * \note Use theora_comment_query_count() to get the legal range for the
1.749 + * count parameter.
1.750 + **/
1.751 +
1.752 +extern char *theora_comment_query(theora_comment *tc, char *tag, int count);
1.753 +
1.754 +/** Look up the number of instances of a tag.
1.755 + * \param tc An initialized theora_comment structure
1.756 + * \param tag The tag to look up
1.757 + * \returns The number on instances of a particular tag.
1.758 + *
1.759 + * Call this first when querying for a specific tag and then interate
1.760 + * over the number of instances with separate calls to
1.761 + * theora_comment_query() to retrieve all instances in order.
1.762 + **/
1.763 +extern int theora_comment_query_count(theora_comment *tc, char *tag);
1.764 +
1.765 +/**
1.766 + * Clear an allocated theora_comment struct so that it can be freed.
1.767 + * \param tc An allocated theora_comment structure.
1.768 + **/
1.769 +extern void theora_comment_clear(theora_comment *tc);
1.770 +
1.771 +/**Encoder control function.
1.772 + * This is used to provide advanced control the encoding process.
1.773 + * \param th A #theora_state handle.
1.774 + * \param req The control code to process.
1.775 + * See \ref encctlcodes_old "the list of available
1.776 + * control codes" for details.
1.777 + * \param buf The parameters for this control code.
1.778 + * \param buf_sz The size of the parameter buffer.*/
1.779 +extern int theora_control(theora_state *th,int req,void *buf,size_t buf_sz);
1.780 +
1.781 +/* @} */ /* end oldfuncs doxygen group */
1.782 +
1.783 +#ifdef __cplusplus
1.784 +}
1.785 +#endif /* __cplusplus */
1.786 +
1.787 +#endif /* _O_THEORA_H_ */
