1 | /******************************************************************** |
2 | * * |
3 | * THIS FILE IS PART OF THE OggTheora SOFTWARE CODEC SOURCE CODE. * |
4 | * USE, DISTRIBUTION AND REPRODUCTION OF THIS LIBRARY SOURCE IS * |
5 | * GOVERNED BY A BSD-STYLE SOURCE LICENSE INCLUDED WITH THIS SOURCE * |
6 | * IN 'COPYING'. PLEASE READ THESE TERMS BEFORE DISTRIBUTING. * |
7 | * * |
8 | * THE Theora SOURCE CODE IS COPYRIGHT (C) 2002-2009 * |
9 | * by the Xiph.Org Foundation http://www.xiph.org/ * |
10 | * * |
11 | ******************************************************************** |
12 | |
13 | function: |
14 | last mod: $Id: theora.h,v 1.8 2004/03/15 22:17:32 derf Exp $ |
15 | |
16 | ********************************************************************/ |
17 | |
18 | /**\mainpage |
19 | * |
20 | * \section intro Introduction |
21 | * |
22 | * This is the documentation for <tt>libtheora</tt> C API. |
23 | * The current reference |
24 | * implementation for <a href="http://www.theora.org/">Theora</a>, a free, |
25 | * patent-unencumbered video codec. |
26 | * Theora is derived from On2's VP3 codec with additional features and |
27 | * integration with Ogg multimedia formats by |
28 | * <a href="http://www.xiph.org/">the Xiph.Org Foundation</a>. |
29 | * Complete documentation of the format itself is available in |
30 | * <a href="http://www.theora.org/doc/Theora.pdf">the Theora |
31 | * specification</a>. |
32 | * |
33 | * \subsection Organization |
34 | * |
35 | * The functions documented here are actually subdivided into three |
36 | * separate libraries: |
37 | * - <tt>libtheoraenc</tt> contains the encoder interface, |
38 | * described in \ref encfuncs. |
39 | * - <tt>libtheoradec</tt> contains the decoder interface and |
40 | * routines shared with the encoder. |
41 | * You must also link to this if you link to <tt>libtheoraenc</tt>. |
42 | * The routines in this library are described in \ref decfuncs and |
43 | * \ref basefuncs. |
44 | * - <tt>libtheora</tt> contains the \ref oldfuncs. |
45 | * |
46 | * New code should link to <tt>libtheoradec</tt> and, if using encoder |
47 | * features, <tt>libtheoraenc</tt>. Together these two export both |
48 | * the standard and the legacy API, so this is all that is needed by |
49 | * any code. The older <tt>libtheora</tt> library is provided just for |
50 | * compatibility with older build configurations. |
51 | * |
52 | * In general the recommended 1.x API symbols can be distinguished |
53 | * by their <tt>th_</tt> or <tt>TH_</tt> namespace prefix. |
54 | * The older, legacy API uses <tt>theora_</tt> or <tt>OC_</tt> |
55 | * prefixes instead. |
56 | */ |
57 | |
58 | /**\file |
59 | * The shared <tt>libtheoradec</tt> and <tt>libtheoraenc</tt> C API. |
60 | * You don't need to include this directly.*/ |
61 | |
62 | #if !defined(_O_THEORA_CODEC_H_) |
63 | # define _O_THEORA_CODEC_H_ (1) |
64 | # include <ogg/ogg.h> |
65 | |
66 | #if defined(__cplusplus) |
67 | extern "C" { |
68 | #endif |
69 | |
70 | |
71 | |
72 | /**\name Return codes*/ |
73 | /*@{*/ |
74 | /**An invalid pointer was provided.*/ |
75 | #define TH_EFAULT (-1) |
76 | /**An invalid argument was provided.*/ |
77 | #define TH_EINVAL (-10) |
78 | /**The contents of the header were incomplete, invalid, or unexpected.*/ |
79 | #define (-20) |
80 | /**The header does not belong to a Theora stream.*/ |
81 | #define TH_ENOTFORMAT (-21) |
82 | /**The bitstream version is too high.*/ |
83 | #define TH_EVERSION (-22) |
84 | /**The specified function is not implemented.*/ |
85 | #define TH_EIMPL (-23) |
86 | /**There were errors in the video data packet.*/ |
87 | #define TH_EBADPACKET (-24) |
88 | /**The decoded packet represented a dropped frame. |
89 | The player can continue to display the current frame, as the contents of the |
90 | decoded frame buffer have not changed.*/ |
91 | #define TH_DUPFRAME (1) |
92 | /*@}*/ |
93 | |
94 | /**The currently defined color space tags. |
95 | * See <a href="http://www.theora.org/doc/Theora.pdf">the Theora |
96 | * specification</a>, Chapter 4, for exact details on the meaning |
97 | * of each of these color spaces.*/ |
98 | typedef enum{ |
99 | /**The color space was not specified at the encoder. |
100 | It may be conveyed by an external means.*/ |
101 | TH_CS_UNSPECIFIED, |
102 | /**A color space designed for NTSC content.*/ |
103 | TH_CS_ITU_REC_470M, |
104 | /**A color space designed for PAL/SECAM content.*/ |
105 | TH_CS_ITU_REC_470BG, |
106 | /**The total number of currently defined color spaces.*/ |
107 | TH_CS_NSPACES |
108 | }th_colorspace; |
109 | |
110 | /**The currently defined pixel format tags. |
111 | * See <a href="http://www.theora.org/doc/Theora.pdf">the Theora |
112 | * specification</a>, Section 4.4, for details on the precise sample |
113 | * locations.*/ |
114 | typedef enum{ |
115 | /**Chroma decimation by 2 in both the X and Y directions (4:2:0). |
116 | The Cb and Cr chroma planes are half the width and half the |
117 | height of the luma plane.*/ |
118 | TH_PF_420, |
119 | /**Currently reserved.*/ |
120 | TH_PF_RSVD, |
121 | /**Chroma decimation by 2 in the X direction (4:2:2). |
122 | The Cb and Cr chroma planes are half the width of the luma plane, but full |
123 | height.*/ |
124 | TH_PF_422, |
125 | /**No chroma decimation (4:4:4). |
126 | The Cb and Cr chroma planes are full width and full height.*/ |
127 | TH_PF_444, |
128 | /**The total number of currently defined pixel formats.*/ |
129 | TH_PF_NFORMATS |
130 | }th_pixel_fmt; |
131 | |
132 | |
133 | |
134 | /**A buffer for a single color plane in an uncompressed image. |
135 | * This contains the image data in a left-to-right, top-down format. |
136 | * Each row of pixels is stored contiguously in memory, but successive |
137 | * rows need not be. |
138 | * Use \a stride to compute the offset of the next row. |
139 | * The encoder accepts both positive \a stride values (top-down in memory) |
140 | * and negative (bottom-up in memory). |
141 | * The decoder currently always generates images with positive strides.*/ |
142 | typedef struct{ |
143 | /**The width of this plane.*/ |
144 | int width; |
145 | /**The height of this plane.*/ |
146 | int height; |
147 | /**The offset in bytes between successive rows.*/ |
148 | int stride; |
149 | /**A pointer to the beginning of the first row.*/ |
150 | unsigned char *data; |
151 | }th_img_plane; |
152 | |
153 | /**A complete image buffer for an uncompressed frame. |
154 | * The chroma planes may be decimated by a factor of two in either |
155 | * direction, as indicated by th_info#pixel_fmt. |
156 | * The width and height of the Y' plane must be multiples of 16. |
157 | * They may need to be cropped for display, using the rectangle |
158 | * specified by th_info#pic_x, th_info#pic_y, th_info#pic_width, |
159 | * and th_info#pic_height. |
160 | * All samples are 8 bits. |
161 | * \note The term YUV often used to describe a colorspace is ambiguous. |
162 | * The exact parameters of the RGB to YUV conversion process aside, in |
163 | * many contexts the U and V channels actually have opposite meanings. |
164 | * To avoid this confusion, we are explicit: the name of the color |
165 | * channels are Y'CbCr, and they appear in that order, always. |
166 | * The prime symbol denotes that the Y channel is non-linear. |
167 | * Cb and Cr stand for "Chroma blue" and "Chroma red", respectively.*/ |
168 | typedef th_img_plane th_ycbcr_buffer[3]; |
169 | |
170 | /**Theora bitstream information. |
171 | * This contains the basic playback parameters for a stream, and corresponds to |
172 | * the initial 'info' header packet. |
173 | * To initialize an encoder, the application fills in this structure and |
174 | * passes it to th_encode_alloc(). |
175 | * A default encoding mode is chosen based on the values of the #quality and |
176 | * #target_bitrate fields. |
177 | * On decode, it is filled in by th_decode_headerin(), and then passed to |
178 | * th_decode_alloc(). |
179 | * |
180 | * Encoded Theora frames must be a multiple of 16 in size; |
181 | * this is what the #frame_width and #frame_height members represent. |
182 | * To handle arbitrary picture sizes, a crop rectangle is specified in the |
183 | * #pic_x, #pic_y, #pic_width and #pic_height members. |
184 | * |
185 | * All frame buffers contain pointers to the full, padded frame. |
186 | * However, the current encoder <em>will not</em> reference pixels outside of |
187 | * the cropped picture region, and the application does not need to fill them |
188 | * in. |
189 | * The decoder <em>will</em> allocate storage for a full frame, but the |
190 | * application <em>should not</em> rely on the padding containing sensible |
191 | * data. |
192 | * |
193 | * It is also generally recommended that the offsets and sizes should still be |
194 | * multiples of 2 to avoid chroma sampling shifts when chroma is sub-sampled. |
195 | * See <a href="http://www.theora.org/doc/Theora.pdf">the Theora |
196 | * specification</a>, Section 4.4, for more details. |
197 | * |
198 | * Frame rate, in frames per second, is stored as a rational fraction, as is |
199 | * the pixel aspect ratio. |
200 | * Note that this refers to the aspect ratio of the individual pixels, not of |
201 | * the overall frame itself. |
202 | * The frame aspect ratio can be computed from pixel aspect ratio using the |
203 | * image dimensions.*/ |
204 | typedef struct{ |
205 | /**\name Theora version |
206 | * Bitstream version information.*/ |
207 | /*@{*/ |
208 | unsigned char version_major; |
209 | unsigned char version_minor; |
210 | unsigned char version_subminor; |
211 | /*@}*/ |
212 | /**The encoded frame width. |
213 | * This must be a multiple of 16, and less than 1048576.*/ |
214 | ogg_uint32_t frame_width; |
215 | /**The encoded frame height. |
216 | * This must be a multiple of 16, and less than 1048576.*/ |
217 | ogg_uint32_t frame_height; |
218 | /**The displayed picture width. |
219 | * This must be no larger than width.*/ |
220 | ogg_uint32_t pic_width; |
221 | /**The displayed picture height. |
222 | * This must be no larger than height.*/ |
223 | ogg_uint32_t pic_height; |
224 | /**The X offset of the displayed picture. |
225 | * This must be no larger than #frame_width-#pic_width or 255, whichever is |
226 | * smaller.*/ |
227 | ogg_uint32_t pic_x; |
228 | /**The Y offset of the displayed picture. |
229 | * This must be no larger than #frame_height-#pic_height, and |
230 | * #frame_height-#pic_height-#pic_y must be no larger than 255. |
231 | * This slightly funny restriction is due to the fact that the offset is |
232 | * specified from the top of the image for consistency with the standard |
233 | * graphics left-handed coordinate system used throughout this API, while |
234 | * it is stored in the encoded stream as an offset from the bottom.*/ |
235 | ogg_uint32_t pic_y; |
236 | /**\name Frame rate |
237 | * The frame rate, as a fraction. |
238 | * If either is 0, the frame rate is undefined.*/ |
239 | /*@{*/ |
240 | ogg_uint32_t fps_numerator; |
241 | ogg_uint32_t fps_denominator; |
242 | /*@}*/ |
243 | /**\name Aspect ratio |
244 | * The aspect ratio of the pixels. |
245 | * If either value is zero, the aspect ratio is undefined. |
246 | * If not specified by any external means, 1:1 should be assumed. |
247 | * The aspect ratio of the full picture can be computed as |
248 | * \code |
249 | * aspect_numerator*pic_width/(aspect_denominator*pic_height). |
250 | * \endcode */ |
251 | /*@{*/ |
252 | ogg_uint32_t aspect_numerator; |
253 | ogg_uint32_t aspect_denominator; |
254 | /*@}*/ |
255 | /**The color space.*/ |
256 | th_colorspace colorspace; |
257 | /**The pixel format.*/ |
258 | th_pixel_fmt pixel_fmt; |
259 | /**The target bit-rate in bits per second. |
260 | If initializing an encoder with this struct, set this field to a non-zero |
261 | value to activate CBR encoding by default.*/ |
262 | int target_bitrate; |
263 | /**The target quality level. |
264 | Valid values range from 0 to 63, inclusive, with higher values giving |
265 | higher quality. |
266 | If initializing an encoder with this struct, and #target_bitrate is set |
267 | to zero, VBR encoding at this quality will be activated by default.*/ |
268 | /*Currently this is set so that a qi of 0 corresponds to distortions of 24 |
269 | times the JND, and each increase by 16 halves that value. |
270 | This gives us fine discrimination at low qualities, yet effective rate |
271 | control at high qualities. |
272 | The qi value 63 is special, however. |
273 | For this, the highest quality, we use one half of a JND for our threshold. |
274 | Due to the lower bounds placed on allowable quantizers in Theora, we will |
275 | not actually be able to achieve quality this good, but this should |
276 | provide as close to visually lossless quality as Theora is capable of. |
277 | We could lift the quantizer restrictions without breaking VP3.1 |
278 | compatibility, but this would result in quantized coefficients that are |
279 | too large for the current bitstream to be able to store. |
280 | We'd have to redesign the token syntax to store these large coefficients, |
281 | which would make transcoding complex.*/ |
282 | int quality; |
283 | /**The amount to shift to extract the last keyframe number from the granule |
284 | * position. |
285 | * This can be at most 31. |
286 | * th_info_init() will set this to a default value (currently <tt>6</tt>, |
287 | * which is good for streaming applications), but you can set it to 0 to |
288 | * make every frame a keyframe. |
289 | * The maximum distance between key frames is |
290 | * <tt>1<<#keyframe_granule_shift</tt>. |
291 | * The keyframe frequency can be more finely controlled with |
292 | * #TH_ENCCTL_SET_KEYFRAME_FREQUENCY_FORCE, which can also be adjusted |
293 | * during encoding (for example, to force the next frame to be a keyframe), |
294 | * but it cannot be set larger than the amount permitted by this field after |
295 | * the headers have been output.*/ |
296 | int keyframe_granule_shift; |
297 | }th_info; |
298 | |
299 | /**The comment information. |
300 | * |
301 | * This structure holds the in-stream metadata corresponding to |
302 | * the 'comment' header packet. |
303 | * The comment header is meant to be used much like someone jotting a quick |
304 | * note on the label of a video. |
305 | * It should be a short, to the point text note that can be more than a couple |
306 | * words, but not more than a short paragraph. |
307 | * |
308 | * The metadata is stored as a series of (tag, value) pairs, in |
309 | * length-encoded string vectors. |
310 | * The first occurrence of the '=' character delimits the tag and value. |
311 | * A particular tag may occur more than once, and order is significant. |
312 | * The character set encoding for the strings is always UTF-8, but the tag |
313 | * names are limited to ASCII, and treated as case-insensitive. |
314 | * See <a href="http://www.theora.org/doc/Theora.pdf">the Theora |
315 | * specification</a>, Section 6.3.3 for details. |
316 | * |
317 | * In filling in this structure, th_decode_headerin() will null-terminate |
318 | * the user_comment strings for safety. |
319 | * However, the bitstream format itself treats them as 8-bit clean vectors, |
320 | * possibly containing null characters, and so the length array should be |
321 | * treated as their authoritative length. |
322 | */ |
323 | typedef struct { |
324 | /**The array of comment string vectors.*/ |
325 | char **; |
326 | /**An array of the corresponding length of each vector, in bytes.*/ |
327 | int *; |
328 | /**The total number of comment strings.*/ |
329 | int ; |
330 | /**The null-terminated vendor string. |
331 | This identifies the software used to encode the stream.*/ |
332 | char *; |
333 | }; |
334 | |
335 | |
336 | |
337 | /**A single base matrix.*/ |
338 | typedef unsigned char th_quant_base[64]; |
339 | |
340 | /**A set of \a qi ranges.*/ |
341 | typedef struct{ |
342 | /**The number of ranges in the set.*/ |
343 | int nranges; |
344 | /**The size of each of the #nranges ranges. |
345 | These must sum to 63.*/ |
346 | const int *sizes; |
347 | /**#nranges <tt>+1</tt> base matrices. |
348 | Matrices \a i and <tt>i+1</tt> form the endpoints of range \a i.*/ |
349 | const th_quant_base *base_matrices; |
350 | }th_quant_ranges; |
351 | |
352 | /**A complete set of quantization parameters. |
353 | The quantizer for each coefficient is calculated as: |
354 | \code |
355 | Q=MAX(MIN(qmin[qti][ci!=0],scale[ci!=0][qi]*base[qti][pli][qi][ci]/100), |
356 | 1024). |
357 | \endcode |
358 | |
359 | \a qti is the quantization type index: 0 for intra, 1 for inter. |
360 | <tt>ci!=0</tt> is 0 for the DC coefficient and 1 for AC coefficients. |
361 | \a qi is the quality index, ranging between 0 (low quality) and 63 (high |
362 | quality). |
363 | \a pli is the color plane index: 0 for Y', 1 for Cb, 2 for Cr. |
364 | \a ci is the DCT coefficient index. |
365 | Coefficient indices correspond to the normal 2D DCT block |
366 | ordering--row-major with low frequencies first--\em not zig-zag order. |
367 | |
368 | Minimum quantizers are constant, and are given by: |
369 | \code |
370 | qmin[2][2]={{4,2},{8,4}}. |
371 | \endcode |
372 | |
373 | Parameters that can be stored in the bitstream are as follows: |
374 | - The two scale matrices ac_scale and dc_scale. |
375 | \code |
376 | scale[2][64]={dc_scale,ac_scale}. |
377 | \endcode |
378 | - The base matrices for each \a qi, \a qti and \a pli (up to 384 in all). |
379 | In order to avoid storing a full 384 base matrices, only a sparse set of |
380 | matrices are stored, and the rest are linearly interpolated. |
381 | This is done as follows. |
382 | For each \a qti and \a pli, a series of \a n \a qi ranges is defined. |
383 | The size of each \a qi range can vary arbitrarily, but they must sum to |
384 | 63. |
385 | Then, <tt>n+1</tt> matrices are specified, one for each endpoint of the |
386 | ranges. |
387 | For interpolation purposes, each range's endpoints are the first \a qi |
388 | value it contains and one past the last \a qi value it contains. |
389 | Fractional values are rounded to the nearest integer, with ties rounded |
390 | away from zero. |
391 | |
392 | Base matrices are stored by reference, so if the same matrices are used |
393 | multiple times, they will only appear once in the bitstream. |
394 | The bitstream is also capable of omitting an entire set of ranges and |
395 | its associated matrices if they are the same as either the previous |
396 | set (indexed in row-major order) or if the inter set is the same as the |
397 | intra set. |
398 | |
399 | - Loop filter limit values. |
400 | The same limits are used for the loop filter in all color planes, despite |
401 | potentially differing levels of quantization in each. |
402 | |
403 | For the current encoder, <tt>scale[ci!=0][qi]</tt> must be no greater |
404 | than <tt>scale[ci!=0][qi-1]</tt> and <tt>base[qti][pli][qi][ci]</tt> must |
405 | be no greater than <tt>base[qti][pli][qi-1][ci]</tt>. |
406 | These two conditions ensure that the actual quantizer for a given \a qti, |
407 | \a pli, and \a ci does not increase as \a qi increases. |
408 | This is not required by the decoder.*/ |
409 | typedef struct{ |
410 | /**The DC scaling factors.*/ |
411 | ogg_uint16_t dc_scale[64]; |
412 | /**The AC scaling factors.*/ |
413 | ogg_uint16_t ac_scale[64]; |
414 | /**The loop filter limit values.*/ |
415 | unsigned char loop_filter_limits[64]; |
416 | /**The \a qi ranges for each \a ci and \a pli.*/ |
417 | th_quant_ranges qi_ranges[2][3]; |
418 | }th_quant_info; |
419 | |
420 | |
421 | |
422 | /**The number of Huffman tables used by Theora.*/ |
423 | #define TH_NHUFFMAN_TABLES (80) |
424 | /**The number of DCT token values in each table.*/ |
425 | #define TH_NDCT_TOKENS (32) |
426 | |
427 | /**A Huffman code for a Theora DCT token. |
428 | * Each set of Huffman codes in a given table must form a complete, prefix-free |
429 | * code. |
430 | * There is no requirement that all the tokens in a table have a valid code, |
431 | * but the current encoder is not optimized to take advantage of this. |
432 | * If each of the five grouops of 16 tables does not contain at least one table |
433 | * with a code for every token, then the encoder may fail to encode certain |
434 | * frames. |
435 | * The complete table in the first group of 16 does not have to be in the same |
436 | * place as the complete table in the other groups, but the complete tables in |
437 | * the remaining four groups must all be in the same place.*/ |
438 | typedef struct{ |
439 | /**The bit pattern for the code, with the LSbit of the pattern aligned in |
440 | * the LSbit of the word.*/ |
441 | ogg_uint32_t pattern; |
442 | /**The number of bits in the code. |
443 | * This must be between 0 and 32, inclusive.*/ |
444 | int nbits; |
445 | }th_huff_code; |
446 | |
447 | |
448 | |
449 | /**\defgroup basefuncs Functions Shared by Encode and Decode*/ |
450 | /*@{*/ |
451 | /**\name Basic shared functions*/ |
452 | /*@{*/ |
453 | /**Retrieves a human-readable string to identify the library vendor and |
454 | * version. |
455 | * \return the version string.*/ |
456 | extern const char *th_version_string(void); |
457 | /**Retrieves the library version number. |
458 | * This is the highest bitstream version that the encoder library will produce, |
459 | * or that the decoder library can decode. |
460 | * This number is composed of a 16-bit major version, 8-bit minor version |
461 | * and 8 bit sub-version, composed as follows: |
462 | * \code |
463 | * (VERSION_MAJOR<<16)+(VERSION_MINOR<<8)+(VERSION_SUBMINOR) |
464 | * \endcode |
465 | * \return the version number.*/ |
466 | extern ogg_uint32_t th_version_number(void); |
467 | /**Converts a granule position to an absolute frame index, starting at |
468 | * <tt>0</tt>. |
469 | * The granule position is interpreted in the context of a given |
470 | * #th_enc_ctx or #th_dec_ctx handle (either will suffice). |
471 | * \param _encdec A previously allocated #th_enc_ctx or #th_dec_ctx |
472 | * handle. |
473 | * \param _granpos The granule position to convert. |
474 | * \returns The absolute frame index corresponding to \a _granpos. |
475 | * \retval -1 The given granule position was invalid (i.e. negative).*/ |
476 | extern ogg_int64_t th_granule_frame(void *_encdec,ogg_int64_t _granpos); |
477 | /**Converts a granule position to an absolute time in seconds. |
478 | * The granule position is interpreted in the context of a given |
479 | * #th_enc_ctx or #th_dec_ctx handle (either will suffice). |
480 | * \param _encdec A previously allocated #th_enc_ctx or #th_dec_ctx |
481 | * handle. |
482 | * \param _granpos The granule position to convert. |
483 | * \return The absolute time in seconds corresponding to \a _granpos. |
484 | * This is the "end time" for the frame, or the latest time it should |
485 | * be displayed. |
486 | * It is not the presentation time. |
487 | * \retval -1 The given granule position was invalid (i.e. negative).*/ |
488 | extern double th_granule_time(void *_encdec,ogg_int64_t _granpos); |
489 | /**Determines whether a Theora packet is a header or not. |
490 | * This function does no verification beyond checking the packet type bit, so |
491 | * it should not be used for bitstream identification; use |
492 | * th_decode_headerin() for that. |
493 | * As per the Theora specification, an empty (0-byte) packet is treated as a |
494 | * data packet (a delta frame with no coded blocks). |
495 | * \param _op An <tt>ogg_packet</tt> containing encoded Theora data. |
496 | * \retval 1 The packet is a header packet |
497 | * \retval 0 The packet is a video data packet.*/ |
498 | extern int (ogg_packet *_op); |
499 | /**Determines whether a theora packet is a key frame or not. |
500 | * This function does no verification beyond checking the packet type and |
501 | * key frame bits, so it should not be used for bitstream identification; use |
502 | * th_decode_headerin() for that. |
503 | * As per the Theora specification, an empty (0-byte) packet is treated as a |
504 | * delta frame (with no coded blocks). |
505 | * \param _op An <tt>ogg_packet</tt> containing encoded Theora data. |
506 | * \retval 1 The packet contains a key frame. |
507 | * \retval 0 The packet contains a delta frame. |
508 | * \retval -1 The packet is not a video data packet.*/ |
509 | extern int th_packet_iskeyframe(ogg_packet *_op); |
510 | /*@}*/ |
511 | |
512 | |
513 | /**\name Functions for manipulating header data*/ |
514 | /*@{*/ |
515 | /**Initializes a th_info structure. |
516 | * This should be called on a freshly allocated #th_info structure before |
517 | * attempting to use it. |
518 | * \param _info The #th_info struct to initialize.*/ |
519 | extern void th_info_init(th_info *_info); |
520 | /**Clears a #th_info structure. |
521 | * This should be called on a #th_info structure after it is no longer |
522 | * needed. |
523 | * \param _info The #th_info struct to clear.*/ |
524 | extern void th_info_clear(th_info *_info); |
525 | |
526 | /**Initialize a #th_comment structure. |
527 | * This should be called on a freshly allocated #th_comment structure |
528 | * before attempting to use it. |
529 | * \param _tc The #th_comment struct to initialize.*/ |
530 | extern void (th_comment *_tc); |
531 | /**Add a comment to an initialized #th_comment structure. |
532 | * \note Neither th_comment_add() nor th_comment_add_tag() support |
533 | * comments containing null values, although the bitstream format does |
534 | * support them. |
535 | * To add such comments you will need to manipulate the #th_comment |
536 | * structure directly. |
537 | * \param _tc The #th_comment struct to add the comment to. |
538 | * \param _comment Must be a null-terminated UTF-8 string containing the |
539 | * comment in "TAG=the value" form.*/ |
540 | extern void (th_comment *_tc, char *); |
541 | /**Add a comment to an initialized #th_comment structure. |
542 | * \note Neither th_comment_add() nor th_comment_add_tag() support |
543 | * comments containing null values, although the bitstream format does |
544 | * support them. |
545 | * To add such comments you will need to manipulate the #th_comment |
546 | * structure directly. |
547 | * \param _tc The #th_comment struct to add the comment to. |
548 | * \param _tag A null-terminated string containing the tag associated with |
549 | * the comment. |
550 | * \param _val The corresponding value as a null-terminated string.*/ |
551 | extern void (th_comment *_tc,char *_tag,char *_val); |
552 | /**Look up a comment value by its tag. |
553 | * \param _tc An initialized #th_comment structure. |
554 | * \param _tag The tag to look up. |
555 | * \param _count The instance of the tag. |
556 | * The same tag can appear multiple times, each with a distinct |
557 | * value, so an index is required to retrieve them all. |
558 | * The order in which these values appear is significant and |
559 | * should be preserved. |
560 | * Use th_comment_query_count() to get the legal range for |
561 | * the \a _count parameter. |
562 | * \return A pointer to the queried tag's value. |
563 | * This points directly to data in the #th_comment structure. |
564 | * It should not be modified or freed by the application, and |
565 | * modifications to the structure may invalidate the pointer. |
566 | * \retval NULL If no matching tag is found.*/ |
567 | extern char *(th_comment *_tc,char *_tag,int _count); |
568 | /**Look up the number of instances of a tag. |
569 | * Call this first when querying for a specific tag and then iterate over the |
570 | * number of instances with separate calls to th_comment_query() to |
571 | * retrieve all the values for that tag in order. |
572 | * \param _tc An initialized #th_comment structure. |
573 | * \param _tag The tag to look up. |
574 | * \return The number on instances of this particular tag.*/ |
575 | extern int (th_comment *_tc,char *_tag); |
576 | /**Clears a #th_comment structure. |
577 | * This should be called on a #th_comment structure after it is no longer |
578 | * needed. |
579 | * It will free all memory used by the structure members. |
580 | * \param _tc The #th_comment struct to clear.*/ |
581 | extern void (th_comment *_tc); |
582 | /*@}*/ |
583 | /*@}*/ |
584 | |
585 | |
586 | |
587 | #if defined(__cplusplus) |
588 | } |
589 | #endif |
590 | |
591 | #endif |
592 | |