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 37 /*!\brief A single instance of the AV1 decoder. 38 *\deprecated This access mechanism is provided for backwards compatibility; 39 * prefer aom_codec_av1_dx(). 40 */ 41 extern aom_codec_iface_t aom_codec_av1_dx_algo; 42 /*!\brief The interface to the AV1 decoder. 43 */ 44 extern aom_codec_iface_t *aom_codec_av1_dx(void); 45 46 /*!@} - end algorithm interface member group */ 47 48 /** Data structure that stores bit accounting for debug 49 */ 50 typedef struct Accounting Accounting; 51 52 #ifndef AOM_INSPECTION_H_ 53 /** Callback that inspects decoder frame data. 54 */ 55 typedef void (*aom_inspect_cb)(void *decoder, void *ctx); 56 57 #endif 58 59 /*!\brief Structure to hold inspection callback and context. 60 * 61 * Defines a structure to hold the inspection callback function and calling 62 * context. 63 */ 64 typedef struct aom_inspect_init { 65 /*! Inspection callback. */ 66 aom_inspect_cb inspect_cb; 67 68 /*! Inspection context. */ 69 void *inspect_ctx; 70 } aom_inspect_init; 71 72 /*!\brief Structure to collect a buffer index when inspecting. 73 * 74 * Defines a structure to hold the buffer and return an index 75 * when calling decode from inspect. This enables us to decode 76 * non showable sub frames. 77 */ 78 typedef struct { 79 /*! Pointer for new position in compressed buffer after decoding 1 OBU. */ 80 const unsigned char *buf; 81 /*! Index into reference buffer array to see result of decoding 1 OBU. */ 82 int idx; 83 /*! Is a show existing frame. */ 84 int show_existing; 85 } Av1DecodeReturn; 86 87 /*!\brief Structure to hold a tile's start address and size in the bitstream. 88 * 89 * Defines a structure to hold a tile's start address and size in the bitstream. 90 */ 91 typedef struct aom_tile_data { 92 /*! Tile data size. */ 93 size_t coded_tile_data_size; 94 /*! Tile's start address. */ 95 const void *coded_tile_data; 96 /*! Extra size information. */ 97 size_t extra_size; 98 } aom_tile_data; 99 100 /*!\brief Max number of tile columns 101 * 102 * This is the limit of number of tile columns allowed within a frame. 103 * 104 * Currently same as "MAX_TILE_COLS" in AV1, the maximum that AV1 supports. 105 * 106 */ 107 #define AOM_MAX_TILE_COLS 64 108 /*!\brief Max number of tile rows 109 * 110 * This is the limit of number of tile rows allowed within a frame. 111 * 112 * Currently same as "MAX_TILE_ROWS" in AV1, the maximum that AV1 supports. 113 * 114 */ 115 #define AOM_MAX_TILE_ROWS 64 116 117 /*!\brief Structure to hold information about tiles in a frame. 118 * 119 * Defines a structure to hold a frame's tile information, namely 120 * number of tile columns, number of tile_rows, and the width and 121 * height of each tile. 122 */ 123 typedef struct aom_tile_info { 124 /*! Indicates the number of tile columns. */ 125 int tile_columns; 126 /*! Indicates the number of tile rows. */ 127 int tile_rows; 128 /*! Indicates the tile widths in units of SB. */ 129 int tile_widths[AOM_MAX_TILE_COLS]; 130 /*! Indicates the tile heights in units of SB. */ 131 int tile_heights[AOM_MAX_TILE_ROWS]; 132 /*! Indicates the number of tile groups present in a frame. */ 133 int num_tile_groups; 134 } aom_tile_info; 135 136 /*!\brief Structure to hold information about still image coding. 137 * 138 * Defines a structure to hold a information regarding still picture 139 * and its header type. 140 */ 141 typedef struct aom_still_picture_info { 142 /*! Video is a single frame still picture */ 143 int is_still_picture; 144 /*! Use full header for still picture */ 145 int is_reduced_still_picture_hdr; 146 } aom_still_picture_info; 147 148 /*!\brief Structure to hold information about S_FRAME. 149 * 150 * Defines a structure to hold a information regarding S_FRAME 151 * and its position. 152 */ 153 typedef struct aom_s_frame_info { 154 /*! Indicates if current frame is S_FRAME */ 155 int is_s_frame; 156 /*! Indicates if current S_FRAME is present at ALTREF frame*/ 157 int is_s_frame_at_altref; 158 } aom_s_frame_info; 159 160 /*!\brief Structure to hold information about screen content tools. 161 * 162 * Defines a structure to hold information about screen content 163 * tools, namely: allow_screen_content_tools, allow_intrabc, and 164 * force_integer_mv. 165 */ 166 typedef struct aom_screen_content_tools_info { 167 /*! Are screen content tools allowed */ 168 int allow_screen_content_tools; 169 /*! Is intrabc allowed */ 170 int allow_intrabc; 171 /*! Is integer mv forced */ 172 int force_integer_mv; 173 } aom_screen_content_tools_info; 174 175 /*!\brief Structure to hold the external reference frame pointer. 176 * 177 * Define a structure to hold the external reference frame pointer. 178 */ 179 typedef struct av1_ext_ref_frame { 180 /*! Start pointer of external references. */ 181 aom_image_t *img; 182 /*! Number of available external references. */ 183 int num; 184 } av1_ext_ref_frame_t; 185 186 /*!\enum aom_dec_control_id 187 * \brief AOM decoder control functions 188 * 189 * This set of macros define the control functions available for the AOM 190 * decoder interface. 191 * The range for decoder control ID is >= 256. 192 * 193 * \sa #aom_codec_control(aom_codec_ctx_t *ctx, int ctrl_id, ...) 194 */ 195 enum aom_dec_control_id { 196 /*!\brief Codec control function to get info on which reference frames were 197 * updated by the last decode, int* parameter 198 */ 199 AOMD_GET_LAST_REF_UPDATES = AOM_DECODER_CTRL_ID_START, 200 201 /*!\brief Codec control function to check if the indicated frame is 202 corrupted, int* parameter 203 */ 204 AOMD_GET_FRAME_CORRUPTED, 205 206 /*!\brief Codec control function to get info on which reference frames were 207 * used by the last decode, int* parameter 208 */ 209 AOMD_GET_LAST_REF_USED, 210 211 /*!\brief Codec control function to get the dimensions that the current 212 * frame is decoded at, int* parameter. This may be different to the 213 * intended display size for the frame as specified in the wrapper or frame 214 * header (see AV1D_GET_DISPLAY_SIZE). 215 */ 216 AV1D_GET_FRAME_SIZE, 217 218 /*!\brief Codec control function to get the current frame's intended display 219 * dimensions (as specified in the wrapper or frame header), int* parameter. 220 * This may be different to the decoded dimensions of this frame (see 221 * AV1D_GET_FRAME_SIZE). 222 */ 223 AV1D_GET_DISPLAY_SIZE, 224 225 /*!\brief Codec control function to get the bit depth of the stream, 226 * unsigned int* parameter 227 */ 228 AV1D_GET_BIT_DEPTH, 229 230 /*!\brief Codec control function to get the image format of the stream, 231 * aom_img_fmt_t* parameter 232 */ 233 AV1D_GET_IMG_FORMAT, 234 235 /*!\brief Codec control function to get the size of the tile, unsigned int 236 parameter */ 237 AV1D_GET_TILE_SIZE, 238 239 /*!\brief Codec control function to get the tile count in a tile list, int* 240 * parameter 241 */ 242 AV1D_GET_TILE_COUNT, 243 244 /*!\brief Codec control function to set the byte alignment of the planes in 245 * the reference buffers, int parameter 246 * 247 * Valid values are power of 2, from 32 to 1024. A value of 0 sets 248 * legacy alignment. I.e. Y plane is aligned to 32 bytes, U plane directly 249 * follows Y plane, and V plane directly follows U plane. Default value is 0. 250 */ 251 AV1_SET_BYTE_ALIGNMENT, 252 253 /*!\brief Codec control function to invert the decoding order to from right to 254 * left, int parameter 255 * 256 * The function is used in a test to confirm the decoding independence of tile 257 * columns. The function may be used in application where this order 258 * of decoding is desired. int parameter 259 * 260 * TODO(yaowu): Rework the unit test that uses this control, and in a future 261 * release, this test-only control shall be removed. 262 */ 263 AV1_INVERT_TILE_DECODE_ORDER, 264 265 /*!\brief Codec control function to set the skip loop filter flag, int 266 * parameter 267 * 268 * Valid values are integers. The decoder will skip the loop filter 269 * when its value is set to nonzero. If the loop filter is skipped the 270 * decoder may accumulate decode artifacts. The default value is 0. 271 */ 272 AV1_SET_SKIP_LOOP_FILTER, 273 274 /*!\brief Codec control function to retrieve a pointer to the Accounting 275 * struct, takes Accounting** as parameter 276 * 277 * If called before a frame has been decoded, this returns AOM_CODEC_ERROR. 278 * The caller should ensure that AOM_CODEC_OK is returned before attempting 279 * to dereference the Accounting pointer. 280 * 281 * \attention When compiled without --enable-accounting, this returns 282 * AOM_CODEC_INCAPABLE. 283 */ 284 AV1_GET_ACCOUNTING, 285 286 /*!\brief Codec control function to get last decoded frame quantizer, 287 * int* parameter 288 * 289 * Returned value uses internal quantizer scale defined by the codec. 290 */ 291 AOMD_GET_LAST_QUANTIZER, 292 293 /*!\brief Codec control function to set the range of tile decoding, int 294 * parameter 295 * 296 * A value that is greater and equal to zero indicates only the specific 297 * row/column is decoded. A value that is -1 indicates the whole row/column 298 * is decoded. A special case is both values are -1 that means the whole 299 * frame is decoded. 300 */ 301 AV1_SET_DECODE_TILE_ROW, 302 AV1_SET_DECODE_TILE_COL, 303 304 /*!\brief Codec control function to set the tile coding mode, int parameter 305 * 306 * - 0 = tiles are coded in normal tile mode 307 * - 1 = tiles are coded in large-scale tile mode 308 */ 309 AV1_SET_TILE_MODE, 310 311 /*!\brief Codec control function to get the frame header information of an 312 * encoded frame, unsigned int* parameter 313 */ 314 AV1D_GET_FRAME_HEADER_INFO, 315 316 /*!\brief Codec control function to get the start address and size of a 317 * tile in the coded bitstream, aom_tile_data* parameter. 318 */ 319 AV1D_GET_TILE_DATA, 320 321 /*!\brief Codec control function to set the external references' pointers in 322 * the decoder, av1_ext_ref_frame_t* parameter. 323 * 324 * This is used while decoding the tile list OBU in large-scale tile coding 325 * mode. 326 */ 327 AV1D_SET_EXT_REF_PTR, 328 329 /*!\brief Codec control function to enable the ext-tile software debug and 330 * testing code in the decoder, unsigned int parameter 331 */ 332 AV1D_EXT_TILE_DEBUG, 333 334 /*!\brief Codec control function to enable the row based multi-threading of 335 * decoding, unsigned int parameter 336 * 337 * - 0 = disabled 338 * - 1 = enabled (default) 339 */ 340 AV1D_SET_ROW_MT, 341 342 /*!\brief Codec control function to indicate whether bitstream is in 343 * Annex-B format, unsigned int parameter 344 */ 345 AV1D_SET_IS_ANNEXB, 346 347 /*!\brief Codec control function to indicate which operating point to use, 348 * int parameter 349 * 350 * A scalable stream may define multiple operating points, each of which 351 * defines a set of temporal and spatial layers to be processed. The 352 * operating point index may take a value between 0 and 353 * operating_points_cnt_minus_1 (which is at most 31). 354 */ 355 AV1D_SET_OPERATING_POINT, 356 357 /*!\brief Codec control function to indicate whether to output one frame per 358 * temporal unit (the default), or one frame per spatial layer. int parameter 359 * 360 * In a scalable stream, each temporal unit corresponds to a single "frame" 361 * of video, and within a temporal unit there may be multiple spatial layers 362 * with different versions of that frame. 363 * For video playback, only the highest-quality version (within the 364 * selected operating point) is needed, but for some use cases it is useful 365 * to have access to multiple versions of a frame when they are available. 366 */ 367 AV1D_SET_OUTPUT_ALL_LAYERS, 368 369 /*!\brief Codec control function to set an aom_inspect_cb callback that is 370 * invoked each time a frame is decoded, aom_inspect_init* parameter 371 * 372 * \attention When compiled without --enable-inspection, this 373 * returns AOM_CODEC_INCAPABLE. 374 */ 375 AV1_SET_INSPECTION_CALLBACK, 376 377 /*!\brief Codec control function to set the skip film grain flag, int 378 * parameter 379 * 380 * Valid values are integers. The decoder will skip the film grain when its 381 * value is set to nonzero. The default value is 0. 382 */ 383 AV1D_SET_SKIP_FILM_GRAIN, 384 385 /*!\brief Codec control function to check the presence of forward key frames 386 */ 387 AOMD_GET_FWD_KF_PRESENT, 388 389 /*!\brief Codec control function to get the frame flags of the previous frame 390 * decoded. This will return a flag of type aom_codec_frame_flags_t. 391 */ 392 AOMD_GET_FRAME_FLAGS, 393 394 /*!\brief Codec control function to check the presence of altref frames */ 395 AOMD_GET_ALTREF_PRESENT, 396 397 /*!\brief Codec control function to get tile information of the previous frame 398 * decoded. This will return a struct of type aom_tile_info. 399 */ 400 AOMD_GET_TILE_INFO, 401 402 /*!\brief Codec control function to get screen content tools information. 403 * It returns a struct of type aom_screen_content_tools_info, which contains 404 * the header flags allow_screen_content_tools, allow_intrabc, and 405 * force_integer_mv. 406 */ 407 AOMD_GET_SCREEN_CONTENT_TOOLS_INFO, 408 409 /*!\brief Codec control function to get the still picture coding information 410 */ 411 AOMD_GET_STILL_PICTURE, 412 413 /*!\brief Codec control function to get superblock size. 414 * It returns an integer, indicating the superblock size 415 * read from the sequence header(0 for BLOCK_64X64 and 416 * 1 for BLOCK_128X128) 417 */ 418 AOMD_GET_SB_SIZE, 419 420 /*!\brief Codec control function to check if the previous frame 421 * decoded has show existing frame flag set. 422 */ 423 AOMD_GET_SHOW_EXISTING_FRAME_FLAG, 424 425 /*!\brief Codec control function to get the S_FRAME coding information 426 */ 427 AOMD_GET_S_FRAME_INFO, 428 }; 429 430 /*!\cond */ 431 /*!\brief AOM decoder control function parameter type 432 * 433 * Defines the data types that AOMD control functions take. 434 * 435 * \note Additional common controls are defined in aom.h. 436 * 437 * \note For each control ID "X", a macro-define of 438 * AOM_CTRL_X is provided. It is used at compile time to determine 439 * if the control ID is supported by the libaom library available, 440 * when the libaom version cannot be controlled. 441 */ 442 AOM_CTRL_USE_TYPE(AOMD_GET_LAST_REF_UPDATES, int *) 443 #define AOM_CTRL_AOMD_GET_LAST_REF_UPDATES 444 445 AOM_CTRL_USE_TYPE(AOMD_GET_FRAME_CORRUPTED, int *) 446 #define AOM_CTRL_AOMD_GET_FRAME_CORRUPTED 447 448 AOM_CTRL_USE_TYPE(AOMD_GET_LAST_REF_USED, int *) 449 #define AOM_CTRL_AOMD_GET_LAST_REF_USED 450 451 AOM_CTRL_USE_TYPE(AOMD_GET_LAST_QUANTIZER, int *) 452 #define AOM_CTRL_AOMD_GET_LAST_QUANTIZER 453 454 AOM_CTRL_USE_TYPE(AOMD_GET_FWD_KF_PRESENT, int *) 455 #define AOM_CTRL_AOMD_GET_FWD_KF_PRESENT 456 457 AOM_CTRL_USE_TYPE(AOMD_GET_ALTREF_PRESENT, int *) 458 #define AOM_CTRL_AOMD_GET_ALTREF_PRESENT 459 460 AOM_CTRL_USE_TYPE(AOMD_GET_FRAME_FLAGS, int *) 461 #define AOM_CTRL_AOMD_GET_FRAME_FLAGS 462 463 AOM_CTRL_USE_TYPE(AOMD_GET_TILE_INFO, aom_tile_info *) 464 #define AOM_CTRL_AOMD_GET_TILE_INFO 465 466 AOM_CTRL_USE_TYPE(AOMD_GET_SCREEN_CONTENT_TOOLS_INFO, 467 aom_screen_content_tools_info *) 468 #define AOM_CTRL_AOMD_GET_SCREEN_CONTENT_TOOLS_INFO 469 470 AOM_CTRL_USE_TYPE(AOMD_GET_STILL_PICTURE, aom_still_picture_info *) 471 #define AOM_CTRL_AOMD_GET_STILL_PICTURE 472 473 AOM_CTRL_USE_TYPE(AOMD_GET_SB_SIZE, aom_superblock_size_t *) 474 #define AOMD_CTRL_AOMD_GET_SB_SIZE 475 476 AOM_CTRL_USE_TYPE(AOMD_GET_SHOW_EXISTING_FRAME_FLAG, int *) 477 #define AOMD_CTRL_AOMD_GET_SHOW_EXISTING_FRAME_FLAG 478 479 AOM_CTRL_USE_TYPE(AOMD_GET_S_FRAME_INFO, aom_s_frame_info *) 480 #define AOMD_CTRL_AOMD_GET_S_FRAME_INFO 481 482 AOM_CTRL_USE_TYPE(AV1D_GET_DISPLAY_SIZE, int *) 483 #define AOM_CTRL_AV1D_GET_DISPLAY_SIZE 484 485 AOM_CTRL_USE_TYPE(AV1D_GET_BIT_DEPTH, unsigned int *) 486 #define AOM_CTRL_AV1D_GET_BIT_DEPTH 487 488 AOM_CTRL_USE_TYPE(AV1D_GET_IMG_FORMAT, aom_img_fmt_t *) 489 #define AOM_CTRL_AV1D_GET_IMG_FORMAT 490 491 AOM_CTRL_USE_TYPE(AV1D_GET_TILE_SIZE, unsigned int *) 492 #define AOM_CTRL_AV1D_GET_TILE_SIZE 493 494 AOM_CTRL_USE_TYPE(AV1D_GET_TILE_COUNT, unsigned int *) 495 #define AOM_CTRL_AV1D_GET_TILE_COUNT 496 497 AOM_CTRL_USE_TYPE(AV1D_GET_FRAME_SIZE, int *) 498 #define AOM_CTRL_AV1D_GET_FRAME_SIZE 499 500 AOM_CTRL_USE_TYPE(AV1_INVERT_TILE_DECODE_ORDER, int) 501 #define AOM_CTRL_AV1_INVERT_TILE_DECODE_ORDER 502 503 AOM_CTRL_USE_TYPE(AV1_GET_ACCOUNTING, Accounting **) 504 #define AOM_CTRL_AV1_GET_ACCOUNTING 505 506 AOM_CTRL_USE_TYPE(AV1_SET_DECODE_TILE_ROW, int) 507 #define AOM_CTRL_AV1_SET_DECODE_TILE_ROW 508 509 AOM_CTRL_USE_TYPE(AV1_SET_DECODE_TILE_COL, int) 510 #define AOM_CTRL_AV1_SET_DECODE_TILE_COL 511 512 AOM_CTRL_USE_TYPE(AV1_SET_TILE_MODE, unsigned int) 513 #define AOM_CTRL_AV1_SET_TILE_MODE 514 515 AOM_CTRL_USE_TYPE(AV1D_GET_FRAME_HEADER_INFO, aom_tile_data *) 516 #define AOM_CTRL_AV1D_GET_FRAME_HEADER_INFO 517 518 AOM_CTRL_USE_TYPE(AV1D_GET_TILE_DATA, aom_tile_data *) 519 #define AOM_CTRL_AV1D_GET_TILE_DATA 520 521 AOM_CTRL_USE_TYPE(AV1D_SET_EXT_REF_PTR, av1_ext_ref_frame_t *) 522 #define AOM_CTRL_AV1D_SET_EXT_REF_PTR 523 524 AOM_CTRL_USE_TYPE(AV1D_EXT_TILE_DEBUG, unsigned int) 525 #define AOM_CTRL_AV1D_EXT_TILE_DEBUG 526 527 AOM_CTRL_USE_TYPE(AV1D_SET_ROW_MT, unsigned int) 528 #define AOM_CTRL_AV1D_SET_ROW_MT 529 530 AOM_CTRL_USE_TYPE(AV1D_SET_SKIP_FILM_GRAIN, int) 531 #define AOM_CTRL_AV1D_SET_SKIP_FILM_GRAIN 532 533 AOM_CTRL_USE_TYPE(AV1D_SET_IS_ANNEXB, unsigned int) 534 #define AOM_CTRL_AV1D_SET_IS_ANNEXB 535 536 AOM_CTRL_USE_TYPE(AV1D_SET_OPERATING_POINT, int) 537 #define AOM_CTRL_AV1D_SET_OPERATING_POINT 538 539 AOM_CTRL_USE_TYPE(AV1D_SET_OUTPUT_ALL_LAYERS, int) 540 #define AOM_CTRL_AV1D_SET_OUTPUT_ALL_LAYERS 541 542 AOM_CTRL_USE_TYPE(AV1_SET_INSPECTION_CALLBACK, aom_inspect_init *) 543 #define AOM_CTRL_AV1_SET_INSPECTION_CALLBACK 544 /*!\endcond */ 545 /*! @} - end defgroup aom_decoder */ 546 #ifdef __cplusplus 547 } // extern "C" 548 #endif 549 550 #endif // AOM_AOM_AOMDX_H_ 551