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...

Macros
#define	OGG_THEORA_CODEC_HEADER (1)

Functions
Basic shared functions
These functions return information about the library itself, or provide high-level information about codec state and packet type. You must link to `libtheoradec` if you use any of the functions in this section.
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
These functions manipulate the th_info and th_comment structures which describe video parameters and key-value metadata, respectively. You must link to `libtheoradec` if you use any of the functions in this section.
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, const char _comment)
	Add a comment to an initialized th_comment structure.
void	th_comment_add_tag (th_comment _tc, const char _tag, const char *_val)
	Add a comment to an initialized th_comment structure.
char *	th_comment_query (th_comment _tc, const char _tag, int _count)
	Look up a comment value by its tag.
int	th_comment_query_count (th_comment _tc, const char _tag)
	Look up the number of instances of a tag.
void	th_comment_clear (th_comment *_tc)
	Clears a th_comment structure.

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.
#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.
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...
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.

Detailed Description

The shared libtheoradec and libtheoraenc C API.

You don't need to include this directly.

Macro Definition Documentation

◆ OGG_THEORA_CODEC_HEADER

#define OGG_THEORA_CODEC_HEADER (1)

◆ TH_DUPFRAME

#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.

◆ TH_EBADHEADER

#define TH_EBADHEADER (-20)

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

◆ TH_EBADPACKET

#define TH_EBADPACKET (-24)

There were errors in the video data packet.

◆ TH_EFAULT

#define TH_EFAULT (-1)

An invalid pointer was provided.

◆ TH_EIMPL

#define TH_EIMPL (-23)

The specified function is not implemented.

◆ TH_EINVAL

#define TH_EINVAL (-10)

An invalid argument was provided.

◆ TH_ENOTFORMAT

#define TH_ENOTFORMAT (-21)

The header does not belong to a Theora stream.

◆ TH_EVERSION

#define TH_EVERSION (-22)

The bitstream version is too high.

◆ TH_NDCT_TOKENS

#define TH_NDCT_TOKENS (32)

The number of DCT token values in each table.

◆ TH_NHUFFMAN_TABLES

#define TH_NHUFFMAN_TABLES (80)

The number of Huffman tables used by Theora.

Typedef Documentation

◆ th_comment

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, so the length array should be treated as their authoritative length.

◆ th_quant_base

typedef unsigned char th_quant_base[64]

A single base matrix.

◆ th_ycbcr_buffer

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

◆ th_colorspace

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.

◆ th_pixel_fmt

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.

Function Documentation

◆ th_comment_add()

void th_comment_add	(	th_comment *	_tc,
		const char *	_comment )

extern

Add a comment to an initialized th_comment structure.

Note: Neither th_comment_add() nor th_comment_add_tag() support comments containing null values, although the bitstream format does support them. To add such comments you will need to manipulate the th_comment structure directly.

Parameters

_tc	The th_comment struct to add the comment to.
_comment	Must be a null-terminated UTF-8 string containing the comment in "TAG=the value" form.

References th_comment_add().

Referenced by th_comment_add().

◆ th_comment_add_tag()

void th_comment_add_tag	(	th_comment *	_tc,
		const char *	_tag,
		const char *	_val )

extern

Add a comment to an initialized th_comment structure.

Note: Neither th_comment_add() nor th_comment_add_tag() support comments containing null values, although the bitstream format does support them. To add such comments you will need to manipulate the th_comment structure directly.

Parameters

_tc	The th_comment struct to add the comment to.
_tag	A null-terminated string containing the tag associated with the comment.
_val	The corresponding value as a null-terminated string.

References th_comment_add_tag().

Referenced by th_comment_add_tag().

◆ th_comment_clear()

void th_comment_clear ( th_comment * _tc )

extern

Clears a th_comment structure.

This should be called on a th_comment structure after it is no longer needed. It will free all memory used by the structure members.

Parameters

_tc	The th_comment struct to clear.

References th_comment_clear().

Referenced by th_comment_clear().

◆ th_comment_init()

void th_comment_init ( th_comment * _tc )

extern

Initialize a th_comment structure.

This should be called on a freshly allocated th_comment structure before attempting to use it.

Parameters

_tc	The th_comment struct to initialize.

References th_comment_init().

Referenced by th_comment_init().

◆ th_comment_query()

char * th_comment_query	(	th_comment *	_tc,
		const char *	_tag,
		int	_count )

extern

Look up a comment value by its tag.

Parameters

_tc	An initialized th_comment structure.
_tag	The tag to look up.
_count	The instance of the tag. The same tag can appear multiple times, each with a distinct value, so an index is required to retrieve them all. The order in which these values appear is significant and should be preserved. Use th_comment_query_count() to get the legal range for the _count parameter.

Returns: A pointer to the queried tag's value. This points directly to data in the th_comment structure. It should not be modified or freed by the application, and modifications to the structure may invalidate the pointer.

Return values

NULL	If no matching tag is found.

References th_comment_query().

Referenced by th_comment_query().

◆ th_comment_query_count()

int th_comment_query_count	(	th_comment *	_tc,
		const char *	_tag )

extern

Look up the number of instances of a tag.

