libtheora: theora.h Source File

libtheora 1.2.0

theora.h
Go to the documentation of this file.
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 https://www.xiph.org/ *
10 * *
11 ********************************************************************
12
13 function:
14
15 ********************************************************************/
16
17#ifndef OGG_THEORA_HEADER
18#define OGG_THEORA_HEADER
19
20#ifdef __cplusplus
21extern "C"
22{
23#endif /* __cplusplus */
24
25#include <stddef.h> /* for size_t */
26
27#include <ogg/ogg.h>
28
117
118
120/* @{ */
121
146 typedef struct {
147 int y_width;
148 int y_height;
149 int y_stride;
150
151 int uv_width;
152 int uv_height;
153 int uv_stride;
154 unsigned char *y;
155 unsigned char *u;
156 unsigned char *v;
157
158} yuv_buffer;
159
163 typedef enum {
164 OC_CS_UNSPECIFIED,
165 OC_CS_ITU_REC_470M,
166 OC_CS_ITU_REC_470BG,
167 OC_CS_NSPACES
168} theora_colorspace;
169
177 typedef enum {
178 OC_PF_420,
179 OC_PF_RSVD,
180 OC_PF_422,
181 OC_PF_444
182} theora_pixelformat;
183
205 typedef struct {
206 ogg_uint32_t width;
207 ogg_uint32_t height;
208 ogg_uint32_t frame_width;
209 ogg_uint32_t frame_height;
210 ogg_uint32_t offset_x;
211 ogg_uint32_t offset_y;
212 ogg_uint32_t fps_numerator;
213 ogg_uint32_t fps_denominator;
214 ogg_uint32_t aspect_numerator;
215 ogg_uint32_t aspect_denominator;
216 theora_colorspace colorspace;
217 int target_bitrate;
218 int quality;
219 int quick_p;
220
221 /* decode only */
222 unsigned char version_major;
223 unsigned char version_minor;
224 unsigned char version_subminor;
225
226 void *codec_setup;
227
228 /* encode only */
229 int dropframes_p;
230 int keyframe_auto_p;
231 ogg_uint32_t keyframe_frequency;
232 ogg_uint32_t keyframe_frequency_force; /* also used for decode init to
233 get granpos shift correct */
234 ogg_uint32_t keyframe_data_target_bitrate;
235 ogg_int32_t keyframe_auto_threshold;
236 ogg_uint32_t keyframe_mindistance;
237 ogg_int32_t noise_sensitivity;
238 ogg_int32_t sharpness;
239
240 theora_pixelformat pixelformat;
241
242} theora_info;
243
246 typedef struct{
247 theora_info *i;
248 ogg_int64_t granulepos;
249
250 void *internal_encode;
251 void *internal_decode;
252
253} theora_state;
254
274 typedef struct theora_comment{
275 char **user_comments;
276 int *comment_lengths;
277 int comments;
278 char *vendor;
279
280} theora_comment;
281
282
284/* \anchor decctlcodes_old
285 * These are the available request codes for theora_control()
286 * when called with a decoder instance.
287 * By convention decoder control codes are odd, to distinguish
288 * them from \ref encctlcodes_old "encoder control codes" which
289 * are even.
290 *
291 * Note that since the 1.0 release, both the legacy and the final
292 * implementation accept all the same control codes, but only the
293 * final API declares the newer codes.
294 *
295 * Keep any experimental or vendor-specific values above \c 0x8000.*/
296
298
305#define TH_DECCTL_GET_PPLEVEL_MAX (1)
306
312#define TH_DECCTL_SET_PPLEVEL (3)
313
326#define TH_ENCCTL_SET_KEYFRAME_FREQUENCY_FORCE (4)
327
335#define TH_DECCTL_SET_GRANPOS (5)
336
338
352#define TH_ENCCTL_SET_QUANT_PARAMS (2)
353
381#define TH_ENCCTL_SET_VP3_COMPATIBLE (10)
382
396#define TH_ENCCTL_GET_SPLEVEL_MAX (12)
397
411#define TH_ENCCTL_SET_SPLEVEL (14)
412
414
415#define OC_FAULT -1
416#define OC_EINVAL -10
417#define OC_DISABLED -11
418#define OC_BADHEADER -20
419#define OC_NOTFORMAT -21
420#define OC_VERSION -22
421#define OC_IMPL -23
422#define OC_BADPACKET -24
423#define OC_NEWPACKET -25
424#define OC_DUPFRAME 1
425
430 extern const char *theora_version_string(void);
431
441 extern ogg_uint32_t theora_version_number(void);
442
449 extern int theora_encode_init(theora_state *th, theora_info *ti);
450
461 extern int theora_encode_YUVin(theora_state *t, yuv_buffer *yuv);
462
475 extern int theora_encode_packetout( theora_state *t, int last_p,
476 ogg_packet *op);
477
488 extern int theora_encode_header(theora_state *t, ogg_packet *op);
489
505 extern int theora_encode_comment(theora_comment *tc, ogg_packet *op);
506
517 extern int theora_encode_tables(theora_state *t, ogg_packet *op);
518
560 extern int theora_decode_header(theora_info *ci, theora_comment *cc,
561 ogg_packet *op);
562
571 extern int theora_decode_init(theora_state *th, theora_info *c);
572
580 extern int theora_decode_packetin(theora_state *th,ogg_packet *op);
581
592 extern int theora_decode_YUVout(theora_state *th,yuv_buffer *yuv);
593
606 extern int theora_packet_isheader(ogg_packet *op);
607
618 extern int theora_packet_iskeyframe(ogg_packet *op);
619
645 int theora_granule_shift(theora_info *ti);
646
663 extern ogg_int64_t theora_granule_frame(theora_state *th,ogg_int64_t granulepos);
664
678 extern double theora_granule_time(theora_state *th,ogg_int64_t granulepos);
679
686 extern void theora_info_init(theora_info *c);
687
693 extern void theora_info_clear(theora_info *c);
694
699 extern void theora_clear(theora_state *t);
700
705 extern void theora_comment_init(theora_comment *tc);
706
718
719 extern void theora_comment_add(theora_comment *tc, char *comment);
720
733 extern void theora_comment_add_tag(theora_comment *tc,
734 char *tag, char *value);
735
749
750 extern char *theora_comment_query(theora_comment *tc, char *tag, int count);
751
761 extern int theora_comment_query_count(theora_comment *tc, char *tag);
762
767 extern void theora_comment_clear(theora_comment *tc);
768
777 extern int theora_control(theora_state *th,int req,void *buf,size_t buf_sz);
778
779/* @} */ /* end oldfuncs doxygen group */
780
781#ifdef __cplusplus
782}
783#endif /* __cplusplus */
784
785#endif /* OGG_THEORA_HEADER */
theora_comment
Comment header metadata.
Definition theora.h:274
theora_comment::comments
int comments
The total number of comment string vectors.
Definition theora.h:277
theora_comment::user_comments
char ** user_comments
An array of comment string vectors.
Definition theora.h:275
theora_comment::comment_lengths
int * comment_lengths
An array of corresponding string vector lengths in bytes.
Definition theora.h:276
theora_comment::vendor
char * vendor
The vendor string identifying the encoder, null terminated.
Definition theora.h:278
theora_info
Theora bitstream info.
Definition theora.h:205
theora_info::keyframe_frequency
ogg_uint32_t keyframe_frequency
Definition theora.h:231
theora_info::target_bitrate
int target_bitrate
nominal bitrate in bits per second
Definition theora.h:217
theora_info::width
ogg_uint32_t width
encoded frame width
Definition theora.h:206
theora_info::keyframe_auto_p
int keyframe_auto_p
Definition theora.h:230
theora_info::frame_height
ogg_uint32_t frame_height
display frame height
Definition theora.h:209
theora_info::quick_p
int quick_p
Quick encode/decode.
Definition theora.h:219
theora_info::fps_numerator
ogg_uint32_t fps_numerator
frame rate numerator
Definition theora.h:212
theora_info::sharpness
ogg_int32_t sharpness
Definition theora.h:238
theora_info::keyframe_data_target_bitrate
ogg_uint32_t keyframe_data_target_bitrate
Definition theora.h:234
theora_info::aspect_numerator
ogg_uint32_t aspect_numerator
pixel aspect ratio numerator
Definition theora.h:214
theora_info::colorspace
theora_colorspace colorspace
colorspace
Definition theora.h:216
theora_info::pixelformat
theora_pixelformat pixelformat
chroma subsampling mode to expect
Definition theora.h:240
theora_info::codec_setup
void * codec_setup
Definition theora.h:226
theora_info::quality
int quality
Nominal quality setting, 0-63.
Definition theora.h:218
theora_info::version_minor
unsigned char version_minor
Definition theora.h:223
theora_info::version_major
unsigned char version_major
Definition theora.h:222
theora_info::frame_width
ogg_uint32_t frame_width
display frame width
Definition theora.h:208
theora_info::offset_y
ogg_uint32_t offset_y
vertical offset of the displayed frame
Definition theora.h:211
theora_info::keyframe_auto_threshold
ogg_int32_t keyframe_auto_threshold
Definition theora.h:235
theora_info::fps_denominator
ogg_uint32_t fps_denominator
frame rate denominator
Definition theora.h:213
theora_info::version_subminor
unsigned char version_subminor
Definition theora.h:224
theora_info::keyframe_mindistance
ogg_uint32_t keyframe_mindistance
Definition theora.h:236
theora_info::noise_sensitivity
ogg_int32_t noise_sensitivity
Definition theora.h:237
theora_info::keyframe_frequency_force
ogg_uint32_t keyframe_frequency_force
Definition theora.h:232
theora_info::height
ogg_uint32_t height
encoded frame height
Definition theora.h:207
theora_info::dropframes_p
int dropframes_p
Definition theora.h:229
theora_info::offset_x
ogg_uint32_t offset_x
horizontal offset of the displayed frame
Definition theora.h:210
theora_info::aspect_denominator
ogg_uint32_t aspect_denominator
pixel aspect ratio denominator
Definition theora.h:215
theora_state
Codec internal state and context.
Definition theora.h:246
theora_state::i
theora_info * i
Definition theora.h:247
theora_state::internal_encode
void * internal_encode
Definition theora.h:250
theora_state::granulepos
ogg_int64_t granulepos
Definition theora.h:248
theora_state::internal_decode
void * internal_decode
Definition theora.h:251
yuv_buffer
A YUV buffer for passing uncompressed frames to and from the codec.
Definition theora.h:146
yuv_buffer::y_height
int y_height
Height of the luminance plane.
Definition theora.h:148
yuv_buffer::uv_height
int uv_height
Height of the chroma planes.
Definition theora.h:152
yuv_buffer::y
unsigned char * y
Pointer to start of luminance data.
Definition theora.h:154
yuv_buffer::u
unsigned char * u
Pointer to start of Cb data.
Definition theora.h:155
yuv_buffer::uv_width
int uv_width
Width of the Cb and Cr chroma planes.
Definition theora.h:151
yuv_buffer::y_stride
int y_stride
Offset in bytes between successive rows.
Definition theora.h:149
yuv_buffer::v
unsigned char * v
Pointer to start of Cr data.
Definition theora.h:156
yuv_buffer::y_width
int y_width
Width of the Y' luminance plane.
Definition theora.h:147
yuv_buffer::uv_stride
int uv_stride
Offset between successive chroma rows.
Definition theora.h:153
theora_decode_header
int theora_decode_header(theora_info *ci, theora_comment *cc, ogg_packet *op)
Decode an Ogg packet, with the expectation that the packet contains an initial header,...
theora_comment_clear
void theora_comment_clear(theora_comment *tc)
Clear an allocated theora_comment struct so that it can be freed.
theora_decode_YUVout
int theora_decode_YUVout(theora_state *th, yuv_buffer *yuv)
Output the next available frame of decoded YUV data.
theora_encode_init
int theora_encode_init(theora_state *th, theora_info *ti)
Initialize the theora encoder.
theora_comment_query_count
int theora_comment_query_count(theora_comment *tc, char *tag)
Look up the number of instances of a tag.
theora_control
int theora_control(theora_state *th, int req, void *buf, size_t buf_sz)
Encoder control function.
theora_decode_init
int theora_decode_init(theora_state *th, theora_info *c)
Initialize a theora_state handle for decoding.
theora_info_init
void theora_info_init(theora_info *c)
Initialize a theora_info structure.
theora_comment_add_tag
void theora_comment_add_tag(theora_comment *tc, char *tag, char *value)
Add a comment to an initialized theora_comment structure.
theora_packet_iskeyframe
int theora_packet_iskeyframe(ogg_packet *op)
Report whether a theora packet is a keyframe or not.
theora_granule_time
double theora_granule_time(theora_state *th, ogg_int64_t granulepos)
Convert a granulepos to absolute time in seconds.
theora_encode_header
int theora_encode_header(theora_state *t, ogg_packet *op)
Request a packet containing the initial header.
theora_encode_comment
int theora_encode_comment(theora_comment *tc, ogg_packet *op)
Request a comment header packet from provided metadata.
theora_encode_tables
int theora_encode_tables(theora_state *t, ogg_packet *op)
Request a packet containing the codebook tables for the stream.
theora_encode_packetout
int theora_encode_packetout(theora_state *t, int last_p, ogg_packet *op)
Request the next packet of encoded video.
theora_comment_add
void theora_comment_add(theora_comment *tc, char *comment)
Add a comment to an initialized theora_comment structure.
theora_granule_frame
ogg_int64_t theora_granule_frame(theora_state *th, ogg_int64_t granulepos)
Convert a granulepos to an absolute frame index, starting at 0.
theora_comment_init
void theora_comment_init(theora_comment *tc)
Initialize an allocated theora_comment structure.
theora_colorspace
theora_colorspace
A Colorspace.
Definition theora.h:163
OC_CS_ITU_REC_470BG
@ OC_CS_ITU_REC_470BG
This is the best option for 'PAL' content.
Definition theora.h:166
OC_CS_NSPACES
@ OC_CS_NSPACES
This marks the end of the defined colorspaces.
Definition theora.h:167
OC_CS_ITU_REC_470M
@ OC_CS_ITU_REC_470M
This is the best option for 'NTSC' content.
Definition theora.h:165
OC_CS_UNSPECIFIED
@ OC_CS_UNSPECIFIED
The colorspace is unknown or unspecified.
Definition theora.h:164
theora_decode_packetin
int theora_decode_packetin(theora_state *th, ogg_packet *op)
Input a packet containing encoded data into the theora decoder.
theora_clear
void theora_clear(theora_state *t)
Free all internal data associated with a theora_state handle.
theora_packet_isheader
int theora_packet_isheader(ogg_packet *op)
Report whether a theora packet is a header or not This function does no verification beyond checking ...
theora_info_clear
void theora_info_clear(theora_info *c)
Clear a theora_info structure.
theora_encode_YUVin
int theora_encode_YUVin(theora_state *t, yuv_buffer *yuv)
Submit a YUV buffer to the theora encoder.
theora_version_string
const char * theora_version_string(void)
Retrieve a human-readable string to identify the encoder vendor and version.
theora_comment_query
char * theora_comment_query(theora_comment *tc, char *tag, int count)
Look up a comment value by tag.
theora_granule_shift
int theora_granule_shift(theora_info *ti)
Report the granulepos shift radix.
theora_version_number
ogg_uint32_t theora_version_number(void)
Retrieve a 32-bit version number.
theora_pixelformat
theora_pixelformat
A Chroma subsampling.
Definition theora.h:177
OC_PF_444
@ OC_PF_444
No chroma subsampling at all (4:4:4)
Definition theora.h:181
OC_PF_422
@ OC_PF_422
Horizonatal chroma subsampling by 2 (4:2:2)
Definition theora.h:180
OC_PF_420
@ OC_PF_420
Chroma subsampling by 2 in each direction (4:2:0)
Definition theora.h:178
OC_PF_RSVD
@ OC_PF_RSVD
Reserved value.
Definition theora.h:179