theoraenc.h File Reference

The libtheoraenc C encoding API. More...

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

Go to the source code of this file.

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 0x8000.
#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.
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 th_enc_ctx	th_enc_ctx
	The encoder context.
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: Fill in a th_info structure with details on the format of the video you wish to encode. Allocate a th_enc_ctx handle with th_encode_alloc(). Perform any additional encoder configuration required with th_encode_ctl(). Repeatedly call th_encode_flushheader() to retrieve all the header packets. For each uncompressed frame: Submit the uncompressed frame via th_encode_ycbcr_in() Repeatedly call th_encode_packetout() to retrieve any video data packets that are ready. Call th_encode_free() to release all encoder memory.
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.
Defines
#define	_O_THEORA_THEORAENC_H_   (1)
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.

---

Detailed Description

The libtheoraenc C encoding API.

---

Define Documentation

#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.). Parameters: [out]  _buf  int: The maximum encoding speed level. Return values: 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. Parameters: [in]  _buf  th_huff_code[TH_NHUFFMAN_TABLES][TH_NDCT_TOKENS] Return values: 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. Parameters: [in]  _buf  ogg_uint32_t: The maximum distance between key frames. [out]  _buf  ogg_uint32_t: The actual maximum distance set. Return values: 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. Parameters: [in]  _buf  th_quant_info Return values: 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. Parameters: [in]  _buf  int: The new encoding speed level. 0 is slowest, larger values use less CPU. Return values: 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. Parameters: [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. Return values: TH_EFAULT  _enc_ctx or _buf is NULL. TH_EINVAL  _buf_sz is not sizeof(int). TH_IMPL  Not supported by this implementation.

---

Typedef Documentation

typedef struct th_enc_ctx th_enc_ctx

The encoder context.

---

Variable Documentation

const th_huff_code TH_VP31_HUFF_CODES[TH_NHUFFMAN_TABLES][TH_NDCT_TOKENS]

The Huffman tables used by VP3.

const th_quant_info TH_VP31_QUANT_INFO

The quantization parameters used by VP3.

---