dav1d.h File Reference

#include <errno.h>
#include <stdarg.h>
#include "common.h"
#include "picture.h"
#include "data.h"
#include "version.h"

Include dependency graph for dav1d.h:

Go to the source code of this file.

Data Structures
struct	Dav1dLogger
struct	Dav1dSettings

Macros
#define	DAV1D_MAX_THREADS   256
#define	DAV1D_MAX_FRAME_DELAY   256

Typedefs
typedef struct Dav1dContext	Dav1dContext
typedef struct Dav1dRef	Dav1dRef

Enumerations
enum	Dav1dInloopFilterType {   DAV1D_INLOOPFILTER_NONE = 0 , DAV1D_INLOOPFILTER_DEBLOCK = 1 << 0 , DAV1D_INLOOPFILTER_CDEF = 1 << 1 , DAV1D_INLOOPFILTER_RESTORATION = 1 << 2 ,   DAV1D_INLOOPFILTER_ALL }
enum	Dav1dDecodeFrameType { DAV1D_DECODEFRAMETYPE_ALL = 0 , DAV1D_DECODEFRAMETYPE_REFERENCE = 1 , DAV1D_DECODEFRAMETYPE_INTRA = 2 , DAV1D_DECODEFRAMETYPE_KEY = 3 }
enum	Dav1dEventFlags { DAV1D_EVENT_FLAG_NEW_SEQUENCE = 1 << 0 , DAV1D_EVENT_FLAG_NEW_OP_PARAMS_INFO = 1 << 1 }

Functions
DAV1D_API const char *	dav1d_version (void)
DAV1D_API unsigned	dav1d_version_api (void)
DAV1D_API void	dav1d_default_settings (Dav1dSettings *s)
DAV1D_API int	dav1d_open (Dav1dContext **c_out, const Dav1dSettings *s)
DAV1D_API int	dav1d_parse_sequence_header (Dav1dSequenceHeader *out, const uint8_t *buf, const size_t sz)
DAV1D_API int	dav1d_send_data (Dav1dContext *c, Dav1dData *in)
DAV1D_API int	dav1d_get_picture (Dav1dContext *c, Dav1dPicture *out)
DAV1D_API int	dav1d_apply_grain (Dav1dContext *c, Dav1dPicture *out, const Dav1dPicture *in)
DAV1D_API void	dav1d_close (Dav1dContext **c_out)
DAV1D_API void	dav1d_flush (Dav1dContext *c)
DAV1D_API int	dav1d_get_event_flags (Dav1dContext *c, enum Dav1dEventFlags *flags)
DAV1D_API int	dav1d_get_decode_error_data_props (Dav1dContext *c, Dav1dDataProps *out)
DAV1D_API int	dav1d_get_frame_delay (const Dav1dSettings *s)

Macro Definition Documentation

DAV1D_MAX_FRAME_DELAY

#define DAV1D_MAX_FRAME_DELAY   256

DAV1D_MAX_THREADS

#define DAV1D_MAX_THREADS   256

Typedef Documentation

Dav1dContext

typedef struct Dav1dContext Dav1dContext

Dav1dRef

typedef struct Dav1dRef Dav1dRef

Enumeration Type Documentation

Dav1dDecodeFrameType

enum Dav1dDecodeFrameType

Enumerator
DAV1D_DECODEFRAMETYPE_ALL	decode and return all frames
DAV1D_DECODEFRAMETYPE_REFERENCE	decode and return frames referenced by other frames only
DAV1D_DECODEFRAMETYPE_INTRA	decode and return intra frames only (includes keyframes)
DAV1D_DECODEFRAMETYPE_KEY	decode and return keyframes only

Dav1dEventFlags

enum Dav1dEventFlags

Enumerator
DAV1D_EVENT_FLAG_NEW_SEQUENCE	The last returned picture contains a reference to a new Sequence Header, either because it's the start of a new coded sequence, or the decoder was flushed before it was generated.
DAV1D_EVENT_FLAG_NEW_OP_PARAMS_INFO	The last returned picture contains a reference to a Sequence Header with new operating parameters information for the current coded sequence.

Dav1dInloopFilterType

enum Dav1dInloopFilterType

Enumerator
DAV1D_INLOOPFILTER_NONE
DAV1D_INLOOPFILTER_DEBLOCK
DAV1D_INLOOPFILTER_CDEF
DAV1D_INLOOPFILTER_RESTORATION
DAV1D_INLOOPFILTER_ALL

Function Documentation

dav1d_apply_grain()

DAV1D_API int dav1d_apply_grain	(	Dav1dContext *	c,
		Dav1dPicture *	out,
		const Dav1dPicture *	in )

Apply film grain to a previously decoded picture. If the picture contains no film grain metadata, then this function merely returns a new reference.

Parameters

c	Input decoder instance.
out	Output frame. The caller assumes ownership of the returned reference.
in	Input frame. No ownership is transferred.

Returns

0: Success, and a frame is returned. Other negative DAV1D_ERR codes: Error due to lack of memory or because of invalid passed-in arguments.

Note

If Dav1dSettings.apply_grain is true, film grain was already applied by dav1d_get_picture, and so calling this function leads to double application of film grain. Users should only call this when needed.

dav1d_close()

DAV1D_API void dav1d_close

(

Dav1dContext **

c_out

)

Close a decoder instance and free all associated memory.

Parameters

c_out

The decoder instance to close. *c_out will be set to NULL.

dav1d_default_settings()

DAV1D_API void dav1d_default_settings

(

Dav1dSettings *

s

)

Initialize settings to default values.

Parameters

s	Input settings context.

dav1d_flush()

DAV1D_API void dav1d_flush

(

Dav1dContext *

c

)

