daala  0.0-1185-g52bbd43-dirty
Experimental Daala video codec API reference.
Macros
daalaenc.h File Reference

The libdaala C encoding API. More...

#include "codec.h"
#include <ogg/ogg.h>

Go to the source code of this file.

Macros

#define _daala_daalaenc_H   (1)
 

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 struct daala_enc_ctx daala_enc_ctx
 The encoder context.
 

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:

  • Fill in a daala_info structure with details on the format of the video you wish to encode.
  • Allocate a daala_enc_ctx handle with daala_encode_alloc().
  • Perform any additional encoder configuration required with daala_encode_ctl().
  • Repeatedly call daala_encode_flusheader() to retrieve all the header packets.
  • For each uncompressed frame:
  • Call daala_encode_free() to release all encoder memory.
#define OD_SET_QUANT   4000
 Set the quantizer scale. More...
 
#define OD_SET_COMPLEXITY   4002
 Configure the encoder's computational complexity level. More...
 
#define OD_GET_COMPLEXITY   4004
 Get the encoder's computational complexity level. More...
 
#define OD_SET_USE_ACTIVITY_MASKING   4006
 Whether activity masking should be used or not. More...
 
#define OD_SET_QM   4008
 Which quantization matrix to use. More...
 
#define OD_SET_USE_DERING   4010
 Whether the bilinear postprocessing filter should be used or not. More...
 
#define OD_SET_MC_USE_CHROMA   4100
 Whether the motion compensation search should use the chroma planes in addition to the luma plane. More...
 
#define OD_SET_MV_RES_MIN   4102
 Minimum motion vectors resolution for the motion compensation search. More...
 
#define OD_SET_MV_LEVEL_MIN   4104
 Minimum motion vectors level for the motion compensation search. More...
 
#define OD_SET_MV_LEVEL_MAX   4106
 Maximum motion vectors level for the motion compensation search. More...
 
#define OD_SET_MC_USE_SATD   4108
 Whether the SATD metric should be used in motion compensation or not. More...
 
daala_enc_ctxdaala_encode_create (const daala_info *info)
 Allocates and initializes an encoder instance. More...
 
int daala_encode_ctl (daala_enc_ctx *enc, int req, void *buf, size_t buf_sz)
 Encoder control function. More...
 
int daala_encode_flush_header (daala_enc_ctx *enc, daala_comment *comments, ogg_packet *op)
 Outputs the next header packet. More...
 
int daala_encode_img_in (daala_enc_ctx *enc, od_img *img, int duration)
 Submits an uncompressed frame to the encoder. More...
 
int daala_encode_packet_out (daala_enc_ctx *enc, int last, ogg_packet *op)
 Retrieves encoded video data packets. More...
 
void daala_encode_free (daala_enc_ctx *enc)
 Frees an allocated encoder instance. More...
 

Detailed Description

The libdaala C encoding API.

Macro Definition Documentation

◆ OD_SET_QUANT

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

◆ OD_SET_COMPLEXITY

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

◆ OD_GET_COMPLEXITY

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

◆ OD_SET_USE_ACTIVITY_MASKING

#define OD_SET_USE_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).

◆ OD_SET_QM

#define OD_SET_QM   4008

Which quantization matrix to use.

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

◆ OD_SET_USE_DERING

#define OD_SET_USE_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).

◆ OD_SET_MC_USE_CHROMA

#define OD_SET_MC_USE_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).

◆ OD_SET_MV_RES_MIN

#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

◆ OD_SET_MV_LEVEL_MIN

#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

◆ OD_SET_MV_LEVEL_MAX

#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

◆ OD_SET_MC_USE_SATD

#define OD_SET_MC_USE_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.

Function Documentation

◆ daala_encode_create()

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.

◆ daala_encode_ctl()

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.

◆ daala_encode_flush_header()

int daala_encode_flush_header ( daala_enc_ctx enc,
daala_comment comments,
ogg_packet *  op 
)

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

◆ daala_encode_img_in()

int daala_encode_img_in ( daala_enc_ctx enc,
od_img 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.

◆ daala_encode_packet_out()

int daala_encode_packet_out ( daala_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
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.
lastSet 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.
opAn 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 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.

◆ daala_encode_free()

void daala_encode_free ( daala_enc_ctx enc)

Frees an allocated encoder instance.

Parameters
encA daala_enc_ctx handle.