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 (6 + 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 /*!brief Can support external frame buffers */ 56 #define AOM_CODEC_CAP_EXTERNAL_FRAME_BUFFER 0x200000 57 58 /*! \brief Initialization-time Feature Enabling 59 * 60 * Certain codec features must be known at initialization time, to allow for 61 * proper memory allocation. 62 * 63 * The available flags are specified by AOM_CODEC_USE_* defines. 64 */ 65 66 /*!\brief Stream properties 67 * 68 * This structure is used to query or set properties of the decoded 69 * stream. 70 */ 71 typedef struct aom_codec_stream_info { 72 unsigned int w; /**< Width (or 0 for unknown/default) */ 73 unsigned int h; /**< Height (or 0 for unknown/default) */ 74 unsigned int is_kf; /**< Current frame is a keyframe */ 75 unsigned int number_spatial_layers; /**< Number of spatial layers */ 76 unsigned int number_temporal_layers; /**< Number of temporal layers */ 77 unsigned int is_annexb; /**< Is Bitstream in Annex-B format */ 78 } aom_codec_stream_info_t; 79 80 /* REQUIRED FUNCTIONS 81 * 82 * The following functions are required to be implemented for all decoders. 83 * They represent the base case functionality expected of all decoders. 84 */ 85 86 /*!\brief Initialization Configurations 87 * 88 * This structure is used to pass init time configuration options to the 89 * decoder. 90 */ 91 typedef struct aom_codec_dec_cfg { 92 unsigned int threads; /**< Maximum number of threads to use, default 1 */ 93 unsigned int w; /**< Width */ 94 unsigned int h; /**< Height */ 95 unsigned int allow_lowbitdepth; /**< Allow use of low-bitdepth coding path */ 96 } aom_codec_dec_cfg_t; /**< alias for struct aom_codec_dec_cfg */ 97 98 /*!\brief Initialize a decoder instance 99 * 100 * Initializes a decoder context using the given interface. Applications 101 * should call the aom_codec_dec_init convenience macro instead of this 102 * function directly, to ensure that the ABI version number parameter 103 * is properly initialized. 104 * 105 * If the library was configured with cmake -DCONFIG_MULTITHREAD=0, this 106 * call is not thread safe and should be guarded with a lock if being used 107 * in a multithreaded context. 108 * 109 * \param[in] ctx Pointer to this instance's context. 110 * \param[in] iface Pointer to the algorithm interface to use. 111 * \param[in] cfg Configuration to use, if known. May be NULL. 112 * \param[in] flags Bitfield of AOM_CODEC_USE_* flags 113 * \param[in] ver ABI version number. Must be set to 114 * AOM_DECODER_ABI_VERSION 115 * \retval #AOM_CODEC_OK 116 * The decoder algorithm initialized. 117 * \retval #AOM_CODEC_MEM_ERROR 118 * Memory allocation failed. 119 */ 120 aom_codec_err_t aom_codec_dec_init_ver(aom_codec_ctx_t *ctx, 121 aom_codec_iface_t *iface, 122 const aom_codec_dec_cfg_t *cfg, 123 aom_codec_flags_t flags, int ver); 124 125 /*!\brief Convenience macro for aom_codec_dec_init_ver() 126 * 127 * Ensures the ABI version parameter is properly set. 128 */ 129 #define aom_codec_dec_init(ctx, iface, cfg, flags) \ 130 aom_codec_dec_init_ver(ctx, iface, cfg, flags, AOM_DECODER_ABI_VERSION) 131 132 /*!\brief Parse stream info from a buffer 133 * 134 * Performs high level parsing of the bitstream. Construction of a decoder 135 * context is not necessary. Can be used to determine if the bitstream is 136 * of the proper format, and to extract information from the stream. 137 * 138 * \param[in] iface Pointer to the algorithm interface 139 * \param[in] data Pointer to a block of data to parse 140 * \param[in] data_sz Size of the data buffer 141 * \param[in,out] si Pointer to stream info to update. The is_annexb 142 * member \ref MUST be properly initialized. This 143 * function sets the rest of the members. 144 * 145 * \retval #AOM_CODEC_OK 146 * Bitstream is parsable and stream information updated. 147 * \retval #AOM_CODEC_INVALID_PARAM 148 * One of the arguments is invalid, for example a NULL pointer. 149 * \retval #AOM_CODEC_UNSUP_BITSTREAM 150 * The decoder didn't recognize the coded data, or the 151 * buffer was too short. 152 */ 153 aom_codec_err_t aom_codec_peek_stream_info(aom_codec_iface_t *iface, 154 const uint8_t *data, size_t data_sz, 155 aom_codec_stream_info_t *si); 156 157 /*!\brief Return information about the current stream. 158 * 159 * Returns information about the stream that has been parsed during decoding. 160 * 161 * \param[in] ctx Pointer to this instance's context 162 * \param[in,out] si Pointer to stream info to update. 163 * 164 * \retval #AOM_CODEC_OK 165 * Bitstream is parsable and stream information updated. 166 * \retval #AOM_CODEC_INVALID_PARAM 167 * One of the arguments is invalid, for example a NULL pointer. 168 * \retval #AOM_CODEC_UNSUP_BITSTREAM 169 * The decoder couldn't parse the submitted data. 170 */ 171 aom_codec_err_t aom_codec_get_stream_info(aom_codec_ctx_t *ctx, 172 aom_codec_stream_info_t *si); 173 174 /*!\brief Decode data 175 * 176 * Processes a buffer of coded data. Encoded data \ref MUST be passed in DTS 177 * (decode time stamp) order. Frames produced will always be in PTS 178 * (presentation time stamp) order. 179 * 180 * \param[in] ctx Pointer to this instance's context 181 * \param[in] data Pointer to this block of new coded data. 182 * \param[in] data_sz Size of the coded data, in bytes. 183 * \param[in] user_priv Application specific data to associate with 184 * this frame. 185 * 186 * \return Returns #AOM_CODEC_OK if the coded data was processed completely 187 * and future pictures can be decoded without error. Otherwise, 188 * see the descriptions of the other error codes in ::aom_codec_err_t 189 * for recoverability capabilities. 190 */ 191 aom_codec_err_t aom_codec_decode(aom_codec_ctx_t *ctx, const uint8_t *data, 192 size_t data_sz, void *user_priv); 193 194 /*!\brief Decoded frames iterator 195 * 196 * Iterates over a list of the frames available for display. The iterator 197 * storage should be initialized to NULL to start the iteration. Iteration is 198 * complete when this function returns NULL. 199 * 200 * The list of available frames becomes valid upon completion of the 201 * aom_codec_decode call, and remains valid until the next call to 202 * aom_codec_decode. 203 * 204 * \param[in] ctx Pointer to this instance's context 205 * \param[in,out] iter Iterator storage, initialized to NULL 206 * 207 * \return Returns a pointer to an image, if one is ready for display. Frames 208 * produced will always be in PTS (presentation time stamp) order. 209 */ 210 aom_image_t *aom_codec_get_frame(aom_codec_ctx_t *ctx, aom_codec_iter_t *iter); 211 212 /*!\defgroup cap_external_frame_buffer External Frame Buffer Functions 213 * 214 * The following function is required to be implemented for all decoders 215 * that advertise the AOM_CODEC_CAP_EXTERNAL_FRAME_BUFFER capability. 216 * Calling this function for codecs that don't advertise this capability 217 * will result in an error code being returned, usually AOM_CODEC_INCAPABLE. 218 * @{ 219 */ 220 221 /*!\brief Pass in external frame buffers for the decoder to use. 222 * 223 * Registers functions to be called when libaom needs a frame buffer 224 * to decode the current frame and a function to be called when libaom does 225 * not internally reference the frame buffer. This set function must 226 * be called before the first call to decode or libaom will assume the 227 * default behavior of allocating frame buffers internally. 228 * 229 * \param[in] ctx Pointer to this instance's context 230 * \param[in] cb_get Pointer to the get callback function 231 * \param[in] cb_release Pointer to the release callback function 232 * \param[in] cb_priv Callback's private data 233 * 234 * \retval #AOM_CODEC_OK 235 * External frame buffers will be used by libaom. 236 * \retval #AOM_CODEC_INVALID_PARAM 237 * One or more of the callbacks were NULL. 238 * \retval #AOM_CODEC_ERROR 239 * Decoder context not initialized. 240 * \retval #AOM_CODEC_INCAPABLE 241 * Algorithm not capable of using external frame buffers. 242 * 243 * \note 244 * When decoding AV1, the application may be required to pass in at least 245 * #AOM_MAXIMUM_WORK_BUFFERS external frame buffers. 246 */ 247 aom_codec_err_t aom_codec_set_frame_buffer_functions( 248 aom_codec_ctx_t *ctx, aom_get_frame_buffer_cb_fn_t cb_get, 249 aom_release_frame_buffer_cb_fn_t cb_release, void *cb_priv); 250 251 /*!@} - end defgroup cap_external_frame_buffer */ 252 253 /*!@} - end defgroup decoder*/ 254 #ifdef __cplusplus 255 } 256 #endif 257 #endif // AOM_AOM_AOM_DECODER_H_ 258