Flush all delayed frames in decoder and clear internal decoder state, to be used when seeking.

Parameters

c	Input decoder instance.

Note

Decoding will start only after a valid sequence header OBU is delivered to dav1d_send_data().

dav1d_get_decode_error_data_props()

DAV1D_API int dav1d_get_decode_error_data_props	(	Dav1dContext *	c,
		Dav1dDataProps *	out )

Retrieve the user-provided metadata associated with the input data packet for the last decoding error reported to the user, i.e. a negative return value (not EAGAIN) from dav1d_send_data() or dav1d_get_picture().

Parameters

c	Input decoder instance.
out	Output Dav1dDataProps. On success, the caller assumes ownership of the returned reference.

Returns

0 on success, or < 0 (a negative DAV1D_ERR code) on error.

dav1d_get_event_flags()

DAV1D_API int dav1d_get_event_flags	(	Dav1dContext *	c,
		enum Dav1dEventFlags *	flags )

Fetch a combination of DAV1D_EVENT_FLAG_* event flags generated by the decoding process.

Parameters

c	Input decoder instance.
flags	Where to write the flags.

Returns

0 on success, or < 0 (a negative DAV1D_ERR code) on error.

Note

Calling this function will clear all the event flags currently stored in the decoder.

dav1d_get_frame_delay()

DAV1D_API int dav1d_get_frame_delay

(

const Dav1dSettings *

s

)

Get the decoder delay, which is the number of internally buffered frames, not including reference frames. This value is guaranteed to be >= 1 and <= max_frame_delay.

Parameters

s	Input settings context.

Returns

Decoder frame delay on success, or < 0 (a negative DAV1D_ERR code) on error.

Note

The returned delay is valid only for a Dav1dContext initialized with the provided Dav1dSettings.

dav1d_get_picture()

DAV1D_API int dav1d_get_picture	(	Dav1dContext *	c,
		Dav1dPicture *	out )

Return a decoded picture.

Parameters

c	Input decoder instance.
out	Output frame. The caller assumes ownership of the returned reference.

Returns

0: Success, and a frame is returned. DAV1D_ERR(EAGAIN): Not enough data to output a frame. dav1d_send_data() should be called with new input. Other negative DAV1D_ERR codes: Error during decoding or because of invalid passed-in arguments.

Note

To drain buffered frames from the decoder (i.e. on end of stream), call this function until it returns DAV1D_ERR(EAGAIN).

Dav1dData data = { 0 };
Dav1dPicture p = { 0 };
int res;
 
read_data(&data);
do {
    res = dav1d_send_data(c, &data);
    // Keep going even if the function can't consume the current data
       packet. It eventually will after one or more frames have been
       returned in this loop.
    if (res < 0 && res != DAV1D_ERR(EAGAIN))
        free_and_abort();
    res = dav1d_get_picture(c, &p);
    if (res < 0) {
        if (res != DAV1D_ERR(EAGAIN))
            free_and_abort();
    } else
        output_and_unref_picture(&p);
// Stay in the loop as long as there's data to consume.
} while (data.sz || read_data(&data) == SUCCESS);
 
// Handle EOS by draining all buffered frames.
do {
    res = dav1d_get_picture(c, &p);
    if (res < 0) {
        if (res != DAV1D_ERR(EAGAIN))
            free_and_abort();
    } else
        output_and_unref_picture(&p);
} while (res == 0);

dav1d_open()

DAV1D_API int dav1d_open	(	Dav1dContext **	c_out,
		const Dav1dSettings *	s )

Allocate and open a decoder instance.

Parameters

c_out	The decoder instance to open. *c_out will be set to the allocated context.
s	Input settings context.

Note

The context must be freed using dav1d_close() when decoding is finished.

Returns

0 on success, or < 0 (a negative DAV1D_ERR code) on error.

dav1d_parse_sequence_header()

DAV1D_API int dav1d_parse_sequence_header	(	Dav1dSequenceHeader *	out,
		const uint8_t *	buf,
		const size_t	sz )

Parse a Sequence Header OBU from bitstream data.

Parameters

out	Output Sequence Header.
buf	The data to be parser.
sz	Size of the data.

Returns

0: Success, and out is filled with the parsed Sequence Header OBU parameters. DAV1D_ERR(ENOENT): No Sequence Header OBUs were found in the buffer. Other negative DAV1D_ERR codes: Invalid data in the buffer, invalid passed-in arguments, and other errors during parsing.

Note

It is safe to feed this function data containing other OBUs than a Sequence Header, as they will simply be ignored. If there is more than one Sequence Header OBU present, only the last will be returned.

dav1d_send_data()

DAV1D_API int dav1d_send_data	(	Dav1dContext *	c,
		Dav1dData *	in )

Feed bitstream data to the decoder, in the form of one or multiple AV1 Open Bitstream Units (OBUs).

Parameters

c	Input decoder instance.
in	Input bitstream data. On success, ownership of the reference is passed to the library.

Returns

0: Success, and the data was consumed. DAV1D_ERR(EAGAIN): The data can't be consumed. dav1d_get_picture() should be called to get one or more frames before the function can consume new data. Other negative DAV1D_ERR codes: Error during decoding or because of invalid passed-in arguments. The reference remains owned by the caller.

dav1d_version()

DAV1D_API const char * dav1d_version

(

void

)

Get library version.

dav1d_version_api()

DAV1D_API unsigned dav1d_version_api

(

void

)

Get library API version.

Returns

A value in the format 0x00XXYYZZ, where XX is the major version, YY the minor version, and ZZ the patch version.

See also

DAV1D_API_MAJOR, DAV1D_API_MINOR, DAV1D_API_PATCH