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.17 2003/12/06 18:06:19 arc Exp $
15
16 ********************************************************************/
17
18#ifndef _O_THEORA_H_
19#define _O_THEORA_H_
20
21#ifdef __cplusplus
22extern "C"
23{
24#endif /* __cplusplus */
25
26#include <stddef.h> /* for size_t */
27
28#include <ogg/ogg.h>
29
30/** \file
31 * The libtheora pre-1.0 legacy C API.
32 *
33 * \ingroup oldfuncs
34 *
35 * \section intro Introduction
36 *
37 * This is the documentation for the libtheora legacy C API, declared in
38 * the theora.h header, which describes the old interface used before
39 * the 1.0 release. This API was widely deployed for several years and
40 * remains supported, but for new code we recommend the cleaner API
41 * declared in theoradec.h and theoraenc.h.
42 *
43 * libtheora is the reference implementation for
44 * <a href="http://www.theora.org/">Theora</a>, a free video codec.
45 * Theora is derived from On2's VP3 codec with improved integration with
46 * Ogg multimedia formats by <a href="http://www.xiph.org/">Xiph.Org</a>.
47 *
48 * \section overview Overview
49 *
50 * This library will both decode and encode theora packets to/from raw YUV
51 * frames. In either case, the packets will most likely either come from or
52 * need to be embedded in an Ogg stream. Use
53 * <a href="http://xiph.org/ogg/">libogg</a> or
54 * <a href="http://www.annodex.net/software/liboggz/index.html">liboggz</a>
55 * to extract/package these packets.
56 *
57 * \section decoding Decoding Process
58 *
59 * Decoding can be separated into the following steps:
60 * -# initialise theora_info and theora_comment structures using
61 * theora_info_init() and theora_comment_init():
62 \verbatim
63 theora_info info;
64 theora_comment comment;
65
66 theora_info_init(&info);
67 theora_comment_init(&comment);
68 \endverbatim
69 * -# retrieve header packets from Ogg stream (there should be 3) and decode
70 * into theora_info and theora_comment structures using
71 * theora_decode_header(). See \ref identification for more information on
72 * identifying which packets are theora packets.
73 \verbatim
74 int i;
75 for (i = 0; i < 3; i++)
76 {
77 (get a theora packet "op" from the Ogg stream)
78 theora_decode_header(&info, &comment, op);
79 }
80 \endverbatim
81 * -# initialise the decoder based on the information retrieved into the
82 * theora_info struct by theora_decode_header(). You will need a
83 * theora_state struct.
84 \verbatim
85 theora_state state;
86
87 theora_decode_init(&state, &info);
88 \endverbatim
89 * -# pass in packets and retrieve decoded frames! See the yuv_buffer
90 * documentation for information on how to retrieve raw YUV data.
91 \verbatim
92 yuf_buffer buffer;
93 while (last packet was not e_o_s) {
94 (get a theora packet "op" from the Ogg stream)
95 theora_decode_packetin(&state, op);
96 theora_decode_YUVout(&state, &buffer);
97 }
98 \endverbatim
99 *
100 *
101 * \subsection identification Identifying Theora Packets
102 *
103 * All streams inside an Ogg file have a unique serial_no attached to the
104 * stream. Typically, you will want to
105 * - retrieve the serial_no for each b_o_s (beginning of stream) page
106 * encountered within the Ogg file;
107 * - test the first (only) packet on that page to determine if it is a theora
108 * packet;
109 * - once you have found a theora b_o_s page then use the retrieved serial_no
110 * to identify future packets belonging to the same theora stream.
111 *
112 * Note that you \e cannot use theora_packet_isheader() to determine if a
113 * packet is a theora packet or not, as this function does not perform any
114 * checking beyond whether a header bit is present. Instead, use the
115 * theora_decode_header() function and check the return value; or examine the
116 * header bytes at the beginning of the Ogg page.
117 */
118
119
120/** \defgroup oldfuncs Legacy pre-1.0 C API */
121/* @{ */
122
123/**
124 * A YUV buffer for passing uncompressed frames to and from the codec.
125 * This holds a Y'CbCr frame in planar format. The CbCr planes can be
126 * subsampled and have their own separate dimensions and row stride
127 * offsets. Note that the strides may be negative in some
128 * configurations. For theora the width and height of the largest plane
129 * must be a multiple of 16. The actual meaningful picture size and
130 * offset are stored in the theora_info structure; frames returned by
131 * the decoder may need to be cropped for display.
132 *
133 * All samples are 8 bits. Within each plane samples are ordered by
134 * row from the top of the frame to the bottom. Within each row samples
135 * are ordered from left to right.
136 *
137 * During decode, the yuv_buffer struct is allocated by the user, but all
138 * fields (including luma and chroma pointers) are filled by the library.
139 * These pointers address library-internal memory and their contents should
140 * not be modified.
141 *
142 * Conversely, during encode the user allocates the struct and fills out all
143 * fields. The user also manages the data addressed by the luma and chroma
144 * pointers. See the encoder_example.c and dump_video.c example files in
145 * theora/examples/ for more information.
146 */
147typedef struct {
148 int y_width; /**< Width of the Y' luminance plane */
149 int y_height; /**< Height of the luminance plane */
150 int y_stride; /**< Offset in bytes between successive rows */
151
152 int uv_width; /**< Width of the Cb and Cr chroma planes */
153 int uv_height; /**< Height of the chroma planes */
154 int uv_stride; /**< Offset between successive chroma rows */
155 unsigned char *y; /**< Pointer to start of luminance data */
156 unsigned char *u; /**< Pointer to start of Cb data */
157 unsigned char *v; /**< Pointer to start of Cr data */
158
159} yuv_buffer;
160
161/**
162 * A Colorspace.
163 */
164typedef enum {
165 OC_CS_UNSPECIFIED, /**< The colorspace is unknown or unspecified */
166 OC_CS_ITU_REC_470M, /**< This is the best option for 'NTSC' content */
167 OC_CS_ITU_REC_470BG, /**< This is the best option for 'PAL' content */
168 OC_CS_NSPACES /**< This marks the end of the defined colorspaces */
169} theora_colorspace;
170
171/**
172 * A Chroma subsampling
173 *
174 * These enumerate the available chroma subsampling options supported
175 * by the theora format. See Section 4.4 of the specification for
176 * exact definitions.
177 */
178typedef enum {
179 OC_PF_420, /**< Chroma subsampling by 2 in each direction (4:2:0) */
180 OC_PF_RSVD, /**< Reserved value */
181 OC_PF_422, /**< Horizonatal chroma subsampling by 2 (4:2:2) */
182 OC_PF_444 /**< No chroma subsampling at all (4:4:4) */
183} theora_pixelformat;
184
185/**
186 * Theora bitstream info.
187 * Contains the basic playback parameters for a stream,
188 * corresponding to the initial 'info' header packet.
189 *
190 * Encoded theora frames must be a multiple of 16 in width and height.
191 * To handle other frame sizes, a crop rectangle is specified in
192 * frame_height and frame_width, offset_x and * offset_y. The offset
193 * and size should still be a multiple of 2 to avoid chroma sampling
194 * shifts. Offset values in this structure are measured from the
195 * upper left of the image.
196 *
197 * Frame rate, in frames per second, is stored as a rational
198 * fraction. Aspect ratio is also stored as a rational fraction, and
199 * refers to the aspect ratio of the frame pixels, not of the
200 * overall frame itself.
201 *
202 * See <a href="http://svn.xiph.org/trunk/theora/examples/encoder_example.c">
203 * examples/encoder_example.c</a> for usage examples of the
204 * other parameters and good default settings for the encoder parameters.
205 */
206typedef struct {
207 ogg_uint32_t width; /**< encoded frame width */
208 ogg_uint32_t height; /**< encoded frame height */
209 ogg_uint32_t frame_width; /**< display frame width */
210 ogg_uint32_t frame_height; /**< display frame height */
211 ogg_uint32_t offset_x; /**< horizontal offset of the displayed frame */
212 ogg_uint32_t offset_y; /**< vertical offset of the displayed frame */
213 ogg_uint32_t fps_numerator; /**< frame rate numerator **/
214 ogg_uint32_t fps_denominator; /**< frame rate denominator **/
215 ogg_uint32_t aspect_numerator; /**< pixel aspect ratio numerator */
216 ogg_uint32_t aspect_denominator; /**< pixel aspect ratio denominator */
217 theora_colorspace colorspace; /**< colorspace */
218 int target_bitrate; /**< nominal bitrate in bits per second */
219 int quality; /**< Nominal quality setting, 0-63 */
220 int quick_p; /**< Quick encode/decode */
221
222 /* decode only */
223 unsigned char version_major;
224 unsigned char version_minor;
225 unsigned char version_subminor;
226
227 void *codec_setup;
228
229 /* encode only */
230 int dropframes_p;
231 int keyframe_auto_p;
232 ogg_uint32_t keyframe_frequency;
233 ogg_uint32_t keyframe_frequency_force; /* also used for decode init to
234 get granpos shift correct */
235 ogg_uint32_t keyframe_data_target_bitrate;
236 ogg_int32_t keyframe_auto_threshold;
237 ogg_uint32_t keyframe_mindistance;
238 ogg_int32_t noise_sensitivity;
239 ogg_int32_t sharpness;
240
241 theora_pixelformat pixelformat; /**< chroma subsampling mode to expect */
242
243} theora_info;
244
245/** Codec internal state and context.
246 */
247typedef struct{
248 theora_info *i;
249 ogg_int64_t granulepos;
250
251 void *internal_encode;
252 void *internal_decode;
253
254} theora_state;
255
256/**
257 * Comment header metadata.
258 *
259 * This structure holds the in-stream metadata corresponding to
260 * the 'comment' header packet.
261 *
262 * Meta data is stored as a series of (tag, value) pairs, in
263 * length-encoded string vectors. The first occurence of the
264 * '=' character delimits the tag and value. A particular tag
265 * may occur more than once. The character set encoding for
266 * the strings is always UTF-8, but the tag names are limited
267 * to case-insensitive ASCII. See the spec for details.
268 *
269 * In filling in this structure, theora_decode_header() will
270 * null-terminate the user_comment strings for safety. However,
271 * the bitstream format itself treats them as 8-bit clean,
272 * and so the length array should be treated as authoritative
273 * for their length.
274 */
275typedef struct theora_comment{
276 char **user_comments; /**< An array of comment string vectors */
277 int *comment_lengths; /**< An array of corresponding string vector lengths in bytes */
278 int comments; /**< The total number of comment string vectors */
279 char *vendor; /**< The vendor string identifying the encoder, null terminated */
280
281} theora_comment;
282
283
284/**\name theora_control() codes */
285/* \anchor decctlcodes_old
286 * These are the available request codes for theora_control()
287 * when called with a decoder instance.
288 * By convention decoder control codes are odd, to distinguish
289 * them from \ref encctlcodes_old "encoder control codes" which
290 * are even.
291 *
292 * Note that since the 1.0 release, both the legacy and the final
293 * implementation accept all the same control codes, but only the
294 * final API declares the newer codes.
295 *
296 * Keep any experimental or vendor-specific values above \c 0x8000.*/
297
298/*@{*/
299
300/**Get the maximum post-processing level.
301 * The decoder supports a post-processing filter that can improve
302 * the appearance of the decoded images. This returns the highest
303 * level setting for this post-processor, corresponding to maximum
304 * improvement and computational expense.
305 */
306#define TH_DECCTL_GET_PPLEVEL_MAX (1)
307
308/**Set the post-processing level.
309 * Sets the level of post-processing to use when decoding the
310 * compressed stream. This must be a value between zero (off)
311 * and the maximum returned by TH_DECCTL_GET_PPLEVEL_MAX.
312 */
313#define TH_DECCTL_SET_PPLEVEL (3)
314
315/**Sets the maximum distance between key frames.
316 * This can be changed during an encode, but will be bounded by
317 * <tt>1<<th_info#keyframe_granule_shift</tt>.
318 * If it is set before encoding begins, th_info#keyframe_granule_shift will
319 * be enlarged appropriately.
320 *
321 * \param[in] buf <tt>ogg_uint32_t</tt>: The maximum distance between key
322 * frames.
323 * \param[out] buf <tt>ogg_uint32_t</tt>: The actual maximum distance set.
324 * \retval OC_FAULT \a theora_state or \a buf is <tt>NULL</tt>.
325 * \retval OC_EINVAL \a buf_sz is not <tt>sizeof(ogg_uint32_t)</tt>.
326 * \retval OC_IMPL Not supported by this implementation.*/
327#define TH_ENCCTL_SET_KEYFRAME_FREQUENCY_FORCE (4)
328
329/**Set the granule position.
330 * Call this after a seek, to update the internal granulepos
331 * in the decoder, to insure that subsequent frames are marked
332 * properly. If you track timestamps yourself and do not use
333 * the granule postion returned by the decoder, then you do
334 * not need to use this control.
335 */
336#define TH_DECCTL_SET_GRANPOS (5)
337
338/**\anchor encctlcodes_old */
339
340/**Sets the quantization parameters to use.
341 * The parameters are copied, not stored by reference, so they can be freed
342 * after this call.
343 * <tt>NULL</tt> may be specified to revert to the default parameters.
344 *
345 * \param[in] buf #th_quant_info
346 * \retval OC_FAULT \a theora_state is <tt>NULL</tt>.
347 * \retval OC_EINVAL Encoding has already begun, the quantization parameters
348 * are not acceptable to this version of the encoder,
349 * \a buf is <tt>NULL</tt> and \a buf_sz is not zero,
350 * or \a buf is non-<tt>NULL</tt> and \a buf_sz is
351 * not <tt>sizeof(#th_quant_info)</tt>.
352 * \retval OC_IMPL Not supported by this implementation.*/
353#define TH_ENCCTL_SET_QUANT_PARAMS (2)
354
355/**Disables any encoder features that would prevent lossless transcoding back
356 * to VP3.
357 * This primarily means disabling block-level QI values and not using 4MV mode
358 * when any of the luma blocks in a macro block are not coded.
359 * It also includes using the VP3 quantization tables and Huffman codes; if you
360 * set them explicitly after calling this function, the resulting stream will
361 * not be VP3-compatible.
362 * If you enable VP3-compatibility when encoding 4:2:2 or 4:4:4 source
363 * material, or when using a picture region smaller than the full frame (e.g.
364 * a non-multiple-of-16 width or height), then non-VP3 bitstream features will
365 * still be disabled, but the stream will still not be VP3-compatible, as VP3
366 * was not capable of encoding such formats.
367 * If you call this after encoding has already begun, then the quantization
368 * tables and codebooks cannot be changed, but the frame-level features will
369 * be enabled or disabled as requested.
370 *
371 * \param[in] buf <tt>int</tt>: a non-zero value to enable VP3 compatibility,
372 * or 0 to disable it (the default).
373 * \param[out] buf <tt>int</tt>: 1 if all bitstream features required for
374 * VP3-compatibility could be set, and 0 otherwise.
375 * The latter will be returned if the pixel format is not
376 * 4:2:0, the picture region is smaller than the full frame,
377 * or if encoding has begun, preventing the quantization
378 * tables and codebooks from being set.
379 * \retval OC_FAULT \a theora_state or \a buf is <tt>NULL</tt>.
380 * \retval OC_EINVAL \a buf_sz is not <tt>sizeof(int)</tt>.
381 * \retval OC_IMPL Not supported by this implementation.*/
382#define TH_ENCCTL_SET_VP3_COMPATIBLE (10)
383
384/**Gets the maximum speed level.
385 * Higher speed levels favor quicker encoding over better quality per bit.
386 * Depending on the encoding mode, and the internal algorithms used, quality
387 * may actually improve, but in this case bitrate will also likely increase.
388 * In any case, overall rate/distortion performance will probably decrease.
389 * The maximum value, and the meaning of each value, may change depending on
390 * the current encoding mode (VBR vs. CQI, etc.).
391 *
392 * \param[out] buf int: The maximum encoding speed level.
393 * \retval OC_FAULT \a theora_state or \a buf is <tt>NULL</tt>.
394 * \retval OC_EINVAL \a buf_sz is not <tt>sizeof(int)</tt>.
395 * \retval OC_IMPL Not supported by this implementation in the current
396 * encoding mode.*/
397#define TH_ENCCTL_GET_SPLEVEL_MAX (12)
398
399/**Sets the speed level.
400 * By default a speed value of 1 is used.
401 *
402 * \param[in] buf int: The new encoding speed level.
403 * 0 is slowest, larger values use less CPU.
404 * \retval OC_FAULT \a theora_state or \a buf is <tt>NULL</tt>.
405 * \retval OC_EINVAL \a buf_sz is not <tt>sizeof(int)</tt>, or the
406 * encoding speed level is out of bounds.
407 * The maximum encoding speed level may be
408 * implementation- and encoding mode-specific, and can be
409 * obtained via #TH_ENCCTL_GET_SPLEVEL_MAX.
410 * \retval OC_IMPL Not supported by this implementation in the current
411 * encoding mode.*/
412#define TH_ENCCTL_SET_SPLEVEL (14)
413
414/*@}*/
415
416#define OC_FAULT -1 /**< General failure */
417#define OC_EINVAL -10 /**< Library encountered invalid internal data */
418#define OC_DISABLED -11 /**< Requested action is disabled */
419#define OC_BADHEADER -20 /**< Header packet was corrupt/invalid */
420#define OC_NOTFORMAT -21 /**< Packet is not a theora packet */
421#define OC_VERSION -22 /**< Bitstream version is not handled */
422#define OC_IMPL -23 /**< Feature or action not implemented */
423#define OC_BADPACKET -24 /**< Packet is corrupt */
424#define OC_NEWPACKET -25 /**< Packet is an (ignorable) unhandled extension */
425#define OC_DUPFRAME 1 /**< Packet is a dropped frame */
426
427/**
428 * Retrieve a human-readable string to identify the encoder vendor and version.
429 * \returns A version string.
430 */
431extern const char *theora_version_string(void);
432
433/**
434 * Retrieve a 32-bit version number.
435 * This number is composed of a 16-bit major version, 8-bit minor version
436 * and 8 bit sub-version, composed as follows:
437<pre>
438 (VERSION_MAJOR<<16) + (VERSION_MINOR<<8) + (VERSION_SUB)
439</pre>
440* \returns The version number.
441*/
442extern ogg_uint32_t theora_version_number(void);
443
444/**
445 * Initialize the theora encoder.
446 * \param th The theora_state handle to initialize for encoding.
447 * \param ti A theora_info struct filled with the desired encoding parameters.
448 * \retval 0 Success
449 */
450extern int theora_encode_init(theora_state *th, theora_info *ti);
451
452/**
453 * Submit a YUV buffer to the theora encoder.
454 * \param t A theora_state handle previously initialized for encoding.
455 * \param yuv A buffer of YUV data to encode. Note that both the yuv_buffer
456 * struct and the luma/chroma buffers within should be allocated by
457 * the user.
458 * \retval OC_EINVAL Encoder is not ready, or is finished.
459 * \retval -1 The size of the given frame differs from those previously input
460 * \retval 0 Success
461 */
462extern int theora_encode_YUVin(theora_state *t, yuv_buffer *yuv);
463
464/**
465 * Request the next packet of encoded video.
466 * The encoded data is placed in a user-provided ogg_packet structure.
467 * \param t A theora_state handle previously initialized for encoding.
468 * \param last_p whether this is the last packet the encoder should produce.
469 * \param op An ogg_packet structure to fill. libtheora will set all
470 * elements of this structure, including a pointer to encoded
471 * data. The memory for the encoded data is owned by libtheora.
472 * \retval 0 No internal storage exists OR no packet is ready
473 * \retval -1 The encoding process has completed
474 * \retval 1 Success
475 */
476extern int theora_encode_packetout( theora_state *t, int last_p,
477 ogg_packet *op);
478
479/**
480 * Request a packet containing the initial header.
481 * A pointer to the header data is placed in a user-provided ogg_packet
482 * structure.
483 * \param t A theora_state handle previously initialized for encoding.
484 * \param op An ogg_packet structure to fill. libtheora will set all
485 * elements of this structure, including a pointer to the header
486 * data. The memory for the header data is owned by libtheora.
487 * \retval 0 Success
488 */
489extern int theora_encode_header(theora_state *t, ogg_packet *op);
490
491/**
492 * Request a comment header packet from provided metadata.
493 * A pointer to the comment data is placed in a user-provided ogg_packet
494 * structure.
495 * \param tc A theora_comment structure filled with the desired metadata
496 * \param op An ogg_packet structure to fill. libtheora will set all
497 * elements of this structure, including a pointer to the encoded
498 * comment data. The memory for the comment data is owned by
499 * the application, and must be freed by it using _ogg_free().
500 * On some systems (such as Windows when using dynamic linking), this
501 * may mean the free is executed in a different module from the
502 * malloc, which will crash; there is no way to free this memory on
503 * such systems.
504 * \retval 0 Success
505 */
506extern int theora_encode_comment(theora_comment *tc, ogg_packet *op);
507
508/**
509 * Request a packet containing the codebook tables for the stream.
510 * A pointer to the codebook data is placed in a user-provided ogg_packet
511 * structure.
512 * \param t A theora_state handle previously initialized for encoding.
513 * \param op An ogg_packet structure to fill. libtheora will set all
514 * elements of this structure, including a pointer to the codebook
515 * data. The memory for the header data is owned by libtheora.
516 * \retval 0 Success
517 */
518extern int theora_encode_tables(theora_state *t, ogg_packet *op);
519
520/**
521 * Decode an Ogg packet, with the expectation that the packet contains
522 * an initial header, comment data or codebook tables.
523 *
524 * \param ci A theora_info structure to fill. This must have been previously
525 * initialized with theora_info_init(). If \a op contains an initial
526 * header, theora_decode_header() will fill \a ci with the
527 * parsed header values. If \a op contains codebook tables,
528 * theora_decode_header() will parse these and attach an internal
529 * representation to \a ci->codec_setup.
530 * \param cc A theora_comment structure to fill. If \a op contains comment
531 * data, theora_decode_header() will fill \a cc with the parsed
532 * comments.
533 * \param op An ogg_packet structure which you expect contains an initial
534 * header, comment data or codebook tables.
535 *
536 * \retval OC_BADHEADER \a op is NULL; OR the first byte of \a op->packet
537 * has the signature of an initial packet, but op is
538 * not a b_o_s packet; OR this packet has the signature
539 * of an initial header packet, but an initial header
540 * packet has already been seen; OR this packet has the
541 * signature of a comment packet, but the initial header
542 * has not yet been seen; OR this packet has the signature
543 * of a comment packet, but contains invalid data; OR
544 * this packet has the signature of codebook tables,
545 * but the initial header or comments have not yet
546 * been seen; OR this packet has the signature of codebook
547 * tables, but contains invalid data;
548 * OR the stream being decoded has a compatible version
549 * but this packet does not have the signature of a
550 * theora initial header, comments, or codebook packet
551 * \retval OC_VERSION The packet data of \a op is an initial header with
552 * a version which is incompatible with this version of
553 * libtheora.
554 * \retval OC_NEWPACKET the stream being decoded has an incompatible (future)
555 * version and contains an unknown signature.
556 * \retval 0 Success
557 *
558 * \note The normal usage is that theora_decode_header() be called on the
559 * first three packets of a theora logical bitstream in succession.
560 */
561extern int theora_decode_header(theora_info *ci, theora_comment *cc,
562 ogg_packet *op);
563
564/**
565 * Initialize a theora_state handle for decoding.
566 * \param th The theora_state handle to initialize.
567 * \param c A theora_info struct filled with the desired decoding parameters.
568 * This is of course usually obtained from a previous call to
569 * theora_decode_header().
570 * \retval 0 Success
571 */
572extern int theora_decode_init(theora_state *th, theora_info *c);
573
574/**
575 * Input a packet containing encoded data into the theora decoder.
576 * \param th A theora_state handle previously initialized for decoding.
577 * \param op An ogg_packet containing encoded theora data.
578 * \retval 0 Success
579 * \retval OC_BADPACKET \a op does not contain encoded video data
580 */
581extern int theora_decode_packetin(theora_state *th,ogg_packet *op);
582
583/**
584 * Output the next available frame of decoded YUV data.
585 * \param th A theora_state handle previously initialized for decoding.
586 * \param yuv A yuv_buffer in which libtheora should place the decoded data.
587 * Note that the buffer struct itself is allocated by the user, but
588 * that the luma and chroma pointers will be filled in by the
589 * library. Also note that these luma and chroma regions should be
590 * considered read-only by the user.
591 * \retval 0 Success
592 */
593extern int theora_decode_YUVout(theora_state *th,yuv_buffer *yuv);
594
595/**
596 * Report whether a theora packet is a header or not
597 * This function does no verification beyond checking the header
598 * flag bit so it should not be used for bitstream identification;
599 * use theora_decode_header() for that.
600 *
601 * \param op An ogg_packet containing encoded theora data.
602 * \retval 1 The packet is a header packet
603 * \retval 0 The packet is not a header packet (and so contains frame data)
604 *
605 * Thus function was added in the 1.0alpha4 release.
606 */
607extern int theora_packet_isheader(ogg_packet *op);
608
609/**
610 * Report whether a theora packet is a keyframe or not
611 *
612 * \param op An ogg_packet containing encoded theora data.
613 * \retval 1 The packet contains a keyframe image
614 * \retval 0 The packet is contains an interframe delta
615 * \retval -1 The packet is not an image data packet at all
616 *
617 * Thus function was added in the 1.0alpha4 release.
618 */
619extern int theora_packet_iskeyframe(ogg_packet *op);
620
621/**
622 * Report the granulepos shift radix
623 *
624 * When embedded in Ogg, Theora uses a two-part granulepos,
625 * splitting the 64-bit field into two pieces. The more-significant
626 * section represents the frame count at the last keyframe,
627 * and the less-significant section represents the count of
628 * frames since the last keyframe. In this way the overall
629 * field is still non-decreasing with time, but usefully encodes
630 * a pointer to the last keyframe, which is necessary for
631 * correctly restarting decode after a seek.
632 *
633 * This function reports the number of bits used to represent
634 * the distance to the last keyframe, and thus how the granulepos
635 * field must be shifted or masked to obtain the two parts.
636 *
637 * Since libtheora returns compressed data in an ogg_packet
638 * structure, this may be generally useful even if the Theora
639 * packets are not being used in an Ogg container.
640 *
641 * \param ti A previously initialized theora_info struct
642 * \returns The bit shift dividing the two granulepos fields
643 *
644 * This function was added in the 1.0alpha5 release.
645 */
646int theora_granule_shift(theora_info *ti);
647
648/**
649 * Convert a granulepos to an absolute frame index, starting at 0.
650 * The granulepos is interpreted in the context of a given theora_state handle.
651 *
652 * Note that while the granulepos encodes the frame count (i.e. starting
653 * from 1) this call returns the frame index, starting from zero. Thus
654 * One can calculate the presentation time by multiplying the index by
655 * the rate.
656 *
657 * \param th A previously initialized theora_state handle (encode or decode)
658 * \param granulepos The granulepos to convert.
659 * \returns The frame index corresponding to \a granulepos.
660 * \retval -1 The given granulepos is undefined (i.e. negative)
661 *
662 * Thus function was added in the 1.0alpha4 release.
663 */
664extern ogg_int64_t theora_granule_frame(theora_state *th,ogg_int64_t granulepos);
665
666/**
667 * Convert a granulepos to absolute time in seconds. The granulepos is
668 * interpreted in the context of a given theora_state handle, and gives
669 * the end time of a frame's presentation as used in Ogg mux ordering.
670 *
671 * \param th A previously initialized theora_state handle (encode or decode)
672 * \param granulepos The granulepos to convert.
673 * \returns The absolute time in seconds corresponding to \a granulepos.
674 * This is the "end time" for the frame, or the latest time it should
675 * be displayed.
676 * It is not the presentation time.
677 * \retval -1. The given granulepos is undefined (i.e. negative).
678 */
679extern double theora_granule_time(theora_state *th,ogg_int64_t granulepos);
680
681/**
682 * Initialize a theora_info structure. All values within the given theora_info
683 * structure are initialized, and space is allocated within libtheora for
684 * internal codec setup data.
685 * \param c A theora_info struct to initialize.
686 */
687extern void theora_info_init(theora_info *c);
688
689/**
690 * Clear a theora_info structure. All values within the given theora_info
691 * structure are cleared, and associated internal codec setup data is freed.
692 * \param c A theora_info struct to initialize.
693 */
694extern void theora_info_clear(theora_info *c);
695
696/**
697 * Free all internal data associated with a theora_state handle.
698 * \param t A theora_state handle.
699 */
700extern void theora_clear(theora_state *t);
701
702/**
703 * Initialize an allocated theora_comment structure
704 * \param tc An allocated theora_comment structure
705 **/
706extern void theora_comment_init(theora_comment *tc);
707
708/**
709 * Add a comment to an initialized theora_comment structure
710 * \param tc A previously initialized theora comment structure
711 * \param comment A null-terminated string encoding the comment in the form
712 * "TAG=the value"
713 *
714 * Neither theora_comment_add() nor theora_comment_add_tag() support
715 * comments containing null values, although the bitstream format
716 * supports this. To add such comments you will need to manipulate
717 * the theora_comment structure directly.
718 **/
719
720extern void theora_comment_add(theora_comment *tc, char *comment);
721
722/**
723 * Add a comment to an initialized theora_comment structure.
724 * \param tc A previously initialized theora comment structure
725 * \param tag A null-terminated string containing the tag
726 * associated with the comment.
727 * \param value The corresponding value as a null-terminated string
728 *
729 * Neither theora_comment_add() nor theora_comment_add_tag() support
730 * comments containing null values, although the bitstream format
731 * supports this. To add such comments you will need to manipulate
732 * the theora_comment structure directly.
733 **/
734extern void theora_comment_add_tag(theora_comment *tc,
735 char *tag, char *value);
736
737/**
738 * Look up a comment value by tag.
739 * \param tc Tn initialized theora_comment structure
740 * \param tag The tag to look up
741 * \param count The instance of the tag. The same tag can appear multiple
742 * times, each with a distinct and ordered value, so an index
743 * is required to retrieve them all.
744 * \returns A pointer to the queried tag's value
745 * \retval NULL No matching tag is found
746 *
747 * \note Use theora_comment_query_count() to get the legal range for the
748 * count parameter.
749 **/
750
751extern char *theora_comment_query(theora_comment *tc, char *tag, int count);
752
753/** Look up the number of instances of a tag.
754 * \param tc An initialized theora_comment structure
755 * \param tag The tag to look up
756 * \returns The number on instances of a particular tag.
757 *
758 * Call this first when querying for a specific tag and then interate
759 * over the number of instances with separate calls to
760 * theora_comment_query() to retrieve all instances in order.
761 **/
762extern int theora_comment_query_count(theora_comment *tc, char *tag);
763
764/**
765 * Clear an allocated theora_comment struct so that it can be freed.
766 * \param tc An allocated theora_comment structure.
767 **/
768extern void theora_comment_clear(theora_comment *tc);
769
770/**Encoder control function.
771 * This is used to provide advanced control the encoding process.
772 * \param th A #theora_state handle.
773 * \param req The control code to process.
774 * See \ref encctlcodes_old "the list of available
775 * control codes" for details.
776 * \param buf The parameters for this control code.
777 * \param buf_sz The size of the parameter buffer.*/
778extern int theora_control(theora_state *th,int req,void *buf,size_t buf_sz);
779
780/* @} */ /* end oldfuncs doxygen group */
781
782#ifdef __cplusplus
783}
784#endif /* __cplusplus */
785
786#endif /* _O_THEORA_H_ */
787