diff options
Diffstat (limited to 'branches/1.0/thirdparties/android/include/theora/theora.h')
| -rw-r--r-- | branches/1.0/thirdparties/android/include/theora/theora.h | 784 |
1 files changed, 0 insertions, 784 deletions
diff --git a/branches/1.0/thirdparties/android/include/theora/theora.h b/branches/1.0/thirdparties/android/include/theora/theora.h deleted file mode 100644 index 575a889..0000000 --- a/branches/1.0/thirdparties/android/include/theora/theora.h +++ /dev/null @@ -1,784 +0,0 @@ -/******************************************************************** - * * - * THIS FILE IS PART OF THE OggTheora SOFTWARE CODEC SOURCE CODE. * - * USE, DISTRIBUTION AND REPRODUCTION OF THIS LIBRARY SOURCE IS * - * GOVERNED BY A BSD-STYLE SOURCE LICENSE INCLUDED WITH THIS SOURCE * - * IN 'COPYING'. PLEASE READ THESE TERMS BEFORE DISTRIBUTING. * - * * - * THE Theora SOURCE CODE IS COPYRIGHT (C) 2002-2009 * - * by the Xiph.Org Foundation http://www.xiph.org/ * - * * - ******************************************************************** - - function: - last mod: $Id: theora.h,v 1.17 2003/12/06 18:06:19 arc Exp $ - - ********************************************************************/ - -#ifndef _O_THEORA_H_ -#define _O_THEORA_H_ - -#ifdef __cplusplus -extern "C" -{ -#endif /* __cplusplus */ - -#include <stddef.h> /* for size_t */ - -#include <ogg/ogg.h> - -/** \file - * The libtheora pre-1.0 legacy C API. - * - * \ingroup oldfuncs - * - * \section intro Introduction - * - * This is the documentation for the libtheora legacy C API, declared in - * the theora.h header, which describes the old interface used before - * the 1.0 release. This API was widely deployed for several years and - * remains supported, but for new code we recommend the cleaner API - * declared in theoradec.h and theoraenc.h. - * - * libtheora is the reference implementation for - * <a href="http://www.theora.org/">Theora</a>, a free video codec. - * Theora is derived from On2's VP3 codec with improved integration with - * Ogg multimedia formats by <a href="http://www.xiph.org/">Xiph.Org</a>. - * - * \section overview Overview - * - * This library will both decode and encode theora packets to/from raw YUV - * frames. In either case, the packets will most likely either come from or - * need to be embedded in an Ogg stream. Use - * <a href="http://xiph.org/ogg/">libogg</a> or - * <a href="http://www.annodex.net/software/liboggz/index.html">liboggz</a> - * to extract/package these packets. - * - * \section decoding Decoding Process - * - * Decoding can be separated into the following steps: - * -# initialise theora_info and theora_comment structures using - * theora_info_init() and theora_comment_init(): - \verbatim - theora_info info; - theora_comment comment; - - theora_info_init(&info); - theora_comment_init(&comment); - \endverbatim - * -# retrieve header packets from Ogg stream (there should be 3) and decode - * into theora_info and theora_comment structures using - * theora_decode_header(). See \ref identification for more information on - * identifying which packets are theora packets. - \verbatim - int i; - for (i = 0; i < 3; i++) - { - (get a theora packet "op" from the Ogg stream) - theora_decode_header(&info, &comment, op); - } - \endverbatim - * -# initialise the decoder based on the information retrieved into the - * theora_info struct by theora_decode_header(). You will need a - * theora_state struct. - \verbatim - theora_state state; - - theora_decode_init(&state, &info); - \endverbatim - * -# pass in packets and retrieve decoded frames! See the yuv_buffer - * documentation for information on how to retrieve raw YUV data. - \verbatim - yuf_buffer buffer; - while (last packet was not e_o_s) { - (get a theora packet "op" from the Ogg stream) - theora_decode_packetin(&state, op); - theora_decode_YUVout(&state, &buffer); - } - \endverbatim - * - * - * \subsection identification Identifying Theora Packets - * - * All streams inside an Ogg file have a unique serial_no attached to the - * stream. Typically, you will want to - * - retrieve the serial_no for each b_o_s (beginning of stream) page - * encountered within the Ogg file; - * - test the first (only) packet on that page to determine if it is a theora - * packet; - * - once you have found a theora b_o_s page then use the retrieved serial_no - * to identify future packets belonging to the same theora stream. - * - * Note that you \e cannot use theora_packet_isheader() to determine if a - * packet is a theora packet or not, as this function does not perform any - * checking beyond whether a header bit is present. Instead, use the - * theora_decode_header() function and check the return value; or examine the - * header bytes at the beginning of the Ogg page. - */ - - -/** \defgroup oldfuncs Legacy pre-1.0 C API */ -/* @{ */ - -/** - * A YUV buffer for passing uncompressed frames to and from the codec. - * This holds a Y'CbCr frame in planar format. The CbCr planes can be - * subsampled and have their own separate dimensions and row stride - * offsets. Note that the strides may be negative in some - * configurations. For theora the width and height of the largest plane - * must be a multiple of 16. The actual meaningful picture size and - * offset are stored in the theora_info structure; frames returned by - * the decoder may need to be cropped for display. - * - * All samples are 8 bits. Within each plane samples are ordered by - * row from the top of the frame to the bottom. Within each row samples - * are ordered from left to right. - * - * During decode, the yuv_buffer struct is allocated by the user, but all - * fields (including luma and chroma pointers) are filled by the library. - * These pointers address library-internal memory and their contents should - * not be modified. - * - * Conversely, during encode the user allocates the struct and fills out all - * fields. The user also manages the data addressed by the luma and chroma - * pointers. See the encoder_example.c and dump_video.c example files in - * theora/examples/ for more information. - */ -typedef struct { - int y_width; /**< Width of the Y' luminance plane */ - int y_height; /**< Height of the luminance plane */ - int y_stride; /**< Offset in bytes between successive rows */ - - int uv_width; /**< Width of the Cb and Cr chroma planes */ - int uv_height; /**< Height of the chroma planes */ - int uv_stride; /**< Offset between successive chroma rows */ - unsigned char *y; /**< Pointer to start of luminance data */ - unsigned char *u; /**< Pointer to start of Cb data */ - unsigned char *v; /**< Pointer to start of Cr data */ - -} yuv_buffer; - -/** - * A Colorspace. - */ -typedef enum { - OC_CS_UNSPECIFIED, /**< The colorspace is unknown or unspecified */ - OC_CS_ITU_REC_470M, /**< This is the best option for 'NTSC' content */ - OC_CS_ITU_REC_470BG, /**< This is the best option for 'PAL' content */ - OC_CS_NSPACES /**< This marks the end of the defined colorspaces */ -} theora_colorspace; - -/** - * A Chroma subsampling - * - * These enumerate the available chroma subsampling options supported - * by the theora format. See Section 4.4 of the specification for - * exact definitions. - */ -typedef enum { - OC_PF_420, /**< Chroma subsampling by 2 in each direction (4:2:0) */ - OC_PF_RSVD, /**< Reserved value */ - OC_PF_422, /**< Horizonatal chroma subsampling by 2 (4:2:2) */ - OC_PF_444 /**< No chroma subsampling at all (4:4:4) */ -} theora_pixelformat; - -/** - * Theora bitstream info. - * Contains the basic playback parameters for a stream, - * corresponding to the initial 'info' header packet. - * - * Encoded theora frames must be a multiple of 16 in width and height. - * To handle other frame sizes, a crop rectangle is specified in - * frame_height and frame_width, offset_x and * offset_y. The offset - * and size should still be a multiple of 2 to avoid chroma sampling - * shifts. Offset values in this structure are measured from the - * upper left of the image. - * - * Frame rate, in frames per second, is stored as a rational - * fraction. Aspect ratio is also stored as a rational fraction, and - * refers to the aspect ratio of the frame pixels, not of the - * overall frame itself. - * - * See <a href="http://svn.xiph.org/trunk/theora/examples/encoder_example.c"> - * examples/encoder_example.c</a> for usage examples of the - * other paramters and good default settings for the encoder parameters. - */ -typedef struct { - ogg_uint32_t width; /**< encoded frame width */ - ogg_uint32_t height; /**< encoded frame height */ - ogg_uint32_t frame_width; /**< display frame width */ - ogg_uint32_t frame_height; /**< display frame height */ - ogg_uint32_t offset_x; /**< horizontal offset of the displayed frame */ - ogg_uint32_t offset_y; /**< vertical offset of the displayed frame */ - ogg_uint32_t fps_numerator; /**< frame rate numerator **/ - ogg_uint32_t fps_denominator; /**< frame rate denominator **/ - ogg_uint32_t aspect_numerator; /**< pixel aspect ratio numerator */ - ogg_uint32_t aspect_denominator; /**< pixel aspect ratio denominator */ - theora_colorspace colorspace; /**< colorspace */ - int target_bitrate; /**< nominal bitrate in bits per second */ - int quality; /**< Nominal quality setting, 0-63 */ - int quick_p; /**< Quick encode/decode */ - - /* decode only */ - unsigned char version_major; - unsigned char version_minor; - unsigned char version_subminor; - - void *codec_setup; - - /* encode only */ - int dropframes_p; - int keyframe_auto_p; - ogg_uint32_t keyframe_frequency; - ogg_uint32_t keyframe_frequency_force; /* also used for decode init to - get granpos shift correct */ - ogg_uint32_t keyframe_data_target_bitrate; - ogg_int32_t keyframe_auto_threshold; - ogg_uint32_t keyframe_mindistance; - ogg_int32_t noise_sensitivity; - ogg_int32_t sharpness; - - theora_pixelformat pixelformat; /**< chroma subsampling mode to expect */ - -} theora_info; - -/** Codec internal state and context. - */ -typedef struct{ - theora_info *i; - ogg_int64_t granulepos; - - void *internal_encode; - void *internal_decode; - -} theora_state; - -/** - * Comment header metadata. - * - * This structure holds the in-stream metadata corresponding to - * the 'comment' header packet. - * - * Meta data is stored as a series of (tag, value) pairs, in - * length-encoded string vectors. The first occurence of the - * '=' character delimits the tag and value. A particular tag - * may occur more than once. The character set encoding for - * the strings is always UTF-8, but the tag names are limited - * to case-insensitive ASCII. See the spec for details. - * - * In filling in this structure, theora_decode_header() will - * null-terminate the user_comment strings for safety. However, - * the bitstream format itself treats them as 8-bit clean, - * and so the length array should be treated as authoritative - * for their length. - */ -typedef struct theora_comment{ - char **user_comments; /**< An array of comment string vectors */ - int *comment_lengths; /**< An array of corresponding string vector lengths in bytes */ - int comments; /**< The total number of comment string vectors */ - char *vendor; /**< The vendor string identifying the encoder, null terminated */ - -} theora_comment; - - -/**\name theora_control() codes */ -/* \anchor decctlcodes_old - * These are the available request codes for theora_control() - * when called with a decoder instance. - * By convention decoder control codes are odd, to distinguish - * them from \ref encctlcodes_old "encoder control codes" which - * are even. - * - * Note that since the 1.0 release, both the legacy and the final - * implementation accept all the same control codes, but only the - * final API declares the newer codes. - * - * Keep any experimental or vendor-specific values above \c 0x8000.*/ - -/*@{*/ - -/**Get the maximum post-processing level. - * The decoder supports a post-processing filter that can improve - * the appearance of the decoded images. This returns the highest - * level setting for this post-processor, corresponding to maximum - * improvement and computational expense. - */ -#define TH_DECCTL_GET_PPLEVEL_MAX (1) - -/**Set the post-processing level. - * Sets the level of post-processing to use when decoding the - * compressed stream. This must be a value between zero (off) - * and the maximum returned by TH_DECCTL_GET_PPLEVEL_MAX. - */ -#define TH_DECCTL_SET_PPLEVEL (3) - -/**Sets the maximum distance between key frames. - * This can be changed during an encode, but will be bounded by - * <tt>1<<th_info#keyframe_granule_shift</tt>. - * If it is set before encoding begins, th_info#keyframe_granule_shift will - * be enlarged appropriately. - * - * \param[in] buf <tt>ogg_uint32_t</tt>: The maximum distance between key - * frames. - * \param[out] buf <tt>ogg_uint32_t</tt>: The actual maximum distance set. - * \retval OC_FAULT \a theora_state or \a buf is <tt>NULL</tt>. - * \retval OC_EINVAL \a buf_sz is not <tt>sizeof(ogg_uint32_t)</tt>. - * \retval OC_IMPL Not supported by this implementation.*/ -#define TH_ENCCTL_SET_KEYFRAME_FREQUENCY_FORCE (4) - -/**Set the granule position. - * Call this after a seek, to update the internal granulepos - * in the decoder, to insure that subsequent frames are marked - * properly. If you track timestamps yourself and do not use - * the granule postion returned by the decoder, then you do - * not need to use this control. - */ -#define TH_DECCTL_SET_GRANPOS (5) - -/**\anchor encctlcodes_old */ - -/**Sets the quantization parameters to use. - * The parameters are copied, not stored by reference, so they can be freed - * after this call. - * <tt>NULL</tt> may be specified to revert to the default parameters. - * - * \param[in] buf #th_quant_info - * \retval OC_FAULT \a theora_state is <tt>NULL</tt>. - * \retval OC_EINVAL Encoding has already begun, the quantization parameters - * are not acceptable to this version of the encoder, - * \a buf is <tt>NULL</tt> and \a buf_sz is not zero, - * or \a buf is non-<tt>NULL</tt> and \a buf_sz is - * not <tt>sizeof(#th_quant_info)</tt>. - * \retval OC_IMPL Not supported by this implementation.*/ -#define TH_ENCCTL_SET_QUANT_PARAMS (2) - -/**Disables any encoder features that would prevent lossless transcoding back - * to VP3. - * This primarily means disabling block-level QI values and not using 4MV mode - * when any of the luma blocks in a macro block are not coded. - * It also includes using the VP3 quantization tables and Huffman codes; if you - * set them explicitly after calling this function, the resulting stream will - * not be VP3-compatible. - * If you enable VP3-compatibility when encoding 4:2:2 or 4:4:4 source - * material, or when using a picture region smaller than the full frame (e.g. - * a non-multiple-of-16 width or height), then non-VP3 bitstream features will - * still be disabled, but the stream will still not be VP3-compatible, as VP3 - * was not capable of encoding such formats. - * If you call this after encoding has already begun, then the quantization - * tables and codebooks cannot be changed, but the frame-level features will - * be enabled or disabled as requested. - * - * \param[in] buf <tt>int</tt>: a non-zero value to enable VP3 compatibility, - * or 0 to disable it (the default). - * \param[out] buf <tt>int</tt>: 1 if all bitstream features required for - * VP3-compatibility could be set, and 0 otherwise. - * The latter will be returned if the pixel format is not - * 4:2:0, the picture region is smaller than the full frame, - * or if encoding has begun, preventing the quantization - * tables and codebooks from being set. - * \retval OC_FAULT \a theora_state or \a buf is <tt>NULL</tt>. - * \retval OC_EINVAL \a buf_sz is not <tt>sizeof(int)</tt>. - * \retval OC_IMPL Not supported by this implementation.*/ -#define TH_ENCCTL_SET_VP3_COMPATIBLE (10) - -/**Gets the maximum speed level. - * Higher speed levels favor quicker encoding over better quality per bit. - * Depending on the encoding mode, and the internal algorithms used, quality - * may actually improve, but in this case bitrate will also likely increase. - * In any case, overall rate/distortion performance will probably decrease. - * The maximum value, and the meaning of each value, may change depending on - * the current encoding mode (VBR vs. CQI, etc.). - * - * \param[out] buf int: The maximum encoding speed level. - * \retval OC_FAULT \a theora_state or \a buf is <tt>NULL</tt>. - * \retval OC_EINVAL \a buf_sz is not <tt>sizeof(int)</tt>. - * \retval OC_IMPL Not supported by this implementation in the current - * encoding mode.*/ -#define TH_ENCCTL_GET_SPLEVEL_MAX (12) - -/**Sets the speed level. - * By default a speed value of 1 is used. - * - * \param[in] buf int: The new encoding speed level. - * 0 is slowest, larger values use less CPU. - * \retval OC_FAULT \a theora_state or \a buf is <tt>NULL</tt>. - * \retval OC_EINVAL \a buf_sz is not <tt>sizeof(int)</tt>, or the - * encoding speed level is out of bounds. - * The maximum encoding speed level may be - * implementation- and encoding mode-specific, and can be - * obtained via #TH_ENCCTL_GET_SPLEVEL_MAX. - * \retval OC_IMPL Not supported by this implementation in the current - * encoding mode.*/ -#define TH_ENCCTL_SET_SPLEVEL (14) - -/*@}*/ - -#define OC_FAULT -1 /**< General failure */ -#define OC_EINVAL -10 /**< Library encountered invalid internal data */ -#define OC_DISABLED -11 /**< Requested action is disabled */ -#define OC_BADHEADER -20 /**< Header packet was corrupt/invalid */ -#define OC_NOTFORMAT -21 /**< Packet is not a theora packet */ -#define OC_VERSION -22 /**< Bitstream version is not handled */ -#define OC_IMPL -23 /**< Feature or action not implemented */ -#define OC_BADPACKET -24 /**< Packet is corrupt */ -#define OC_NEWPACKET -25 /**< Packet is an (ignorable) unhandled extension */ -#define OC_DUPFRAME 1 /**< Packet is a dropped frame */ - -/** - * Retrieve a human-readable string to identify the encoder vendor and version. - * \returns A version string. - */ -extern const char *theora_version_string(void); - -/** - * Retrieve a 32-bit version number. - * This number is composed of a 16-bit major version, 8-bit minor version - * and 8 bit sub-version, composed as follows: -<pre> - (VERSION_MAJOR<<16) + (VERSION_MINOR<<8) + (VERSION_SUB) -</pre> -* \returns The version number. -*/ -extern ogg_uint32_t theora_version_number(void); - -/** - * Initialize the theora encoder. - * \param th The theora_state handle to initialize for encoding. - * \param ti A theora_info struct filled with the desired encoding parameters. - * \retval 0 Success - */ -extern int theora_encode_init(theora_state *th, theora_info *ti); - -/** - * Submit a YUV buffer to the theora encoder. - * \param t A theora_state handle previously initialized for encoding. - * \param yuv A buffer of YUV data to encode. Note that both the yuv_buffer - * struct and the luma/chroma buffers within should be allocated by - * the user. - * \retval OC_EINVAL Encoder is not ready, or is finished. - * \retval -1 The size of the given frame differs from those previously input - * \retval 0 Success - */ -extern int theora_encode_YUVin(theora_state *t, yuv_buffer *yuv); - -/** - * Request the next packet of encoded video. - * The encoded data is placed in a user-provided ogg_packet structure. - * \param t A theora_state handle previously initialized for encoding. - * \param last_p whether this is the last packet the encoder should produce. - * \param op An ogg_packet structure to fill. libtheora will set all - * elements of this structure, including a pointer to encoded - * data. The memory for the encoded data is owned by libtheora. - * \retval 0 No internal storage exists OR no packet is ready - * \retval -1 The encoding process has completed - * \retval 1 Success - */ -extern int theora_encode_packetout( theora_state *t, int last_p, - ogg_packet *op); - -/** - * Request a packet containing the initial header. - * A pointer to the header data is placed in a user-provided ogg_packet - * structure. - * \param t A theora_state handle previously initialized for encoding. - * \param op An ogg_packet structure to fill. libtheora will set all - * elements of this structure, including a pointer to the header - * data. The memory for the header data is owned by libtheora. - * \retval 0 Success - */ -extern int theora_encode_header(theora_state *t, ogg_packet *op); - -/** - * Request a comment header packet from provided metadata. - * A pointer to the comment data is placed in a user-provided ogg_packet - * structure. - * \param tc A theora_comment structure filled with the desired metadata - * \param op An ogg_packet structure to fill. libtheora will set all - * elements of this structure, including a pointer to the encoded - * comment data. The memory for the comment data is owned by - * libtheora. - * \retval 0 Success - */ -extern int theora_encode_comment(theora_comment *tc, ogg_packet *op); - -/** - * Request a packet containing the codebook tables for the stream. - * A pointer to the codebook data is placed in a user-provided ogg_packet - * structure. - * \param t A theora_state handle previously initialized for encoding. - * \param op An ogg_packet structure to fill. libtheora will set all - * elements of this structure, including a pointer to the codebook - * data. The memory for the header data is owned by libtheora. - * \retval 0 Success - */ -extern int theora_encode_tables(theora_state *t, ogg_packet *op); - -/** - * Decode an Ogg packet, with the expectation that the packet contains - * an initial header, comment data or codebook tables. - * - * \param ci A theora_info structure to fill. This must have been previously - * initialized with theora_info_init(). If \a op contains an initial - * header, theora_decode_header() will fill \a ci with the - * parsed header values. If \a op contains codebook tables, - * theora_decode_header() will parse these and attach an internal - * representation to \a ci->codec_setup. - * \param cc A theora_comment structure to fill. If \a op contains comment - * data, theora_decode_header() will fill \a cc with the parsed - * comments. - * \param op An ogg_packet structure which you expect contains an initial - * header, comment data or codebook tables. - * - * \retval OC_BADHEADER \a op is NULL; OR the first byte of \a op->packet - * has the signature of an initial packet, but op is - * not a b_o_s packet; OR this packet has the signature - * of an initial header packet, but an initial header - * packet has already been seen; OR this packet has the - * signature of a comment packet, but the initial header - * has not yet been seen; OR this packet has the signature - * of a comment packet, but contains invalid data; OR - * this packet has the signature of codebook tables, - * but the initial header or comments have not yet - * been seen; OR this packet has the signature of codebook - * tables, but contains invalid data; - * OR the stream being decoded has a compatible version - * but this packet does not have the signature of a - * theora initial header, comments, or codebook packet - * \retval OC_VERSION The packet data of \a op is an initial header with - * a version which is incompatible with this version of - * libtheora. - * \retval OC_NEWPACKET the stream being decoded has an incompatible (future) - * version and contains an unknown signature. - * \retval 0 Success - * - * \note The normal usage is that theora_decode_header() be called on the - * first three packets of a theora logical bitstream in succession. - */ -extern int theora_decode_header(theora_info *ci, theora_comment *cc, - ogg_packet *op); - -/** - * Initialize a theora_state handle for decoding. - * \param th The theora_state handle to initialize. - * \param c A theora_info struct filled with the desired decoding parameters. - * This is of course usually obtained from a previous call to - * theora_decode_header(). - * \retval 0 Success - */ -extern int theora_decode_init(theora_state *th, theora_info *c); - -/** - * Input a packet containing encoded data into the theora decoder. - * \param th A theora_state handle previously initialized for decoding. - * \param op An ogg_packet containing encoded theora data. - * \retval 0 Success - * \retval OC_BADPACKET \a op does not contain encoded video data - */ -extern int theora_decode_packetin(theora_state *th,ogg_packet *op); - -/** - * Output the next available frame of decoded YUV data. - * \param th A theora_state handle previously initialized for decoding. - * \param yuv A yuv_buffer in which libtheora should place the decoded data. - * Note that the buffer struct itself is allocated by the user, but - * that the luma and chroma pointers will be filled in by the - * library. Also note that these luma and chroma regions should be - * considered read-only by the user. - * \retval 0 Success - */ -extern int theora_decode_YUVout(theora_state *th,yuv_buffer *yuv); - -/** - * Report whether a theora packet is a header or not - * This function does no verification beyond checking the header - * flag bit so it should not be used for bitstream identification; - * use theora_decode_header() for that. - * - * \param op An ogg_packet containing encoded theora data. - * \retval 1 The packet is a header packet - * \retval 0 The packet is not a header packet (and so contains frame data) - * - * Thus function was added in the 1.0alpha4 release. - */ -extern int theora_packet_isheader(ogg_packet *op); - -/** - * Report whether a theora packet is a keyframe or not - * - * \param op An ogg_packet containing encoded theora data. - * \retval 1 The packet contains a keyframe image - * \retval 0 The packet is contains an interframe delta - * \retval -1 The packet is not an image data packet at all - * - * Thus function was added in the 1.0alpha4 release. - */ -extern int theora_packet_iskeyframe(ogg_packet *op); - -/** - * Report the granulepos shift radix - * - * When embedded in Ogg, Theora uses a two-part granulepos, - * splitting the 64-bit field into two pieces. The more-significant - * section represents the frame count at the last keyframe, - * and the less-significant section represents the count of - * frames since the last keyframe. In this way the overall - * field is still non-decreasing with time, but usefully encodes - * a pointer to the last keyframe, which is necessary for - * correctly restarting decode after a seek. - * - * This function reports the number of bits used to represent - * the distance to the last keyframe, and thus how the granulepos - * field must be shifted or masked to obtain the two parts. - * - * Since libtheora returns compressed data in an ogg_packet - * structure, this may be generally useful even if the Theora - * packets are not being used in an Ogg container. - * - * \param ti A previously initialized theora_info struct - * \returns The bit shift dividing the two granulepos fields - * - * This function was added in the 1.0alpha5 release. - */ -int theora_granule_shift(theora_info *ti); - -/** - * Convert a granulepos to an absolute frame index, starting at 0. - * The granulepos is interpreted in the context of a given theora_state handle. - * - * Note that while the granulepos encodes the frame count (i.e. starting - * from 1) this call returns the frame index, starting from zero. Thus - * One can calculate the presentation time by multiplying the index by - * the rate. - * - * \param th A previously initialized theora_state handle (encode or decode) - * \param granulepos The granulepos to convert. - * \returns The frame index corresponding to \a granulepos. - * \retval -1 The given granulepos is undefined (i.e. negative) - * - * Thus function was added in the 1.0alpha4 release. - */ -extern ogg_int64_t theora_granule_frame(theora_state *th,ogg_int64_t granulepos); - -/** - * Convert a granulepos to absolute time in seconds. The granulepos is - * interpreted in the context of a given theora_state handle, and gives - * the end time of a frame's presentation as used in Ogg mux ordering. - * - * \param th A previously initialized theora_state handle (encode or decode) - * \param granulepos The granulepos to convert. - * \returns The absolute time in seconds corresponding to \a granulepos. - * This is the "end time" for the frame, or the latest time it should - * be displayed. - * It is not the presentation time. - * \retval -1. The given granulepos is undefined (i.e. negative), or - * \retval -1. The function has been disabled because floating - * point support is not available. - */ -extern double theora_granule_time(theora_state *th,ogg_int64_t granulepos); - -/** - * Initialize a theora_info structure. All values within the given theora_info - * structure are initialized, and space is allocated within libtheora for - * internal codec setup data. - * \param c A theora_info struct to initialize. - */ -extern void theora_info_init(theora_info *c); - -/** - * Clear a theora_info structure. All values within the given theora_info - * structure are cleared, and associated internal codec setup data is freed. - * \param c A theora_info struct to initialize. - */ -extern void theora_info_clear(theora_info *c); - -/** - * Free all internal data associated with a theora_state handle. - * \param t A theora_state handle. - */ -extern void theora_clear(theora_state *t); - -/** - * Initialize an allocated theora_comment structure - * \param tc An allocated theora_comment structure - **/ -extern void theora_comment_init(theora_comment *tc); - -/** - * Add a comment to an initialized theora_comment structure - * \param tc A previously initialized theora comment structure - * \param comment A null-terminated string encoding the comment in the form - * "TAG=the value" - * - * Neither theora_comment_add() nor theora_comment_add_tag() support - * comments containing null values, although the bitstream format - * supports this. To add such comments you will need to manipulate - * the theora_comment structure directly. - **/ - -extern void theora_comment_add(theora_comment *tc, char *comment); - -/** - * Add a comment to an initialized theora_comment structure. - * \param tc A previously initialized theora comment structure - * \param tag A null-terminated string containing the tag - * associated with the comment. - * \param value The corresponding value as a null-terminated string - * - * Neither theora_comment_add() nor theora_comment_add_tag() support - * comments containing null values, although the bitstream format - * supports this. To add such comments you will need to manipulate - * the theora_comment structure directly. - **/ -extern void theora_comment_add_tag(theora_comment *tc, - char *tag, char *value); - -/** - * Look up a comment value by tag. - * \param tc Tn initialized theora_comment structure - * \param tag The tag to look up - * \param count The instance of the tag. The same tag can appear multiple - * times, each with a distinct and ordered value, so an index - * is required to retrieve them all. - * \returns A pointer to the queried tag's value - * \retval NULL No matching tag is found - * - * \note Use theora_comment_query_count() to get the legal range for the - * count parameter. - **/ - -extern char *theora_comment_query(theora_comment *tc, char *tag, int count); - -/** Look up the number of instances of a tag. - * \param tc An initialized theora_comment structure - * \param tag The tag to look up - * \returns The number on instances of a particular tag. - * - * Call this first when querying for a specific tag and then interate - * over the number of instances with separate calls to - * theora_comment_query() to retrieve all instances in order. - **/ -extern int theora_comment_query_count(theora_comment *tc, char *tag); - -/** - * Clear an allocated theora_comment struct so that it can be freed. - * \param tc An allocated theora_comment structure. - **/ -extern void theora_comment_clear(theora_comment *tc); - -/**Encoder control function. - * This is used to provide advanced control the encoding process. - * \param th A #theora_state handle. - * \param req The control code to process. - * See \ref encctlcodes_old "the list of available - * control codes" for details. - * \param buf The parameters for this control code. - * \param buf_sz The size of the parameter buffer.*/ -extern int theora_control(theora_state *th,int req,void *buf,size_t buf_sz); - -/* @} */ /* end oldfuncs doxygen group */ - -#ifdef __cplusplus -} -#endif /* __cplusplus */ - -#endif /* _O_THEORA_H_ */ |
