dav1d: dav1d/dav1d.h File Reference

dav1d 1.3.0 dav1d is an AV1 decoder

Loading...
Searching...
No Matches
Data Structures | Macros | Typedefs | Enumerations | Functions
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_ERR
#define DAV1D_ERR(e)
Definition common.h:58
dav1d_get_picture
DAV1D_API int dav1d_get_picture(Dav1dContext *c, Dav1dPicture *out)
dav1d_send_data
DAV1D_API int dav1d_send_data(Dav1dContext *c, Dav1dData *in)
Dav1dData
Definition data.h:40
Dav1dData::sz
size_t sz
data size
Definition data.h:42
Dav1dPicture
Definition picture.h:53

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