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 #ifdef __cplusplus 32 extern "C" { 33 #endif 34 35 #include <errno.h> 36 #include <stdarg.h> 37 38 #include "common.h" 39 #include "picture.h" 40 #include "data.h" 41 #include "version.h" 42 43 typedef struct Dav1dContext Dav1dContext; 44 typedef struct Dav1dRef Dav1dRef; 45 46 #define DAV1D_MAX_FRAME_THREADS 256 47 #define DAV1D_MAX_TILE_THREADS 64 48 #define DAV1D_MAX_POSTFILTER_THREADS 256 49 50 typedef struct Dav1dLogger { 51 void *cookie; ///< Custom data to pass to the callback. 52 /** 53 * Logger callback. May be NULL to disable logging. 54 * 55 * @param cookie Custom pointer passed to all calls. 56 * @param format The vprintf compatible format string. 57 * @param ap List of arguments referenced by the format string. 58 */ 59 void (*callback)(void *cookie, const char *format, va_list ap); 60 } Dav1dLogger; 61 62 typedef struct Dav1dSettings { 63 int n_frame_threads; 64 int n_tile_threads; 65 int apply_grain; 66 int operating_point; ///< select an operating point for scalable AV1 bitstreams (0 - 31) 67 int all_layers; ///< output all spatial layers of a scalable AV1 biststream 68 unsigned frame_size_limit; ///< maximum frame size, in pixels (0 = unlimited) 69 Dav1dPicAllocator allocator; ///< Picture allocator callback. 70 Dav1dLogger logger; ///< Logger callback. 71 int n_postfilter_threads; 72 uint8_t reserved[28]; ///< reserved for future use 73 } Dav1dSettings; 74 75 /** 76 * Get library version. 77 */ 78 DAV1D_API const char *dav1d_version(void); 79 80 /** 81 * Initialize settings to default values. 82 * 83 * @param s Input settings context. 84 */ 85 DAV1D_API void dav1d_default_settings(Dav1dSettings *s); 86 87 /** 88 * Allocate and open a decoder instance. 89 * 90 * @param c_out The decoder instance to open. *c_out will be set to the 91 * allocated context. 92 * @param s Input settings context. 93 * 94 * @note The context must be freed using dav1d_close() when decoding is 95 * finished. 96 * 97 * @return 0 on success, or < 0 (a negative DAV1D_ERR code) on error. 98 */ 99 DAV1D_API int dav1d_open(Dav1dContext **c_out, const Dav1dSettings *s); 100 101 /** 102 * Parse a Sequence Header OBU from bitstream data. 103 * 104 * @param out Output Sequence Header. 105 * @param buf The data to be parser. 106 * @param sz Size of the data. 107 * 108 * @return 0 on success, or < 0 (a negative DAV1D_ERR code) on error. 109 * 110 * @note It is safe to feed this function data containing other OBUs than a 111 * Sequence Header, as they will simply be ignored. If there is more than 112 * one Sequence Header OBU present, only the last will be returned. 113 */ 114 DAV1D_API int dav1d_parse_sequence_header(Dav1dSequenceHeader *out, 115 const uint8_t *buf, const size_t sz); 116 117 /** 118 * Feed bitstream data to the decoder. 119 * 120 * @param c Input decoder instance. 121 * @param in Input bitstream data. On success, ownership of the reference is 122 * passed to the library. 123 * 124 * @return 125 * 0: Success, and the data was consumed. 126 * DAV1D_ERR(EAGAIN): The data can't be consumed. dav1d_get_picture() should 127 * be called to get one or more frames before the function 128 * can consume new data. 129 * other negative DAV1D_ERR codes: Error during decoding or because of invalid 130 * passed-in arguments. 131 */ 132 DAV1D_API int dav1d_send_data(Dav1dContext *c, Dav1dData *in); 133 134 /** 135 * Return a decoded picture. 136 * 137 * @param c Input decoder instance. 138 * @param out Output frame. The caller assumes ownership of the returned 139 * reference. 140 * 141 * @return 142 * 0: Success, and a frame is returned. 143 * DAV1D_ERR(EAGAIN): Not enough data to output a frame. dav1d_send_data() 144 * should be called with new input. 145 * other negative DAV1D_ERR codes: Error during decoding or because of invalid 146 * passed-in arguments. 147 * 148 * @note To drain buffered frames from the decoder (i.e. on end of stream), 149 * call this function until it returns DAV1D_ERR(EAGAIN). 150 * 151 * @code{.c} 152 * Dav1dData data = { 0 }; 153 * Dav1dPicture p = { 0 }; 154 * int res; 155 * 156 * read_data(&data); 157 * do { 158 * res = dav1d_send_data(c, &data); 159 * // Keep going even if the function can't consume the current data 160 * packet. It eventually will after one or more frames have been 161 * returned in this loop. 162 * if (res < 0 && res != DAV1D_ERR(EAGAIN)) 163 * free_and_abort(); 164 * res = dav1d_get_picture(c, &p); 165 * if (res < 0) { 166 * if (res != DAV1D_ERR(EAGAIN)) 167 * free_and_abort(); 168 * } else 169 * output_and_unref_picture(&p); 170 * // Stay in the loop as long as there's data to consume. 171 * } while (data.sz || read_data(&data) == SUCCESS); 172 * 173 * // Handle EOS by draining all buffered frames. 174 * do { 175 * res = dav1d_get_picture(c, &p); 176 * if (res < 0) { 177 * if (res != DAV1D_ERR(EAGAIN)) 178 * free_and_abort(); 179 * } else 180 * output_and_unref_picture(&p); 181 * } while (res == 0); 182 * @endcode 183 */ 184 DAV1D_API int dav1d_get_picture(Dav1dContext *c, Dav1dPicture *out); 185 186 /** 187 * Close a decoder instance and free all associated memory. 188 * 189 * @param c_out The decoder instance to close. *c_out will be set to NULL. 190 */ 191 DAV1D_API void dav1d_close(Dav1dContext **c_out); 192 193 /** 194 * Flush all delayed frames in decoder and clear internal decoder state, 195 * to be used when seeking. 196 * 197 * @param c Input decoder instance. 198 * 199 * @note Decoding will start only after a valid sequence header OBU is 200 * delivered to dav1d_send_data(). 201 * 202 */ 203 DAV1D_API void dav1d_flush(Dav1dContext *c); 204 205 enum Dav1dEventFlags { 206 /** 207 * The last returned picture contains a reference to a new Sequence Header, 208 * either because it's the start of a new coded sequence, or the decoder was 209 * flushed before it was generated. 210 */ 211 DAV1D_EVENT_FLAG_NEW_SEQUENCE = 1 << 0, 212 /** 213 * The last returned picture contains a reference to a Sequence Header with 214 * new operating parameters information for the current coded sequence. 215 */ 216 DAV1D_EVENT_FLAG_NEW_OP_PARAMS_INFO = 1 << 1, 217 }; 218 219 /** 220 * Fetch a combination of DAV1D_EVENT_FLAG_* event flags generated by the decoding 221 * process. 222 * 223 * @param c Input decoder instance. 224 * @param flags Where to write the flags. 225 * 226 * @return 0 on success, or < 0 (a negative DAV1D_ERR code) on error. 227 * 228 * @note Calling this function will clear all the event flags currently stored in 229 * the decoder. 230 * 231 */ 232 DAV1D_API int dav1d_get_event_flags(Dav1dContext *c, enum Dav1dEventFlags *flags); 233 234 # ifdef __cplusplus 235 } 236 # endif 237 238 #endif /* DAV1D_H */ 239