theora.h File Reference

The libtheora C API. More...

#include <ogg/ogg.h>

Go to the source code of this file.

Data Structures
struct	yuv_buffer
	A YUV buffer for passing uncompressed frames to and from the codec. More...
struct	theora_info
	Theora bitstream info. More...
struct	theora_state
	Codec internal state and context. More...
struct	theora_comment
	Comment header metadata. More...
Defines
#define	OC_FAULT   -1
	general failure
#define	OC_EINVAL   -10
	library encountered invalid internal data
#define	OC_DISABLED   -11
	requested action is disabled
#define	OC_BADHEADER   -20
	header packet was corrupt/invalid
#define	OC_NOTFORMAT   -21
	packet is not a theora packet
#define	OC_VERSION   -22
	bitstream version is not handled
#define	OC_IMPL   -23
	feature or action not implemented
#define	OC_BADPACKET   -24
	packet is corrupt
#define	OC_NEWPACKET   -25
	packet is an (ignorable) unhandled extension
Typedefs
typedef theora_comment	theora_comment
	Comment header metadata.
Enumerations
enum	theora_colorspace { OC_CS_UNSPECIFIED, OC_CS_ITU_REC_470M, OC_CS_ITU_REC_470BG }
	A Colorspace. More...
Functions
const char *	theora_version_string (void)
	Retrieve a human-readable string to identify the encoder vendor and version.
ogg_uint32_t	theora_version_number (void)
	Retrieve a 32-bit version number.
int	theora_encode_init (theora_state *th, theora_info *c)
	Initialize the theora encoder.
int	theora_encode_YUVin (theora_state *t, yuv_buffer *yuv)
	Submit a YUV buffer to the theora encoder.
int	theora_encode_packetout (theora_state *t, int last_p, ogg_packet *op)
	Request the next packet of encoded video.
int	theora_encode_header (theora_state *t, ogg_packet *op)
	Request a packet containing the initial header.
int	theora_encode_comment (theora_comment *tc, ogg_packet *op)
	Request a comment header packet from provided metadata.
int	theora_encode_tables (theora_state *t, ogg_packet *op)
	Request a packet containing the codebook tables for the stream.
int	theora_decode_header (theora_info *ci, theora_comment *cc, ogg_packet *op)
	Decode an Ogg packet, with the expectation that the packet contains an initial header, comment data or codebook tables.
int	theora_decode_init (theora_state *th, theora_info *c)
	Initialize a theora_state handle for decoding.
int	theora_decode_packetin (theora_state *th, ogg_packet *op)
	Input a packet containing encoded data into the theora decoder.
int	theora_decode_YUVout (theora_state *th, yuv_buffer *yuv)
	Output the next available frame of decoded YUV data.
int	theora_packet_isheader (ogg_packet *op)
	Report whether a theora packet is a header or not This function does no verification beyond checking the header flag bit so it should not be used for bitstream identification; use theora_decode_header() for that.
int	theora_packet_iskeyframe (ogg_packet *op)
	Report whether a theora packet is a keyframe or not.
ogg_int64_t	theora_granule_frame (theora_state *th, ogg_int64_t granulepos)
	Convert a granulepos to an absolute frame number.
double	theora_granule_time (theora_state *th, ogg_int64_t granulepos)
	Convert a granulepos to absolute time in seconds.
void	theora_info_init (theora_info *c)
	Initialize a theora_info structure.
void	theora_info_clear (theora_info *c)
	Clear a theora_info structure.
void	theora_clear (theora_state *t)
	Free all internal data associated with a theora_state handle.
void	theora_comment_init (theora_comment *tc)
	Initialize an allocated theora_comment structure.
void	theora_comment_add (theora_comment *tc, char *comment)
	Add a comment to an initialized theora_comment structure.
void	theora_comment_add_tag (theora_comment *tc, char *tag, char *value)
	Add a comment to an initialized theora_comment structure.
char *	theora_comment_query (theora_comment *tc, char *tag, int count)
	look up a comment value by tag
int	theora_comment_query_count (theora_comment *tc, char *tag)
	look up the number of instances of a tag
void	theora_comment_clear (theora_comment *tc)
	clears an allocated theora_comment struct so that it can be freed.

---

Detailed Description

The libtheora C API.

---

Typedef Documentation

typedef struct theora_comment theora_comment

