libtheoraenc
C encoding API. More...
#include <ogg/ogg.h>
#include "codec.h"
Go to the source code of this file.
Defines | |
#define | _O_THEORA_THEORAENC_H_ (1) |
th_encode_ctl() codes | |
These are the available request codes for th_encode_ctl().
By convention, these are even, to distinguish them from the decoder control codes. Keep any experimental or vendor-specific values above | |
#define | TH_ENCCTL_SET_HUFFMAN_CODES (0) |
Sets the Huffman tables to use. | |
#define | TH_ENCCTL_SET_QUANT_PARAMS (2) |
Sets the quantization parameters to use. | |
#define | TH_ENCCTL_SET_KEYFRAME_FREQUENCY_FORCE (4) |
Sets the maximum distance between key frames. | |
#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. | |
Typedefs | |
Encoder state | |
The following data structure is opaque, and its contents are not publicly defined by this API.
Referring to its internals directly is unsupported, and may break without warning. | |
typedef struct th_enc_ctx | th_enc_ctx |
The encoder context. | |
Functions | |
Functions for encoding | |
You must link to libtheoraenc and libtheoradec if you use any of the functions in this section.The functions are listed in the order they are used in a typical encode. The basic steps are:
| |
th_enc_ctx * | th_encode_alloc (const th_info *_info) |
Allocates an encoder instance. | |
int | th_encode_ctl (th_enc_ctx *_enc, int _req, void *_buf, size_t _buf_sz) |
Encoder control function. | |
int | th_encode_flushheader (th_enc_ctx *_enc, th_comment *_comments, ogg_packet *_op) |
Outputs the next header packet. | |
int | th_encode_ycbcr_in (th_enc_ctx *_enc, th_ycbcr_buffer _ycbcr) |
Submits an uncompressed frame to the encoder. | |
int | th_encode_packetout (th_enc_ctx *_enc, int _last, ogg_packet *_op) |
Retrieves encoded video data packets. | |
void | th_encode_free (th_enc_ctx *_enc) |
Frees an allocated encoder instance. | |
Variables | |
const th_quant_info | TH_VP31_QUANT_INFO |
The quantization parameters used by VP3. | |
const th_huff_code | TH_VP31_HUFF_CODES [TH_NHUFFMAN_TABLES][TH_NDCT_TOKENS] |
The Huffman tables used by VP3. |
libtheoraenc
C encoding API.
#define _O_THEORA_THEORAENC_H_ (1) |
#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.).
[out] | _buf | int: The maximum encoding speed level. |
TH_EFAULT | _enc_ctx or _buf is NULL . | |
TH_EINVAL | _buf_sz is not sizeof(int) . | |
TH_IMPL | Not supported by this implementation in the current encoding mode. |
#define TH_ENCCTL_SET_HUFFMAN_CODES (0) |
Sets the Huffman tables to use.
The tables are copied, not stored by reference, so they can be freed after this call. NULL
may be specified to revert to the default tables.
[in] | _buf | th_huff_code[TH_NHUFFMAN_TABLES][TH_NDCT_TOKENS] |
TH_EFAULT | _enc_ctx is NULL . | |
TH_EINVAL | Encoding has already begun or one or more of the given tables is not full or prefix-free, _buf is NULL and _buf_sz is not zero, or _buf is non-NULL and _buf_sz is not sizeof(th_huff_code)*TH_NHUFFMAN_TABLES*TH_NDCT_TOKENS . | |
TH_IMPL | Not supported by this implementation. |
#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.
[in] | _buf | ogg_uint32_t : The maximum distance between key frames. |
[out] | _buf | ogg_uint32_t : The actual maximum distance set. |
TH_EFAULT | _enc_ctx or _buf is NULL . | |
TH_EINVAL | _buf_sz is not sizeof(ogg_uint32_t) . | |
TH_IMPL | Not supported by this implementation. |
#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. For the current encoder, scale[ci!=0][qi]
must be no greater than scale[ci!=0][qi-1]
and base[qti][pli][qi][ci]
must be no greater than base[qti][pli][qi-1][ci]
. These two conditions ensure that the actual quantizer for a given qti, pli, and ci does not increase as qi increases.
[in] | _buf | th_quant_info |
TH_EFAULT | _enc_ctx is NULL . | |
TH_EINVAL | Encoding has already begun, the quantization parameters do not meet one of the above stated conditions, _buf is NULL and _buf_sz is not zero, or _buf is non-NULL and _buf_sz is not sizeof(th_quant_info) . | |
TH_IMPL | Not supported by this implementation. |
#define TH_ENCCTL_SET_SPLEVEL (14) |
Sets the speed level.
By default, the slowest speed (0) is used.
[in] | _buf | int: The new encoding speed level. 0 is slowest, larger values use less CPU. |
TH_EFAULT | _enc_ctx or _buf is NULL . | |
TH_EINVAL | _buf_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. | |
TH_IMPL | Not supported by this implementation in the current encoding mode. |
#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.
[in] | _buf | int : a non-zero value to enable VP3 compatibility, or 0 to disable it (the default). |
[out] | _buf | int : 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. |
TH_EFAULT | _enc_ctx or _buf is NULL . | |
TH_EINVAL | _buf_sz is not sizeof(int) . | |
TH_IMPL | Not supported by this implementation. |
typedef struct th_enc_ctx th_enc_ctx |
The encoder context.
const th_huff_code TH_VP31_HUFF_CODES[TH_NHUFFMAN_TABLES][TH_NDCT_TOKENS] |
The Huffman tables used by VP3.
The quantization parameters used by VP3.