daala  0.0-1696-g7278368
Experimental Daala video codec API reference.
 All Data Structures Files Functions Variables Typedefs Macros Groups
Modules | Macros
Functions for Encoding

Modules

 Configuration keys for the encoder ctl interface.
 Encoder CTL settings.

Macros

#define OD_SET_QUANT   4000
 Set the quantizer scale.
#define OD_SET_COMPLEXITY   4002
 Configure the encoder's computational complexity level.
#define OD_GET_COMPLEXITY   4004
 Get the encoder's computational complexity level.
#define OD_SET_ACTIVITY_MASKING   4006
 Whether activity masking should be used or not.
#define OD_SET_QM   4008
 Which quantization matrix to use.
#define OD_SET_DERING   4010
 Whether the bilinear postprocessing filter should be used or not.
#define OD_SET_MC_CHROMA   4100
 Whether the motion compensation search should use the chroma planes in addition to the luma plane.
#define OD_SET_MV_RES_MIN   4102
 Minimum motion vectors resolution for the motion compensation search.
#define OD_SET_MV_LEVEL_MIN   4104
 Minimum motion vectors level for the motion compensation search.
#define OD_SET_MV_LEVEL_MAX   4106
 Maximum motion vectors level for the motion compensation search.
#define OD_SET_MC_SATD   4108
 Whether the SATD metric should be used in motion compensation or not.
#define OD_SET_B_FRAMES   4110
 Number of B frames used by encoder.
#define OD_SET_BITRATE   4112
 Sets the current encoding bitrate.
#define OD_SET_RATE_FLAGS   4114
 Modifies the default bitrate management behavior.
#define OD_SET_RATE_BUFFER   4116
 Sets the size of the bitrate management bit reservoir as a function of number of frames.
#define OD_2PASS_OUT   4118
 Enable pass 1 of two-pass encoding mode and retrieve the first pass metrics.
#define OD_2PASS_IN   4120
 Submits two-pass encoding metric data collected the first encoding pass to the second pass.

Functions for encoding

You must link to libdaalabase and libdaalaenc 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:

daala_enc_ctxdaala_encode_create (const daala_info *info)
 Allocates and initializes an encoder instance.
int daala_encode_ctl (daala_enc_ctx *enc, int req, void *buf, size_t buf_sz)
 Encoder control function.
int daala_encode_flush_header (daala_enc_ctx *enc, daala_comment *comments, daala_packet *dp)
 Outputs the next header packet.
int daala_encode_img_in (daala_enc_ctx *enc, daala_image *img, int duration)
 Submits an uncompressed frame to the encoder.
int daala_encode_packet_out (daala_enc_ctx *enc, int last, daala_packet *dp)
 Retrieves encoded video data packets.
void daala_encode_free (daala_enc_ctx *enc)
 Frees an allocated encoder instance.

Detailed Description

Macro Definition Documentation

#define OD_SET_QUANT   4000

Set the quantizer scale.

The passed buffer is interpreted as containing a single int. The valid range is 0-511.

#define OD_SET_COMPLEXITY   4002

Configure the encoder's computational complexity level.

See Also
OD_GET_COMPLEXITY
Parameters
[in]_bufint: The new encoder complexity level. Values must lie in the range 0...10, inclusive, with higher values requiring more CPU but generally producing better quality at a given bitrate.
#define OD_GET_COMPLEXITY   4004

Get the encoder's computational complexity level.

See Also
OD_SET_COMPLEXITY
Parameters
[in]_bufint: Returns a value in the range 0...10, inclusive. Higher values indicate higher CPU requirements, but generally producing better quality at a given bitrate.
#define OD_SET_ACTIVITY_MASKING   4006

Whether activity masking should be used or not.

Parameters
[in]_bufint: 0 to disable the use of activity masking, a non-zero value otherwise (the default).
#define OD_SET_QM   4008

Which quantization matrix to use.

Parameters
[in]_bufint: 0 => flat quantization matrix, 1 => HVS (the default).
#define OD_SET_DERING   4010

Whether the bilinear postprocessing filter should be used or not.

Parameters
[in]_bufint: 0 to disable the bilinear postprocessing filter, a non-zero value otherwise (the default).
#define OD_SET_MC_CHROMA   4100

Whether the motion compensation search should use the chroma planes in addition to the luma plane.

Parameters
[in]_bufint: 0 to disable the use of the chroma planes, a non-zero value otherwise (the default).
#define OD_SET_MV_RES_MIN   4102

Minimum motion vectors resolution for the motion compensation search.

