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

#include <ogg/ogg.h>

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...
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.
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.
Typedefs
typedef th_img_plane	th_ycbcr_buffer [3]
	A complete image buffer for an uncompressed frame.
typedef struct th_comment	th_comment
	The comment information.
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...
Functions
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.

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 struct th_comment th_comment

The comment information.

This structure holds the in-stream metadata corresponding to the 'comment' header packet. The comment header is meant to be used much like someone jotting a quick note on the label of a video. It should be a short, to the point text note that can be more than a couple words, but not more than a short paragraph.

The metadata is stored as a series of (tag, value) pairs, in length-encoded string vectors. The first occurrence of the '=' character delimits the tag and value. A particular tag may occur more than once, and order is significant. The character set encoding for the strings is always UTF-8, but the tag names are limited to ASCII, and treated as case-insensitive. See the Theora specification, Section 6.3.3 for details.

In filling in this structure, th_decode_headerin() will null-terminate the user_comment strings for safety. However, the bitstream format itself treats them as 8-bit clean vectors, possibly containing null characters, and so the length array should be treated as their authoritative length.

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.

Data Structures

Defines

Typedefs

Enumerations

Functions

Detailed Description

Define Documentation

Typedef Documentation

Enumeration Type Documentation