libtheora 1.1.1
Data Structures | Typedefs | Enumerations
theora.h File Reference

The libtheora pre-1.0 legacy C API. More...

#include <stddef.h>
#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...
 

Typedefs

typedef struct theora_comment theora_comment
 Comment header metadata.
 

Enumerations

enum  theora_colorspace { OC_CS_UNSPECIFIED , OC_CS_ITU_REC_470M , OC_CS_ITU_REC_470BG , OC_CS_NSPACES }
 A Colorspace. More...
 
enum  theora_pixelformat { OC_PF_420 , OC_PF_RSVD , OC_PF_422 , OC_PF_444 }
 A Chroma subsampling. More...
 

theora_control() codes

#define TH_DECCTL_GET_PPLEVEL_MAX   (1)
 Get the maximum post-processing level.
 
#define TH_DECCTL_SET_PPLEVEL   (3)
 Set the post-processing level.
 
#define TH_ENCCTL_SET_KEYFRAME_FREQUENCY_FORCE   (4)
 Sets the maximum distance between key frames.
 
#define TH_DECCTL_SET_GRANPOS   (5)
 Set the granule position.
 
#define TH_ENCCTL_SET_QUANT_PARAMS   (2)
 
 
#define TH_ENCCTL_SET_VP3_COMPATIBLE   (10)
 Disables any encoder features that would prevent lossless transcoding back to VP3.
 
#define TH_ENCCTL_GET_SPLEVEL_MAX   (12)
 Gets the maximum speed level.
 
#define TH_ENCCTL_SET_SPLEVEL   (14)
 Sets the speed level.
 
#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.
 
#define OC_DUPFRAME   1
 Packet is a dropped frame.
 
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 *ti)
 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.
 
int theora_granule_shift (theora_info *ti)
 Report the granulepos shift radix.
 
ogg_int64_t theora_granule_frame (theora_state *th, ogg_int64_t granulepos)
 Convert a granulepos to an absolute frame index, starting at 0.
 
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)
 Clear an allocated theora_comment struct so that it can be freed.
 
int theora_control (theora_state *th, int req, void *buf, size_t buf_sz)
 Encoder control function.
 

Detailed Description

The libtheora pre-1.0 legacy C API.

Introduction

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.

