1 /********************************************************************
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. *
8 * THE Theora SOURCE CODE IS COPYRIGHT (C) 2002-2003 *
9 * by the Xiph.Org Foundation http://www.xiph.org/ *
11 ********************************************************************
14 last mod: $Id: theora.h 16826 2010-01-27 04:16:24Z xiphmont $
16 ********************************************************************/
18 #include <ext/libogg/ogg.h>
24 OC_CS_UNSPECIFIED, /**< the colorspace is unknown or unspecified */
25 OC_CS_ITU_REC_470M, /**< best option for 'NTSC' content */
26 OC_CS_ITU_REC_470BG, /**< best option for 'PAL' content */
27 OC_CS_NSPACES /* mark the end of the defined colorspaces */
31 * A Chroma subsampling
33 * These enumerate the available chroma subsampling options supported
34 * by the theora format. See Section 4.4 of the specification for
38 OC_PF_420, /**< Chroma subsampling by 2 in each direction (4:2:0) */
39 OC_PF_RSVD, /**< reserved value */
40 OC_PF_422, /**< Horizonatal chroma subsampling by 2 (4:2:2) */
41 OC_PF_444, /**< No chroma subsampling at all (4:4:4) */
45 * Theora bitstream info.
46 * Contains the basic playback parameters for a stream,
47 * corresponds to the initial 'info' header packet.
49 * Encoded theora frames must be a multiple of 16 is size;
50 * this is what the width and height members represent. To
51 * handle other sizes, a crop rectangle is specified in
52 * frame_height and frame_width, offset_x and offset_y. The
53 * offset and size should still be a power of 2 to avoid
54 * chroma sampling shifts.
56 * Frame rate, in frames per second is stored as a rational
57 * fraction. So is the aspect ratio. Note that this refers
58 * to the aspect ratio of the frame pixels, not of the
59 * overall frame itself.
61 * see the example code for use of the other parameters and
62 * good default settings for the encoder parameters.
67 ogg_uint32_t frame_width;
68 ogg_uint32_t frame_height;
69 ogg_uint32_t offset_x;
70 ogg_uint32_t offset_y;
71 ogg_uint32_t fps_numerator;
72 ogg_uint32_t fps_denominator;
73 ogg_uint32_t aspect_numerator;
74 ogg_uint32_t aspect_denominator;
75 theora_colorspace colorspace;
77 int quality; /**< nominal quality setting, 0-63 */
78 int quick_p; /**< quick encode/decode */
81 unsigned char version_major;
82 unsigned char version_minor;
83 unsigned char version_subminor;
92 ogg_uint32_t keyframe_frequency;
93 ogg_uint32_t keyframe_data_target_bitrate;
94 ogg_int32_t keyframe_auto_threshold;
95 ogg_uint32_t keyframe_mindistance;
96 ogg_int32_t noise_sensitivity;
97 ogg_int32_t sharpness;
99 theora_pixelformat pixelformat;
104 * Comment header metadata.
106 * This structure holds the in-stream metadata corresponding to
107 * the 'comment' header packet.
109 * Meta data is stored as a series of (tag, value) pairs, in
110 * length-encoded string vectors. The first occurence of the
111 * '=' character delimits the tag and value. A particular tag
112 * may occur more than once. The character set encoding for
113 * the strings is always utf-8, but the tag names are limited
114 * to case-insensitive ascii. See the spec for details.
116 * In filling in this structure, theora_decode_header() will
117 * null-terminate the user_comment strings for safety. However,
118 * the bitstream format itself treats them as 8-bit clean,
119 * and so the length array should be treated as authoritative
122 typedef struct theora_comment{
123 char **user_comments; /**< an array of comment string vectors */
124 int *comment_lengths; /**< an array of corresponding string vector lengths in bytes */
125 int comments; /**< the total number of comment string vectors */
126 char *vendor; /**< the vendor string identifying the encoder, null terminated */
130 #define OC_FAULT -1 /**< general failure */
131 #define OC_EINVAL -10 /**< library encountered invalid internal data */
132 #define OC_DISABLED -11 /**< requested action is disabled */
133 #define OC_BADHEADER -20 /**< header packet was corrupt/invalid */
134 #define OC_NOTFORMAT -21 /**< packet is not a theora packet */
135 #define OC_VERSION -22 /**< bitstream version is not handled */
136 #define OC_IMPL -23 /**< feature or action not implemented */
137 #define OC_BADPACKET -24 /**< packet is corrupt */
138 #define OC_NEWPACKET -25 /**< packet is an (ignorable) unhandled extension */
141 * Decode an Ogg packet, with the expectation that the packet contains
142 * an initial header, comment data or codebook tables.
144 * \param ci A theora_info structure to fill. This must have been previously
145 * initialized with theora_info_init(). If \a op contains an initial
146 * header, theora_decode_header() will fill \a ci with the
147 * parsed header values. If \a op contains codebook tables,
148 * theora_decode_header() will parse these and attach an internal
149 * representation to \a ci->codec_setup.
150 * \param cc A theora_comment structure to fill. If \a op contains comment
151 * data, theora_decode_header() will fill \a cc with the parsed
153 * \param op An ogg_packet structure which you expect contains an initial
154 * header, comment data or codebook tables.
156 * \retval OC_BADHEADER \a op is NULL; OR the first byte of \a op->packet
157 * has the signature of an initial packet, but op is
158 * not a b_o_s packet; OR this packet has the signature
159 * of an initial header packet, but an initial header
160 * packet has already been seen; OR this packet has the
161 * signature of a comment packet, but the initial header
162 * has not yet been seen; OR this packet has the signature
163 * of a comment packet, but contains invalid data; OR
164 * this packet has the signature of codebook tables,
165 * but the initial header or comments have not yet
166 * been seen; OR this packet has the signature of codebook
167 * tables, but contains invalid data;
168 * OR the stream being decoded has a compatible version
169 * but this packet does not have the signature of a
170 * theora initial header, comments, or codebook packet
171 * \retval OC_VERSION The packet data of \a op is an initial header with
172 * a version which is incompatible with this version of
174 * \retval OC_NEWPACKET the stream being decoded has an incompatible (future)
175 * version and contains an unknown signature.
178 * \note The normal usage is that theora_decode_header() be called on the
179 * first three packets of a theora logical bitstream in succession.
181 extern int theora_decode_header(theora_info *ci, theora_comment *cc,
184 void theora_info_clear(theora_info *c);
185 void theora_comment_clear(theora_comment *tc);