Functions for encoding | |
You must link to 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. |
th_enc_ctx* th_encode_alloc | ( | const th_info * | _info | ) |
Allocates an encoder instance.
_info | A th_info struct filled with the desired encoding parameters. |
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.
_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.
_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. |
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.
_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.
_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. |
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.
_enc | A th_enc_ctx handle. | |
_ycbcr | A buffer of Y'CbCr data to encode. If the width and height of the buffer matches the frame size the encoder was initialized with, the encoder will only reference the portion inside the picture region. Any data outside this region will be ignored, and need not map to a valid address. Alternatively, you can pass a buffer equal to the size of the picture region, if this is less than the full frame size. When using subsampled chroma planes, odd picture sizes or odd picture offsets may require an unexpected chroma plane size, and their use is generally discouraged, as they will not be well-supported by players and other media frameworks. See Section 4.4 of the Theora specification for details if you wish to use them anyway. |
0 | Success. | |
TH_EFAULT | _enc or _ycbcr is NULL . | |
TH_EINVAL | The buffer size matches neither the frame size nor the picture size the encoder was initialized with, or encoding has already completed. |