codec.h File Reference

The shared libtheoradec and libtheoraenc C API. More...

#include <ogg/ogg.h>

Go to the source code of this file.

Data Structures

struct  th_img_plane
 A buffer for a single color plane in an uncompressed image. More...
struct  th_info
 Theora bitstream information. More...
struct  th_comment
 The comment information. More...
struct  th_quant_ranges
 A set of qi ranges. More...
struct  th_quant_info
 A complete set of quantization parameters. More...
struct  th_huff_code
 A Huffman code for a Theora DCT token. More...

Return codes

#define TH_EFAULT   (-1)
 An invalid pointer was provided.
#define TH_EINVAL   (-10)
 An invalid argument was provided.
#define TH_EBADHEADER   (-20)
 The contents of the header were incomplete, invalid, or unexpected.
#define TH_ENOTFORMAT   (-21)
 The header does not belong to a Theora stream.
#define TH_EVERSION   (-22)
 The bitstream version is too high.
#define TH_EIMPL   (-23)
 The specified function is not implemented.
#define TH_EBADPACKET   (-24)
 There were errors in the video data packet.
#define TH_DUPFRAME   (1)
 The decoded packet represented a dropped frame.

Basic shared functions

const char * th_version_string (void)
 Retrieves a human-readable string to identify the library vendor and version.
ogg_uint32_t th_version_number (void)
 Retrieves the library version number.
ogg_int64_t th_granule_frame (void *_encdec, ogg_int64_t _granpos)
 Converts a granule position to an absolute frame index, starting at 0.
double th_granule_time (void *_encdec, ogg_int64_t _granpos)
 Converts a granule position to an absolute time in seconds.
int th_packet_isheader (ogg_packet *_op)
 Determines whether a Theora packet is a header or not.
int th_packet_iskeyframe (ogg_packet *_op)
 Determines whether a theora packet is a key frame or not.

Functions for manipulating header data

void th_info_init (th_info *_info)
 Initializes a th_info structure.
void th_info_clear (th_info *_info)
 Clears a th_info structure.
void th_comment_init (th_comment *_tc)
 Initialize a th_comment structure.
void th_comment_add (th_comment *_tc, char *_comment)
 Add a comment to an initialized th_comment structure.
void th_comment_add_tag (th_comment *_tc, char *_tag, char *_val)
 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.
int th_comment_query_count (th_comment *_tc, char *_tag)
 Look up the number of instances of a tag.
void th_comment_clear (th_comment *_tc)
 Clears a th_comment structure.

Defines

#define _O_THEORA_CODEC_H_   (1)
#define TH_NHUFFMAN_TABLES   (80)
 The number of Huffman tables used by Theora.
#define TH_NDCT_TOKENS   (32)
 The number of DCT token values in each table.

Typedefs

typedef th_img_plane th_ycbcr_buffer [3]
 A complete image buffer for an uncompressed frame.
typedef unsigned char th_quant_base [64]
 A single base matrix.

Enumerations

enum  th_colorspace { TH_CS_UNSPECIFIED, TH_CS_ITU_REC_470M, TH_CS_ITU_REC_470BG, TH_CS_NSPACES }
 The currently defined color space tags. More...
enum  th_pixel_fmt {
  TH_PF_420, TH_PF_RSVD, TH_PF_422, TH_PF_444,
  TH_PF_NFORMATS
}
 The currently defined pixel format tags. More...


Detailed Description

The shared libtheoradec and libtheoraenc C API.

You don't need to include this directly.


Define Documentation

#define _O_THEORA_CODEC_H_   (1)
 

#define TH_DUPFRAME   (1)
 

The decoded packet represented a dropped frame.

The player can continue to display the current frame, as the contents of the decoded frame buffer have not changed.

#define TH_EBADHEADER   (-20)
 

The contents of the header were incomplete, invalid, or unexpected.

#define TH_EBADPACKET   (-24)
 

There were errors in the video data packet.

#define TH_EFAULT   (-1)
 

An invalid pointer was provided.

#define TH_EIMPL   (-23)
 

The specified function is not implemented.

#define TH_EINVAL   (-10)
 

An invalid argument was provided.

#define TH_ENOTFORMAT   (-21)
 

The header does not belong to a Theora stream.

#define TH_EVERSION   (-22)
 

The bitstream version is too high.

#define TH_NDCT_TOKENS   (32)
 

The number of DCT token values in each table.

#define TH_NHUFFMAN_TABLES   (80)
 

The number of Huffman tables used by Theora.


Typedef Documentation

typedef unsigned char th_quant_base[64]
 

A single base matrix.

typedef th_img_plane th_ycbcr_buffer[3]
 

A complete image buffer for an uncompressed frame.

The chroma planes may be decimated by a factor of two in either direction, as indicated by th_info::pixel_fmt. The width and height of the Y' plane must be multiples of 16. They may need to be cropped for display, using the rectangle specified by th_info::pic_x, th_info::pic_y, th_info::pic_width, and th_info::pic_height. All samples are 8 bits.

Note:
The term YUV often used to describe a colorspace is ambiguous. The exact parameters of the RGB to YUV conversion process aside, in many contexts the U and V channels actually have opposite meanings. To avoid this confusion, we are explicit: the name of the color channels are Y'CbCr, and they appear in that order, always. The prime symbol denotes that the Y channel is non-linear. Cb and Cr stand for "Chroma blue" and "Chroma red", respectively.


Enumeration Type Documentation

enum th_colorspace
 

The currently defined color space tags.

See the Theora specification, Chapter 4, for exact details on the meaning of each of these color spaces.

Enumerator:
TH_CS_UNSPECIFIED  The color space was not specified at the encoder.

It may be conveyed by an external means.

TH_CS_ITU_REC_470M  A color space designed for NTSC content.
TH_CS_ITU_REC_470BG  A color space designed for PAL/SECAM content.
TH_CS_NSPACES  The total number of currently defined color spaces.

enum th_pixel_fmt
 

The currently defined pixel format tags.

See the Theora specification, Section 4.4, for details on the precise sample locations.

Enumerator:
TH_PF_420  Chroma decimation by 2 in both the X and Y directions (4:2:0).

The Cb and Cr chroma planes are half the width and half the height of the luma plane.

TH_PF_RSVD  Currently reserved.
TH_PF_422  Chroma decimation by 2 in the X direction (4:2:2).

The Cb and Cr chroma planes are half the width of the luma plane, but full height.

TH_PF_444  No chroma decimation (4:4:4).

The Cb and Cr chroma planes are full width and full height.

TH_PF_NFORMATS  The total number of currently defined pixel formats.


Generated on Mon Nov 3 10:42:44 2008 for libtheora by  doxygen 1.4.6