Call this first when querying for a specific tag and then iterate over the number of instances with separate calls to th_comment_query() to retrieve all the values for that tag in order.

Parameters

_tc	An initialized th_comment structure.
_tag	The tag to look up.

Returns: The number of instances of this particular tag.

References th_comment_query_count().

Referenced by th_comment_query_count().

◆ th_granule_frame()

ogg_int64_t th_granule_frame	(	void *	_encdec,
		ogg_int64_t	_granpos )

extern

Converts a granule position to an absolute frame index, starting at 0.

The granule position is interpreted in the context of a given th_enc_ctx or th_dec_ctx handle (either will suffice).

Parameters

_encdec	A previously allocated th_enc_ctx or th_dec_ctx handle.
_granpos	The granule position to convert.

Returns: The absolute frame index corresponding to _granpos.

Return values

-1	The given granule position was invalid (i.e. negative).

References th_granule_frame().

Referenced by th_granule_frame().

◆ th_granule_time()

double th_granule_time	(	void *	_encdec,
		ogg_int64_t	_granpos )

extern

Converts a granule position to an absolute time in seconds.

The granule position is interpreted in the context of a given th_enc_ctx or th_dec_ctx handle (either will suffice).

Parameters

_encdec	A previously allocated th_enc_ctx or th_dec_ctx handle.
_granpos	The granule position to convert.

Returns: The absolute time in seconds corresponding to _granpos. This is the "end time" for the frame, or the latest time it should be displayed. It is not the presentation time.

Return values

-1	The given granule position was invalid (i.e. negative).

References th_granule_time().

Referenced by th_granule_time().

◆ th_info_clear()

void th_info_clear ( th_info * _info )

extern

Clears a th_info structure.

This should be called on a th_info structure after it is no longer needed.

Parameters

_info The th_info struct to clear.

References th_info_clear().

Referenced by th_info_clear().

◆ th_info_init()

void th_info_init ( th_info * _info )

extern

Initializes a th_info structure.

This should be called on a freshly allocated th_info structure before attempting to use it.

Parameters

_info The th_info struct to initialize.

References th_info_init().

Referenced by th_info_init().

◆ th_packet_isheader()

int th_packet_isheader ( ogg_packet * _op )

extern

Determines whether a Theora packet is a header or not.

This function does no verification beyond checking the packet type bit, so it should not be used for bitstream identification; use th_decode_headerin() for that. As per the Theora specification, an empty (0-byte) packet is treated as a data packet (a delta frame with no coded blocks).

Parameters

_op	An ogg_packet containing encoded Theora data.

Return values

1	The packet is a header packet
0	The packet is a video data packet.

References th_packet_isheader().

Referenced by th_packet_isheader().

◆ th_packet_iskeyframe()

int th_packet_iskeyframe ( ogg_packet * _op )

extern

Determines whether a theora packet is a key frame or not.

This function does no verification beyond checking the packet type and key frame bits, so it should not be used for bitstream identification; use th_decode_headerin() for that. As per the Theora specification, an empty (0-byte) packet is treated as a delta frame (with no coded blocks).

Parameters

_op	An ogg_packet containing encoded Theora data.

Return values

1	The packet contains a key frame.
0	The packet contains a delta frame.
-1	The packet is not a video data packet.

References th_packet_iskeyframe().

Referenced by th_packet_iskeyframe().

◆ th_version_number()

ogg_uint32_t th_version_number ( void )

extern

Retrieves the library version number.

This is the highest bitstream version that the encoder library will produce, or that the decoder library can decode. This number is composed of a 16-bit major version, 8-bit minor version and 8 bit sub-version, composed as follows:

(VERSION_MAJOR<<16)+(VERSION_MINOR<<8)+(VERSION_SUBMINOR)

Returns: the version number.

References th_version_number().

Referenced by th_version_number().

◆ th_version_string()

const char * th_version_string ( void )

extern

Retrieves a human-readable string to identify the library vendor and version.

Returns: the version string.

References th_version_string().

Referenced by th_version_string().

Data Structures

Macros

Functions

Return codes

Detailed Description

Macro Definition Documentation

◆ OGG_THEORA_CODEC_HEADER

◆ TH_DUPFRAME

◆ TH_EBADHEADER

◆ TH_EBADPACKET

◆ TH_EFAULT

◆ TH_EIMPL

◆ TH_EINVAL

◆ TH_ENOTFORMAT

◆ TH_EVERSION

◆ TH_NDCT_TOKENS

◆ TH_NHUFFMAN_TABLES

Typedef Documentation

◆ th_comment

◆ th_quant_base

◆ th_ycbcr_buffer

Enumeration Type Documentation

◆ th_colorspace

◆ th_pixel_fmt

Function Documentation

◆ th_comment_add()

◆ th_comment_add_tag()

◆ th_comment_clear()

◆ th_comment_init()

◆ th_comment_query()

◆ th_comment_query_count()

◆ th_granule_frame()

◆ th_granule_time()

◆ th_info_clear()

◆ th_info_init()

◆ th_packet_isheader()

◆ th_packet_iskeyframe()

◆ th_version_number()

◆ th_version_string()