1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
1.2 +++ b/media/libtheora/include/theora/codec.h Wed Dec 31 06:09:35 2014 +0100
1.3 @@ -0,0 +1,591 @@
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 +/**\mainpage
1.22 + *
1.23 + * \section intro Introduction
1.24 + *
1.25 + * This is the documentation for <tt>libtheora</tt> C API.
1.26 + * The current reference
1.27 + * implementation for <a href="http://www.theora.org/">Theora</a>, a free,
1.28 + * patent-unencumbered video codec.
1.29 + * Theora is derived from On2's VP3 codec with additional features and
1.30 + * integration with Ogg multimedia formats by
1.31 + * <a href="http://www.xiph.org/">the Xiph.Org Foundation</a>.
1.32 + * Complete documentation of the format itself is available in
1.33 + * <a href="http://www.theora.org/doc/Theora.pdf">the Theora
1.34 + * specification</a>.
1.35 + *
1.36 + * \subsection Organization
1.37 + *
1.38 + * The functions documented here are actually subdivided into three
1.39 + * separate libraries:
1.40 + * - <tt>libtheoraenc</tt> contains the encoder interface,
1.41 + * described in \ref encfuncs.
1.42 + * - <tt>libtheoradec</tt> contains the decoder interface and
1.43 + * routines shared with the encoder.
1.44 + * You must also link to this if you link to <tt>libtheoraenc</tt>.
1.45 + * The routines in this library are described in \ref decfuncs and
1.46 + * \ref basefuncs.
1.47 + * - <tt>libtheora</tt> contains the \ref oldfuncs.
1.48 + *
1.49 + * New code should link to <tt>libtheoradec</tt> and, if using encoder
1.50 + * features, <tt>libtheoraenc</tt>. Together these two export both
1.51 + * the standard and the legacy API, so this is all that is needed by
1.52 + * any code. The older <tt>libtheora</tt> library is provided just for
1.53 + * compatibility with older build configurations.
1.54 + *
1.55 + * In general the recommended 1.x API symbols can be distinguished
1.56 + * by their <tt>th_</tt> or <tt>TH_</tt> namespace prefix.
1.57 + * The older, legacy API uses <tt>theora_</tt> or <tt>OC_</tt>
1.58 + * prefixes instead.
1.59 + */
1.60 +
1.61 +/**\file
1.62 + * The shared <tt>libtheoradec</tt> and <tt>libtheoraenc</tt> C API.
1.63 + * You don't need to include this directly.*/
1.64 +
1.65 +#if !defined(_O_THEORA_CODEC_H_)
1.66 +# define _O_THEORA_CODEC_H_ (1)
1.67 +# include <ogg/ogg.h>
1.68 +
1.69 +#if defined(__cplusplus)
1.70 +extern "C" {
1.71 +#endif
1.72 +
1.73 +
1.74 +
1.75 +/**\name Return codes*/
1.76 +/*@{*/
1.77 +/**An invalid pointer was provided.*/
1.78 +#define TH_EFAULT (-1)
1.79 +/**An invalid argument was provided.*/
1.80 +#define TH_EINVAL (-10)
1.81 +/**The contents of the header were incomplete, invalid, or unexpected.*/
1.82 +#define TH_EBADHEADER (-20)
1.83 +/**The header does not belong to a Theora stream.*/
1.84 +#define TH_ENOTFORMAT (-21)
1.85 +/**The bitstream version is too high.*/
1.86 +#define TH_EVERSION (-22)
1.87 +/**The specified function is not implemented.*/
1.88 +#define TH_EIMPL (-23)
1.89 +/**There were errors in the video data packet.*/
1.90 +#define TH_EBADPACKET (-24)
1.91 +/**The decoded packet represented a dropped frame.
1.92 + The player can continue to display the current frame, as the contents of the
1.93 + decoded frame buffer have not changed.*/
1.94 +#define TH_DUPFRAME (1)
1.95 +/*@}*/
1.96 +
1.97 +/**The currently defined color space tags.
1.98 + * See <a href="http://www.theora.org/doc/Theora.pdf">the Theora
1.99 + * specification</a>, Chapter 4, for exact details on the meaning
1.100 + * of each of these color spaces.*/
1.101 +typedef enum{
1.102 + /**The color space was not specified at the encoder.
1.103 + It may be conveyed by an external means.*/
1.104 + TH_CS_UNSPECIFIED,
1.105 + /**A color space designed for NTSC content.*/
1.106 + TH_CS_ITU_REC_470M,
1.107 + /**A color space designed for PAL/SECAM content.*/
1.108 + TH_CS_ITU_REC_470BG,
1.109 + /**The total number of currently defined color spaces.*/
1.110 + TH_CS_NSPACES
1.111 +}th_colorspace;
1.112 +
1.113 +/**The currently defined pixel format tags.
1.114 + * See <a href="http://www.theora.org/doc/Theora.pdf">the Theora
1.115 + * specification</a>, Section 4.4, for details on the precise sample
1.116 + * locations.*/
1.117 +typedef enum{
1.118 + /**Chroma decimation by 2 in both the X and Y directions (4:2:0).
1.119 + The Cb and Cr chroma planes are half the width and half the
1.120 + height of the luma plane.*/
1.121 + TH_PF_420,
1.122 + /**Currently reserved.*/
1.123 + TH_PF_RSVD,
1.124 + /**Chroma decimation by 2 in the X direction (4:2:2).
1.125 + The Cb and Cr chroma planes are half the width of the luma plane, but full
1.126 + height.*/
1.127 + TH_PF_422,
1.128 + /**No chroma decimation (4:4:4).
1.129 + The Cb and Cr chroma planes are full width and full height.*/
1.130 + TH_PF_444,
1.131 + /**The total number of currently defined pixel formats.*/
1.132 + TH_PF_NFORMATS
1.133 +}th_pixel_fmt;
1.134 +
1.135 +
1.136 +
1.137 +/**A buffer for a single color plane in an uncompressed image.
1.138 + * This contains the image data in a left-to-right, top-down format.
1.139 + * Each row of pixels is stored contiguously in memory, but successive
1.140 + * rows need not be.
1.141 + * Use \a stride to compute the offset of the next row.
1.142 + * The encoder accepts both positive \a stride values (top-down in memory)
1.143 + * and negative (bottom-up in memory).
1.144 + * The decoder currently always generates images with positive strides.*/
1.145 +typedef struct{
1.146 + /**The width of this plane.*/
1.147 + int width;
1.148 + /**The height of this plane.*/
1.149 + int height;
1.150 + /**The offset in bytes between successive rows.*/
1.151 + int stride;
1.152 + /**A pointer to the beginning of the first row.*/
1.153 + unsigned char *data;
1.154 +}th_img_plane;
1.155 +
1.156 +/**A complete image buffer for an uncompressed frame.
1.157 + * The chroma planes may be decimated by a factor of two in either
1.158 + * direction, as indicated by th_info#pixel_fmt.
1.159 + * The width and height of the Y' plane must be multiples of 16.
1.160 + * They may need to be cropped for display, using the rectangle
1.161 + * specified by th_info#pic_x, th_info#pic_y, th_info#pic_width,
1.162 + * and th_info#pic_height.
1.163 + * All samples are 8 bits.
1.164 + * \note The term YUV often used to describe a colorspace is ambiguous.
1.165 + * The exact parameters of the RGB to YUV conversion process aside, in
1.166 + * many contexts the U and V channels actually have opposite meanings.
1.167 + * To avoid this confusion, we are explicit: the name of the color
1.168 + * channels are Y'CbCr, and they appear in that order, always.
1.169 + * The prime symbol denotes that the Y channel is non-linear.
1.170 + * Cb and Cr stand for "Chroma blue" and "Chroma red", respectively.*/
1.171 +typedef th_img_plane th_ycbcr_buffer[3];
1.172 +
1.173 +/**Theora bitstream information.
1.174 + * This contains the basic playback parameters for a stream, and corresponds to
1.175 + * the initial 'info' header packet.
1.176 + * To initialize an encoder, the application fills in this structure and
1.177 + * passes it to th_encode_alloc().
1.178 + * A default encoding mode is chosen based on the values of the #quality and
1.179 + * #target_bitrate fields.
1.180 + * On decode, it is filled in by th_decode_headerin(), and then passed to
1.181 + * th_decode_alloc().
1.182 + *
1.183 + * Encoded Theora frames must be a multiple of 16 in size;
1.184 + * this is what the #frame_width and #frame_height members represent.
1.185 + * To handle arbitrary picture sizes, a crop rectangle is specified in the
1.186 + * #pic_x, #pic_y, #pic_width and #pic_height members.
1.187 + *
1.188 + * All frame buffers contain pointers to the full, padded frame.
1.189 + * However, the current encoder <em>will not</em> reference pixels outside of
1.190 + * the cropped picture region, and the application does not need to fill them
1.191 + * in.
1.192 + * The decoder <em>will</em> allocate storage for a full frame, but the
1.193 + * application <em>should not</em> rely on the padding containing sensible
1.194 + * data.
1.195 + *
1.196 + * It is also generally recommended that the offsets and sizes should still be
1.197 + * multiples of 2 to avoid chroma sampling shifts when chroma is sub-sampled.
1.198 + * See <a href="http://www.theora.org/doc/Theora.pdf">the Theora
1.199 + * specification</a>, Section 4.4, for more details.
1.200 + *
1.201 + * Frame rate, in frames per second, is stored as a rational fraction, as is
1.202 + * the pixel aspect ratio.
1.203 + * Note that this refers to the aspect ratio of the individual pixels, not of
1.204 + * the overall frame itself.
1.205 + * The frame aspect ratio can be computed from pixel aspect ratio using the
1.206 + * image dimensions.*/
1.207 +typedef struct{
1.208 + /**\name Theora version
1.209 + * Bitstream version information.*/
1.210 + /*@{*/
1.211 + unsigned char version_major;
1.212 + unsigned char version_minor;
1.213 + unsigned char version_subminor;
1.214 + /*@}*/
1.215 + /**The encoded frame width.
1.216 + * This must be a multiple of 16, and less than 1048576.*/
1.217 + ogg_uint32_t frame_width;
1.218 + /**The encoded frame height.
1.219 + * This must be a multiple of 16, and less than 1048576.*/
1.220 + ogg_uint32_t frame_height;
1.221 + /**The displayed picture width.
1.222 + * This must be no larger than width.*/
1.223 + ogg_uint32_t pic_width;
1.224 + /**The displayed picture height.
1.225 + * This must be no larger than height.*/
1.226 + ogg_uint32_t pic_height;
1.227 + /**The X offset of the displayed picture.
1.228 + * This must be no larger than #frame_width-#pic_width or 255, whichever is
1.229 + * smaller.*/
1.230 + ogg_uint32_t pic_x;
1.231 + /**The Y offset of the displayed picture.
1.232 + * This must be no larger than #frame_height-#pic_height, and
1.233 + * #frame_height-#pic_height-#pic_y must be no larger than 255.
1.234 + * This slightly funny restriction is due to the fact that the offset is
1.235 + * specified from the top of the image for consistency with the standard
1.236 + * graphics left-handed coordinate system used throughout this API, while
1.237 + * it is stored in the encoded stream as an offset from the bottom.*/
1.238 + ogg_uint32_t pic_y;
1.239 + /**\name Frame rate
1.240 + * The frame rate, as a fraction.
1.241 + * If either is 0, the frame rate is undefined.*/
1.242 + /*@{*/
1.243 + ogg_uint32_t fps_numerator;
1.244 + ogg_uint32_t fps_denominator;
1.245 + /*@}*/
1.246 + /**\name Aspect ratio
1.247 + * The aspect ratio of the pixels.
1.248 + * If either value is zero, the aspect ratio is undefined.
1.249 + * If not specified by any external means, 1:1 should be assumed.
1.250 + * The aspect ratio of the full picture can be computed as
1.251 + * \code
1.252 + * aspect_numerator*pic_width/(aspect_denominator*pic_height).
1.253 + * \endcode */
1.254 + /*@{*/
1.255 + ogg_uint32_t aspect_numerator;
1.256 + ogg_uint32_t aspect_denominator;
1.257 + /*@}*/
1.258 + /**The color space.*/
1.259 + th_colorspace colorspace;
1.260 + /**The pixel format.*/
1.261 + th_pixel_fmt pixel_fmt;
1.262 + /**The target bit-rate in bits per second.
1.263 + If initializing an encoder with this struct, set this field to a non-zero
1.264 + value to activate CBR encoding by default.*/
1.265 + int target_bitrate;
1.266 + /**The target quality level.
1.267 + Valid values range from 0 to 63, inclusive, with higher values giving
1.268 + higher quality.
1.269 + If initializing an encoder with this struct, and #target_bitrate is set
1.270 + to zero, VBR encoding at this quality will be activated by default.*/
1.271 + /*Currently this is set so that a qi of 0 corresponds to distortions of 24
1.272 + times the JND, and each increase by 16 halves that value.
1.273 + This gives us fine discrimination at low qualities, yet effective rate
1.274 + control at high qualities.
1.275 + The qi value 63 is special, however.
1.276 + For this, the highest quality, we use one half of a JND for our threshold.
1.277 + Due to the lower bounds placed on allowable quantizers in Theora, we will
1.278 + not actually be able to achieve quality this good, but this should
1.279 + provide as close to visually lossless quality as Theora is capable of.
1.280 + We could lift the quantizer restrictions without breaking VP3.1
1.281 + compatibility, but this would result in quantized coefficients that are
1.282 + too large for the current bitstream to be able to store.
1.283 + We'd have to redesign the token syntax to store these large coefficients,
1.284 + which would make transcoding complex.*/
1.285 + int quality;
1.286 + /**The amount to shift to extract the last keyframe number from the granule
1.287 + * position.
1.288 + * This can be at most 31.
1.289 + * th_info_init() will set this to a default value (currently <tt>6</tt>,
1.290 + * which is good for streaming applications), but you can set it to 0 to
1.291 + * make every frame a keyframe.
1.292 + * The maximum distance between key frames is
1.293 + * <tt>1<<#keyframe_granule_shift</tt>.
1.294 + * The keyframe frequency can be more finely controlled with
1.295 + * #TH_ENCCTL_SET_KEYFRAME_FREQUENCY_FORCE, which can also be adjusted
1.296 + * during encoding (for example, to force the next frame to be a keyframe),
1.297 + * but it cannot be set larger than the amount permitted by this field after
1.298 + * the headers have been output.*/
1.299 + int keyframe_granule_shift;
1.300 +}th_info;
1.301 +
1.302 +/**The comment information.
1.303 + *
1.304 + * This structure holds the in-stream metadata corresponding to
1.305 + * the 'comment' header packet.
1.306 + * The comment header is meant to be used much like someone jotting a quick
1.307 + * note on the label of a video.
1.308 + * It should be a short, to the point text note that can be more than a couple
1.309 + * words, but not more than a short paragraph.
1.310 + *
1.311 + * The metadata is stored as a series of (tag, value) pairs, in
1.312 + * length-encoded string vectors.
1.313 + * The first occurrence of the '=' character delimits the tag and value.
1.314 + * A particular tag may occur more than once, and order is significant.
1.315 + * The character set encoding for the strings is always UTF-8, but the tag
1.316 + * names are limited to ASCII, and treated as case-insensitive.
1.317 + * See <a href="http://www.theora.org/doc/Theora.pdf">the Theora
1.318 + * specification</a>, Section 6.3.3 for details.
1.319 + *
1.320 + * In filling in this structure, th_decode_headerin() will null-terminate
1.321 + * the user_comment strings for safety.
1.322 + * However, the bitstream format itself treats them as 8-bit clean vectors,
1.323 + * possibly containing null characters, and so the length array should be
1.324 + * treated as their authoritative length.
1.325 + */
1.326 +typedef struct th_comment{
1.327 + /**The array of comment string vectors.*/
1.328 + char **user_comments;
1.329 + /**An array of the corresponding length of each vector, in bytes.*/
1.330 + int *comment_lengths;
1.331 + /**The total number of comment strings.*/
1.332 + int comments;
1.333 + /**The null-terminated vendor string.
1.334 + This identifies the software used to encode the stream.*/
1.335 + char *vendor;
1.336 +}th_comment;
1.337 +
1.338 +
1.339 +
1.340 +/**A single base matrix.*/
1.341 +typedef unsigned char th_quant_base[64];
1.342 +
1.343 +/**A set of \a qi ranges.*/
1.344 +typedef struct{
1.345 + /**The number of ranges in the set.*/
1.346 + int nranges;
1.347 + /**The size of each of the #nranges ranges.
1.348 + These must sum to 63.*/
1.349 + const int *sizes;
1.350 + /**#nranges <tt>+1</tt> base matrices.
1.351 + Matrices \a i and <tt>i+1</tt> form the endpoints of range \a i.*/
1.352 + const th_quant_base *base_matrices;
1.353 +}th_quant_ranges;
1.354 +
1.355 +/**A complete set of quantization parameters.
1.356 + The quantizer for each coefficient is calculated as:
1.357 + \code
1.358 + Q=MAX(MIN(qmin[qti][ci!=0],scale[ci!=0][qi]*base[qti][pli][qi][ci]/100),
1.359 + 1024).
1.360 + \endcode
1.361 +
1.362 + \a qti is the quantization type index: 0 for intra, 1 for inter.
1.363 + <tt>ci!=0</tt> is 0 for the DC coefficient and 1 for AC coefficients.
1.364 + \a qi is the quality index, ranging between 0 (low quality) and 63 (high
1.365 + quality).
1.366 + \a pli is the color plane index: 0 for Y', 1 for Cb, 2 for Cr.
1.367 + \a ci is the DCT coefficient index.
1.368 + Coefficient indices correspond to the normal 2D DCT block
1.369 + ordering--row-major with low frequencies first--\em not zig-zag order.
1.370 +
1.371 + Minimum quantizers are constant, and are given by:
1.372 + \code
1.373 + qmin[2][2]={{4,2},{8,4}}.
1.374 + \endcode
1.375 +
1.376 + Parameters that can be stored in the bitstream are as follows:
1.377 + - The two scale matrices ac_scale and dc_scale.
1.378 + \code
1.379 + scale[2][64]={dc_scale,ac_scale}.
1.380 + \endcode
1.381 + - The base matrices for each \a qi, \a qti and \a pli (up to 384 in all).
1.382 + In order to avoid storing a full 384 base matrices, only a sparse set of
1.383 + matrices are stored, and the rest are linearly interpolated.
1.384 + This is done as follows.
1.385 + For each \a qti and \a pli, a series of \a n \a qi ranges is defined.
1.386 + The size of each \a qi range can vary arbitrarily, but they must sum to
1.387 + 63.
1.388 + Then, <tt>n+1</tt> matrices are specified, one for each endpoint of the
1.389 + ranges.
1.390 + For interpolation purposes, each range's endpoints are the first \a qi
1.391 + value it contains and one past the last \a qi value it contains.
1.392 + Fractional values are rounded to the nearest integer, with ties rounded
1.393 + away from zero.
1.394 +
1.395 + Base matrices are stored by reference, so if the same matrices are used
1.396 + multiple times, they will only appear once in the bitstream.
1.397 + The bitstream is also capable of omitting an entire set of ranges and
1.398 + its associated matrices if they are the same as either the previous
1.399 + set (indexed in row-major order) or if the inter set is the same as the
1.400 + intra set.
1.401 +
1.402 + - Loop filter limit values.
1.403 + The same limits are used for the loop filter in all color planes, despite
1.404 + potentially differing levels of quantization in each.
1.405 +
1.406 + For the current encoder, <tt>scale[ci!=0][qi]</tt> must be no greater
1.407 + than <tt>scale[ci!=0][qi-1]</tt> and <tt>base[qti][pli][qi][ci]</tt> must
1.408 + be no greater than <tt>base[qti][pli][qi-1][ci]</tt>.
1.409 + These two conditions ensure that the actual quantizer for a given \a qti,
1.410 + \a pli, and \a ci does not increase as \a qi increases.
1.411 + This is not required by the decoder.*/
1.412 +typedef struct{
1.413 + /**The DC scaling factors.*/
1.414 + ogg_uint16_t dc_scale[64];
1.415 + /**The AC scaling factors.*/
1.416 + ogg_uint16_t ac_scale[64];
1.417 + /**The loop filter limit values.*/
1.418 + unsigned char loop_filter_limits[64];
1.419 + /**The \a qi ranges for each \a ci and \a pli.*/
1.420 + th_quant_ranges qi_ranges[2][3];
1.421 +}th_quant_info;
1.422 +
1.423 +
1.424 +
1.425 +/**The number of Huffman tables used by Theora.*/
1.426 +#define TH_NHUFFMAN_TABLES (80)
1.427 +/**The number of DCT token values in each table.*/
1.428 +#define TH_NDCT_TOKENS (32)
1.429 +
1.430 +/**A Huffman code for a Theora DCT token.
1.431 + * Each set of Huffman codes in a given table must form a complete, prefix-free
1.432 + * code.
1.433 + * There is no requirement that all the tokens in a table have a valid code,
1.434 + * but the current encoder is not optimized to take advantage of this.
1.435 + * If each of the five grouops of 16 tables does not contain at least one table
1.436 + * with a code for every token, then the encoder may fail to encode certain
1.437 + * frames.
1.438 + * The complete table in the first group of 16 does not have to be in the same
1.439 + * place as the complete table in the other groups, but the complete tables in
1.440 + * the remaining four groups must all be in the same place.*/
1.441 +typedef struct{
1.442 + /**The bit pattern for the code, with the LSbit of the pattern aligned in
1.443 + * the LSbit of the word.*/
1.444 + ogg_uint32_t pattern;
1.445 + /**The number of bits in the code.
1.446 + * This must be between 0 and 32, inclusive.*/
1.447 + int nbits;
1.448 +}th_huff_code;
1.449 +
1.450 +
1.451 +
1.452 +/**\defgroup basefuncs Functions Shared by Encode and Decode*/
1.453 +/*@{*/
1.454 +/**\name Basic shared functions*/
1.455 +/*@{*/
1.456 +/**Retrieves a human-readable string to identify the library vendor and
1.457 + * version.
1.458 + * \return the version string.*/
1.459 +extern const char *th_version_string(void);
1.460 +/**Retrieves the library version number.
1.461 + * This is the highest bitstream version that the encoder library will produce,
1.462 + * or that the decoder library can decode.
1.463 + * This number is composed of a 16-bit major version, 8-bit minor version
1.464 + * and 8 bit sub-version, composed as follows:
1.465 + * \code
1.466 + * (VERSION_MAJOR<<16)+(VERSION_MINOR<<8)+(VERSION_SUBMINOR)
1.467 + * \endcode
1.468 + * \return the version number.*/
1.469 +extern ogg_uint32_t th_version_number(void);
1.470 +/**Converts a granule position to an absolute frame index, starting at
1.471 + * <tt>0</tt>.
1.472 + * The granule position is interpreted in the context of a given
1.473 + * #th_enc_ctx or #th_dec_ctx handle (either will suffice).
1.474 + * \param _encdec A previously allocated #th_enc_ctx or #th_dec_ctx
1.475 + * handle.
1.476 + * \param _granpos The granule position to convert.
1.477 + * \returns The absolute frame index corresponding to \a _granpos.
1.478 + * \retval -1 The given granule position was invalid (i.e. negative).*/
1.479 +extern ogg_int64_t th_granule_frame(void *_encdec,ogg_int64_t _granpos);
1.480 +/**Converts a granule position to an absolute time in seconds.
1.481 + * The granule position is interpreted in the context of a given
1.482 + * #th_enc_ctx or #th_dec_ctx handle (either will suffice).
1.483 + * \param _encdec A previously allocated #th_enc_ctx or #th_dec_ctx
1.484 + * handle.
1.485 + * \param _granpos The granule position to convert.
1.486 + * \return The absolute time in seconds corresponding to \a _granpos.
1.487 + * This is the "end time" for the frame, or the latest time it should
1.488 + * be displayed.
1.489 + * It is not the presentation time.
1.490 + * \retval -1 The given granule position was invalid (i.e. negative).*/
1.491 +extern double th_granule_time(void *_encdec,ogg_int64_t _granpos);
1.492 +/**Determines whether a Theora packet is a header or not.
1.493 + * This function does no verification beyond checking the packet type bit, so
1.494 + * it should not be used for bitstream identification; use
1.495 + * th_decode_headerin() for that.
1.496 + * As per the Theora specification, an empty (0-byte) packet is treated as a
1.497 + * data packet (a delta frame with no coded blocks).
1.498 + * \param _op An <tt>ogg_packet</tt> containing encoded Theora data.
1.499 + * \retval 1 The packet is a header packet
1.500 + * \retval 0 The packet is a video data packet.*/
1.501 +extern int th_packet_isheader(ogg_packet *_op);
1.502 +/**Determines whether a theora packet is a key frame or not.
1.503 + * This function does no verification beyond checking the packet type and
1.504 + * key frame bits, so it should not be used for bitstream identification; use
1.505 + * th_decode_headerin() for that.
1.506 + * As per the Theora specification, an empty (0-byte) packet is treated as a
1.507 + * delta frame (with no coded blocks).
1.508 + * \param _op An <tt>ogg_packet</tt> containing encoded Theora data.
1.509 + * \retval 1 The packet contains a key frame.
1.510 + * \retval 0 The packet contains a delta frame.
1.511 + * \retval -1 The packet is not a video data packet.*/
1.512 +extern int th_packet_iskeyframe(ogg_packet *_op);
1.513 +/*@}*/
1.514 +
1.515 +
1.516 +/**\name Functions for manipulating header data*/
1.517 +/*@{*/
1.518 +/**Initializes a th_info structure.
1.519 + * This should be called on a freshly allocated #th_info structure before
1.520 + * attempting to use it.
1.521 + * \param _info The #th_info struct to initialize.*/
1.522 +extern void th_info_init(th_info *_info);
1.523 +/**Clears a #th_info structure.
1.524 + * This should be called on a #th_info structure after it is no longer
1.525 + * needed.
1.526 + * \param _info The #th_info struct to clear.*/
1.527 +extern void th_info_clear(th_info *_info);
1.528 +
1.529 +/**Initialize a #th_comment structure.
1.530 + * This should be called on a freshly allocated #th_comment structure
1.531 + * before attempting to use it.
1.532 + * \param _tc The #th_comment struct to initialize.*/
1.533 +extern void th_comment_init(th_comment *_tc);
1.534 +/**Add a comment to an initialized #th_comment structure.
1.535 + * \note Neither th_comment_add() nor th_comment_add_tag() support
1.536 + * comments containing null values, although the bitstream format does
1.537 + * support them.
1.538 + * To add such comments you will need to manipulate the #th_comment
1.539 + * structure directly.
1.540 + * \param _tc The #th_comment struct to add the comment to.
1.541 + * \param _comment Must be a null-terminated UTF-8 string containing the
1.542 + * comment in "TAG=the value" form.*/
1.543 +extern void th_comment_add(th_comment *_tc, char *_comment);
1.544 +/**Add a comment to an initialized #th_comment structure.
1.545 + * \note Neither th_comment_add() nor th_comment_add_tag() support
1.546 + * comments containing null values, although the bitstream format does
1.547 + * support them.
1.548 + * To add such comments you will need to manipulate the #th_comment
1.549 + * structure directly.
1.550 + * \param _tc The #th_comment struct to add the comment to.
1.551 + * \param _tag A null-terminated string containing the tag associated with
1.552 + * the comment.
1.553 + * \param _val The corresponding value as a null-terminated string.*/
1.554 +extern void th_comment_add_tag(th_comment *_tc,char *_tag,char *_val);
1.555 +/**Look up a comment value by its tag.
1.556 + * \param _tc An initialized #th_comment structure.
1.557 + * \param _tag The tag to look up.
1.558 + * \param _count The instance of the tag.
1.559 + * The same tag can appear multiple times, each with a distinct
1.560 + * value, so an index is required to retrieve them all.
1.561 + * The order in which these values appear is significant and
1.562 + * should be preserved.
1.563 + * Use th_comment_query_count() to get the legal range for
1.564 + * the \a _count parameter.
1.565 + * \return A pointer to the queried tag's value.
1.566 + * This points directly to data in the #th_comment structure.
1.567 + * It should not be modified or freed by the application, and
1.568 + * modifications to the structure may invalidate the pointer.
1.569 + * \retval NULL If no matching tag is found.*/
1.570 +extern char *th_comment_query(th_comment *_tc,char *_tag,int _count);
1.571 +/**Look up the number of instances of a tag.
1.572 + * Call this first when querying for a specific tag and then iterate over the
1.573 + * number of instances with separate calls to th_comment_query() to
1.574 + * retrieve all the values for that tag in order.
1.575 + * \param _tc An initialized #th_comment structure.
1.576 + * \param _tag The tag to look up.
1.577 + * \return The number on instances of this particular tag.*/
1.578 +extern int th_comment_query_count(th_comment *_tc,char *_tag);
1.579 +/**Clears a #th_comment structure.
1.580 + * This should be called on a #th_comment structure after it is no longer
1.581 + * needed.
1.582 + * It will free all memory used by the structure members.
1.583 + * \param _tc The #th_comment struct to clear.*/
1.584 +extern void th_comment_clear(th_comment *_tc);
1.585 +/*@}*/
1.586 +/*@}*/
1.587 +
1.588 +
1.589 +
1.590 +#if defined(__cplusplus)
1.591 +}
1.592 +#endif
1.593 +
1.594 +#endif
