libtheora: codec.h Source File

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
59
63
64#if !defined(OGG_THEORA_CODEC_HEADER)
65# define OGG_THEORA_CODEC_HEADER (1)
66# include <ogg/ogg.h>
67
68#if defined(__cplusplus)
69extern "C" {
70#endif
71
72
73
77#define TH_EFAULT (-1)
79#define TH_EINVAL (-10)
81#define TH_EBADHEADER (-20)
83#define TH_ENOTFORMAT (-21)
85#define TH_EVERSION (-22)
87#define TH_EIMPL (-23)
89#define TH_EBADPACKET (-24)
93#define TH_DUPFRAME (1)
95
100 typedef enum{
103 TH_CS_UNSPECIFIED,
105 TH_CS_ITU_REC_470M,
107 TH_CS_ITU_REC_470BG,
109 TH_CS_NSPACES
110}th_colorspace;
111
116 typedef enum{
120 TH_PF_420,
122 TH_PF_RSVD,
126 TH_PF_422,
129 TH_PF_444,
131 TH_PF_NFORMATS
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
170 typedef th_img_plane th_ycbcr_buffer[3];
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;
258 th_colorspace colorspace;
260 th_pixel_fmt pixel_fmt;
264 int target_bitrate;
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;
298 int keyframe_granule_shift;
299}th_info;
300
325 typedef struct th_comment{
327 char **user_comments;
329 int *comment_lengths;
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;
352}th_quant_ranges;
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];
420}th_quant_info;
421
422
423
425#define TH_NHUFFMAN_TABLES (80)
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);
519
520
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 */
th_packet_isheader
int th_packet_isheader(ogg_packet *_op)
Determines whether a Theora packet is a header or not.
th_ycbcr_buffer
th_img_plane th_ycbcr_buffer[3]
A complete image buffer for an uncompressed frame.
Definition codec.h:170
th_info_init
void th_info_init(th_info *_info)
Initializes a th_info structure.
th_colorspace
th_colorspace
The currently defined color space tags.
Definition codec.h:100
TH_CS_ITU_REC_470BG
@ TH_CS_ITU_REC_470BG
A color space designed for PAL/SECAM content.
Definition codec.h:107
TH_CS_NSPACES
@ TH_CS_NSPACES
The total number of currently defined color spaces.
Definition codec.h:109
TH_CS_ITU_REC_470M
@ TH_CS_ITU_REC_470M
A color space designed for NTSC content.
Definition codec.h:105
TH_CS_UNSPECIFIED
@ TH_CS_UNSPECIFIED
The color space was not specified at the encoder.
Definition codec.h:103
th_version_string
const char * th_version_string(void)
Retrieves a human-readable string to identify the library vendor and version.
th_pixel_fmt
th_pixel_fmt
The currently defined pixel format tags.
Definition codec.h:116
TH_PF_422
@ TH_PF_422
Chroma decimation by 2 in the X direction (4:2:2).
Definition codec.h:126
TH_PF_444
@ TH_PF_444
No chroma decimation (4:4:4).
Definition codec.h:129
TH_PF_NFORMATS
@ TH_PF_NFORMATS
The total number of currently defined pixel formats.
Definition codec.h:131
TH_PF_RSVD
@ TH_PF_RSVD
Currently reserved.
Definition codec.h:122
TH_PF_420
@ TH_PF_420
Chroma decimation by 2 in both the X and Y directions (4:2:0).
Definition codec.h:120
th_quant_base
unsigned char th_quant_base[64]
A single base matrix.
Definition codec.h:340
th_comment_add
void th_comment_add(th_comment *_tc, const char *_comment)
Add a comment to an initialized th_comment structure.
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.
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_comment_query
char * th_comment_query(th_comment *_tc, const char *_tag, int _count)
Look up a comment value by its tag.
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_clear
void th_info_clear(th_info *_info)
Clears a th_info structure.
th_version_number
ogg_uint32_t th_version_number(void)
Retrieves the library version number.
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_comment_clear
void th_comment_clear(th_comment *_tc)
Clears a th_comment structure.
th_packet_iskeyframe
int th_packet_iskeyframe(ogg_packet *_op)
Determines whether a theora packet is a key frame or not.
th_comment
The comment information.
Definition codec.h:325
th_comment::comments
int comments
The total number of comment strings.
Definition codec.h:331
th_comment::comment_lengths
int * comment_lengths
An array of the corresponding length of each vector, in bytes.
Definition codec.h:329
th_comment::vendor
char * vendor
The null-terminated vendor string.
Definition codec.h:334
th_comment::user_comments
char ** user_comments
The array of comment string vectors.
Definition codec.h:327
th_huff_code
A Huffman code for a Theora DCT token.
Definition codec.h:440
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:443
th_huff_code::nbits
int nbits
The number of bits in the code.
Definition codec.h:446
th_img_plane
A buffer for a single color plane in an uncompressed image.
Definition codec.h:144
th_img_plane::height
int height
The height of this plane.
Definition codec.h:148
th_img_plane::width
int width
The width of this plane.
Definition codec.h:146
th_img_plane::stride
int stride
The offset in bytes between successive rows.
Definition codec.h:150
th_img_plane::data
unsigned char * data
A pointer to the beginning of the first row.
Definition codec.h:152
th_info
Theora bitstream information.
Definition codec.h:206
th_info::aspect_denominator
ogg_uint32_t aspect_denominator
Definition codec.h:255
th_info::target_bitrate
int target_bitrate
The target bit-rate in bits per second.
Definition codec.h:264
th_info::fps_numerator
ogg_uint32_t fps_numerator
Definition codec.h:242
th_info::pixel_fmt
th_pixel_fmt pixel_fmt
The pixel format.
Definition codec.h:260
th_info::pic_width
ogg_uint32_t pic_width
The displayed picture width.
Definition codec.h:222
th_info::pic_x
ogg_uint32_t pic_x
The X offset of the displayed picture.
Definition codec.h:229
th_info::aspect_numerator
ogg_uint32_t aspect_numerator
Definition codec.h:254
th_info::version_major
unsigned char version_major
Definition codec.h:210
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:298
th_info::frame_height
ogg_uint32_t frame_height
The encoded frame height.
Definition codec.h:219
th_info::frame_width
ogg_uint32_t frame_width
The encoded frame width.
Definition codec.h:216
th_info::pic_height
ogg_uint32_t pic_height
The displayed picture height.
Definition codec.h:225
th_info::pic_y
ogg_uint32_t pic_y
The Y offset of the displayed picture.
Definition codec.h:237
th_info::colorspace
th_colorspace colorspace
The color space.
Definition codec.h:258
th_info::quality
int quality
The target quality level.
Definition codec.h:284
th_info::fps_denominator
ogg_uint32_t fps_denominator
Definition codec.h:243
th_info::version_minor
unsigned char version_minor
Definition codec.h:211
th_info::version_subminor
unsigned char version_subminor
Definition codec.h:212
th_quant_info
A complete set of quantization parameters.
Definition codec.h:411
th_quant_info::ac_scale
ogg_uint16_t ac_scale[64]
The AC scaling factors.
Definition codec.h:415
th_quant_info::loop_filter_limits
unsigned char loop_filter_limits[64]
The loop filter limit values.
Definition codec.h:417
th_quant_info::qi_ranges
th_quant_ranges qi_ranges[2][3]
The qi ranges for each ci and pli.
Definition codec.h:419
th_quant_info::dc_scale
ogg_uint16_t dc_scale[64]
The DC scaling factors.
Definition codec.h:413
th_quant_ranges
A set of qi ranges.
Definition codec.h:343
th_quant_ranges::base_matrices
const th_quant_base * base_matrices
nranges +1 base matrices.
Definition codec.h:351
th_quant_ranges::nranges
int nranges
The number of ranges in the set.
Definition codec.h:345
th_quant_ranges::sizes
const int * sizes
The size of each of the nranges ranges.
Definition codec.h:348