Parameters
[in]_bufint: 0 => 1/8 pel (default), 1 => 1/4 pel, 2 => 1/2 pel
#define OD_SET_MV_LEVEL_MIN   4104

Minimum motion vectors level for the motion compensation search.

If this level is greater than the maximum level, the maximum level will be used instead.

Parameters
[in]_bufint: level between 0 and 4 Default: 0
#define OD_SET_MV_LEVEL_MAX   4106

Maximum motion vectors level for the motion compensation search.

Parameters
[in]_bufint: level between 0 and 4 Default: 4
#define OD_SET_MC_SATD   4108

Whether the SATD metric should be used in motion compensation or not.

Parameters
[in]_bufint: 0 to disable the use of SATD (the default), a non-zero value otherwise.
#define OD_SET_B_FRAMES   4110

Number of B frames used by encoder.

Parameters
[in]_bufint: The number of B frames. Values must lie in the range 0...OD_MAX_B_FRAMES, inclusive.
#define OD_SET_BITRATE   4112

Sets the current encoding bitrate.

Once a bitrate is set, the encoder must use a rate-controlled mode for all future frames (this restriction may be relaxed in a future version). Due to the buffer delay, the exact bitrate of each section of the encode is not guaranteed. The encoder may have already used more bits than allowed for the frames it has encoded, expecting to make them up in future frames, or it may have used fewer, holding the excess in reserve. The exact transition between two bitrates is not well-defined by this API, but may be affected by flags set with OD_SET_RATE_FLAGS. After a number of frames equal to the buffer delay, one may expect further output to average at the target bitrate.

Parameters
[in]buflong: The new target bitrate, in bits per second.
Return values
OD_SUCCESSSuccess.
OD_EFAULTenc or buf is NULL.
OD_EINVALThe target bitrate was not positive. A future version of this library may allow passing 0 to disabled rate-controlled mode and return to a quality-based mode, in which case this function will not return an error for that value.
OD_EIMPLNot supported by this implementation.
#define OD_SET_RATE_FLAGS   4114

Modifies the default bitrate management behavior.

Use to allow or disallow frame dropping, and to enable or disable capping bit reservoir overflows and underflows. See the list of available flags. The flags are set by default to OD_RATECTL_DROP_FRAMES|OD_RATECTL_CAP_OVERFLOW.

Parameters
[in]bufint: Any combination of the available flags:
Return values
OD_SUCCESSSuccess.
OD_EFAULTenc or buf is NULL.
OD_EINVALbuf_sz is not sizeof(int) or rate control is not enabled.
OD_EIMPLNot supported by this implementation in the current encoding mode.
#define OD_SET_RATE_BUFFER   4116

Sets the size of the bitrate management bit reservoir as a function of number of frames.

The reservoir size affects how quickly bitrate management reacts to instantaneous changes in the video complexity. Larger reservoirs react more slowly, and provide better overall quality, but require more buffering by a client, adding more latency to live streams. By default, libdaala sets the reservoir to the maximum distance between keyframes, subject to a minimum and maximum limit. This call may be used to increase or decrease the reservoir, increasing or decreasing the allowed temporary variance in bitrate. An implementation may impose some limits on the size of a reservoir it can handle, in which case the actual reservoir size may not be exactly what was requested. The actual value set will be returned.

Parameters
[in]bufint: Requested size of the reservoir measured in frames.
[out]bufint: The actual size of the reservoir set.
Return values
OD_EFAULTenc or buf is NULL.
OD_EINVALbuf_sz is not sizeof(int), or rate control is not enabled. The buffer has an implementation defined minimum and maximum size and the value in buf will be adjusted to match the actual value set.
OD_EIMPLNot supported by this implementation in the current encoding mode.
#define OD_2PASS_OUT   4118

Enable pass 1 of two-pass encoding mode and retrieve the first pass metrics.

Pass 1 mode must be enabled before the first frame is encoded, and a target bitrate must have already been specified to the encoder. Although this does not have to be the exact rate that will be used in the second pass, closer values may produce better results. The first call returns the size of the two-pass header data, along with some placeholder content, and sets the encoder into pass 1 mode implicitly. This call sets the encoder to pass 1 mode implicitly. Then, a subsequent call must be made after each call to daala_encode_img_in() to retrieve the metrics for that frame. An additional, final call must be made to retrieve the summary data, containing such information as the total number of frames, etc. This must be stored in place of the placeholder data that was returned in the first call, before the frame metrics data. All of this data must be presented back to the encoder during pass 2 using OD_2PASS_IN.

