Main Page | Data Structures | File List | Globals

theora.h File Reference

#include <ogg/ogg.h>

Go to the source code of this file.

Data Structures

struct  yuv_buffer
struct  theora_info
struct  theora_state
struct  theora_comment

Defines

#define OC_FAULT   -1
#define OC_EINVAL   -10
#define OC_DISABLED   -11
#define OC_BADHEADER   -20
#define OC_NOTFORMAT   -21
#define OC_VERSION   -22
#define OC_IMPL   -23
#define OC_BADPACKET   -24
#define OC_NEWPACKET   -25

Typedefs

typedef theora_comment theora_comment

Enumerations

enum  theora_colorspace { OC_CS_UNSPECIFIED, OC_CS_ITU_REC_470M, OC_CS_ITU_REC_470BG }

Functions

const char * theora_version_string (void)
ogg_uint32_t theora_version_number (void)
int theora_encode_init (theora_state *th, theora_info *c)
int theora_encode_YUVin (theora_state *t, yuv_buffer *yuv)
int theora_encode_packetout (theora_state *t, int last_p, ogg_packet *op)
int theora_encode_header (theora_state *t, ogg_packet *op)
int theora_encode_comment (theora_comment *tc, ogg_packet *op)
int theora_encode_tables (theora_state *t, ogg_packet *op)
int theora_decode_header (theora_info *ci, theora_comment *cc, ogg_packet *op)
int theora_decode_init (theora_state *th, theora_info *c)
int theora_decode_packetin (theora_state *th, ogg_packet *op)
int theora_decode_YUVout (theora_state *th, yuv_buffer *yuv)
double theora_granule_time (theora_state *th, ogg_int64_t granulepos)
ogg_int64_t theora_granule_frame (theora_state *th, ogg_int64_t granulepos)
void theora_info_init (theora_info *c)
void theora_info_clear (theora_info *c)
void theora_clear (theora_state *t)
void theora_comment_init (theora_comment *tc)
void theora_comment_add (theora_comment *tc, char *comment)
void theora_comment_add_tag (theora_comment *tc, char *tag, char *value)
char * theora_comment_query (theora_comment *tc, char *tag, int count)
int theora_comment_query_count (theora_comment *tc, char *tag)
void theora_comment_clear (theora_comment *tc)

Detailed Description

The libtheora C API.

Enumeration Type Documentation

enum theora_colorspace
 

A Colorspace.

Function Documentation

void theora_clear (  theora_state *  t  ) 
 

Free all internal data associated with a theora_state handle.

Parameters:
t A theora_state handle.

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 ???
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
) 
 

Input a YUV buffer into 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)

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.

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 vendor and version.

Returns:
a version string.

Generated on Wed Sep 15 22:40:11 2004 for libtheora by doxygen 1.3.8