Logo Search packages:      
Sourcecode: libtheora version File versions  Download package

theora.h File Reference

Detailed Description

The libtheora pre-1.0 legacy C API.


This is the documentation for the libtheora legacy C API, declared in the theora.h header, which describes the old interface used before the 1.0 release. This API was widely deployed for several years and remains supported, but for new code we recommend the cleaner API declared in theoradec.h and theoraenc.h.

libtheora is the reference implementation for Theora, a free video codec. Theora is derived from On2's VP3 codec with improved integration with Ogg multimedia formats by Xiph.Org.


This library will both decode and encode theora packets to/from raw YUV frames. In either case, the packets will most likely either come from or need to be embedded in an Ogg stream. Use libogg or liboggz to extract/package these packets.

Decoding Process

Decoding can be separated into the following steps:
  1. initialise theora_info and theora_comment structures using theora_info_init() and theora_comment_init():
     theora_info     info;
     theora_comment  comment;
  2. retrieve header packets from Ogg stream (there should be 3) and decode into theora_info and theora_comment structures using theora_decode_header(). See Identifying Theora Packets for more information on identifying which packets are theora packets.
     int i;
     for (i = 0; i < 3; i++)
       (get a theora packet "op" from the Ogg stream)
       theora_decode_header(&info, &comment, op);
  3. initialise the decoder based on the information retrieved into the theora_info struct by theora_decode_header(). You will need a theora_state struct.
     theora_state state;
     theora_decode_init(&state, &info);
  4. pass in packets and retrieve decoded frames! See the yuv_buffer documentation for information on how to retrieve raw YUV data.
     yuf_buffer buffer;
     while (last packet was not e_o_s) {
       (get a theora packet "op" from the Ogg stream)
       theora_decode_packetin(&state, op);
       theora_decode_YUVout(&state, &buffer);

Identifying Theora Packets

All streams inside an Ogg file have a unique serial_no attached to the stream. Typically, you will want to

Note that you cannot use theora_packet_isheader() to determine if a packet is a theora packet or not, as this function does not perform any checking beyond whether a header bit is present. Instead, use the theora_decode_header() function and check the return value; or examine the header bytes at the beginning of the Ogg page.

Definition in file theora.h.

#include <stddef.h>
#include <ogg/ogg.h>

Go to the source code of this file.


struct  theora_comment
struct  theora_info
struct  theora_state
struct  yuv_buffer


#define OC_BADHEADER   -20
#define OC_BADPACKET   -24
#define OC_DISABLED   -11
#define OC_DUPFRAME   1
#define OC_EINVAL   -10
#define OC_FAULT   -1
#define OC_IMPL   -23
#define OC_NEWPACKET   -25
#define OC_NOTFORMAT   -21
#define OC_VERSION   -22
theora_control() codes
#define TH_ENCCTL_SET_SPLEVEL   (14)


enum  theora_colorspace { OC_CS_UNSPECIFIED, OC_CS_ITU_REC_470M, OC_CS_ITU_REC_470BG, OC_CS_NSPACES }
enum  theora_pixelformat { OC_PF_420, OC_PF_RSVD, OC_PF_422, OC_PF_444 }


void theora_clear (theora_state *t)
void theora_comment_add (theora_comment *tc, char *comment)
void theora_comment_add_tag (theora_comment *tc, char *tag, char *value)
void theora_comment_clear (theora_comment *tc)
void theora_comment_init (theora_comment *tc)
char * theora_comment_query (theora_comment *tc, char *tag, int count)
int theora_comment_query_count (theora_comment *tc, char *tag)
int theora_control (theora_state *th, int req, void *buf, size_t buf_sz)
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)
int theora_encode_comment (theora_comment *tc, ogg_packet *op)
int theora_encode_header (theora_state *t, ogg_packet *op)
int theora_encode_init (theora_state *th, theora_info *ti)
int theora_encode_packetout (theora_state *t, int last_p, ogg_packet *op)
int theora_encode_tables (theora_state *t, ogg_packet *op)
int theora_encode_YUVin (theora_state *t, yuv_buffer *yuv)
ogg_int64_t theora_granule_frame (theora_state *th, ogg_int64_t granulepos)
int theora_granule_shift (theora_info *ti)
double theora_granule_time (theora_state *th, ogg_int64_t granulepos)
void theora_info_clear (theora_info *c)
void theora_info_init (theora_info *c)
int theora_packet_isheader (ogg_packet *op)
int theora_packet_iskeyframe (ogg_packet *op)
ogg_uint32_t theora_version_number (void)
const char * theora_version_string (void)

Generated by  Doxygen 1.6.0   Back to index