Files | |
file | theora.h |
The libtheora pre-1.0 legacy C API. | |
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... | |
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) |
Sets the quantization parameters to use. | |
#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. | |
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 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. |
|
Header packet was corrupt/invalid.
|
|
Packet is corrupt.
|
|
Requested action is disabled.
|
|
Packet is a dropped frame.
|
|
Library encountered invalid internal data.
|
|
General failure.
|
|
Feature or action not implemented.
|
|
Packet is an (ignorable) unhandled extension.
|
|
Packet is not a theora packet.
|
|
Bitstream version is not handled.
|
|
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. |
|
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. |
|
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. |
|
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.).
|
|
Sets the maximum distance between key frames.
This can be changed during an encode, but will be bounded by
|
|
Sets the quantization parameters to use.
The parameters are copied, not stored by reference, so they can be freed after this call.
|
|
Sets the speed level. By default a speed value of 1 is used.
|
|
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.
|
|
A Colorspace.
|
|
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. |
|
Free all internal data associated with a theora_state handle.
|
|
Add a comment to an initialized theora_comment structure.
|
|
Add a comment to an initialized theora_comment structure.
|
|
Clear an allocated theora_comment struct so that it can be freed.
|
|
Initialize an allocated theora_comment structure.
|
|
Look up a comment value by tag.
|
|
Look up the number of instances of a tag.
|
|
Encoder control function. This is used to provide advanced control the encoding process.
|
|
Decode an Ogg packet, with the expectation that the packet contains an initial header, comment data or codebook tables.
|
|
Initialize a theora_state handle for decoding.
|
|
Input a packet containing encoded data into the theora decoder.
|
|
Output the next available frame of decoded YUV data.
|
|
Request a comment header packet from provided metadata. A pointer to the comment data is placed in a user-provided ogg_packet structure.
|
|
Request a packet containing the initial header. A pointer to the header data is placed in a user-provided ogg_packet structure.
|
|
Initialize the theora encoder.
|
|
Request the next packet of encoded video. The encoded data is placed in a user-provided ogg_packet structure.
|
|
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.
|
|
Submit a YUV buffer to the theora encoder.
|
|
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.
|
|
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.
|
|
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.
|
|
Clear a theora_info structure. All values within the given theora_info structure are cleared, and associated internal codec setup data is freed.
|
|
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.
|
|
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.
|
|
Report whether a theora packet is a keyframe or not.
|
|
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)
|
|
Retrieve a human-readable string to identify the encoder vendor and version.
|