libtheora  1.1.1
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 
62 #if !defined(_O_THEORA_CODEC_H_)
63 # define _O_THEORA_CODEC_H_ (1)
64 # include <ogg/ogg.h>
65 
66 #if defined(__cplusplus)
67 extern "C" {
68 #endif
69 
70 
71 
75 #define TH_EFAULT (-1)
77 #define TH_EINVAL (-10)
79 #define TH_EBADHEADER (-20)
81 #define TH_ENOTFORMAT (-21)
83 #define TH_EVERSION (-22)
85 #define TH_EIMPL (-23)
87 #define TH_EBADPACKET (-24)
91 #define TH_DUPFRAME (1)
98 typedef enum{
109 
114 typedef enum{
131 
132 
133 
142 typedef struct{
144  int width;
146  int height;
148  int stride;
150  unsigned char *data;
151 }th_img_plane;
152 
169 
204 typedef struct{
208  unsigned char version_major;
209  unsigned char version_minor;
210  unsigned char version_subminor;
214  ogg_uint32_t frame_width;
217  ogg_uint32_t frame_height;
220  ogg_uint32_t pic_width;
223  ogg_uint32_t pic_height;
227  ogg_uint32_t pic_x;
235  ogg_uint32_t pic_y;
240  ogg_uint32_t fps_numerator;
241  ogg_uint32_t fps_denominator;
252  ogg_uint32_t aspect_numerator;
253  ogg_uint32_t aspect_denominator;
268  /*Currently this is set so that a qi of 0 corresponds to distortions of 24
269  times the JND, and each increase by 16 halves that value.
270  This gives us fine discrimination at low qualities, yet effective rate
271  control at high qualities.
272  The qi value 63 is special, however.
273  For this, the highest quality, we use one half of a JND for our threshold.
274  Due to the lower bounds placed on allowable quantizers in Theora, we will
275  not actually be able to achieve quality this good, but this should
276  provide as close to visually lossless quality as Theora is capable of.
277  We could lift the quantizer restrictions without breaking VP3.1
278  compatibility, but this would result in quantized coefficients that are
279  too large for the current bitstream to be able to store.
280  We'd have to redesign the token syntax to store these large coefficients,
281  which would make transcoding complex.*/
282  int quality;
297 }th_info;
298 
323 typedef struct th_comment{
329  int comments;
332  char *vendor;
334 
335 
336 
338 typedef unsigned char th_quant_base[64];
339 
341 typedef struct{
343  int nranges;
346  const int *sizes;
351 
409 typedef struct{
411  ogg_uint16_t dc_scale[64];
413  ogg_uint16_t ac_scale[64];
415  unsigned char loop_filter_limits[64];
417  th_quant_ranges qi_ranges[2][3];
419 
420 
421 
423 #define TH_NHUFFMAN_TABLES (80)
425 #define TH_NDCT_TOKENS (32)
426 
438 typedef struct{
441  ogg_uint32_t pattern;
444  int nbits;
445 }th_huff_code;
446 
447 
448 
456 extern const char *th_version_string(void);
466 extern ogg_uint32_t th_version_number(void);
476 extern ogg_int64_t th_granule_frame(void *_encdec,ogg_int64_t _granpos);
488 extern double th_granule_time(void *_encdec,ogg_int64_t _granpos);
498 extern int th_packet_isheader(ogg_packet *_op);
509 extern int th_packet_iskeyframe(ogg_packet *_op);
519 extern void th_info_init(th_info *_info);
524 extern void th_info_clear(th_info *_info);
525 
530 extern void th_comment_init(th_comment *_tc);
540 extern void th_comment_add(th_comment *_tc, char *_comment);
551 extern void th_comment_add_tag(th_comment *_tc,char *_tag,char *_val);
567 extern char *th_comment_query(th_comment *_tc,char *_tag,int _count);
575 extern int th_comment_query_count(th_comment *_tc,char *_tag);
581 extern void th_comment_clear(th_comment *_tc);
584 
585 
586 
587 #if defined(__cplusplus)
588 }
589 #endif
590 
591 #endif
int th_packet_isheader(ogg_packet *_op)
Determines whether a Theora packet is a header or not.
const char * th_version_string(void)
Retrieves a human-readable string to identify the library vendor and version.
void th_comment_add(th_comment *_tc, char *_comment)
Add a comment to an initialized th_comment structure.
char * th_comment_query(th_comment *_tc, char *_tag, int _count)
Look up a comment value by its tag.
th_img_plane th_ycbcr_buffer[3]
A complete image buffer for an uncompressed frame.
Definition: codec.h:168
void th_info_init(th_info *_info)
Initializes a th_info structure.
th_colorspace
The currently defined color space tags.
Definition: codec.h:98
@ TH_CS_ITU_REC_470BG
A color space designed for PAL/SECAM content.
Definition: codec.h:105
@ TH_CS_NSPACES
The total number of currently defined color spaces.
Definition: codec.h:107
@ TH_CS_ITU_REC_470M
A color space designed for NTSC content.
Definition: codec.h:103
@ TH_CS_UNSPECIFIED
The color space was not specified at the encoder.
Definition: codec.h:101
th_pixel_fmt
The currently defined pixel format tags.
Definition: codec.h:114
@ TH_PF_422
Chroma decimation by 2 in the X direction (4:2:2).
Definition: codec.h:124
@ TH_PF_444
No chroma decimation (4:4:4).
Definition: codec.h:127
@ TH_PF_NFORMATS
The total number of currently defined pixel formats.
Definition: codec.h:129
@ TH_PF_RSVD
Currently reserved.
Definition: codec.h:120
@ TH_PF_420
Chroma decimation by 2 in both the X and Y directions (4:2:0).
Definition: codec.h:118
unsigned char th_quant_base[64]
A single base matrix.
Definition: codec.h:338
void th_comment_add_tag(th_comment *_tc, char *_tag, char *_val)
Add a comment to an initialized th_comment structure.
void th_comment_init(th_comment *_tc)
Initialize a th_comment structure.
double th_granule_time(void *_encdec, ogg_int64_t _granpos)
Converts a granule position to an absolute time in seconds.
int th_comment_query_count(th_comment *_tc, char *_tag)
Look up the number of instances of a tag.
ogg_int64_t th_granule_frame(void *_encdec, ogg_int64_t _granpos)
Converts a granule position to an absolute frame index, starting at 0.
struct th_comment th_comment
The comment information.
void th_info_clear(th_info *_info)
Clears a th_info structure.
ogg_uint32_t th_version_number(void)
Retrieves the library version number.
void th_comment_clear(th_comment *_tc)
Clears a th_comment structure.
int th_packet_iskeyframe(ogg_packet *_op)
Determines whether a theora packet is a key frame or not.
The comment information.
Definition: codec.h:323
int comments
The total number of comment strings.
Definition: codec.h:329
int * comment_lengths
An array of the corresponding length of each vector, in bytes.
Definition: codec.h:327
char * vendor
The null-terminated vendor string.
Definition: codec.h:332
char ** user_comments
The array of comment string vectors.
Definition: codec.h:325
A Huffman code for a Theora DCT token.
Definition: codec.h:438
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:441
int nbits
The number of bits in the code.
Definition: codec.h:444
A buffer for a single color plane in an uncompressed image.
Definition: codec.h:142
int height
The height of this plane.
Definition: codec.h:146
int width
The width of this plane.
Definition: codec.h:144
int stride
The offset in bytes between successive rows.
Definition: codec.h:148
unsigned char * data
A pointer to the beginning of the first row.
Definition: codec.h:150
Theora bitstream information.
Definition: codec.h:204
ogg_uint32_t aspect_denominator
Definition: codec.h:253
int target_bitrate
The target bit-rate in bits per second.
Definition: codec.h:262
ogg_uint32_t fps_numerator
Definition: codec.h:240
th_pixel_fmt pixel_fmt
The pixel format.
Definition: codec.h:258
ogg_uint32_t pic_width
The displayed picture width.
Definition: codec.h:220
ogg_uint32_t pic_x
The X offset of the displayed picture.
Definition: codec.h:227
ogg_uint32_t aspect_numerator
Definition: codec.h:252
unsigned char version_major
Definition: codec.h:208
int keyframe_granule_shift
The amount to shift to extract the last keyframe number from the granule position.
Definition: codec.h:296
ogg_uint32_t frame_height
The encoded frame height.
Definition: codec.h:217
ogg_uint32_t frame_width
The encoded frame width.
Definition: codec.h:214
ogg_uint32_t pic_height
The displayed picture height.
Definition: codec.h:223
ogg_uint32_t pic_y
The Y offset of the displayed picture.
Definition: codec.h:235
th_colorspace colorspace
The color space.
Definition: codec.h:256
int quality
The target quality level.
Definition: codec.h:282
ogg_uint32_t fps_denominator
Definition: codec.h:241
unsigned char version_minor
Definition: codec.h:209
unsigned char version_subminor
Definition: codec.h:210
A complete set of quantization parameters.
Definition: codec.h:409
A set of qi ranges.
Definition: codec.h:341
const th_quant_base * base_matrices
nranges +1 base matrices.
Definition: codec.h:349
int nranges
The number of ranges in the set.
Definition: codec.h:343
const int * sizes
The size of each of the nranges ranges.
Definition: codec.h:346