Comment header metadata. This structure holds the in-stream metadata corresponding to the 'comment' header packet. Meta data is stored as a series of (tag, value) pairs, in length-encoded string vectors. The first occurence of the '=' character delimits the tag and value. A particular tag may occur more than once. The character set encoding for the strings is always utf-8, but the tag names are limited to case-insensitive ascii. See the spec for details. In filling in this structure, theora_decode_header() will null-terminate the user_comment strings for safety. However, the bitstream format itself treats them as 8-bit clean, and so the length array should be treated as authoritative for their length.

---

Enumeration Type Documentation

enum theora_colorspace

A Colorspace. Enumeration values: OC_CS_UNSPECIFIED  the colorspace is unknown or unspecified OC_CS_ITU_REC_470M  best option for 'NTSC' content OC_CS_ITU_REC_470BG  best option for 'PAL' content

---

Function Documentation

void theora_clear (  theora_state *  t  )

Free all internal data associated with a theora_state handle. Parameters: t  A theora_state handle.

void theora_comment_add (  theora_comment *  tc, char *  comment )

Add a comment to an initialized theora_comment structure. Parameters: comment  must be a null-terminated string encoding the comment in "TAG=the value" form

void theora_comment_add_tag (  theora_comment *  tc, char *  tag, char *  value )

Add a comment to an initialized theora_comment structure. Parameters: tag  a null-terminated string containing the tag associated with the comment. value  the corresponding value as a null-terminated string Neither theora_comment_add() nor theora_comment_add_tag() support comments containing null values, although the bitstream format supports this. To add such comments you will need to manipulate the theora_comment structure directly

char* theora_comment_query (  theora_comment *  tc, char *  tag, int  count )

look up a comment value by tag Parameters: tc  an initialized theora_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 and ordered value, so an index is required to retrieve them all. Use theora_comment_query_count() to get the legal range for the count parameter Returns: a pointer to the queried tag's value Return values: NULL  if no matching tag is found

int theora_comment_query_count (  theora_comment *  tc, char *  tag )

look up the number of instances of a tag Parameters: tc  an initialized theora_comment structure tag  the tag to look up Returns: the number on instances of a particular tag. Call this first when querying for a specific tag and then interate over the number of instances with separate calls to theora_comment_query() to retrieve all instances in order.

int theora_decode_header (  theora_info *  ci, theora_comment *  cc, ogg_packet *  op )

Decode an Ogg packet, with the expectation that the packet contains an initial header, comment data or codebook tables. Parameters: ci  A theora_info structure to fill. This must have been previously initialized with theora_info_init(). If op contains an initial header, theora_decode_header() will fill ci with the parsed header values. If op contains codebook tables, theora_decode_header() will parse these and attach an internal representation to ci->codec_setup. cc  A theora_comment structure to fill. If op contains comment data, theora_decode_header() will fill cc with the parsed comments. op  An ogg_packet structure which you expect contains an initial header, comment data or codebook tables. Return values: OC_BADHEADER  op is NULL; OR the first byte of op->packet has the signature of an initial packet, but op is not a b_o_s packet; OR this packet has the signature of an initial header packet, but an initial header packet has already been seen; OR this packet has the signature of a comment packet, but the initial header has not yet been seen; OR this packet has the signature of a comment packet, but contains invalid data; OR this packet has the signature of codebook tables, but the initial header or comments have not yet been seen; OR this packet has the signature of codebook tables, but contains invalid data; OR the stream being decoded has a compatible version but this packet does not have the signature of a theora initial header, comments, or codebook packet OC_VERSION  The packet data of op is an initial header with a version which is incompatible with this version of libtheora. OC_NEWPACKET  the stream being decoded has an incompatible (future) version and contains an unknown signature. 0  Success Note: The normal usage is that theora_decode_header() be called on the first three packets of a theora logical bitstream in succession.

int theora_decode_init (  theora_state *  th, theora_info *  c )

Initialize a theora_state handle for decoding. Parameters: th  The theora_state handle to initialize. c  A theora_info struct filled with the desired decoding parameters. This is of course usually obtained from a previous call to theora_decode_header(). Returns: 0 Success

int theora_decode_packetin (  theora_state *  th, ogg_packet *  op )

Input a packet containing encoded data into the theora decoder. Parameters: th  A theora_state handle previously initialized for decoding. op  An ogg_packet containing encoded theora data. Return values: OC_BADPACKET  op does not contain encoded video data

int theora_decode_YUVout (  theora_state *  th, yuv_buffer *  yuv )

Output the next available frame of decoded YUV data. Parameters: th  A theora_state handle previously initialized for decoding. yuv  A yuv_buffer in which libtheora should place the decoded data. Return values: 0  Success

int theora_encode_comment (  theora_comment *  tc, ogg_packet *  op )