Overview

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;
      
    theora_info_init(&info);
    theora_comment_init(&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.

Macro Definition Documentation

◆ OC_BADHEADER

#define OC_BADHEADER   -20

Header packet was corrupt/invalid.

◆ OC_BADPACKET

#define OC_BADPACKET   -24

Packet is corrupt.

◆ OC_DISABLED

#define OC_DISABLED   -11

Requested action is disabled.

◆ OC_DUPFRAME

#define OC_DUPFRAME   1

Packet is a dropped frame.

◆ OC_EINVAL

#define OC_EINVAL   -10

Library encountered invalid internal data.

◆ OC_FAULT

#define OC_FAULT   -1

General failure.

◆ OC_IMPL

#define OC_IMPL   -23

Feature or action not implemented.

◆ OC_NEWPACKET

#define OC_NEWPACKET   -25

Packet is an (ignorable) unhandled extension.

◆ OC_NOTFORMAT

#define OC_NOTFORMAT   -21

Packet is not a theora packet.

◆ OC_VERSION

#define OC_VERSION   -22

Bitstream version is not handled.

◆ TH_DECCTL_GET_PPLEVEL_MAX

#define TH_DECCTL_GET_PPLEVEL_MAX   (1)

Get the maximum post-processing level.

The decoder supports a post-processing filter that can improve the appearance of the decoded images. This returns the highest level setting for this post-processor, corresponding to maximum improvement and computational expense.

◆ TH_DECCTL_SET_GRANPOS

#define TH_DECCTL_SET_GRANPOS   (5)

Set the granule position.

Call this after a seek, to update the internal granulepos in the decoder, to insure that subsequent frames are marked properly. If you track timestamps yourself and do not use the granule postion returned by the decoder, then you do not need to use this control.

◆ TH_DECCTL_SET_PPLEVEL

#define TH_DECCTL_SET_PPLEVEL   (3)

Set the post-processing level.

Sets the level of post-processing to use when decoding the compressed stream. This must be a value between zero (off) and the maximum returned by TH_DECCTL_GET_PPLEVEL_MAX.

◆ TH_ENCCTL_GET_SPLEVEL_MAX

#define TH_ENCCTL_GET_SPLEVEL_MAX   (12)

Gets the maximum speed level.

Higher speed levels favor quicker encoding over better quality per bit. Depending on the encoding mode, and the internal algorithms used, quality may actually improve, but in this case bitrate will also likely increase. In any case, overall rate/distortion performance will probably decrease. The maximum value, and the meaning of each value, may change depending on the current encoding mode (VBR vs. CQI, etc.).

Parameters
[out]bufint: The maximum encoding speed level.
Return values
OC_FAULTtheora_state or buf is NULL.
OC_EINVALbuf_sz is not sizeof(int).
OC_IMPLNot supported by this implementation in the current encoding mode.

◆ TH_ENCCTL_SET_KEYFRAME_FREQUENCY_FORCE

#define TH_ENCCTL_SET_KEYFRAME_FREQUENCY_FORCE   (4)

Sets the maximum distance between key frames.

This can be changed during an encode, but will be bounded by 1<<th_info::keyframe_granule_shift. If it is set before encoding begins, th_info::keyframe_granule_shift will be enlarged appropriately.

Parameters
[in]bufogg_uint32_t: The maximum distance between key frames.
[out]bufogg_uint32_t: The actual maximum distance set.
Return values
OC_FAULTtheora_state or buf is NULL.
OC_EINVALbuf_sz is not sizeof(ogg_uint32_t).
OC_IMPLNot supported by this implementation.

◆ TH_ENCCTL_SET_QUANT_PARAMS

#define TH_ENCCTL_SET_QUANT_PARAMS   (2)

Sets the quantization parameters to use. The parameters are copied, not stored by reference, so they can be freed after this call. NULL may be specified to revert to the default parameters.

Parameters
[in]bufth_quant_info
Return values
OC_FAULTtheora_state is NULL.
OC_EINVALEncoding has already begun, the quantization parameters are not acceptable to this version of the encoder, buf is NULL and buf_sz is not zero, or buf is non-NULL and buf_sz is not sizeof(th_quant_info).
OC_IMPLNot supported by this implementation.

◆ TH_ENCCTL_SET_SPLEVEL

#define TH_ENCCTL_SET_SPLEVEL   (14)

Sets the speed level.

By default a speed value of 1 is used.

Parameters
[in]bufint: The new encoding speed level. 0 is slowest, larger values use less CPU.
Return values
OC_FAULTtheora_state or buf is NULL.
OC_EINVALbuf_sz is not sizeof(int), or the encoding speed level is out of bounds. The maximum encoding speed level may be implementation- and encoding mode-specific, and can be obtained via TH_ENCCTL_GET_SPLEVEL_MAX.
OC_IMPLNot supported by this implementation in the current encoding mode.

◆ TH_ENCCTL_SET_VP3_COMPATIBLE

#define TH_ENCCTL_SET_VP3_COMPATIBLE   (10)

Disables any encoder features that would prevent lossless transcoding back to VP3.

This primarily means disabling block-level QI values and not using 4MV mode when any of the luma blocks in a macro block are not coded. It also includes using the VP3 quantization tables and Huffman codes; if you set them explicitly after calling this function, the resulting stream will not be VP3-compatible. If you enable VP3-compatibility when encoding 4:2:2 or 4:4:4 source material, or when using a picture region smaller than the full frame (e.g. a non-multiple-of-16 width or height), then non-VP3 bitstream features will still be disabled, but the stream will still not be VP3-compatible, as VP3 was not capable of encoding such formats. If you call this after encoding has already begun, then the quantization tables and codebooks cannot be changed, but the frame-level features will be enabled or disabled as requested.

Parameters
[in]bufint: a non-zero value to enable VP3 compatibility, or 0 to disable it (the default).
[out]bufint: 1 if all bitstream features required for VP3-compatibility could be set, and 0 otherwise. The latter will be returned if the pixel format is not 4:2:0, the picture region is smaller than the full frame, or if encoding has begun, preventing the quantization tables and codebooks from being set.
Return values
OC_FAULTtheora_state or buf is NULL.
OC_EINVALbuf_sz is not sizeof(int).
OC_IMPLNot supported by this implementation.

Typedef Documentation

◆ 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

◆ theora_colorspace

A Colorspace.

Enumerator
OC_CS_UNSPECIFIED 

The colorspace is unknown or unspecified.

OC_CS_ITU_REC_470M 

This is the best option for 'NTSC' content.

OC_CS_ITU_REC_470BG 

This is the best option for 'PAL' content.

OC_CS_NSPACES 

This marks the end of the defined colorspaces.

◆ theora_pixelformat

A Chroma subsampling.

These enumerate the available chroma subsampling options supported by the theora format. See Section 4.4 of the specification for exact definitions.

Enumerator
OC_PF_420 

Chroma subsampling by 2 in each direction (4:2:0)

OC_PF_RSVD 

Reserved value.

OC_PF_422 

Horizonatal chroma subsampling by 2 (4:2:2)

OC_PF_444 

No chroma subsampling at all (4:4:4)

Function Documentation

◆ theora_clear()

void theora_clear ( theora_state t)

Free all internal data associated with a theora_state handle.

Parameters
tA theora_state handle.

◆ theora_comment_add()

void theora_comment_add ( theora_comment tc,
char *  comment 
)

Add a comment to an initialized theora_comment structure.

Parameters
tcA previously initialized theora comment structure
commentA null-terminated string encoding the comment in the form "TAG=the value"

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.

◆ theora_comment_add_tag()

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

Add a comment to an initialized theora_comment structure.

Parameters
tcA previously initialized theora comment structure
tagA null-terminated string containing the tag associated with the comment.
valueThe 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.

◆ theora_comment_clear()

void theora_comment_clear ( theora_comment tc)

Clear an allocated theora_comment struct so that it can be freed.

Parameters
tcAn allocated theora_comment structure.

◆ theora_comment_init()

void theora_comment_init ( theora_comment tc)

Initialize an allocated theora_comment structure.

Parameters
tcAn allocated theora_comment structure

◆ theora_comment_query()

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

Look up a comment value by tag.

Parameters
tcTn initialized theora_comment structure
tagThe tag to look up
countThe 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.
Returns
A pointer to the queried tag's value
Return values
NULLNo matching tag is found
Note
Use theora_comment_query_count() to get the legal range for the count parameter.

◆ theora_comment_query_count()

int theora_comment_query_count ( theora_comment tc,
char *  tag 
)

Look up the number of instances of a tag.

Parameters
tcAn initialized theora_comment structure
tagThe 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.

◆ theora_control()

int theora_control ( theora_state th,
int  req,
void *  buf,
size_t  buf_sz 
)

Encoder control function.

This is used to provide advanced control the encoding process.

Parameters
thA theora_state handle.
reqThe control code to process. See the list of available control codes" for details.
bufThe parameters for this control code.
buf_szThe size of the parameter buffer.

◆ theora_decode_header()

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
ciA 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.
ccA theora_comment structure to fill. If op contains comment data, theora_decode_header() will fill cc with the parsed comments.
opAn ogg_packet structure which you expect contains an initial header, comment data or codebook tables.
Return values
OC_BADHEADERop 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_VERSIONThe packet data of op is an initial header with a version which is incompatible with this version of libtheora.
OC_NEWPACKETthe stream being decoded has an incompatible (future) version and contains an unknown signature.
0Success
Note
The normal usage is that theora_decode_header() be called on the first three packets of a theora logical bitstream in succession.

◆ theora_decode_init()

int theora_decode_init ( theora_state th,
theora_info c 
)

Initialize a theora_state handle for decoding.

Parameters
thThe theora_state handle to initialize.
cA theora_info struct filled with the desired decoding parameters. This is of course usually obtained from a previous call to theora_decode_header().
Return values
0Success

◆ theora_decode_packetin()

int theora_decode_packetin ( theora_state th,
ogg_packet *  op 
)

Input a packet containing encoded data into the theora decoder.

Parameters
thA theora_state handle previously initialized for decoding.
opAn ogg_packet containing encoded theora data.
Return values
0Success
OC_BADPACKETop does not contain encoded video data

◆ theora_decode_YUVout()

int theora_decode_YUVout ( theora_state th,
yuv_buffer yuv 
)

Output the next available frame of decoded YUV data.

Parameters
thA theora_state handle previously initialized for decoding.
yuvA yuv_buffer in which libtheora should place the decoded data. Note that the buffer struct itself is allocated by the user, but that the luma and chroma pointers will be filled in by the library. Also note that these luma and chroma regions should be considered read-only by the user.
Return values
0Success

◆ theora_encode_comment()

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
tcA theora_comment structure filled with the desired metadata
opAn 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
0Success

◆ theora_encode_header()

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
tA theora_state handle previously initialized for encoding.
opAn 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
0Success

◆ theora_encode_init()

int theora_encode_init ( theora_state th,
theora_info ti 
)

Initialize the theora encoder.

Parameters
thThe theora_state handle to initialize for encoding.
tiA theora_info struct filled with the desired encoding parameters.
Return values
0Success

◆ theora_encode_packetout()

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
tA theora_state handle previously initialized for encoding.
last_pwhether this is the last packet the encoder should produce.
opAn 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
0No internal storage exists OR no packet is ready
-1The encoding process has completed
1Success

◆ theora_encode_tables()

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
tA theora_state handle previously initialized for encoding.
opAn 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
0Success

◆ theora_encode_YUVin()

int theora_encode_YUVin ( theora_state t,
yuv_buffer yuv 
)

Submit a YUV buffer to the theora encoder.

Parameters
tA theora_state handle previously initialized for encoding.
yuvA buffer of YUV data to encode. Note that both the yuv_buffer struct and the luma/chroma buffers within should be allocated by the user.
Return values
OC_EINVALEncoder is not ready, or is finished.
-1The size of the given frame differs from those previously input
0Success

◆ theora_granule_frame()

ogg_int64_t theora_granule_frame ( theora_state th,
ogg_int64_t  granulepos 
)

Convert a granulepos to an absolute frame index, starting at 0.

The granulepos is interpreted in the context of a given theora_state handle.

Note that while the granulepos encodes the frame count (i.e. starting from 1) this call returns the frame index, starting from zero. Thus One can calculate the presentation time by multiplying the index by the rate.

Parameters
thA previously initialized theora_state handle (encode or decode)
granuleposThe granulepos to convert.
Returns
The frame index corresponding to granulepos.
Return values
-1The given granulepos is undefined (i.e. negative)

Thus function was added in the 1.0alpha4 release.

◆ theora_granule_shift()

int theora_granule_shift ( theora_info ti)

Report the granulepos shift radix.

When embedded in Ogg, Theora uses a two-part granulepos, splitting the 64-bit field into two pieces. The more-significant section represents the frame count at the last keyframe, and the less-significant section represents the count of frames since the last keyframe. In this way the overall field is still non-decreasing with time, but usefully encodes a pointer to the last keyframe, which is necessary for correctly restarting decode after a seek.

This function reports the number of bits used to represent the distance to the last keyframe, and thus how the granulepos field must be shifted or masked to obtain the two parts.

Since libtheora returns compressed data in an ogg_packet structure, this may be generally useful even if the Theora packets are not being used in an Ogg container.

Parameters
tiA previously initialized theora_info struct
Returns
The bit shift dividing the two granulepos fields

This function was added in the 1.0alpha5 release.

◆ theora_granule_time()

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, and gives the end time of a frame's presentation as used in Ogg mux ordering.

Parameters
thA previously initialized theora_state handle (encode or decode)
granuleposThe granulepos to convert.
Returns
The absolute time in seconds corresponding to granulepos. 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 granulepos is undefined (i.e. negative), or
-1.The function has been disabled because floating point support is not available.

◆ theora_info_clear()

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
cA theora_info struct to initialize.

◆ theora_info_init()

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
cA theora_info struct to initialize.

◆ theora_packet_isheader()

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
opAn ogg_packet containing encoded theora data.
Return values
1The packet is a header packet
0The packet is not a header packet (and so contains frame data)

Thus function was added in the 1.0alpha4 release.

◆ theora_packet_iskeyframe()

int theora_packet_iskeyframe ( ogg_packet *  op)

Report whether a theora packet is a keyframe or not.

Parameters
opAn ogg_packet containing encoded theora data.
Return values
1The packet contains a keyframe image
0The packet is contains an interframe delta
-1The packet is not an image data packet at all

Thus function was added in the 1.0alpha4 release.

◆ theora_version_number()

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.

◆ theora_version_string()

const char * theora_version_string ( void  )

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

Returns
A version string.