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
21 extern "C"
22 {
23 #endif /* __cplusplus */
24 
25 #include <stddef.h> /* for size_t */
26 
27 #include <ogg/ogg.h>
28 
120 /* @{ */
121 
146 typedef struct {
147  int y_width;
148  int y_height;
149  int y_stride;
151  int uv_width;
152  int uv_height;
153  int uv_stride;
154  unsigned char *y;
155  unsigned char *u;
156  unsigned char *v;
158 } yuv_buffer;
159 
163 typedef enum {
169 
177 typedef enum {
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;
218  int quality;
219  int quick_p;
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 */
231  ogg_uint32_t keyframe_frequency;
232  ogg_uint32_t keyframe_frequency_force; /* also used for decode init to
233  get granpos shift correct */
236  ogg_uint32_t keyframe_mindistance;
237  ogg_int32_t noise_sensitivity;
238  ogg_int32_t sharpness;
239 
242 } theora_info;
243 
246 typedef struct{
248  ogg_int64_t granulepos;
249 
252 
253 } theora_state;
254 
274 typedef struct theora_comment{
275  char **user_comments;
277  int comments;
278  char *vendor;
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 
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 
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 
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
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 
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 
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 
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 
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 */
int theora_packet_iskeyframe(ogg_packet *op)
Report whether a theora packet is a keyframe or not.
int theora_control(theora_state *th, int req, void *buf, size_t buf_sz)
Encoder control function.
ogg_uint32_t fps_numerator
frame rate numerator
Definition: theora.h:212
int quality
Nominal quality setting, 0-63.
Definition: theora.h:218
void theora_comment_add_tag(theora_comment *tc, char *tag, char *value)
Add a comment to an initialized theora_comment structure.
double theora_granule_time(theora_state *th, ogg_int64_t granulepos)
Convert a granulepos to absolute time in seconds.
The colorspace is unknown or unspecified.
Definition: theora.h:164
int theora_encode_YUVin(theora_state *t, yuv_buffer *yuv)
Submit a YUV buffer to the theora encoder.
void theora_clear(theora_state *t)
Free all internal data associated with a theora_state handle.
Comment header metadata.
Definition: theora.h:274
int theora_encode_header(theora_state *t, ogg_packet *op)
Request a packet containing the initial header.
char * theora_comment_query(theora_comment *tc, char *tag, int count)
Look up a comment value by tag.
void theora_comment_clear(theora_comment *tc)
Clear an allocated theora_comment struct so that it can be freed.
theora_colorspace colorspace
colorspace
Definition: theora.h:216
theora_info * i
Definition: theora.h:247
void * internal_decode
Definition: theora.h:251
Codec internal state and context.
Definition: theora.h:246
unsigned char * y
Pointer to start of luminance data.
Definition: theora.h:154
int uv_width
Width of the Cb and Cr chroma planes.
Definition: theora.h:151
int quick_p
Quick encode/decode.
Definition: theora.h:219
ogg_int64_t theora_granule_frame(theora_state *th, ogg_int64_t granulepos)
Convert a granulepos to an absolute frame index, starting at 0.
void * internal_encode
Definition: theora.h:250
ogg_uint32_t fps_denominator
frame rate denominator
Definition: theora.h:213
This is the best option for 'NTSC' content.
Definition: theora.h:165
int theora_decode_YUVout(theora_state *th, yuv_buffer *yuv)
Output the next available frame of decoded YUV data.
unsigned char * u
Pointer to start of Cb data.
Definition: theora.h:155
ogg_int32_t noise_sensitivity
Definition: theora.h:237
ogg_uint32_t width
encoded frame width
Definition: theora.h:206
Chroma subsampling by 2 in each direction (4:2:0)
Definition: theora.h:178
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, comment data or codebook tables.
ogg_uint32_t frame_height
display frame height
Definition: theora.h:209
char ** user_comments
An array of comment string vectors.
Definition: theora.h:275
int theora_packet_isheader(ogg_packet *op)
Report whether a theora packet is a header or not This function does no verification beyond checking ...
ogg_uint32_t aspect_denominator
pixel aspect ratio denominator
Definition: theora.h:215
ogg_uint32_t aspect_numerator
pixel aspect ratio numerator
Definition: theora.h:214
void theora_comment_add(theora_comment *tc, char *comment)
Add a comment to an initialized theora_comment structure.
int theora_encode_packetout(theora_state *t, int last_p, ogg_packet *op)
Request the next packet of encoded video.
Theora bitstream info.
Definition: theora.h:205
theora_colorspace
A Colorspace.
Definition: theora.h:163
ogg_uint32_t frame_width
display frame width
Definition: theora.h:208
int uv_height
Height of the chroma planes.
Definition: theora.h:152
int keyframe_auto_p
Definition: theora.h:230
int theora_encode_init(theora_state *th, theora_info *ti)
Initialize the theora encoder.
int comments
The total number of comment string vectors.
Definition: theora.h:277
int theora_decode_init(theora_state *th, theora_info *c)
Initialize a theora_state handle for decoding.
ogg_uint32_t offset_y
vertical offset of the displayed frame
Definition: theora.h:211
theora_pixelformat
A Chroma subsampling.
Definition: theora.h:177
ogg_int32_t keyframe_auto_threshold
Definition: theora.h:235
No chroma subsampling at all (4:4:4)
Definition: theora.h:181
int theora_decode_packetin(theora_state *th, ogg_packet *op)
Input a packet containing encoded data into the theora decoder.
Reserved value.
Definition: theora.h:179
char * vendor
The vendor string identifying the encoder, null terminated.
Definition: theora.h:278
unsigned char * v
Pointer to start of Cr data.
Definition: theora.h:156
int y_height
Height of the luminance plane.
Definition: theora.h:148
int target_bitrate
nominal bitrate in bits per second
Definition: theora.h:217
int dropframes_p
Definition: theora.h:229
int theora_comment_query_count(theora_comment *tc, char *tag)
Look up the number of instances of a tag.
ogg_int64_t granulepos
Definition: theora.h:248
int * comment_lengths
An array of corresponding string vector lengths in bytes.
Definition: theora.h:276
ogg_int32_t sharpness
Definition: theora.h:238
int y_width
Width of the Y' luminance plane.
Definition: theora.h:147
void theora_info_clear(theora_info *c)
Clear a theora_info structure.
void theora_info_init(theora_info *c)
Initialize a theora_info structure.
unsigned char version_subminor
Definition: theora.h:224
int uv_stride
Offset between successive chroma rows.
Definition: theora.h:153
unsigned char version_major
Definition: theora.h:222
struct theora_comment theora_comment
Comment header metadata.
void * codec_setup
Definition: theora.h:226
int theora_granule_shift(theora_info *ti)
Report the granulepos shift radix.
ogg_uint32_t theora_version_number(void)
Retrieve a 32-bit version number.
void theora_comment_init(theora_comment *tc)
Initialize an allocated theora_comment structure.
ogg_uint32_t keyframe_data_target_bitrate
Definition: theora.h:234
ogg_uint32_t offset_x
horizontal offset of the displayed frame
Definition: theora.h:210
ogg_uint32_t keyframe_mindistance
Definition: theora.h:236
int theora_encode_comment(theora_comment *tc, ogg_packet *op)
Request a comment header packet from provided metadata.
This marks the end of the defined colorspaces.
Definition: theora.h:167
ogg_uint32_t keyframe_frequency_force
Definition: theora.h:232
int theora_encode_tables(theora_state *t, ogg_packet *op)
Request a packet containing the codebook tables for the stream.
ogg_uint32_t height
encoded frame height
Definition: theora.h:207
theora_pixelformat pixelformat
chroma subsampling mode to expect
Definition: theora.h:240
unsigned char version_minor
Definition: theora.h:223
This is the best option for 'PAL' content.
Definition: theora.h:166
Horizonatal chroma subsampling by 2 (4:2:2)
Definition: theora.h:180
int y_stride
Offset in bytes between successive rows.
Definition: theora.h:149
ogg_uint32_t keyframe_frequency
Definition: theora.h:231
A YUV buffer for passing uncompressed frames to and from the codec.
Definition: theora.h:146