Request a comment header packet from provided metadata. A pointer to the comment data is placed in a user-provided ogg_packet structure. Parameters: tc  A theora_comment structure filled with the desired metadata op  An ogg_packet structure to fill. libtheora will set all elements of this structure, including a pointer to the encoded comment data. The memory for the comment data is owned by libtheora. Return values: 0  Success

int theora_encode_header (  theora_state *  t, ogg_packet *  op )

Request a packet containing the initial header. A pointer to the header data is placed in a user-provided ogg_packet structure. Parameters: t  A theora_state handle previously initialized for encoding. op  An ogg_packet structure to fill. libtheora will set all elements of this structure, including a pointer to the header data. The memory for the header data is owned by libtheora. Return values: 0  Success

int theora_encode_init (  theora_state *  th, theora_info *  c )

Initialize the theora encoder. Parameters: th  The theora_state handle to initialize for encoding. ti  A theora_info struct filled with the desired encoding parameters. Returns: 0 Success

int theora_encode_packetout (  theora_state *  t, int  last_p, ogg_packet *  op )

Request the next packet of encoded video. The encoded data is placed in a user-provided ogg_packet structure. Parameters: t  A theora_state handle previously initialized for encoding. last_p  whether this is the last packet the encoder should produce. op  An ogg_packet structure to fill. libtheora will set all elements of this structure, including a pointer to encoded data. The memory for the encoded data is owned by libtheora. Return values: 0  No internal storage exists OR no packet is ready -1  The encoding process has completed 1  Success

int theora_encode_tables (  theora_state *  t, ogg_packet *  op )

Request a packet containing the codebook tables for the stream. A pointer to the codebook data is placed in a user-provided ogg_packet structure. Parameters: t  A theora_state handle previously initialized for encoding. op  An ogg_packet structure to fill. libtheora will set all elements of this structure, including a pointer to the codebook data. The memory for the header data is owned by libtheora. Return values: 0  Success

int theora_encode_YUVin (  theora_state *  t, yuv_buffer *  yuv )

Submit a YUV buffer to the theora encoder. Parameters: t  A theora_state handle previously initialized for encoding. yuv  A buffer of YUV data to encode. Return values: OC_EINVAL  Encoder is not ready, or is finished. -1  The size of the given frame differs from those previously input 0  Success

ogg_int64_t theora_granule_frame (  theora_state *  th, ogg_int64_t  granulepos )

Convert a granulepos to an absolute frame number. The granulepos is interpreted in the context of a given theora_state handle. Parameters: th  A previously initialized theora_state handle (encode or decode) granulepos  The granulepos to convert. Returns: The frame number corresponding to granulepos. Return values: -1  The given granulepos is invalid (ie. negative) Thus function was added in the 1.0alpha4 release.

double theora_granule_time (  theora_state *  th, ogg_int64_t  granulepos )

Convert a granulepos to absolute time in seconds. The granulepos is interpreted in the context of a given theora_state handle. Parameters: th  A previously initialized theora_state handle (encode or decode) granulepos  The granulepos to convert. Returns: The absolute time in seconds corresponding to granulepos. Return values: -1  The given granulepos is invalid (ie. negative)

void theora_info_clear (  theora_info *  c  )

Clear a theora_info structure. All values within the given theora_info structure are cleared, and associated internal codec setup data is freed. Parameters: c  A theora_info struct to initialize.

void theora_info_init (  theora_info *  c  )

Initialize a theora_info structure. All values within the given theora_info structure are initialized, and space is allocated within libtheora for internal codec setup data. Parameters: c  A theora_info struct to initialize.

int theora_packet_isheader (  ogg_packet *  op  )

Report whether a theora packet is a header or not This function does no verification beyond checking the header flag bit so it should not be used for bitstream identification; use theora_decode_header() for that. Parameters: op  An ogg_packet containing encoded theora data. Return values: 1  The packet is a header packet 0  The packet is not a header packet (and so contains frame data) Thus function was added in the 1.0alpha4 release.

int theora_packet_iskeyframe (  ogg_packet *  op  )

Report whether a theora packet is a keyframe or not. Parameters: op  An ogg_packet containing encoded theora data. Return values: 1  The packet contains a keyframe image 0  The packet is contains an interframe delta -1  the packet is not an image data packet at all Thus function was added in the 1.0alpha4 release.

ogg_uint32_t theora_version_number (  void   )

Retrieve a 32-bit version number. 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_SUB) Returns: the version number.

const char* theora_version_string (  void   )

Retrieve a human-readable string to identify the encoder vendor and version. Returns: a version string.

---