Functions for Encoding


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.

Function Documentation

th_enc_ctx* th_encode_alloc ( const th_info _info  ) 

Allocates an encoder instance.

Parameters:
_info A th_info struct filled with the desired encoding parameters.
Returns:
The initialized th_enc_ctx handle.
Return values:
NULL If the encoding parameters were invalid.

int th_encode_ctl ( th_enc_ctx _enc,
int  _req,
void *  _buf,
size_t  _buf_sz 
)

Encoder control function.

This is used to provide advanced control the encoding process.

Parameters:
_enc A th_enc_ctx handle.
_req The control code to process. See the list of available control codes for details.
_buf The parameters for this control code.
_buf_sz The size of the parameter buffer.

int th_encode_flushheader ( th_enc_ctx _enc,
th_comment _comments,
ogg_packet *  _op 
)

Outputs the next header packet.

This should be called repeatedly after encoder initialization until it returns 0 in order to get all of the header packets, in order, before encoding actual video data.

Parameters:
_enc A th_enc_ctx handle.
_comments The metadata to place in the comment header, when it is encoded.
_op An ogg_packet structure to fill. All of the elements of this structure will be set, including a pointer to the header data. The memory for the header data is owned by libtheoraenc, and may be invalidated when the next encoder function is called.
Returns:
A positive value indicates that a header packet was successfully produced.
Return values:
0 No packet was produced, and no more header packets remain.
TH_EFAULT _enc, _comments, or _op was NULL.

void th_encode_free ( th_enc_ctx _enc  ) 

Frees an allocated encoder instance.

Parameters:
_enc A th_enc_ctx handle.

int th_encode_packetout ( th_enc_ctx _enc,
int  _last,
ogg_packet *  _op 
)

Retrieves encoded video data packets.

This should be called repeatedly after each frame is submitted to flush any encoded packets, until it returns 0. The encoder will not buffer these packets as subsequent frames are compressed, so a failure to do so will result in lost video data.

Note:
Currently the encoder operates in a one-frame-in, one-packet-out manner. However, this may be changed in the future.
Parameters:
_enc A th_enc_ctx handle.
_last Set this flag to a non-zero value if no more uncompressed frames will be submitted. This ensures that a proper EOS flag is set on the last packet.
_op An ogg_packet structure to fill. All of the elements of this structure will be set, including a pointer to the video data. The memory for the video data is owned by libtheoraenc, and may be invalidated when the next encoder function is called.
Returns:
A positive value indicates that a video data packet was successfully produced.
Return values:
0 No packet was produced, and no more encoded video data remains.
TH_EFAULT _enc or _op was NULL.

int th_encode_ycbcr_in ( th_enc_ctx _enc,
th_ycbcr_buffer  _ycbcr 
)

Submits an uncompressed frame to the encoder.

Parameters:
_enc A th_enc_ctx handle.
_ycbcr A buffer of Y'CbCr data to encode.
Return values:
0 Success.
TH_EFAULT _enc or _ycbcr is NULL.
TH_EINVAL The buffer size does not match the frame size the encoder was initialized with, or encoding has already completed.


Generated on Wed Aug 5 12:38:08 2009 for libtheora by  doxygen 1.5.8