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 110 */ 111 enum aom_dec_control_id { 112 /** control function to get info on which reference frames were updated 113 * by the last decode 114 */ 115 AOMD_GET_LAST_REF_UPDATES = AOM_DECODER_CTRL_ID_START, 116 117 /** check if the indicated frame is corrupted */ 118 AOMD_GET_FRAME_CORRUPTED, 119 120 /** control function to get info on which reference frames were used 121 * by the last decode 122 */ 123 AOMD_GET_LAST_REF_USED, 124 125 /** control function to get the dimensions that the current frame is decoded 126 * at. This may be different to the intended display size for the frame as 127 * specified in the wrapper or frame header (see AV1D_GET_DISPLAY_SIZE). */ 128 AV1D_GET_FRAME_SIZE, 129 130 /** control function to get the current frame's intended display dimensions 131 * (as specified in the wrapper or frame header). This may be different to 132 * the decoded dimensions of this frame (see AV1D_GET_FRAME_SIZE). */ 133 AV1D_GET_DISPLAY_SIZE, 134 135 /** control function to get the bit depth of the stream. */ 136 AV1D_GET_BIT_DEPTH, 137 138 /** control function to get the image format of the stream. */ 139 AV1D_GET_IMG_FORMAT, 140 141 /** control function to get the size of the tile. */ 142 AV1D_GET_TILE_SIZE, 143 144 /** control function to get the tile count in a tile list. */ 145 AV1D_GET_TILE_COUNT, 146 147 /** control function to set the byte alignment of the planes in the reference 148 * buffers. Valid values are power of 2, from 32 to 1024. A value of 0 sets 149 * legacy alignment. I.e. Y plane is aligned to 32 bytes, U plane directly 150 * follows Y plane, and V plane directly follows U plane. Default value is 0. 151 */ 152 AV1_SET_BYTE_ALIGNMENT, 153 154 /** control function to invert the decoding order to from right to left. The 155 * function is used in a test to confirm the decoding independence of tile 156 * columns. The function may be used in application where this order 157 * of decoding is desired. 158 * 159 * TODO(yaowu): Rework the unit test that uses this control, and in a future 160 * release, this test-only control shall be removed. 161 */ 162 AV1_INVERT_TILE_DECODE_ORDER, 163 164 /** control function to set the skip loop filter flag. Valid values are 165 * integers. The decoder will skip the loop filter when its value is set to 166 * nonzero. If the loop filter is skipped the decoder may accumulate decode 167 * artifacts. The default value is 0. 168 */ 169 AV1_SET_SKIP_LOOP_FILTER, 170 171 /** control function to retrieve a pointer to the Accounting struct. When 172 * compiled without --enable-accounting, this returns AOM_CODEC_INCAPABLE. 173 * If called before a frame has been decoded, this returns AOM_CODEC_ERROR. 174 * The caller should ensure that AOM_CODEC_OK is returned before attempting 175 * to dereference the Accounting pointer. 176 */ 177 AV1_GET_ACCOUNTING, 178 179 /** control function to get last decoded frame quantizer. Returned value uses 180 * internal quantizer scale defined by the codec. 181 */ 182 AOMD_GET_LAST_QUANTIZER, 183 184 /** control function to set the range of tile decoding. A value that is 185 * greater and equal to zero indicates only the specific row/column is 186 * decoded. A value that is -1 indicates the whole row/column is decoded. 187 * A special case is both values are -1 that means the whole frame is 188 * decoded. 189 */ 190 AV1_SET_DECODE_TILE_ROW, 191 AV1_SET_DECODE_TILE_COL, 192 /** control function to set the tile coding mode. A value that is equal to 193 * zero indicates the tiles are coded in normal tile mode. A value that is 194 * 1 indicates the tiles are coded in large-scale tile mode. 195 */ 196 AV1_SET_TILE_MODE, 197 /** control function to get the frame header information of an encoded frame 198 * in the bitstream. This provides a way to access a frame's header data. 199 */ 200 AV1D_GET_FRAME_HEADER_INFO, 201 /** control function to get the start address and size of a tile in the coded 202 * bitstream. This provides a way to access a specific tile's bitstream data. 203 */ 204 AV1D_GET_TILE_DATA, 205 /** control function to set the external references' pointers in the decoder. 206 * This is used while decoding the tile list OBU in large-scale tile coding 207 * mode. 208 */ 209 AV1D_SET_EXT_REF_PTR, 210 /** control function to enable the ext-tile software debug and testing code in 211 * the decoder. 212 */ 213 AV1D_EXT_TILE_DEBUG, 214 215 /** control function to enable the row based multi-threading of decoding. A 216 * value that is equal to 1 indicates that row based multi-threading is 217 * enabled. 218 */ 219 AV1D_SET_ROW_MT, 220 221 /** control function to indicate whether bitstream is in Annex-B format. */ 222 AV1D_SET_IS_ANNEXB, 223 224 /** control function to indicate which operating point to use. A scalable 225 * stream may define multiple operating points, each of which defines a 226 * set of temporal and spatial layers to be processed. The operating point 227 * index may take a value between 0 and operating_points_cnt_minus_1 (which 228 * is at most 31). 229 */ 230 AV1D_SET_OPERATING_POINT, 231 232 /** control function to indicate whether to output one frame per temporal 233 * unit (the default), or one frame per spatial layer. 234 * In a scalable stream, each temporal unit corresponds to a single "frame" 235 * of video, and within a temporal unit there may be multiple spatial layers 236 * with different versions of that frame. 237 * For video playback, only the highest-quality version (within the 238 * selected operating point) is needed, but for some use cases it is useful 239 * to have access to multiple versions of a frame when they are available. 240 */ 241 AV1D_SET_OUTPUT_ALL_LAYERS, 242 243 /** control function to set an aom_inspect_cb callback that is invoked each 244 * time a frame is decoded. When compiled without --enable-inspection, this 245 * returns AOM_CODEC_INCAPABLE. 246 */ 247 AV1_SET_INSPECTION_CALLBACK, 248 249 /** control function to set the skip film grain flag. Valid values are 250 * integers. The decoder will skip the film grain when its value is set to 251 * nonzero. The default value is 0. 252 */ 253 AV1D_SET_SKIP_FILM_GRAIN, 254 255 AOM_DECODER_CTRL_ID_MAX, 256 }; 257 258 /*!\cond */ 259 /*!\brief AOM decoder control function parameter type 260 * 261 * Defines the data types that AOMD control functions take. Note that 262 * additional common controls are defined in aom.h 263 * 264 */ 265 266 AOM_CTRL_USE_TYPE(AOMD_GET_LAST_REF_UPDATES, int *) 267 #define AOM_CTRL_AOMD_GET_LAST_REF_UPDATES 268 AOM_CTRL_USE_TYPE(AOMD_GET_FRAME_CORRUPTED, int *) 269 #define AOM_CTRL_AOMD_GET_FRAME_CORRUPTED 270 AOM_CTRL_USE_TYPE(AOMD_GET_LAST_REF_USED, int *) 271 #define AOM_CTRL_AOMD_GET_LAST_REF_USED 272 AOM_CTRL_USE_TYPE(AOMD_GET_LAST_QUANTIZER, int *) 273 #define AOM_CTRL_AOMD_GET_LAST_QUANTIZER 274 AOM_CTRL_USE_TYPE(AV1D_GET_DISPLAY_SIZE, int *) 275 #define AOM_CTRL_AV1D_GET_DISPLAY_SIZE 276 AOM_CTRL_USE_TYPE(AV1D_GET_BIT_DEPTH, unsigned int *) 277 #define AOM_CTRL_AV1D_GET_BIT_DEPTH 278 AOM_CTRL_USE_TYPE(AV1D_GET_IMG_FORMAT, aom_img_fmt_t *) 279 #define AOM_CTRL_AV1D_GET_IMG_FORMAT 280 AOM_CTRL_USE_TYPE(AV1D_GET_TILE_SIZE, unsigned int *) 281 #define AOM_CTRL_AV1D_GET_TILE_SIZE 282 AOM_CTRL_USE_TYPE(AV1D_GET_TILE_COUNT, unsigned int *) 283 #define AOM_CTRL_AV1D_GET_TILE_COUNT 284 AOM_CTRL_USE_TYPE(AV1D_GET_FRAME_SIZE, int *) 285 #define AOM_CTRL_AV1D_GET_FRAME_SIZE 286 AOM_CTRL_USE_TYPE(AV1_INVERT_TILE_DECODE_ORDER, int) 287 #define AOM_CTRL_AV1_INVERT_TILE_DECODE_ORDER 288 AOM_CTRL_USE_TYPE(AV1_GET_ACCOUNTING, Accounting **) 289 #define AOM_CTRL_AV1_GET_ACCOUNTING 290 AOM_CTRL_USE_TYPE(AV1_SET_DECODE_TILE_ROW, int) 291 #define AOM_CTRL_AV1_SET_DECODE_TILE_ROW 292 AOM_CTRL_USE_TYPE(AV1_SET_DECODE_TILE_COL, int) 293 #define AOM_CTRL_AV1_SET_DECODE_TILE_COL 294 AOM_CTRL_USE_TYPE(AV1_SET_TILE_MODE, unsigned int) 295 #define AOM_CTRL_AV1_SET_TILE_MODE 296 AOM_CTRL_USE_TYPE(AV1D_GET_FRAME_HEADER_INFO, aom_tile_data *) 297 #define AOM_CTRL_AV1D_GET_FRAME_HEADER_INFO 298 AOM_CTRL_USE_TYPE(AV1D_GET_TILE_DATA, aom_tile_data *) 299 #define AOM_CTRL_AV1D_GET_TILE_DATA 300 AOM_CTRL_USE_TYPE(AV1D_SET_EXT_REF_PTR, av1_ext_ref_frame_t *) 301 #define AOM_CTRL_AV1D_SET_EXT_REF_PTR 302 AOM_CTRL_USE_TYPE(AV1D_EXT_TILE_DEBUG, unsigned int) 303 #define AOM_CTRL_AV1D_EXT_TILE_DEBUG 304 AOM_CTRL_USE_TYPE(AV1D_SET_ROW_MT, unsigned int) 305 #define AOM_CTRL_AV1D_SET_ROW_MT 306 AOM_CTRL_USE_TYPE(AV1D_SET_SKIP_FILM_GRAIN, int) 307 #define AOM_CTRL_AV1D_SET_SKIP_FILM_GRAIN 308 AOM_CTRL_USE_TYPE(AV1D_SET_IS_ANNEXB, unsigned int) 309 #define AOM_CTRL_AV1D_SET_IS_ANNEXB 310 AOM_CTRL_USE_TYPE(AV1D_SET_OPERATING_POINT, int) 311 #define AOM_CTRL_AV1D_SET_OPERATING_POINT 312 AOM_CTRL_USE_TYPE(AV1D_SET_OUTPUT_ALL_LAYERS, int) 313 #define AOM_CTRL_AV1D_SET_OUTPUT_ALL_LAYERS 314 AOM_CTRL_USE_TYPE(AV1_SET_INSPECTION_CALLBACK, aom_inspect_init *) 315 #define AOM_CTRL_AV1_SET_INSPECTION_CALLBACK 316 /*!\endcond */ 317 /*! @} - end defgroup aom_decoder */ 318 319 #ifdef __cplusplus 320 } // extern "C" 321 #endif 322 323 #endif // AOM_AOM_AOMDX_H_ 324