codec.h
Go to the documentation of this file.
/********************************************************************
* *
* THIS FILE IS PART OF THE OggTheora SOFTWARE CODEC SOURCE CODE. *
* USE, DISTRIBUTION AND REPRODUCTION OF THIS LIBRARY SOURCE IS *
* GOVERNED BY A BSD-STYLE SOURCE LICENSE INCLUDED WITH THIS SOURCE *
* IN 'COPYING'. PLEASE READ THESE TERMS BEFORE DISTRIBUTING. *
* *
* THE Theora SOURCE CODE IS COPYRIGHT (C) 2002-2009 *
* by the Xiph.Org Foundation http://www.xiph.org/ *
* *
********************************************************************
function:
last mod: $Id: theora.h,v 1.8 2004/03/15 22:17:32 derf Exp $
********************************************************************/
#if !defined(_O_THEORA_CODEC_H_)
# define _O_THEORA_CODEC_H_ (1)
# include <ogg/ogg.h>
#if defined(__cplusplus)
extern "C" {
#endif
#define TH_EFAULT (-1)
#define TH_EINVAL (-10)
#define TH_EBADHEADER (-20)
#define TH_ENOTFORMAT (-21)
#define TH_EVERSION (-22)
#define TH_EIMPL (-23)
#define TH_EBADPACKET (-24)
#define TH_DUPFRAME (1)
typedef enum{
TH_CS_UNSPECIFIED,
TH_CS_ITU_REC_470M,
TH_CS_ITU_REC_470BG,
TH_CS_NSPACES
}th_colorspace;
typedef enum{
TH_PF_420,
TH_PF_RSVD,
TH_PF_422,
TH_PF_444,
TH_PF_NFORMATS
}th_pixel_fmt;
typedef struct{
int width;
int height;
int stride;
unsigned char *data;
}th_img_plane;
typedef th_img_plane th_ycbcr_buffer[3];
typedef struct{
unsigned char version_major;
unsigned char version_minor;
unsigned char version_subminor;
ogg_uint32_t frame_width;
ogg_uint32_t frame_height;
ogg_uint32_t pic_width;
ogg_uint32_t pic_height;
ogg_uint32_t pic_x;
ogg_uint32_t pic_y;
ogg_uint32_t fps_numerator;
ogg_uint32_t fps_denominator;
ogg_uint32_t aspect_numerator;
ogg_uint32_t aspect_denominator;
th_colorspace colorspace;
th_pixel_fmt pixel_fmt;
int target_bitrate;
/*Currently this is set so that a qi of 0 corresponds to distortions of 24
times the JND, and each increase by 16 halves that value.
This gives us fine discrimination at low qualities, yet effective rate
control at high qualities.
The qi value 63 is special, however.
For this, the highest quality, we use one half of a JND for our threshold.
Due to the lower bounds placed on allowable quantizers in Theora, we will
not actually be able to achieve quality this good, but this should
provide as close to visually lossless quality as Theora is capable of.
We could lift the quantizer restrictions without breaking VP3.1
compatibility, but this would result in quantized coefficients that are
too large for the current bitstream to be able to store.
We'd have to redesign the token syntax to store these large coefficients,
which would make transcoding complex.*/
int quality;
int keyframe_granule_shift;
}th_info;
typedef struct th_comment{
char **user_comments;
int *comment_lengths;
int comments;
char *vendor;
}th_comment;
typedef unsigned char th_quant_base[64];
typedef struct{
int nranges;
const int *sizes;
const th_quant_base *base_matrices;
}th_quant_ranges;
typedef struct{
ogg_uint16_t dc_scale[64];
ogg_uint16_t ac_scale[64];
unsigned char loop_filter_limits[64];
th_quant_ranges qi_ranges[2][3];
}th_quant_info;
#define TH_NHUFFMAN_TABLES (80)
#define TH_NDCT_TOKENS (32)
typedef struct{
ogg_uint32_t pattern;
int nbits;
}th_huff_code;
extern const char *th_version_string(void);
extern ogg_uint32_t th_version_number(void);
extern ogg_int64_t th_granule_frame(void *_encdec,ogg_int64_t _granpos);
extern double th_granule_time(void *_encdec,ogg_int64_t _granpos);
extern int th_packet_isheader(ogg_packet *_op);
extern int th_packet_iskeyframe(ogg_packet *_op);
extern void th_info_init(th_info *_info);
extern void th_info_clear(th_info *_info);
extern void th_comment_init(th_comment *_tc);
extern void th_comment_add(th_comment *_tc, char *_comment);
extern void th_comment_add_tag(th_comment *_tc,char *_tag,char *_val);
extern char *th_comment_query(th_comment *_tc,char *_tag,int _count);
extern int th_comment_query_count(th_comment *_tc,char *_tag);
extern void th_comment_clear(th_comment *_tc);
#if defined(__cplusplus)
}
#endif
#endif
TH_PF_444
No chroma decimation (4:4:4).
Definition: codec.h:127
TH_PF_420
Chroma decimation by 2 in both the X and Y directions (4:2:0).
Definition: codec.h:118
th_info::pic_y
ogg_uint32_t pic_y
The Y offset of the displayed picture.
Definition: codec.h:235
th_quant_info
A complete set of quantization parameters.
Definition: codec.h:409
th_info
Theora bitstream information.
Definition: codec.h:204
th_info::fps_numerator
ogg_uint32_t fps_numerator
Definition: codec.h:240
th_quant_ranges::base_matrices
const th_quant_base * base_matrices
nranges +1 base matrices.
Definition: codec.h:349
th_info::frame_width
ogg_uint32_t frame_width
The encoded frame width.
Definition: codec.h:214
th_huff_code
A Huffman code for a Theora DCT token.
Definition: codec.h:438
th_huff_code::nbits
int nbits
The number of bits in the code.
Definition: codec.h:444
th_comment
The comment information.
Definition: codec.h:323
th_comment_add
void th_comment_add(th_comment *_tc, char *_comment)
Add a comment to an initialized 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::user_comments
char ** user_comments
The array of comment string vectors.
Definition: codec.h:325
th_info::target_bitrate
int target_bitrate
The target bit-rate in bits per second.
Definition: codec.h:262
th_comment_add_tag
void th_comment_add_tag(th_comment *_tc, char *_tag, char *_val)
Add a comment to an initialized th_comment structure.
th_info::version_minor
unsigned char version_minor
Definition: codec.h:209
th_info::quality
int quality
The target quality level.
Definition: codec.h:282
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_info::pixel_fmt
th_pixel_fmt pixel_fmt
The pixel format.
Definition: codec.h:258
th_comment::comments
int comments
The total number of comment strings.
Definition: codec.h:329
th_info::aspect_denominator
ogg_uint32_t aspect_denominator
Definition: codec.h:253
th_version_number
ogg_uint32_t th_version_number(void)
Retrieves the library version number.
th_quant_ranges::nranges
int nranges
The number of ranges in the set.
Definition: codec.h:343
th_info::version_subminor
unsigned char version_subminor
Definition: codec.h:210
th_packet_isheader
int th_packet_isheader(ogg_packet *_op)
Determines whether a Theora packet is a header or not.
th_comment::comment_lengths
int * comment_lengths
An array of the corresponding length of each vector, in bytes.
Definition: codec.h:327
TH_PF_NFORMATS
The total number of currently defined pixel formats.
Definition: codec.h:129
th_info::pic_x
ogg_uint32_t pic_x
The X offset of the displayed picture.
Definition: codec.h:227
th_info::colorspace
th_colorspace colorspace
The color space.
Definition: codec.h:256
TH_CS_UNSPECIFIED
The color space was not specified at the encoder.
Definition: codec.h:101
th_info::frame_height
ogg_uint32_t frame_height
The encoded frame height.
Definition: codec.h:217
th_quant_ranges
A set of qi ranges.
Definition: codec.h:341
th_info_clear
void th_info_clear(th_info *_info)
Clears a th_info structure.
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:441
th_version_string
const char * th_version_string(void)
Retrieves a human-readable string to identify the library vendor and version.
th_img_plane::data
unsigned char * data
A pointer to the beginning of the first row.
Definition: codec.h:150
TH_PF_422
Chroma decimation by 2 in the X direction (4:2:2).
Definition: codec.h:124
th_ycbcr_buffer
th_img_plane th_ycbcr_buffer[3]
A complete image buffer for an uncompressed frame.
Definition: codec.h:168
th_info_init
void th_info_init(th_info *_info)
Initializes a th_info structure.
th_comment_init
void th_comment_init(th_comment *_tc)
Initialize a th_comment structure.
th_pixel_fmt
th_pixel_fmt
The currently defined pixel format tags.
Definition: codec.h:114
th_info::pic_width
ogg_uint32_t pic_width
The displayed picture width.
Definition: codec.h:220
th_info::fps_denominator
ogg_uint32_t fps_denominator
Definition: codec.h:241
th_info::pic_height
ogg_uint32_t pic_height
The displayed picture height.
Definition: codec.h:223
th_img_plane
A buffer for a single color plane in an uncompressed image.
Definition: codec.h:142
th_comment_clear
void th_comment_clear(th_comment *_tc)
Clears a th_comment structure.
th_comment_query
char * th_comment_query(th_comment *_tc, char *_tag, int _count)
Look up a comment value by its tag.
th_img_plane::height
int height
The height of this plane.
Definition: codec.h:146
th_quant_base
unsigned char th_quant_base[64]
A single base matrix.
Definition: codec.h:338
TH_CS_NSPACES
The total number of currently defined color spaces.
Definition: codec.h:107
th_img_plane::width
int width
The width of this plane.
Definition: codec.h:144
th_quant_ranges::sizes
const int * sizes
The size of each of the nranges ranges.
Definition: codec.h:346
th_img_plane::stride
int stride
The offset in bytes between successive rows.
Definition: codec.h:148
th_info::aspect_numerator
ogg_uint32_t aspect_numerator
Definition: codec.h:252
th_comment
struct th_comment th_comment
The comment information.
th_colorspace
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_granule_time
double th_granule_time(void *_encdec, ogg_int64_t _granpos)
Converts a granule position to an absolute time in seconds.
TH_PF_RSVD
Currently reserved.
Definition: codec.h:120
th_comment_query_count
int th_comment_query_count(th_comment *_tc, char *_tag)
Look up the number of instances of a tag.
th_comment::vendor
char * vendor
The null-terminated vendor string.
Definition: codec.h:332
th_info::version_major
unsigned char version_major
Definition: codec.h:208
TH_CS_ITU_REC_470M
A color space designed for NTSC content.
Definition: codec.h:103
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:296