libtheora  1.2.0alpha1+git
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 http://www.xiph.org/ *
10  * *
11  ********************************************************************
12 
13  function:
14  last mod: $Id: theora.h,v 1.8 2004/03/15 22:17:32 derf Exp $
15 
16  ********************************************************************/
17 
65 #if !defined(_O_THEORA_CODEC_H_)
66 # define _O_THEORA_CODEC_H_ (1)
67 # include <ogg/ogg.h>
68 
69 #if defined(__cplusplus)
70 extern "C" {
71 #endif
72 
73 
74 
78 #define TH_EFAULT (-1)
79 
80 #define TH_EINVAL (-10)
81 
82 #define TH_EBADHEADER (-20)
83 
84 #define TH_ENOTFORMAT (-21)
85 
86 #define TH_EVERSION (-22)
87 
88 #define TH_EIMPL (-23)
89 
90 #define TH_EBADPACKET (-24)
91 
94 #define TH_DUPFRAME (1)
95 
101 typedef enum{
112 
117 typedef enum{
133 }th_pixel_fmt;
134 
135 
136 
145 typedef struct{
147  int width;
149  int height;
151  int stride;
153  unsigned char *data;
154 }th_img_plane;
155 
172 
207 typedef struct{
211  unsigned char version_major;
212  unsigned char version_minor;
213  unsigned char version_subminor;
217  ogg_uint32_t frame_width;
220  ogg_uint32_t frame_height;
223  ogg_uint32_t pic_width;
226  ogg_uint32_t pic_height;
230  ogg_uint32_t pic_x;
238  ogg_uint32_t pic_y;
243  ogg_uint32_t fps_numerator;
244  ogg_uint32_t fps_denominator;
255  ogg_uint32_t aspect_numerator;
256  ogg_uint32_t aspect_denominator;
271  /*Currently this is set so that a qi of 0 corresponds to distortions of 24
272  times the JND, and each increase by 16 halves that value.
273  This gives us fine discrimination at low qualities, yet effective rate
274  control at high qualities.
275  The qi value 63 is special, however.
276  For this, the highest quality, we use one half of a JND for our threshold.
277  Due to the lower bounds placed on allowable quantizers in Theora, we will
278  not actually be able to achieve quality this good, but this should
279  provide as close to visually lossless quality as Theora is capable of.
280  We could lift the quantizer restrictions without breaking VP3.1
281  compatibility, but this would result in quantized coefficients that are
282  too large for the current bitstream to be able to store.
283  We'd have to redesign the token syntax to store these large coefficients,
284  which would make transcoding complex.*/
285  int quality;
300 }th_info;
301 
326 typedef struct th_comment{
332  int comments;
335  char *vendor;
336 }th_comment;
337 
338 
339 
341 typedef unsigned char th_quant_base[64];
342 
344 typedef struct{
346  int nranges;
349  const int *sizes;
354 
412 typedef struct{
414  ogg_uint16_t dc_scale[64];
416  ogg_uint16_t ac_scale[64];
418  unsigned char loop_filter_limits[64];
420  th_quant_ranges qi_ranges[2][3];
422 
423 
424 
426 #define TH_NHUFFMAN_TABLES (80)
427 
428 #define TH_NDCT_TOKENS (32)
429 
441 typedef struct{
444  ogg_uint32_t pattern;
447  int nbits;
448 }th_huff_code;
449 
450 
451 
465 extern const char *th_version_string(void);
475 extern ogg_uint32_t th_version_number(void);
485 extern ogg_int64_t th_granule_frame(void *_encdec,ogg_int64_t _granpos);
497 extern double th_granule_time(void *_encdec,ogg_int64_t _granpos);
507 extern int th_packet_isheader(ogg_packet *_op);
518 extern int th_packet_iskeyframe(ogg_packet *_op);
533 extern void th_info_init(th_info *_info);
538 extern void th_info_clear(th_info *_info);
539 
544 extern void th_comment_init(th_comment *_tc);
554 extern void th_comment_add(th_comment *_tc,const char *_comment);
565 extern void th_comment_add_tag(th_comment *_tc,const char *_tag,
566  const char *_val);
582 extern char *th_comment_query(th_comment *_tc,const char *_tag,int _count);
590 extern int th_comment_query_count(th_comment *_tc,const char *_tag);
596 extern void th_comment_clear(th_comment *_tc);
599 
600 
601 
602 #if defined(__cplusplus)
603 }
604 #endif
605 
606 #endif
TH_PF_420
@ TH_PF_420
Chroma decimation by 2 in both the X and Y directions (4:2:0).
Definition: codec.h:121
th_img_plane::stride
int stride
The offset in bytes between successive rows.
Definition: codec.h:151
th_info::pic_y
ogg_uint32_t pic_y
The Y offset of the displayed picture.
Definition: codec.h:238
th_comment::user_comments
char ** user_comments
The array of comment string vectors.
Definition: codec.h:328
th_quant_ranges::base_matrices
const th_quant_base * base_matrices
nranges +1 base matrices.
Definition: codec.h:352
th_info
Theora bitstream information.
Definition: codec.h:207
TH_CS_ITU_REC_470M
@ TH_CS_ITU_REC_470M
A color space designed for NTSC content.
Definition: codec.h:106
th_comment_query
char * th_comment_query(th_comment *_tc, const char *_tag, int _count)
Look up a comment value by its tag.
TH_PF_RSVD
@ TH_PF_RSVD
Currently reserved.
Definition: codec.h:123
th_info::fps_numerator
ogg_uint32_t fps_numerator
Definition: codec.h:243
th_info_clear
void th_info_clear(th_info *_info)
Clears a th_info structure.
th_comment_add_tag
void th_comment_add_tag(th_comment *_tc, const char *_tag, const char *_val)
Add a comment to an initialized th_comment structure.
th_colorspace
th_colorspace
The currently defined color space tags.
Definition: codec.h:101
TH_PF_NFORMATS
@ TH_PF_NFORMATS
The total number of currently defined pixel formats.
Definition: codec.h:132
th_img_plane::width
int width
The width of this plane.
Definition: codec.h:147
TH_PF_444
@ TH_PF_444
No chroma decimation (4:4:4).
Definition: codec.h:130
th_info::fps_denominator
ogg_uint32_t fps_denominator
Definition: codec.h:244
th_comment::comment_lengths
int * comment_lengths
An array of the corresponding length of each vector, in bytes.
Definition: codec.h:330
th_quant_ranges::nranges
int nranges
The number of ranges in the set.
Definition: codec.h:346
th_ycbcr_buffer
th_img_plane th_ycbcr_buffer[3]
A complete image buffer for an uncompressed frame.
Definition: codec.h:171
th_info::frame_height
ogg_uint32_t frame_height
The encoded frame height.
Definition: codec.h:220
TH_CS_UNSPECIFIED
@ TH_CS_UNSPECIFIED
The color space was not specified at the encoder.
Definition: codec.h:104
th_info::aspect_denominator
ogg_uint32_t aspect_denominator
Definition: codec.h:256
TH_CS_ITU_REC_470BG
@ TH_CS_ITU_REC_470BG
A color space designed for PAL/SECAM content.
Definition: codec.h:108
th_info::version_minor
unsigned char version_minor
Definition: codec.h:212
th_comment_query_count
int th_comment_query_count(th_comment *_tc, const char *_tag)
Look up the number of instances of a tag.
th_info::colorspace
th_colorspace colorspace
The color space.
Definition: codec.h:259
th_img_plane::data
unsigned char * data
A pointer to the beginning of the first row.
Definition: codec.h:153
th_granule_frame
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_PF_422
@ TH_PF_422
Chroma decimation by 2 in the X direction (4:2:2).
Definition: codec.h:127
th_quant_info
A complete set of quantization parameters.
Definition: codec.h:412
th_pixel_fmt
th_pixel_fmt
The currently defined pixel format tags.
Definition: codec.h:117
th_info::pic_width
ogg_uint32_t pic_width
The displayed picture width.
Definition: codec.h:223
th_info::pic_height
ogg_uint32_t pic_height
The displayed picture height.
Definition: codec.h:226
th_huff_code::nbits
int nbits
The number of bits in the code.
Definition: codec.h:447
th_info::version_major
unsigned char version_major
Definition: codec.h:211
th_comment
The comment information.
Definition: codec.h:326
th_version_number
ogg_uint32_t th_version_number(void)
Retrieves the library version number.
th_info::target_bitrate
int target_bitrate
The target bit-rate in bits per second.
Definition: codec.h:265
th_quant_ranges::sizes
const int * sizes
The size of each of the nranges ranges.
Definition: codec.h:349
th_quant_ranges
A set of qi ranges.
Definition: codec.h:344
th_info::pic_x
ogg_uint32_t pic_x
The X offset of the displayed picture.
Definition: codec.h:230
th_quant_base
unsigned char th_quant_base[64]
A single base matrix.
Definition: codec.h:341
th_img_plane
A buffer for a single color plane in an uncompressed image.
Definition: codec.h:145
th_info::frame_width
ogg_uint32_t frame_width
The encoded frame width.
Definition: codec.h:217
th_comment::vendor
char * vendor
The null-terminated vendor string.
Definition: codec.h:335
th_packet_isheader
int th_packet_isheader(ogg_packet *_op)
Determines whether a Theora packet is a header or not.
th_version_string
const char * th_version_string(void)
Retrieves a human-readable string to identify the library vendor and version.
th_info::aspect_numerator
ogg_uint32_t aspect_numerator
Definition: codec.h:255
th_comment
struct th_comment th_comment
The comment information.
TH_CS_NSPACES
@ TH_CS_NSPACES
The total number of currently defined color spaces.
Definition: codec.h:110
th_packet_iskeyframe
int th_packet_iskeyframe(ogg_packet *_op)
Determines whether a theora packet is a key frame or not.
th_huff_code::pattern
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:444
th_info::quality
int quality
The target quality level.
Definition: codec.h:285
th_img_plane::height
int height
The height of this plane.
Definition: codec.h:149
th_info::pixel_fmt
th_pixel_fmt pixel_fmt
The pixel format.
Definition: codec.h:261
th_info_init
void th_info_init(th_info *_info)
Initializes a th_info structure.
th_info::keyframe_granule_shift
int keyframe_granule_shift
The amount to shift to extract the last keyframe number from the granule position.
Definition: codec.h:299
th_comment_add
void th_comment_add(th_comment *_tc, const char *_comment)
Add a comment to an initialized th_comment structure.
th_info::version_subminor
unsigned char version_subminor
Definition: codec.h:213
th_huff_code
A Huffman code for a Theora DCT token.
Definition: codec.h:441
th_comment_clear
void th_comment_clear(th_comment *_tc)
Clears a th_comment structure.
th_comment::comments
int comments
The total number of comment strings.
Definition: codec.h:332
th_comment_init
void th_comment_init(th_comment *_tc)
Initialize a th_comment structure.
th_granule_time
double th_granule_time(void *_encdec, ogg_int64_t _granpos)
Converts a granule position to an absolute time in seconds.