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 /*!\file 13 * \brief Describes the decoder algorithm interface for algorithm 14 * implementations. 15 * 16 * This file defines the private structures and data types that are only 17 * relevant to implementing an algorithm, as opposed to using it. 18 * 19 * To create a decoder algorithm class, an interface structure is put 20 * into the global namespace: 21 * <pre> 22 * my_codec.c: 23 * aom_codec_iface_t my_codec = { 24 * "My Codec v1.0", 25 * AOM_CODEC_ALG_ABI_VERSION, 26 * ... 27 * }; 28 * </pre> 29 * 30 * An application instantiates a specific decoder instance by using 31 * aom_codec_init() and a pointer to the algorithm's interface structure: 32 * <pre> 33 * my_app.c: 34 * extern aom_codec_iface_t my_codec; 35 * { 36 * aom_codec_ctx_t algo; 37 * res = aom_codec_init(&algo, &my_codec); 38 * } 39 * </pre> 40 * 41 * Once initialized, the instance is managed using other functions from 42 * the aom_codec_* family. 43 */ 44 #ifndef AOM_AOM_INTERNAL_AOM_CODEC_INTERNAL_H_ 45 #define AOM_AOM_INTERNAL_AOM_CODEC_INTERNAL_H_ 46 #include "../aom_decoder.h" 47 #include "../aom_encoder.h" 48 #include <stdarg.h> 49 50 #ifdef __cplusplus 51 extern "C" { 52 #endif 53 54 /*!\brief Current ABI version number 55 * 56 * \internal 57 * If this file is altered in any way that changes the ABI, this value 58 * must be bumped. Examples include, but are not limited to, changing 59 * types, removing or reassigning enums, adding/removing/rearranging 60 * fields to structures 61 */ 62 #define AOM_CODEC_INTERNAL_ABI_VERSION (7) /**<\hideinitializer*/ 63 64 typedef struct aom_codec_alg_priv aom_codec_alg_priv_t; 65 66 /*!\brief init function pointer prototype 67 * 68 * Performs algorithm-specific initialization of the decoder context. This 69 * function is called by the generic aom_codec_init() wrapper function, so 70 * plugins implementing this interface may trust the input parameters to be 71 * properly initialized. 72 * 73 * \param[in] ctx Pointer to this instance's context 74 * \retval #AOM_CODEC_OK 75 * The input stream was recognized and decoder initialized. 76 * \retval #AOM_CODEC_MEM_ERROR 77 * Memory operation failed. 78 */ 79 typedef aom_codec_err_t (*aom_codec_init_fn_t)(aom_codec_ctx_t *ctx); 80 81 /*!\brief destroy function pointer prototype 82 * 83 * Performs algorithm-specific destruction of the decoder context. This 84 * function is called by the generic aom_codec_destroy() wrapper function, 85 * so plugins implementing this interface may trust the input parameters 86 * to be properly initialized. 87 * 88 * \param[in] ctx Pointer to this instance's context 89 * \retval #AOM_CODEC_OK 90 * The input stream was recognized and decoder initialized. 91 * \retval #AOM_CODEC_MEM_ERROR 92 * Memory operation failed. 93 */ 94 typedef aom_codec_err_t (*aom_codec_destroy_fn_t)(aom_codec_alg_priv_t *ctx); 95 96 /*!\brief parse stream info function pointer prototype 97 * 98 * Performs high level parsing of the bitstream. This function is called by the 99 * generic aom_codec_peek_stream_info() wrapper function, so plugins 100 * implementing this interface may trust the input parameters to be properly 101 * initialized. 102 * 103 * \param[in] data Pointer to a block of data to parse 104 * \param[in] data_sz Size of the data buffer 105 * \param[in,out] si Pointer to stream info to update. The is_annexb 106 * member \ref MUST be properly initialized. This 107 * function sets the rest of the members. 108 * 109 * \retval #AOM_CODEC_OK 110 * Bitstream is parsable and stream information updated 111 */ 112 typedef aom_codec_err_t (*aom_codec_peek_si_fn_t)(const uint8_t *data, 113 size_t data_sz, 114 aom_codec_stream_info_t *si); 115 116 /*!\brief Return information about the current stream. 117 * 118 * Returns information about the stream that has been parsed during decoding. 119 * 120 * \param[in] ctx Pointer to this instance's context 121 * \param[in,out] si Pointer to stream info to update 122 * 123 * \retval #AOM_CODEC_OK 124 * Bitstream is parsable and stream information updated 125 */ 126 typedef aom_codec_err_t (*aom_codec_get_si_fn_t)(aom_codec_alg_priv_t *ctx, 127 aom_codec_stream_info_t *si); 128 129 /*!\brief control function pointer prototype 130 * 131 * This function is used to exchange algorithm specific data with the decoder 132 * instance. This can be used to implement features specific to a particular 133 * algorithm. 134 * 135 * This function is called by the generic aom_codec_control() wrapper 136 * function, so plugins implementing this interface may trust the input 137 * parameters to be properly initialized. However, this interface does not 138 * provide type safety for the exchanged data or assign meanings to the 139 * control IDs. Those details should be specified in the algorithm's 140 * header file. In particular, the ctrl_id parameter is guaranteed to exist 141 * in the algorithm's control mapping table, and the data parameter may be NULL. 142 * 143 * 144 * \param[in] ctx Pointer to this instance's context 145 * \param[in] ctrl_id Algorithm specific control identifier 146 * \param[in,out] data Data to exchange with algorithm instance. 147 * 148 * \retval #AOM_CODEC_OK 149 * The internal state data was deserialized. 150 */ 151 typedef aom_codec_err_t (*aom_codec_control_fn_t)(aom_codec_alg_priv_t *ctx, 152 va_list ap); 153 154 /*!\brief control function pointer mapping 155 * 156 * This structure stores the mapping between control identifiers and 157 * implementing functions. Each algorithm provides a list of these 158 * mappings. This list is searched by the aom_codec_control() wrapper 159 * function to determine which function to invoke. The special 160 * value {0, NULL} is used to indicate end-of-list, and must be 161 * present. The special value {0, <non-null>} can be used as a catch-all 162 * mapping. This implies that ctrl_id values chosen by the algorithm 163 * \ref MUST be non-zero. 164 */ 165 typedef const struct aom_codec_ctrl_fn_map { 166 int ctrl_id; 167 aom_codec_control_fn_t fn; 168 } aom_codec_ctrl_fn_map_t; 169 170 /*!\brief decode data function pointer prototype 171 * 172 * Processes a buffer of coded data. This function is called by the generic 173 * aom_codec_decode() wrapper function, so plugins implementing this interface 174 * may trust the input parameters to be properly initialized. 175 * 176 * \param[in] ctx Pointer to this instance's context 177 * \param[in] data Pointer to this block of new coded data. 178 * \param[in] data_sz Size of the coded data, in bytes. 179 * 180 * \return Returns #AOM_CODEC_OK if the coded data was processed completely 181 * and future pictures can be decoded without error. Otherwise, 182 * see the descriptions of the other error codes in ::aom_codec_err_t 183 * for recoverability capabilities. 184 */ 185 typedef aom_codec_err_t (*aom_codec_decode_fn_t)(aom_codec_alg_priv_t *ctx, 186 const uint8_t *data, 187 size_t data_sz, 188 void *user_priv); 189 190 /*!\brief Decoded frames iterator 191 * 192 * Iterates over a list of the frames available for display. The iterator 193 * storage should be initialized to NULL to start the iteration. Iteration is 194 * complete when this function returns NULL. 195 * 196 * The list of available frames becomes valid upon completion of the 197 * aom_codec_decode call, and remains valid until the next call to 198 * aom_codec_decode. 199 * 200 * \param[in] ctx Pointer to this instance's context 201 * \param[in out] iter Iterator storage, initialized to NULL 202 * 203 * \return Returns a pointer to an image, if one is ready for display. Frames 204 * produced will always be in PTS (presentation time stamp) order. 205 */ 206 typedef aom_image_t *(*aom_codec_get_frame_fn_t)(aom_codec_alg_priv_t *ctx, 207 aom_codec_iter_t *iter); 208 209 /*!\brief Pass in external frame buffers for the decoder to use. 210 * 211 * Registers functions to be called when libaom needs a frame buffer 212 * to decode the current frame and a function to be called when libaom does 213 * not internally reference the frame buffer. This set function must 214 * be called before the first call to decode or libaom will assume the 215 * default behavior of allocating frame buffers internally. 216 * 217 * \param[in] ctx Pointer to this instance's context 218 * \param[in] cb_get Pointer to the get callback function 219 * \param[in] cb_release Pointer to the release callback function 220 * \param[in] cb_priv Callback's private data 221 * 222 * \retval #AOM_CODEC_OK 223 * External frame buffers will be used by libaom. 224 * \retval #AOM_CODEC_INVALID_PARAM 225 * One or more of the callbacks were NULL. 226 * \retval #AOM_CODEC_ERROR 227 * Decoder context not initialized, or algorithm not capable of 228 * using external frame buffers. 229 * 230 * \note 231 * When decoding AV1, the application may be required to pass in at least 232 * #AOM_MAXIMUM_WORK_BUFFERS external frame 233 * buffers. 234 */ 235 typedef aom_codec_err_t (*aom_codec_set_fb_fn_t)( 236 aom_codec_alg_priv_t *ctx, aom_get_frame_buffer_cb_fn_t cb_get, 237 aom_release_frame_buffer_cb_fn_t cb_release, void *cb_priv); 238 239 typedef aom_codec_err_t (*aom_codec_encode_fn_t)(aom_codec_alg_priv_t *ctx, 240 const aom_image_t *img, 241 aom_codec_pts_t pts, 242 unsigned long duration, 243 aom_enc_frame_flags_t flags); 244 typedef const aom_codec_cx_pkt_t *(*aom_codec_get_cx_data_fn_t)( 245 aom_codec_alg_priv_t *ctx, aom_codec_iter_t *iter); 246 247 typedef aom_codec_err_t (*aom_codec_enc_config_set_fn_t)( 248 aom_codec_alg_priv_t *ctx, const aom_codec_enc_cfg_t *cfg); 249 typedef aom_fixed_buf_t *(*aom_codec_get_global_headers_fn_t)( 250 aom_codec_alg_priv_t *ctx); 251 252 typedef aom_image_t *(*aom_codec_get_preview_frame_fn_t)( 253 aom_codec_alg_priv_t *ctx); 254 255 /*!\brief Decoder algorithm interface interface 256 * 257 * All decoders \ref MUST expose a variable of this type. 258 */ 259 struct aom_codec_iface { 260 const char *name; /**< Identification String */ 261 int abi_version; /**< Implemented ABI version */ 262 aom_codec_caps_t caps; /**< Decoder capabilities */ 263 aom_codec_init_fn_t init; /**< \copydoc ::aom_codec_init_fn_t */ 264 aom_codec_destroy_fn_t destroy; /**< \copydoc ::aom_codec_destroy_fn_t */ 265 aom_codec_ctrl_fn_map_t *ctrl_maps; /**< \copydoc ::aom_codec_ctrl_fn_map_t */ 266 struct aom_codec_dec_iface { 267 aom_codec_peek_si_fn_t peek_si; /**< \copydoc ::aom_codec_peek_si_fn_t */ 268 aom_codec_get_si_fn_t get_si; /**< \copydoc ::aom_codec_get_si_fn_t */ 269 aom_codec_decode_fn_t decode; /**< \copydoc ::aom_codec_decode_fn_t */ 270 aom_codec_get_frame_fn_t 271 get_frame; /**< \copydoc ::aom_codec_get_frame_fn_t */ 272 aom_codec_set_fb_fn_t set_fb_fn; /**< \copydoc ::aom_codec_set_fb_fn_t */ 273 } dec; 274 struct aom_codec_enc_iface { 275 int cfg_count; 276 const aom_codec_enc_cfg_t *cfgs; /**< \copydoc ::aom_codec_enc_cfg_t */ 277 aom_codec_encode_fn_t encode; /**< \copydoc ::aom_codec_encode_fn_t */ 278 aom_codec_get_cx_data_fn_t 279 get_cx_data; /**< \copydoc ::aom_codec_get_cx_data_fn_t */ 280 aom_codec_enc_config_set_fn_t 281 cfg_set; /**< \copydoc ::aom_codec_enc_config_set_fn_t */ 282 aom_codec_get_global_headers_fn_t 283 get_glob_hdrs; /**< \copydoc ::aom_codec_get_global_headers_fn_t */ 284 aom_codec_get_preview_frame_fn_t 285 get_preview; /**< \copydoc ::aom_codec_get_preview_frame_fn_t */ 286 } enc; 287 }; 288 289 /*!\brief Instance private storage 290 * 291 * This structure is allocated by the algorithm's init function. It can be 292 * extended in one of two ways. First, a second, algorithm specific structure 293 * can be allocated and the priv member pointed to it. Alternatively, this 294 * structure can be made the first member of the algorithm specific structure, 295 * and the pointer cast to the proper type. 296 */ 297 struct aom_codec_priv { 298 const char *err_detail; 299 aom_codec_flags_t init_flags; 300 struct { 301 aom_fixed_buf_t cx_data_dst_buf; 302 unsigned int cx_data_pad_before; 303 unsigned int cx_data_pad_after; 304 aom_codec_cx_pkt_t cx_data_pkt; 305 } enc; 306 }; 307 308 #define CAST(id, arg) va_arg((arg), aom_codec_control_type_##id) 309 310 /* CODEC_INTERFACE convenience macro 311 * 312 * By convention, each codec interface is a struct with extern linkage, where 313 * the symbol is suffixed with _algo. A getter function is also defined to 314 * return a pointer to the struct, since in some cases it's easier to work 315 * with text symbols than data symbols (see issue #169). This function has 316 * the same name as the struct, less the _algo suffix. The CODEC_INTERFACE 317 * macro is provided to define this getter function automatically. 318 */ 319 #define CODEC_INTERFACE(id) \ 320 aom_codec_iface_t *id(void) { return &id##_algo; } \ 321 aom_codec_iface_t id##_algo 322 323 /* Internal Utility Functions 324 * 325 * The following functions are intended to be used inside algorithms as 326 * utilities for manipulating aom_codec_* data structures. 327 */ 328 struct aom_codec_pkt_list { 329 unsigned int cnt; 330 unsigned int max; 331 struct aom_codec_cx_pkt pkts[1]; 332 }; 333 334 #define aom_codec_pkt_list_decl(n) \ 335 union { \ 336 struct aom_codec_pkt_list head; \ 337 struct { \ 338 struct aom_codec_pkt_list head; \ 339 struct aom_codec_cx_pkt pkts[n]; \ 340 } alloc; \ 341 } 342 343 #define aom_codec_pkt_list_init(m) \ 344 (m)->alloc.head.cnt = 0, \ 345 (m)->alloc.head.max = sizeof((m)->alloc.pkts) / sizeof((m)->alloc.pkts[0]) 346 347 int aom_codec_pkt_list_add(struct aom_codec_pkt_list *, 348 const struct aom_codec_cx_pkt *); 349 350 const aom_codec_cx_pkt_t *aom_codec_pkt_list_get( 351 struct aom_codec_pkt_list *list, aom_codec_iter_t *iter); 352 353 #include <stdio.h> 354 #include <setjmp.h> 355 356 struct aom_internal_error_info { 357 aom_codec_err_t error_code; 358 int has_detail; 359 char detail[80]; 360 int setjmp; // Boolean: whether 'jmp' is valid. 361 jmp_buf jmp; 362 }; 363 364 #define CLANG_ANALYZER_NORETURN 365 #if defined(__has_feature) 366 #if __has_feature(attribute_analyzer_noreturn) 367 #undef CLANG_ANALYZER_NORETURN 368 #define CLANG_ANALYZER_NORETURN __attribute__((analyzer_noreturn)) 369 #endif 370 #endif 371 372 void aom_internal_error(struct aom_internal_error_info *info, 373 aom_codec_err_t error, const char *fmt, 374 ...) CLANG_ANALYZER_NORETURN; 375 376 void aom_merge_corrupted_flag(int *corrupted, int value); 377 #ifdef __cplusplus 378 } // extern "C" 379 #endif 380 381 #endif // AOM_AOM_INTERNAL_AOM_CODEC_INTERNAL_H_ 382