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 #ifndef AOM_AOM_AOM_DECODER_H_ 12 #define AOM_AOM_AOM_DECODER_H_ 13 14 /*!\defgroup decoder Decoder Algorithm Interface 15 * \ingroup codec 16 * This abstraction allows applications using this decoder to easily support 17 * multiple video formats with minimal code duplication. This section describes 18 * the interface common to all decoders. 19 * @{ 20 */ 21 22 /*!\file 23 * \brief Describes the decoder algorithm interface to applications. 24 * 25 * This file describes the interface between an application and a 26 * video decoder algorithm. 27 * 28 */ 29 #ifdef __cplusplus 30 extern "C" { 31 #endif 32 33 #include "aom/aom_codec.h" 34 #include "aom/aom_frame_buffer.h" 35 36 /*!\brief Current ABI version number 37 * 38 * \internal 39 * If this file is altered in any way that changes the ABI, this value 40 * must be bumped. Examples include, but are not limited to, changing 41 * types, removing or reassigning enums, adding/removing/rearranging 42 * fields to structures 43 */ 44 #define AOM_DECODER_ABI_VERSION \ 45 (3 + AOM_CODEC_ABI_VERSION) /**<\hideinitializer*/ 46 47 /*! \brief Decoder capabilities bitfield 48 * 49 * Each decoder advertises the capabilities it supports as part of its 50 * ::aom_codec_iface_t interface structure. Capabilities are extra interfaces 51 * or functionality, and are not required to be supported by a decoder. 52 * 53 * The available flags are specified by AOM_CODEC_CAP_* defines. 54 */ 55 #define AOM_CODEC_CAP_PUT_SLICE 0x10000 /**< Will issue put_slice callbacks */ 56 #define AOM_CODEC_CAP_PUT_FRAME 0x20000 /**< Will issue put_frame callbacks */ 57 #define AOM_CODEC_CAP_POSTPROC 0x40000 /**< Can postprocess decoded frame */ 58 59 /*! \brief Initialization-time Feature Enabling 60 * 61 * Certain codec features must be known at initialization time, to allow for 62 * proper memory allocation. 63 * 64 * The available flags are specified by AOM_CODEC_USE_* defines. 65 */ 66 /*!brief Can support external frame buffers */ 67 #define AOM_CODEC_CAP_EXTERNAL_FRAME_BUFFER 0x200000 68 69 #define AOM_CODEC_USE_POSTPROC 0x10000 /**< Postprocess decoded frame */ 70 71 /*!\brief Stream properties 72 * 73 * This structure is used to query or set properties of the decoded 74 * stream. 75 */ 76 typedef struct aom_codec_stream_info { 77 unsigned int w; /**< Width (or 0 for unknown/default) */ 78 unsigned int h; /**< Height (or 0 for unknown/default) */ 79 unsigned int is_kf; /**< Current frame is a keyframe */ 80 unsigned int number_spatial_layers; /**< Number of spatial layers */ 81 unsigned int number_temporal_layers; /**< Number of temporal layers */ 82 unsigned int is_annexb; /**< Is Bitstream in Annex-B format */ 83 } aom_codec_stream_info_t; 84 85 /* REQUIRED FUNCTIONS 86 * 87 * The following functions are required to be implemented for all decoders. 88 * They represent the base case functionality expected of all decoders. 89 */ 90 91 /*!\brief Initialization Configurations 92 * 93 * This structure is used to pass init time configuration options to the 94 * decoder. 95 */ 96 typedef struct aom_codec_dec_cfg { 97 unsigned int threads; /**< Maximum number of threads to use, default 1 */ 98 unsigned int w; /**< Width */ 99 unsigned int h; /**< Height */ 100 unsigned int allow_lowbitdepth; /**< Allow use of low-bitdepth coding path */ 101 cfg_options_t cfg; /**< Options defined per config attributes */ 102 } aom_codec_dec_cfg_t; /**< alias for struct aom_codec_dec_cfg */ 103 104 /*!\brief Initialize a decoder instance 105 * 106 * Initializes a decoder context using the given interface. Applications 107 * should call the aom_codec_dec_init convenience macro instead of this 108 * function directly, to ensure that the ABI version number parameter 109 * is properly initialized. 110 * 111 * If the library was configured with --disable-multithread, this call 112 * is not thread safe and should be guarded with a lock if being used 113 * in a multithreaded context. 114 * 115 * \param[in] ctx Pointer to this instance's context. 116 * \param[in] iface Pointer to the algorithm interface to use. 117 * \param[in] cfg Configuration to use, if known. May be NULL. 118 * \param[in] flags Bitfield of AOM_CODEC_USE_* flags 119 * \param[in] ver ABI version number. Must be set to 120 * AOM_DECODER_ABI_VERSION 121 * \retval #AOM_CODEC_OK 122 * The decoder algorithm initialized. 123 * \retval #AOM_CODEC_MEM_ERROR 124 * Memory allocation failed. 125 */ 126 aom_codec_err_t aom_codec_dec_init_ver(aom_codec_ctx_t *ctx, 127 aom_codec_iface_t *iface, 128 const aom_codec_dec_cfg_t *cfg, 129 aom_codec_flags_t flags, int ver); 130 131 /*!\brief Convenience macro for aom_codec_dec_init_ver() 132 * 133 * Ensures the ABI version parameter is properly set. 134 */ 135 #define aom_codec_dec_init(ctx, iface, cfg, flags) \ 136 aom_codec_dec_init_ver(ctx, iface, cfg, flags, AOM_DECODER_ABI_VERSION) 137 138 /*!\brief Parse stream info from a buffer 139 * 140 * Performs high level parsing of the bitstream. Construction of a decoder 141 * context is not necessary. Can be used to determine if the bitstream is 142 * of the proper format, and to extract information from the stream. 143 * 144 * \param[in] iface Pointer to the algorithm interface 145 * \param[in] data Pointer to a block of data to parse 146 * \param[in] data_sz Size of the data buffer 147 * \param[in,out] si Pointer to stream info to update. The is_annexb 148 * member \ref MUST be properly initialized. This 149 * function sets the rest of the members. 150 * 151 * \retval #AOM_CODEC_OK 152 * Bitstream is parsable and stream information updated. 153 * \retval #AOM_CODEC_INVALID_PARAM 154 * One of the arguments is invalid, for example a NULL pointer. 155 * \retval #AOM_CODEC_UNSUP_BITSTREAM 156 * The decoder didn't recognize the coded data, or the 157 * buffer was too short. 158 */ 159 aom_codec_err_t aom_codec_peek_stream_info(aom_codec_iface_t *iface, 160 const uint8_t *data, size_t data_sz, 161 aom_codec_stream_info_t *si); 162 163 /*!\brief Return information about the current stream. 164 * 165 * Returns information about the stream that has been parsed during decoding. 166 * 167 * \param[in] ctx Pointer to this instance's context 168 * \param[in,out] si Pointer to stream info to update. 169 * 170 * \retval #AOM_CODEC_OK 171 * Bitstream is parsable and stream information updated. 172 * \retval #AOM_CODEC_INVALID_PARAM 173 * One of the arguments is invalid, for example a NULL pointer. 174 * \retval #AOM_CODEC_UNSUP_BITSTREAM 175 * The decoder couldn't parse the submitted data. 176 */ 177 aom_codec_err_t aom_codec_get_stream_info(aom_codec_ctx_t *ctx, 178 aom_codec_stream_info_t *si); 179 180 /*!\brief Decode data 181 * 182 * Processes a buffer of coded data. If the processing results in a new 183 * decoded frame becoming available, PUT_SLICE and PUT_FRAME events may be 184 * generated, as appropriate. Encoded data \ref MUST be passed in DTS (decode 185 * time stamp) order. Frames produced will always be in PTS (presentation 186 * time stamp) order. 187 * 188 * \param[in] ctx Pointer to this instance's context 189 * \param[in] data Pointer to this block of new coded data. If 190 * NULL, a AOM_CODEC_CB_PUT_FRAME event is posted 191 * for the previously decoded frame. 192 * \param[in] data_sz Size of the coded data, in bytes. 193 * \param[in] user_priv Application specific data to associate with 194 * this frame. 195 * 196 * \return Returns #AOM_CODEC_OK if the coded data was processed completely 197 * and future pictures can be decoded without error. Otherwise, 198 * see the descriptions of the other error codes in ::aom_codec_err_t 199 * for recoverability capabilities. 200 */ 201 aom_codec_err_t aom_codec_decode(aom_codec_ctx_t *ctx, const uint8_t *data, 202 size_t data_sz, void *user_priv); 203 204 /*!\brief Decoded frames iterator 205 * 206 * Iterates over a list of the frames available for display. The iterator 207 * storage should be initialized to NULL to start the iteration. Iteration is 208 * complete when this function returns NULL. 209 * 210 * The list of available frames becomes valid upon completion of the 211 * aom_codec_decode call, and remains valid until the next call to 212 * aom_codec_decode. 213 * 214 * \param[in] ctx Pointer to this instance's context 215 * \param[in,out] iter Iterator storage, initialized to NULL 216 * 217 * \return Returns a pointer to an image, if one is ready for display. Frames 218 * produced will always be in PTS (presentation time stamp) order. 219 */ 220 aom_image_t *aom_codec_get_frame(aom_codec_ctx_t *ctx, aom_codec_iter_t *iter); 221 222 /*!\defgroup cap_put_frame Frame-Based Decoding Functions 223 * 224 * The following functions are required to be implemented for all decoders 225 * that advertise the AOM_CODEC_CAP_PUT_FRAME capability. Calling these 226 * functions 227 * for codecs that don't advertise this capability will result in an error 228 * code being returned, usually AOM_CODEC_ERROR 229 * @{ 230 */ 231 232 /*!\brief put frame callback prototype 233 * 234 * This callback is invoked by the decoder to notify the application of 235 * the availability of decoded image data. 236 */ 237 typedef void (*aom_codec_put_frame_cb_fn_t)(void *user_priv, 238 const aom_image_t *img); 239 240 /*!\brief Register for notification of frame completion. 241 * 242 * Registers a given function to be called when a decoded frame is 243 * available. 244 * 245 * \param[in] ctx Pointer to this instance's context 246 * \param[in] cb Pointer to the callback function 247 * \param[in] user_priv User's private data 248 * 249 * \retval #AOM_CODEC_OK 250 * Callback successfully registered. 251 * \retval #AOM_CODEC_ERROR 252 * Decoder context not initialized, or algorithm not capable of 253 * posting slice completion. 254 */ 255 aom_codec_err_t aom_codec_register_put_frame_cb(aom_codec_ctx_t *ctx, 256 aom_codec_put_frame_cb_fn_t cb, 257 void *user_priv); 258 259 /*!@} - end defgroup cap_put_frame */ 260 261 /*!\defgroup cap_put_slice Slice-Based Decoding Functions 262 * 263 * The following functions are required to be implemented for all decoders 264 * that advertise the AOM_CODEC_CAP_PUT_SLICE capability. Calling these 265 * functions 266 * for codecs that don't advertise this capability will result in an error 267 * code being returned, usually AOM_CODEC_ERROR 268 * @{ 269 */ 270 271 /*!\brief put slice callback prototype 272 * 273 * This callback is invoked by the decoder to notify the application of 274 * the availability of partially decoded image data. The 275 */ 276 typedef void (*aom_codec_put_slice_cb_fn_t)(void *user_priv, 277 const aom_image_t *img, 278 const aom_image_rect_t *valid, 279 const aom_image_rect_t *update); 280 281 /*!\brief Register for notification of slice completion. 282 * 283 * Registers a given function to be called when a decoded slice is 284 * available. 285 * 286 * \param[in] ctx Pointer to this instance's context 287 * \param[in] cb Pointer to the callback function 288 * \param[in] user_priv User's private data 289 * 290 * \retval #AOM_CODEC_OK 291 * Callback successfully registered. 292 * \retval #AOM_CODEC_ERROR 293 * Decoder context not initialized, or algorithm not capable of 294 * posting slice completion. 295 */ 296 aom_codec_err_t aom_codec_register_put_slice_cb(aom_codec_ctx_t *ctx, 297 aom_codec_put_slice_cb_fn_t cb, 298 void *user_priv); 299 300 /*!@} - end defgroup cap_put_slice*/ 301 302 /*!\defgroup cap_external_frame_buffer External Frame Buffer Functions 303 * 304 * The following section is required to be implemented for all decoders 305 * that advertise the AOM_CODEC_CAP_EXTERNAL_FRAME_BUFFER capability. 306 * Calling this function for codecs that don't advertise this capability 307 * will result in an error code being returned, usually AOM_CODEC_ERROR. 308 * 309 * \note 310 * Currently this only works with AV1. 311 * @{ 312 */ 313 314 /*!\brief Pass in external frame buffers for the decoder to use. 315 * 316 * Registers functions to be called when libaom needs a frame buffer 317 * to decode the current frame and a function to be called when libaom does 318 * not internally reference the frame buffer. This set function must 319 * be called before the first call to decode or libaom will assume the 320 * default behavior of allocating frame buffers internally. 321 * 322 * \param[in] ctx Pointer to this instance's context 323 * \param[in] cb_get Pointer to the get callback function 324 * \param[in] cb_release Pointer to the release callback function 325 * \param[in] cb_priv Callback's private data 326 * 327 * \retval #AOM_CODEC_OK 328 * External frame buffers will be used by libaom. 329 * \retval #AOM_CODEC_INVALID_PARAM 330 * One or more of the callbacks were NULL. 331 * \retval #AOM_CODEC_ERROR 332 * Decoder context not initialized, or algorithm not capable of 333 * using external frame buffers. 334 * 335 * \note 336 * When decoding AV1, the application may be required to pass in at least 337 * #AOM_MAXIMUM_WORK_BUFFERS external frame 338 * buffers. 339 */ 340 aom_codec_err_t aom_codec_set_frame_buffer_functions( 341 aom_codec_ctx_t *ctx, aom_get_frame_buffer_cb_fn_t cb_get, 342 aom_release_frame_buffer_cb_fn_t cb_release, void *cb_priv); 343 344 /*!@} - end defgroup cap_external_frame_buffer */ 345 346 /*!@} - end defgroup decoder*/ 347 #ifdef __cplusplus 348 } 349 #endif 350 #endif // AOM_AOM_AOM_DECODER_H_ 351