Parameters
[out]<tt>char*buf: Returns a pointer to internal storage containing the two pass metrics data. This storage is only valid until the next call, or until the encoder context is freed, and must be copied by the application.
Return values
>=0The number of bytes of metric data available in the returned buffer.
OD_EFAULTenc or buf is NULL.
OD_EINVALbuf_sz is not sizeof(char *), no target bitrate has been set, or the first call was made after the first frame was submitted for encoding.
OD_EIMPLNot supported by this implementation.
#define OD_2PASS_IN   4120

Submits two-pass encoding metric data collected the first encoding pass to the second pass.

The first call must be made before the first frame is encoded, and a target bitrate must have already been specified to the encoder. It sets the encoder to pass 2 mode implicitly; this cannot be disabled. The encoder may require reading data from some or all of the frames in advance, depending on, e.g., the reservoir size used in the second pass. You must call this function repeatedly before each frame to provide data until either a) it fails to consume all of the data presented or b) all of the pass 1 data has been consumed. In the first case, you must save the remaining data to be presented after the next frame. You can call this function with a NULL argument to get an upper bound on the number of bytes that will be required before the next frame.

When pass 2 is first enabled, the default bit reservoir is set to the entire file; this gives maximum flexibility but can lead to very high peak rates. You can subsequently set it to another value with OD_SET_RATE_BUFFER (e.g., to set it to the keyframe interval for non-live streaming), however, you may then need to provide more data before the next frame.

Parameters
[in]bufchar[]: A buffer containing the data returned by OD_2PASS_OUT in pass 1. You may pass NULL for buf to return an upper bound on the number of additional bytes needed before the next frame. The summary data returned at the end of pass 1 must be at the head of the buffer on the first call with a non-NULL buf, and the placeholder data returned at the start of pass 1 should be omitted. After each call you should advance this buffer by the number of bytes consumed.
Return values
>0The number of bytes of metric data required/consumed.
0No more data is required before the next frame.
OD_EFAULTenc is NULL.
OD_EINVALNo target bitrate has been set, or the first call was made after the first frame was submitted for encoding.
OD_ENOTFORMATThe data did not appear to be pass 1 from a compatible implementation of this library.
OD_EBADHEADERThe data was invalid; this may be returned when attempting to read an aborted pass 1 file that still has the placeholder data in place of the summary data.
OD_EIMPLNot supported by this implementation.

Function Documentation

daala_enc_ctx* daala_encode_create ( const daala_info info)

Allocates and initializes an encoder instance.

Parameters
infoA daala_info struct filled with the desired encoding parameters.
Returns
The initialized daala_enc_ctx handle.
Return values
NULLif the encoding parameters were invalid.
int daala_encode_ctl ( daala_enc_ctx enc,
int  req,
void *  buf,
size_t  buf_sz 
)

Encoder control function.

This is used to provide advanced control of the encoding process.

Parameters
encA daala_enc_ctx handle.
reqThe control code to process. See the list of available control codes for details.
bufThe parameters for this control code.
buf_szThe size of the parameter buffer.
int daala_encode_flush_header ( daala_enc_ctx enc,
daala_comment comments,
daala_packet dp 
)

Outputs the next header packet.

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

Parameters
encA daala_enc_ctx handle.
commentsThe metadata to place in the comment header, when it is encoded. Users should free the returned data with daala_comment_clear().
dpA daala_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 libdaala.
Returns
A positive value indicates that a header packet was successfully produced.
Return values
0No packet was produced, and no more header packets remain.
OD_EFAULTenc, comments or op was NULL.
int daala_encode_img_in ( daala_enc_ctx enc,
daala_image img,
int  duration 
)

Submits an uncompressed frame to the encoder.

Parameters
encA daala_enc_ctx handle.
imgA buffer of image data to encode.
durationThe duration to display the frame for, in timebase units. If a non-zero frame duration was specified in the header, then this parameter is ignored.
Return values
0Success.
OD_EFAULTenc or img was NULL.
OD_EINVALThe image size does not match the frame size the encoder was initialized with, or encoding has already completed.
int daala_encode_packet_out ( daala_enc_ctx enc,
int  last,
daala_packet dp 
)

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
Current the encoder operates in a one-frame-in, one-packet-out manner. However, this may be changed in the future.
Parameters
encA daala_enc_ctx handle. This ensures that a proper EOS flag is set on the last packet.
dpA daala_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 libdaala.
Returns
A positive value indicates that a video data packet was successfully produced.
Return values
0No packet was produced, and no more encoded video data remains.
OD_EFAULTenc or op was NULL.
void daala_encode_free ( daala_enc_ctx enc)

Frees an allocated encoder instance.

Parameters
encA daala_enc_ctx handle.