theoraenc.h File Reference

The 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 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.
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 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: 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.
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.