libtheora  1.2.0
codec.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 
64 #if !defined(OGG_THEORA_CODEC_HEADER)
65 # define OGG_THEORA_CODEC_HEADER (1)
66 # include <ogg/ogg.h>
67 
68 #if defined(__cplusplus)
69 extern "C" {
70 #endif
71 
72 
73 
77 #define TH_EFAULT (-1)
78 
79 #define TH_EINVAL (-10)
80 
81 #define TH_EBADHEADER (-20)
82 
83 #define TH_ENOTFORMAT (-21)
84 
85 #define TH_EVERSION (-22)
86 
87 #define TH_EIMPL (-23)
88 
89 #define TH_EBADPACKET (-24)
90 
93 #define TH_DUPFRAME (1)
94 
100 typedef enum{
111 
116 typedef enum{
132 }th_pixel_fmt;
133 
134 
135 
144 typedef struct{
146  int width;
148  int height;
150  int stride;
152  unsigned char *data;
153 }th_img_plane;
154 
171 
206 typedef struct{
210  unsigned char version_major;
211  unsigned char version_minor;
212  unsigned char version_subminor;
216  ogg_uint32_t frame_width;
219  ogg_uint32_t frame_height;
222  ogg_uint32_t pic_width;
225  ogg_uint32_t pic_height;
229  ogg_uint32_t pic_x;
237  ogg_uint32_t pic_y;
242  ogg_uint32_t fps_numerator;
243  ogg_uint32_t fps_denominator;
254  ogg_uint32_t aspect_numerator;
255  ogg_uint32_t aspect_denominator;
270  /*Currently this is set so that a qi of 0 corresponds to distortions of 24
271  times the JND, and each increase by 16 halves that value.
272  This gives us fine discrimination at low qualities, yet effective rate
273  control at high qualities.
274  The qi value 63 is special, however.
275  For this, the highest quality, we use one half of a JND for our threshold.
276  Due to the lower bounds placed on allowable quantizers in Theora, we will
277  not actually be able to achieve quality this good, but this should
278  provide as close to visually lossless quality as Theora is capable of.
279  We could lift the quantizer restrictions without breaking VP3.1
280  compatibility, but this would result in quantized coefficients that are
281  too large for the current bitstream to be able to store.
282  We'd have to redesign the token syntax to store these large coefficients,
283  which would make transcoding complex.*/
284  int quality;
299 }th_info;
300 
325 typedef struct th_comment{
331  int comments;
334  char *vendor;
335 }th_comment;
336 
337 
338 
340 typedef unsigned char th_quant_base[64];
341 
343 typedef struct{
345  int nranges;
348  const int *sizes;
351  const th_quant_base *base_matrices;
353 
411 typedef struct{
413  ogg_uint16_t dc_scale[64];
415  ogg_uint16_t ac_scale[64];
417  unsigned char loop_filter_limits[64];
419  th_quant_ranges qi_ranges[2][3];
421 
422 
423 
425 #define TH_NHUFFMAN_TABLES (80)
426 
427 #define TH_NDCT_TOKENS (32)
428 
440 typedef struct{
443  ogg_uint32_t pattern;
446  int nbits;
447 }th_huff_code;
448 
449 
450 
464 extern const char *th_version_string(void);
474 extern ogg_uint32_t th_version_number(void);
484 extern ogg_int64_t th_granule_frame(void *_encdec,ogg_int64_t _granpos);
496 extern double th_granule_time(void *_encdec,ogg_int64_t _granpos);
506 extern int th_packet_isheader(ogg_packet *_op);
517 extern int th_packet_iskeyframe(ogg_packet *_op);
532 extern void th_info_init(th_info *_info);
537 extern void th_info_clear(th_info *_info);
538 
543 extern void th_comment_init(th_comment *_tc);
553 extern void th_comment_add(th_comment *_tc,const char *_comment);
564 extern void th_comment_add_tag(th_comment *_tc,const char *_tag,
565  const char *_val);
581 extern char *th_comment_query(th_comment *_tc,const char *_tag,int _count);
589 extern int th_comment_query_count(th_comment *_tc,const char *_tag);
595 extern void th_comment_clear(th_comment *_tc);
598 
599 
600 
601 #if defined(__cplusplus)
602 }
603 #endif
604 
605 #endif /* OGG_THEORA_CODEC_HEADER */
No chroma decimation (4:4:4).
Definition: codec.h:129
Chroma decimation by 2 in both the X and Y directions (4:2:0).
Definition: codec.h:120
ogg_uint32_t pic_y
The Y offset of the displayed picture.
Definition: codec.h:237
A complete set of quantization parameters.
Definition: codec.h:411
Theora bitstream information.
Definition: codec.h:206
ogg_uint32_t fps_numerator
Definition: codec.h:242
const th_quant_base * base_matrices
nranges +1 base matrices.
Definition: codec.h:351
ogg_uint32_t frame_width
The encoded frame width.
Definition: codec.h:216
A Huffman code for a Theora DCT token.
Definition: codec.h:440
int nbits
The number of bits in the code.
Definition: codec.h:446
The comment information.
Definition: codec.h:325
int th_packet_iskeyframe(ogg_packet *_op)
Determines whether a theora packet is a key frame or not.
char ** user_comments
The array of comment string vectors.
Definition: codec.h:327
int target_bitrate
The target bit-rate in bits per second.
Definition: codec.h:264
unsigned char version_minor
Definition: codec.h:211
int quality
The target quality level.
Definition: codec.h:284
ogg_int64_t th_granule_frame(void *_encdec, ogg_int64_t _granpos)
Converts a granule position to an absolute frame index, starting at 0.
th_pixel_fmt pixel_fmt
The pixel format.
Definition: codec.h:260
int comments
The total number of comment strings.
Definition: codec.h:331
ogg_uint32_t aspect_denominator
Definition: codec.h:255
ogg_uint32_t th_version_number(void)
Retrieves the library version number.
int nranges
The number of ranges in the set.
Definition: codec.h:345
unsigned char version_subminor
Definition: codec.h:212
int th_packet_isheader(ogg_packet *_op)
Determines whether a Theora packet is a header or not.
int * comment_lengths
An array of the corresponding length of each vector, in bytes.
Definition: codec.h:329
The total number of currently defined pixel formats.
Definition: codec.h:131
ogg_uint32_t pic_x
The X offset of the displayed picture.
Definition: codec.h:229
void th_comment_add(th_comment *_tc, const char *_comment)
Add a comment to an initialized th_comment structure.
th_colorspace colorspace
The color space.
Definition: codec.h:258
The color space was not specified at the encoder.
Definition: codec.h:103
ogg_uint32_t frame_height
The encoded frame height.
Definition: codec.h:219
A set of qi ranges.
Definition: codec.h:343
void th_info_clear(th_info *_info)
Clears a th_info structure.
ogg_uint32_t pattern
The bit pattern for the code, with the LSbit of the pattern aligned in the LSbit of the word...
Definition: codec.h:443
const char * th_version_string(void)
Retrieves a human-readable string to identify the library vendor and version.
unsigned char * data
A pointer to the beginning of the first row.
Definition: codec.h:152
void th_comment_add_tag(th_comment *_tc, const char *_tag, const char *_val)
Add a comment to an initialized th_comment structure.
Chroma decimation by 2 in the X direction (4:2:2).
Definition: codec.h:126
th_img_plane th_ycbcr_buffer[3]
A complete image buffer for an uncompressed frame.
Definition: codec.h:170
void th_info_init(th_info *_info)
Initializes a th_info structure.
void th_comment_init(th_comment *_tc)
Initialize a th_comment structure.
th_pixel_fmt
The currently defined pixel format tags.
Definition: codec.h:116
ogg_uint32_t pic_width
The displayed picture width.
Definition: codec.h:222
ogg_uint32_t fps_denominator
Definition: codec.h:243
ogg_uint32_t pic_height
The displayed picture height.
Definition: codec.h:225
A buffer for a single color plane in an uncompressed image.
Definition: codec.h:144
void th_comment_clear(th_comment *_tc)
Clears a th_comment structure.
char * th_comment_query(th_comment *_tc, const char *_tag, int _count)
Look up a comment value by its tag.
int height
The height of this plane.
Definition: codec.h:148
unsigned char th_quant_base[64]
A single base matrix.
Definition: codec.h:340
The total number of currently defined color spaces.
Definition: codec.h:109
int width
The width of this plane.
Definition: codec.h:146
const int * sizes
The size of each of the nranges ranges.
Definition: codec.h:348
int th_comment_query_count(th_comment *_tc, const char *_tag)
Look up the number of instances of a tag.
int stride
The offset in bytes between successive rows.
Definition: codec.h:150
ogg_uint32_t aspect_numerator
Definition: codec.h:254
struct th_comment th_comment
The comment information.
th_colorspace
The currently defined color space tags.
Definition: codec.h:100
A color space designed for PAL/SECAM content.
Definition: codec.h:107
double th_granule_time(void *_encdec, ogg_int64_t _granpos)
Converts a granule position to an absolute time in seconds.
Currently reserved.
Definition: codec.h:122
char * vendor
The null-terminated vendor string.
Definition: codec.h:334
unsigned char version_major
Definition: codec.h:210
A color space designed for NTSC content.
Definition: codec.h:105
int keyframe_granule_shift
The amount to shift to extract the last keyframe number from the granule position.
Definition: codec.h:298