1 /* 2 * Copyright (c) 2016, Alliance for Open Media. All rights reserved 3 * 4 * This source code is subject to the terms of the BSD 2 Clause License and 5 * the Alliance for Open Media Patent License 1.0. If the BSD 2 Clause License 6 * was not distributed with this source code in the LICENSE file, you can 7 * obtain it at www.aomedia.org/license/software. If the Alliance for Open 8 * Media Patent License 1.0 was not distributed with this source code in the 9 * PATENTS file, you can obtain it at www.aomedia.org/license/patent. 10 */ 11 12 /*!\defgroup aom_decoder AOMedia AOM/AV1 Decoder 13 * \ingroup aom 14 * 15 * @{ 16 */ 17 /*!\file 18 * \brief Provides definitions for using AOM or AV1 within the aom Decoder 19 * interface. 20 */ 21 #ifndef AOM_AOM_AOMDX_H_ 22 #define AOM_AOM_AOMDX_H_ 23 24 #ifdef __cplusplus 25 extern "C" { 26 #endif 27 28 /* Include controls common to both the encoder and decoder */ 29 #include "aom/aom.h" 30 31 /*!\name Algorithm interface for AV1 32 * 33 * This interface provides the capability to decode AV1 streams. 34 * @{ 35 */ 36 extern aom_codec_iface_t aom_codec_av1_dx_algo; 37 extern aom_codec_iface_t *aom_codec_av1_dx(void); 38 /*!@} - end algorithm interface member group*/ 39 40 /** Data structure that stores bit accounting for debug 41 */ 42 typedef struct Accounting Accounting; 43 44 #ifndef AOM_INSPECTION_H_ 45 /** Callback that inspects decoder frame data. 46 */ 47 typedef void (*aom_inspect_cb)(void *decoder, void *ctx); 48 49 #endif 50 51 /*!\brief Structure to hold inspection callback and context. 52 * 53 * Defines a structure to hold the inspection callback function and calling 54 * context. 55 */ 56 typedef struct aom_inspect_init { 57 /*! Inspection callback. */ 58 aom_inspect_cb inspect_cb; 59 60 /*! Inspection context. */ 61 void *inspect_ctx; 62 } aom_inspect_init; 63 64 /*!\brief Structure to collect a buffer index when inspecting. 65 * 66 * Defines a structure to hold the buffer and return an index 67 * when calling decode from inspect. This enables us to decode 68 * non showable sub frames. 69 */ 70 typedef struct { 71 /*! Pointer for new position in compressed buffer after decoding 1 OBU. */ 72 const unsigned char *buf; 73 /*! Index into reference buffer array to see result of decoding 1 OBU. */ 74 int idx; 75 /*! Is a show existing frame. */ 76 int show_existing; 77 } Av1DecodeReturn; 78 79 /*!\brief Structure to hold a tile's start address and size in the bitstream. 80 * 81 * Defines a structure to hold a tile's start address and size in the bitstream. 82 */ 83 typedef struct aom_tile_data { 84 /*! Tile data size. */ 85 size_t coded_tile_data_size; 86 /*! Tile's start address. */ 87 const void *coded_tile_data; 88 /*! Extra size information. */ 89 size_t extra_size; 90 } aom_tile_data; 91 92 /*!\brief Structure to hold the external reference frame pointer. 93 * 94 * Define a structure to hold the external reference frame pointer. 95 */ 96 typedef struct av1_ext_ref_frame { 97 /*! Start pointer of external references. */ 98 aom_image_t *img; 99 /*! Number of available external references. */ 100 int num; 101 } av1_ext_ref_frame_t; 102 103 /*!\enum aom_dec_control_id 104 * \brief AOM decoder control functions 105 * 106 * This set of macros define the control functions available for the AOM 107 * decoder interface. 108 * 109 * \sa #aom_codec_control(aom_codec_ctx_t *ctx, int ctrl_id, ...) 110 */ 111 enum aom_dec_control_id { 112 /*!\brief Codec control function to get info on which reference frames were 113 * updated by the last decode, int* parameter 114 */ 115 AOMD_GET_LAST_REF_UPDATES = AOM_DECODER_CTRL_ID_START, 116 117 /*!\brief Codec control function to check if the indicated frame is 118 corrupted, int* parameter 119 */ 120 AOMD_GET_FRAME_CORRUPTED, 121 122 /*!\brief Codec control function to get info on which reference frames were 123 * used by the last decode, int* parameter 124 */ 125 AOMD_GET_LAST_REF_USED, 126 127 /*!\brief Codec control function to get the dimensions that the current 128 * frame is decoded at, int* parameter. This may be different to the 129 * intended display size for the frame as specified in the wrapper or frame 130 * header (see AV1D_GET_DISPLAY_SIZE). 131 */ 132 AV1D_GET_FRAME_SIZE, 133 134 /*!\brief Codec control function to get the current frame's intended display 135 * dimensions (as specified in the wrapper or frame header), int* parameter. 136 * This may be different to the decoded dimensions of this frame (see 137 * AV1D_GET_FRAME_SIZE). 138 */ 139 AV1D_GET_DISPLAY_SIZE, 140 141 /*!\brief Codec control function to get the bit depth of the stream, 142 * unsigned int* parameter 143 */ 144 AV1D_GET_BIT_DEPTH, 145 146 /*!\brief Codec control function to get the image format of the stream, 147 * aom_img_fmt_t* parameter 148 */ 149 AV1D_GET_IMG_FORMAT, 150 151 /*!\brief Codec control function to get the size of the tile, unsigned int 152 parameter */ 153 AV1D_GET_TILE_SIZE, 154 155 /*!\brief Codec control function to get the tile count in a tile list, int* 156 * parameter 157 */ 158 AV1D_GET_TILE_COUNT, 159 160 /*!\brief Codec control function to set the byte alignment of the planes in 161 * the reference buffers, int parameter 162 * 163 * Valid values are power of 2, from 32 to 1024. A value of 0 sets 164 * legacy alignment. I.e. Y plane is aligned to 32 bytes, U plane directly 165 * follows Y plane, and V plane directly follows U plane. Default value is 0. 166 */ 167 AV1_SET_BYTE_ALIGNMENT, 168 169 /*!\brief Codec control function to invert the decoding order to from right to 170 * left, int parameter 171 * 172 * The function is used in a test to confirm the decoding independence of tile 173 * columns. The function may be used in application where this order 174 * of decoding is desired. int parameter 175 * 176 * TODO(yaowu): Rework the unit test that uses this control, and in a future 177 * release, this test-only control shall be removed. 178 */ 179 AV1_INVERT_TILE_DECODE_ORDER, 180 181 /*!\brief Codec control function to set the skip loop filter flag, int 182 * parameter 183 * 184 * Valid values are integers. The decoder will skip the loop filter 185 * when its value is set to nonzero. If the loop filter is skipped the 186 * decoder may accumulate decode artifacts. The default value is 0. 187 */ 188 AV1_SET_SKIP_LOOP_FILTER, 189 190 /*!\brief Codec control function to retrieve a pointer to the Accounting 191 * struct, takes Accounting** as parameter 192 * 193 * If called before a frame has been decoded, this returns AOM_CODEC_ERROR. 194 * The caller should ensure that AOM_CODEC_OK is returned before attempting 195 * to dereference the Accounting pointer. 196 * 197 * \attention When compiled without --enable-accounting, this returns 198 * AOM_CODEC_INCAPABLE. 199 */ 200 AV1_GET_ACCOUNTING, 201 202 /*!\brief Codec control function to get last decoded frame quantizer, 203 * int* parameter 204 * 205 * Returned value uses internal quantizer scale defined by the codec. 206 */ 207 AOMD_GET_LAST_QUANTIZER, 208 209 /*!\brief Codec control function to set the range of tile decoding, int 210 * parameter 211 * 212 * A value that is greater and equal to zero indicates only the specific 213 * row/column is decoded. A value that is -1 indicates the whole row/column 214 * is decoded. A special case is both values are -1 that means the whole 215 * frame is decoded. 216 */ 217 AV1_SET_DECODE_TILE_ROW, 218 AV1_SET_DECODE_TILE_COL, 219 220 /*!\brief Codec control function to set the tile coding mode, int parameter 221 * 222 * - 0 = tiles are coded in normal tile mode 223 * - 1 = tiles are coded in large-scale tile mode 224 */ 225 AV1_SET_TILE_MODE, 226 227 /*!\brief Codec control function to get the frame header information of an 228 * encoded frame, unsigned int* parameter 229 */ 230 AV1D_GET_FRAME_HEADER_INFO, 231 232 /*!\brief Codec control function to get the start address and size of a 233 * tile in the coded bitstream, aom_tile_data* parameter. 234 */ 235 AV1D_GET_TILE_DATA, 236 237 /*!\brief Codec control function to set the external references' pointers in 238 * the decoder, av1_ext_ref_frame_t* parameter. 239 * 240 * This is used while decoding the tile list OBU in large-scale tile coding 241 * mode. 242 */ 243 AV1D_SET_EXT_REF_PTR, 244 245 /*!\brief Codec control function to enable the ext-tile software debug and 246 * testing code in the decoder, unsigned int parameter 247 */ 248 AV1D_EXT_TILE_DEBUG, 249 250 /*!\brief Codec control function to enable the row based multi-threading of 251 * decoding, unsigned int parameter 252 * 253 * - 0 = disabled 254 * - 1 = enabled (default) 255 */ 256 AV1D_SET_ROW_MT, 257 258 /*!\brief Codec control function to indicate whether bitstream is in 259 * Annex-B format, unsigned int parameter 260 */ 261 AV1D_SET_IS_ANNEXB, 262 263 /*!\brief Codec control function to indicate which operating point to use, 264 * int parameter 265 * 266 * A scalable stream may define multiple operating points, each of which 267 * defines a set of temporal and spatial layers to be processed. The 268 * operating point index may take a value between 0 and 269 * operating_points_cnt_minus_1 (which is at most 31). 270 */ 271 AV1D_SET_OPERATING_POINT, 272 273 /*!\brief Codec control function to indicate whether to output one frame per 274 * temporal unit (the default), or one frame per spatial layer. int parameter 275 * 276 * In a scalable stream, each temporal unit corresponds to a single "frame" 277 * of video, and within a temporal unit there may be multiple spatial layers 278 * with different versions of that frame. 279 * For video playback, only the highest-quality version (within the 280 * selected operating point) is needed, but for some use cases it is useful 281 * to have access to multiple versions of a frame when they are available. 282 */ 283 AV1D_SET_OUTPUT_ALL_LAYERS, 284 285 /*!\brief Codec control function to set an aom_inspect_cb callback that is 286 * invoked each time a frame is decoded, aom_inspect_init* parameter 287 * 288 * \attention When compiled without --enable-inspection, this 289 * returns AOM_CODEC_INCAPABLE. 290 */ 291 AV1_SET_INSPECTION_CALLBACK, 292 293 /*!\brief Codec control function to set the skip film grain flag, int 294 * parameter 295 * 296 * Valid values are integers. The decoder will skip the film grain when its 297 * value is set to nonzero. The default value is 0. 298 */ 299 AV1D_SET_SKIP_FILM_GRAIN, 300 301 AOM_DECODER_CTRL_ID_MAX, 302 }; 303 304 /*!\cond */ 305 /*!\brief AOM decoder control function parameter type 306 * 307 * Defines the data types that AOMD control functions take. 308 * 309 * \note Additional common controls are defined in aom.h. 310 * 311 * \note For each control ID "X", a macro-define of 312 * AOM_CTRL_X is provided. It is used at compile time to determine 313 * if the control ID is supported by the libaom library available, 314 * when the libaom version cannot be controlled. 315 */ 316 AOM_CTRL_USE_TYPE(AOMD_GET_LAST_REF_UPDATES, int *) 317 #define AOM_CTRL_AOMD_GET_LAST_REF_UPDATES 318 319 AOM_CTRL_USE_TYPE(AOMD_GET_FRAME_CORRUPTED, int *) 320 #define AOM_CTRL_AOMD_GET_FRAME_CORRUPTED 321 322 AOM_CTRL_USE_TYPE(AOMD_GET_LAST_REF_USED, int *) 323 #define AOM_CTRL_AOMD_GET_LAST_REF_USED 324 325 AOM_CTRL_USE_TYPE(AOMD_GET_LAST_QUANTIZER, int *) 326 #define AOM_CTRL_AOMD_GET_LAST_QUANTIZER 327 328 AOM_CTRL_USE_TYPE(AV1D_GET_DISPLAY_SIZE, int *) 329 #define AOM_CTRL_AV1D_GET_DISPLAY_SIZE 330 331 AOM_CTRL_USE_TYPE(AV1D_GET_BIT_DEPTH, unsigned int *) 332 #define AOM_CTRL_AV1D_GET_BIT_DEPTH 333 334 AOM_CTRL_USE_TYPE(AV1D_GET_IMG_FORMAT, aom_img_fmt_t *) 335 #define AOM_CTRL_AV1D_GET_IMG_FORMAT 336 337 AOM_CTRL_USE_TYPE(AV1D_GET_TILE_SIZE, unsigned int *) 338 #define AOM_CTRL_AV1D_GET_TILE_SIZE 339 340 AOM_CTRL_USE_TYPE(AV1D_GET_TILE_COUNT, unsigned int *) 341 #define AOM_CTRL_AV1D_GET_TILE_COUNT 342 343 AOM_CTRL_USE_TYPE(AV1D_GET_FRAME_SIZE, int *) 344 #define AOM_CTRL_AV1D_GET_FRAME_SIZE 345 346 AOM_CTRL_USE_TYPE(AV1_INVERT_TILE_DECODE_ORDER, int) 347 #define AOM_CTRL_AV1_INVERT_TILE_DECODE_ORDER 348 349 AOM_CTRL_USE_TYPE(AV1_GET_ACCOUNTING, Accounting **) 350 #define AOM_CTRL_AV1_GET_ACCOUNTING 351 352 AOM_CTRL_USE_TYPE(AV1_SET_DECODE_TILE_ROW, int) 353 #define AOM_CTRL_AV1_SET_DECODE_TILE_ROW 354 355 AOM_CTRL_USE_TYPE(AV1_SET_DECODE_TILE_COL, int) 356 #define AOM_CTRL_AV1_SET_DECODE_TILE_COL 357 358 AOM_CTRL_USE_TYPE(AV1_SET_TILE_MODE, unsigned int) 359 #define AOM_CTRL_AV1_SET_TILE_MODE 360 361 AOM_CTRL_USE_TYPE(AV1D_GET_FRAME_HEADER_INFO, aom_tile_data *) 362 #define AOM_CTRL_AV1D_GET_FRAME_HEADER_INFO 363 364 AOM_CTRL_USE_TYPE(AV1D_GET_TILE_DATA, aom_tile_data *) 365 #define AOM_CTRL_AV1D_GET_TILE_DATA 366 367 AOM_CTRL_USE_TYPE(AV1D_SET_EXT_REF_PTR, av1_ext_ref_frame_t *) 368 #define AOM_CTRL_AV1D_SET_EXT_REF_PTR 369 370 AOM_CTRL_USE_TYPE(AV1D_EXT_TILE_DEBUG, unsigned int) 371 #define AOM_CTRL_AV1D_EXT_TILE_DEBUG 372 373 AOM_CTRL_USE_TYPE(AV1D_SET_ROW_MT, unsigned int) 374 #define AOM_CTRL_AV1D_SET_ROW_MT 375 376 AOM_CTRL_USE_TYPE(AV1D_SET_SKIP_FILM_GRAIN, int) 377 #define AOM_CTRL_AV1D_SET_SKIP_FILM_GRAIN 378 379 AOM_CTRL_USE_TYPE(AV1D_SET_IS_ANNEXB, unsigned int) 380 #define AOM_CTRL_AV1D_SET_IS_ANNEXB 381 382 AOM_CTRL_USE_TYPE(AV1D_SET_OPERATING_POINT, int) 383 #define AOM_CTRL_AV1D_SET_OPERATING_POINT 384 385 AOM_CTRL_USE_TYPE(AV1D_SET_OUTPUT_ALL_LAYERS, int) 386 #define AOM_CTRL_AV1D_SET_OUTPUT_ALL_LAYERS 387 388 AOM_CTRL_USE_TYPE(AV1_SET_INSPECTION_CALLBACK, aom_inspect_init *) 389 #define AOM_CTRL_AV1_SET_INSPECTION_CALLBACK 390 /*!\endcond */ 391 /*! @} - end defgroup aom_decoder */ 392 393 #ifdef __cplusplus 394 } // extern "C" 395 #endif 396 397 #endif // AOM_AOM_AOMDX_H_ 398