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:



th_enc_ctxth_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.


Generated on Mon Nov 3 10:42:44 2008 for libtheora by  doxygen 1.4.6