#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. | |
#define | OC_DUPFRAME 1 |
Packet is a dropped frame. | |
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... | |
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 *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 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) |
Clear an allocated theora_comment struct so that it can be freed. |
enum theora_colorspace |
enum 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.
void theora_clear | ( | theora_state * | t | ) |
void theora_comment_add | ( | theora_comment * | tc, | |
char * | comment | |||
) |
Add a comment to an initialized theora_comment structure.
tc | A previously initialized theora comment structure | |
comment | A null-terminated string encoding the comment in the form "TAG=the value" |
void theora_comment_add_tag | ( | theora_comment * | tc, | |
char * | tag, | |||
char * | value | |||
) |
Add a comment to an initialized theora_comment structure.
tc | A previously initialized theora comment structure | |
tag | A null-terminated string containing the tag associated with the comment. | |
value | The corresponding value as a null-terminated string |
void theora_comment_clear | ( | theora_comment * | tc | ) |
Clear an allocated theora_comment struct so that it can be freed.
tc | An allocated theora_comment structure. |
void theora_comment_init | ( | theora_comment * | tc | ) |
Initialize an allocated theora_comment structure.
tc | An allocated theora_comment structure |
char* theora_comment_query | ( | theora_comment * | tc, | |
char * | tag, | |||
int | count | |||
) |
Look up a comment value by tag.
tc | Tn 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. |
NULL | No matching tag is found |
int theora_comment_query_count | ( | theora_comment * | tc, | |
char * | tag | |||
) |
Look up the number of instances of a tag.
tc | An initialized theora_comment structure | |
tag | The tag to look up |
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.
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. |
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 |
int theora_decode_init | ( | theora_state * | th, | |
theora_info * | c | |||
) |
Initialize a theora_state handle for decoding.
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(). |
0 | Success |
int theora_decode_packetin | ( | theora_state * | th, | |
ogg_packet * | op | |||
) |
Input a packet containing encoded data into the theora decoder.
th | A theora_state handle previously initialized for decoding. | |
op | An ogg_packet containing encoded theora data. |
0 | Success | |
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.
th | A theora_state handle previously initialized for decoding. | |
yuv | A yuv_buffer in which libtheora should place the decoded data. |
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.
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. |
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.
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. |
0 | Success |
int theora_encode_init | ( | theora_state * | th, | |
theora_info * | ti | |||
) |
Initialize the theora encoder.
th | The theora_state handle to initialize for encoding. | |
ti | A theora_info struct filled with the desired encoding parameters. |
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.
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. |
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.
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. |
0 | Success |
int theora_encode_YUVin | ( | theora_state * | t, | |
yuv_buffer * | yuv | |||
) |
Submit a YUV buffer to the theora encoder.
t | A theora_state handle previously initialized for encoding. | |
yuv | A buffer of YUV data to encode. |
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.
th | A previously initialized theora_state handle (encode or decode) | |
granulepos | The granulepos to convert. |
-1 | The given granulepos is undefined (i.e. negative) |
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.
ti | A previously initialized theora_info struct |
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.
th | A previously initialized theora_state handle (encode or decode) | |
granulepos | The granulepos to convert. |
-1. | The given granulepos is undefined (i.e. negative), or | |
-1. | The function has been disabled because floating point support is not available. |
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.
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.
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.
op | An ogg_packet containing encoded theora data. |
1 | The packet is a header packet | |
0 | The packet is not a header packet (and so contains frame data) |
int theora_packet_iskeyframe | ( | ogg_packet * | op | ) |
Report whether a theora packet is a keyframe or not.
op | An ogg_packet containing encoded theora data. |
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 |
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)
const char* theora_version_string | ( | void | ) |
Retrieve a human-readable string to identify the encoder vendor and version.