1 /* 2 * Copyright © 2018-2021, VideoLAN and dav1d authors 3 * Copyright © 2018, Two Orioles, LLC 4 * All rights reserved. 5 * 6 * Redistribution and use in source and binary forms, with or without 7 * modification, are permitted provided that the following conditions are met: 8 * 9 * 1. Redistributions of source code must retain the above copyright notice, this 10 * list of conditions and the following disclaimer. 11 * 12 * 2. Redistributions in binary form must reproduce the above copyright notice, 13 * this list of conditions and the following disclaimer in the documentation 14 * and/or other materials provided with the distribution. 15 * 16 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND 17 * ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED 18 * WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE 19 * DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR 20 * ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES 21 * (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; 22 * LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND 23 * ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT 24 * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS 25 * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. 26 */ 27 28 #ifndef DAV1D_H 29 #define DAV1D_H 30 31 #include <errno.h> 32 #include <stdarg.h> 33 34 #include "common.h" 35 #include "picture.h" 36 #include "data.h" 37 #include "version.h" 38 39 #ifdef __cplusplus 40 extern "C" { 41 #endif 42 43 typedef struct Dav1dContext Dav1dContext; 44 typedef struct Dav1dRef Dav1dRef; 45 46 #define DAV1D_MAX_THREADS 256 47 #define DAV1D_MAX_FRAME_DELAY 256 48 49 typedef struct Dav1dLogger { 50 void *cookie; ///< Custom data to pass to the callback. 51 /** 52 * Logger callback. May be NULL to disable logging. 53 * 54 * @param cookie Custom pointer passed to all calls. 55 * @param format The vprintf compatible format string. 56 * @param ap List of arguments referenced by the format string. 57 */ 58 void (*callback)(void *cookie, const char *format, va_list ap); 59 } Dav1dLogger; 60 61 enum Dav1dInloopFilterType { 62 DAV1D_INLOOPFILTER_NONE = 0, 63 DAV1D_INLOOPFILTER_DEBLOCK = 1 << 0, 64 DAV1D_INLOOPFILTER_CDEF = 1 << 1, 65 DAV1D_INLOOPFILTER_RESTORATION = 1 << 2, 66 DAV1D_INLOOPFILTER_ALL = DAV1D_INLOOPFILTER_DEBLOCK | 67 DAV1D_INLOOPFILTER_CDEF | 68 DAV1D_INLOOPFILTER_RESTORATION, 69 }; 70 71 enum Dav1dDecodeFrameType { 72 DAV1D_DECODEFRAMETYPE_ALL = 0, ///< decode and return all frames 73 DAV1D_DECODEFRAMETYPE_REFERENCE = 1,///< decode and return frames referenced by other frames only 74 DAV1D_DECODEFRAMETYPE_INTRA = 2, ///< decode and return intra frames only (includes keyframes) 75 DAV1D_DECODEFRAMETYPE_KEY = 3, ///< decode and return keyframes only 76 }; 77 78 typedef struct Dav1dSettings { 79 int n_threads; ///< number of threads (0 = number of logical cores in host system, default 0) 80 int max_frame_delay; ///< Set to 1 for low-latency decoding (0 = ceil(sqrt(n_threads)), default 0) 81 int apply_grain; ///< whether to apply film grain on output frames (default 1) 82 int operating_point; ///< select an operating point for scalable AV1 bitstreams (0 - 31, default 0) 83 int all_layers; ///< output all spatial layers of a scalable AV1 biststream (default 1) 84 unsigned frame_size_limit; ///< maximum frame size, in pixels (0 = unlimited, default 0) 85 Dav1dPicAllocator allocator; ///< Picture allocator callback. 86 Dav1dLogger logger; ///< Logger callback. 87 int strict_std_compliance; ///< whether to abort decoding on standard compliance violations 88 ///< that don't affect actual bitstream decoding (e.g. inconsistent 89 ///< or invalid metadata, default 0) 90 int output_invisible_frames; ///< output invisibly coded frames (in coding order) in addition 91 ///< to all visible frames. Because of show-existing-frame, this 92 ///< means some frames may appear twice (once when coded, 93 ///< once when shown, default 0) 94 enum Dav1dInloopFilterType inloop_filters; ///< postfilters to enable during decoding (default 95 ///< DAV1D_INLOOPFILTER_ALL) 96 enum Dav1dDecodeFrameType decode_frame_type; ///< frame types to decode (default 97 ///< DAV1D_DECODEFRAMETYPE_ALL) 98 uint8_t reserved[16]; ///< reserved for future use 99 } Dav1dSettings; 100 101 /** 102 * Get library version. 103 */ 104 DAV1D_API const char *dav1d_version(void); 105 106 /** 107 * Get library API version. 108 * 109 * @return A value in the format 0x00XXYYZZ, where XX is the major version, 110 * YY the minor version, and ZZ the patch version. 111 * @see DAV1D_API_MAJOR, DAV1D_API_MINOR, DAV1D_API_PATCH 112 */ 113 DAV1D_API unsigned dav1d_version_api(void); 114 115 /** 116 * Initialize settings to default values. 117 * 118 * @param s Input settings context. 119 */ 120 DAV1D_API void dav1d_default_settings(Dav1dSettings *s); 121 122 /** 123 * Allocate and open a decoder instance. 124 * 125 * @param c_out The decoder instance to open. *c_out will be set to the 126 * allocated context. 127 * @param s Input settings context. 128 * 129 * @note The context must be freed using dav1d_close() when decoding is 130 * finished. 131 * 132 * @return 0 on success, or < 0 (a negative DAV1D_ERR code) on error. 133 */ 134 DAV1D_API int dav1d_open(Dav1dContext **c_out, const Dav1dSettings *s); 135 136 /** 137 * Parse a Sequence Header OBU from bitstream data. 138 * 139 * @param out Output Sequence Header. 140 * @param buf The data to be parser. 141 * @param sz Size of the data. 142 * 143 * @return 144 * 0: Success, and out is filled with the parsed Sequence Header 145 * OBU parameters. 146 * DAV1D_ERR(ENOENT): No Sequence Header OBUs were found in the buffer. 147 * Other negative DAV1D_ERR codes: Invalid data in the buffer, invalid passed-in 148 * arguments, and other errors during parsing. 149 * 150 * @note It is safe to feed this function data containing other OBUs than a 151 * Sequence Header, as they will simply be ignored. If there is more than 152 * one Sequence Header OBU present, only the last will be returned. 153 */ 154 DAV1D_API int dav1d_parse_sequence_header(Dav1dSequenceHeader *out, 155 const uint8_t *buf, const size_t sz); 156 157 /** 158 * Feed bitstream data to the decoder, in the form of one or multiple AV1 159 * Open Bitstream Units (OBUs). 160 * 161 * @param c Input decoder instance. 162 * @param in Input bitstream data. On success, ownership of the reference is 163 * passed to the library. 164 * 165 * @return 166 * 0: Success, and the data was consumed. 167 * DAV1D_ERR(EAGAIN): The data can't be consumed. dav1d_get_picture() should 168 * be called to get one or more frames before the function 169 * can consume new data. 170 * Other negative DAV1D_ERR codes: Error during decoding or because of invalid 171 * passed-in arguments. The reference remains 172 * owned by the caller. 173 */ 174 DAV1D_API int dav1d_send_data(Dav1dContext *c, Dav1dData *in); 175 176 /** 177 * Return a decoded picture. 178 * 179 * @param c Input decoder instance. 180 * @param out Output frame. The caller assumes ownership of the returned 181 * reference. 182 * 183 * @return 184 * 0: Success, and a frame is returned. 185 * DAV1D_ERR(EAGAIN): Not enough data to output a frame. dav1d_send_data() 186 * should be called with new input. 187 * Other negative DAV1D_ERR codes: Error during decoding or because of invalid 188 * passed-in arguments. 189 * 190 * @note To drain buffered frames from the decoder (i.e. on end of stream), 191 * call this function until it returns DAV1D_ERR(EAGAIN). 192 * 193 * @code{.c} 194 * Dav1dData data = { 0 }; 195 * Dav1dPicture p = { 0 }; 196 * int res; 197 * 198 * read_data(&data); 199 * do { 200 * res = dav1d_send_data(c, &data); 201 * // Keep going even if the function can't consume the current data 202 * packet. It eventually will after one or more frames have been 203 * returned in this loop. 204 * if (res < 0 && res != DAV1D_ERR(EAGAIN)) 205 * free_and_abort(); 206 * res = dav1d_get_picture(c, &p); 207 * if (res < 0) { 208 * if (res != DAV1D_ERR(EAGAIN)) 209 * free_and_abort(); 210 * } else 211 * output_and_unref_picture(&p); 212 * // Stay in the loop as long as there's data to consume. 213 * } while (data.sz || read_data(&data) == SUCCESS); 214 * 215 * // Handle EOS by draining all buffered frames. 216 * do { 217 * res = dav1d_get_picture(c, &p); 218 * if (res < 0) { 219 * if (res != DAV1D_ERR(EAGAIN)) 220 * free_and_abort(); 221 * } else 222 * output_and_unref_picture(&p); 223 * } while (res == 0); 224 * @endcode 225 */ 226 DAV1D_API int dav1d_get_picture(Dav1dContext *c, Dav1dPicture *out); 227 228 /** 229 * Apply film grain to a previously decoded picture. If the picture contains no 230 * film grain metadata, then this function merely returns a new reference. 231 * 232 * @param c Input decoder instance. 233 * @param out Output frame. The caller assumes ownership of the returned 234 * reference. 235 * @param in Input frame. No ownership is transferred. 236 * 237 * @return 238 * 0: Success, and a frame is returned. 239 * Other negative DAV1D_ERR codes: Error due to lack of memory or because of 240 * invalid passed-in arguments. 241 * 242 * @note If `Dav1dSettings.apply_grain` is true, film grain was already applied 243 * by `dav1d_get_picture`, and so calling this function leads to double 244 * application of film grain. Users should only call this when needed. 245 */ 246 DAV1D_API int dav1d_apply_grain(Dav1dContext *c, Dav1dPicture *out, 247 const Dav1dPicture *in); 248 249 /** 250 * Close a decoder instance and free all associated memory. 251 * 252 * @param c_out The decoder instance to close. *c_out will be set to NULL. 253 */ 254 DAV1D_API void dav1d_close(Dav1dContext **c_out); 255 256 /** 257 * Flush all delayed frames in decoder and clear internal decoder state, 258 * to be used when seeking. 259 * 260 * @param c Input decoder instance. 261 * 262 * @note Decoding will start only after a valid sequence header OBU is 263 * delivered to dav1d_send_data(). 264 * 265 */ 266 DAV1D_API void dav1d_flush(Dav1dContext *c); 267 268 enum Dav1dEventFlags { 269 /** 270 * The last returned picture contains a reference to a new Sequence Header, 271 * either because it's the start of a new coded sequence, or the decoder was 272 * flushed before it was generated. 273 */ 274 DAV1D_EVENT_FLAG_NEW_SEQUENCE = 1 << 0, 275 /** 276 * The last returned picture contains a reference to a Sequence Header with 277 * new operating parameters information for the current coded sequence. 278 */ 279 DAV1D_EVENT_FLAG_NEW_OP_PARAMS_INFO = 1 << 1, 280 }; 281 282 /** 283 * Fetch a combination of DAV1D_EVENT_FLAG_* event flags generated by the decoding 284 * process. 285 * 286 * @param c Input decoder instance. 287 * @param flags Where to write the flags. 288 * 289 * @return 0 on success, or < 0 (a negative DAV1D_ERR code) on error. 290 * 291 * @note Calling this function will clear all the event flags currently stored in 292 * the decoder. 293 * 294 */ 295 DAV1D_API int dav1d_get_event_flags(Dav1dContext *c, enum Dav1dEventFlags *flags); 296 297 /** 298 * Retrieve the user-provided metadata associated with the input data packet 299 * for the last decoding error reported to the user, i.e. a negative return 300 * value (not EAGAIN) from dav1d_send_data() or dav1d_get_picture(). 301 * 302 * @param c Input decoder instance. 303 * @param out Output Dav1dDataProps. On success, the caller assumes ownership of 304 * the returned reference. 305 * 306 * @return 0 on success, or < 0 (a negative DAV1D_ERR code) on error. 307 */ 308 DAV1D_API int dav1d_get_decode_error_data_props(Dav1dContext *c, Dav1dDataProps *out); 309 310 /** 311 * Get the decoder delay, which is the number of internally buffered frames, not 312 * including reference frames. 313 * This value is guaranteed to be >= 1 and <= max_frame_delay. 314 * 315 * @param s Input settings context. 316 * 317 * @return Decoder frame delay on success, or < 0 (a negative DAV1D_ERR code) on 318 * error. 319 * 320 * @note The returned delay is valid only for a Dav1dContext initialized with the 321 * provided Dav1dSettings. 322 */ 323 DAV1D_API int dav1d_get_frame_delay(const Dav1dSettings *s); 324 325 #ifdef __cplusplus 326 } /* extern "C" */ 327 #endif 328 329 #endif /* DAV1D_H */ 330