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 (5) /**<\hideinitializer*/ 63 64 typedef struct aom_codec_alg_priv aom_codec_alg_priv_t; 65 typedef struct aom_codec_priv_enc_mr_cfg aom_codec_priv_enc_mr_cfg_t; 66 67 /*!\brief init function pointer prototype 68 * 69 * Performs algorithm-specific initialization of the decoder context. This 70 * function is called by the generic aom_codec_init() wrapper function, so 71 * plugins implementing this interface may trust the input parameters to be 72 * properly initialized. 73 * 74 * \param[in] ctx Pointer to this instance's context 75 * \retval #AOM_CODEC_OK 76 * The input stream was recognized and decoder initialized. 77 * \retval #AOM_CODEC_MEM_ERROR 78 * Memory operation failed. 79 */ 80 typedef aom_codec_err_t (*aom_codec_init_fn_t)( 81 aom_codec_ctx_t *ctx, aom_codec_priv_enc_mr_cfg_t *data); 82 83 /*!\brief destroy function pointer prototype 84 * 85 * Performs algorithm-specific destruction of the decoder context. This 86 * function is called by the generic aom_codec_destroy() wrapper function, 87 * so plugins implementing this interface may trust the input parameters 88 * to be properly initialized. 89 * 90 * \param[in] ctx Pointer to this instance's context 91 * \retval #AOM_CODEC_OK 92 * The input stream was recognized and decoder initialized. 93 * \retval #AOM_CODEC_MEM_ERROR 94 * Memory operation failed. 95 */ 96 typedef aom_codec_err_t (*aom_codec_destroy_fn_t)(aom_codec_alg_priv_t *ctx); 97 98 /*!\brief parse stream info function pointer prototype 99 * 100 * Performs high level parsing of the bitstream. This function is called by the 101 * generic aom_codec_peek_stream_info() wrapper function, so plugins 102 * implementing this interface may trust the input parameters to be properly 103 * initialized. 104 * 105 * \param[in] data Pointer to a block of data to parse 106 * \param[in] data_sz Size of the data buffer 107 * \param[in,out] si Pointer to stream info to update. The is_annexb 108 * member \ref MUST be properly initialized. This 109 * function sets the rest of the members. 110 * 111 * \retval #AOM_CODEC_OK 112 * Bitstream is parsable and stream information updated 113 */ 114 typedef aom_codec_err_t (*aom_codec_peek_si_fn_t)(const uint8_t *data, 115 size_t data_sz, 116 aom_codec_stream_info_t *si); 117 118 /*!\brief Return information about the current stream. 119 * 120 * Returns information about the stream that has been parsed during decoding. 121 * 122 * \param[in] ctx Pointer to this instance's context 123 * \param[in,out] si Pointer to stream info to update 124 * 125 * \retval #AOM_CODEC_OK 126 * Bitstream is parsable and stream information updated 127 */ 128 typedef aom_codec_err_t (*aom_codec_get_si_fn_t)(aom_codec_alg_priv_t *ctx, 129 aom_codec_stream_info_t *si); 130 131 /*!\brief control function pointer prototype 132 * 133 * This function is used to exchange algorithm specific data with the decoder 134 * instance. This can be used to implement features specific to a particular 135 * algorithm. 136 * 137 * This function is called by the generic aom_codec_control() wrapper 138 * function, so plugins implementing this interface may trust the input 139 * parameters to be properly initialized. However, this interface does not 140 * provide type safety for the exchanged data or assign meanings to the 141 * control codes. Those details should be specified in the algorithm's 142 * header file. In particular, the ctrl_id parameter is guaranteed to exist 143 * in the algorithm's control mapping table, and the data parameter may be NULL. 144 * 145 * 146 * \param[in] ctx Pointer to this instance's context 147 * \param[in] ctrl_id Algorithm specific control identifier 148 * \param[in,out] data Data to exchange with algorithm instance. 149 * 150 * \retval #AOM_CODEC_OK 151 * The internal state data was deserialized. 152 */ 153 typedef aom_codec_err_t (*aom_codec_control_fn_t)(aom_codec_alg_priv_t *ctx, 154 va_list ap); 155 156 /*!\brief control function pointer mapping 157 * 158 * This structure stores the mapping between control identifiers and 159 * implementing functions. Each algorithm provides a list of these 160 * mappings. This list is searched by the aom_codec_control() wrapper 161 * function to determine which function to invoke. The special 162 * value {0, NULL} is used to indicate end-of-list, and must be 163 * present. The special value {0, <non-null>} can be used as a catch-all 164 * mapping. This implies that ctrl_id values chosen by the algorithm 165 * \ref MUST be non-zero. 166 */ 167 typedef const struct aom_codec_ctrl_fn_map { 168 int ctrl_id; 169 aom_codec_control_fn_t fn; 170 } aom_codec_ctrl_fn_map_t; 171 172 /*!\brief decode data function pointer prototype 173 * 174 * Processes a buffer of coded data. If the processing results in a new 175 * decoded frame becoming available, #AOM_CODEC_CB_PUT_SLICE and 176 * #AOM_CODEC_CB_PUT_FRAME events are generated as appropriate. This 177 * function is called by the generic aom_codec_decode() wrapper function, 178 * so plugins implementing this interface may trust the input parameters 179 * to be properly initialized. 180 * 181 * \param[in] ctx Pointer to this instance's context 182 * \param[in] data Pointer to this block of new coded data. If 183 * NULL, a #AOM_CODEC_CB_PUT_FRAME event is posted 184 * for the previously decoded frame. 185 * \param[in] data_sz Size of the coded data, in bytes. 186 * 187 * \return Returns #AOM_CODEC_OK if the coded data was processed completely 188 * and future pictures can be decoded without error. Otherwise, 189 * see the descriptions of the other error codes in ::aom_codec_err_t 190 * for recoverability capabilities. 191 */ 192 typedef aom_codec_err_t (*aom_codec_decode_fn_t)(aom_codec_alg_priv_t *ctx, 193 const uint8_t *data, 194 size_t data_sz, 195 void *user_priv); 196 197 /*!\brief Decoded frames iterator 198 * 199 * Iterates over a list of the frames available for display. The iterator 200 * storage should be initialized to NULL to start the iteration. Iteration is 201 * complete when this function returns NULL. 202 * 203 * The list of available frames becomes valid upon completion of the 204 * aom_codec_decode call, and remains valid until the next call to 205 * aom_codec_decode. 206 * 207 * \param[in] ctx Pointer to this instance's context 208 * \param[in out] iter Iterator storage, initialized to NULL 209 * 210 * \return Returns a pointer to an image, if one is ready for display. Frames 211 * produced will always be in PTS (presentation time stamp) order. 212 */ 213 typedef aom_image_t *(*aom_codec_get_frame_fn_t)(aom_codec_alg_priv_t *ctx, 214 aom_codec_iter_t *iter); 215 216 /*!\brief Pass in external frame buffers for the decoder to use. 217 * 218 * Registers functions to be called when libaom needs a frame buffer 219 * to decode the current frame and a function to be called when libaom does 220 * not internally reference the frame buffer. This set function must 221 * be called before the first call to decode or libaom will assume the 222 * default behavior of allocating frame buffers internally. 223 * 224 * \param[in] ctx Pointer to this instance's context 225 * \param[in] cb_get Pointer to the get callback function 226 * \param[in] cb_release Pointer to the release callback function 227 * \param[in] cb_priv Callback's private data 228 * 229 * \retval #AOM_CODEC_OK 230 * External frame buffers will be used by libaom. 231 * \retval #AOM_CODEC_INVALID_PARAM 232 * One or more of the callbacks were NULL. 233 * \retval #AOM_CODEC_ERROR 234 * Decoder context not initialized, or algorithm not capable of 235 * using external frame buffers. 236 * 237 * \note 238 * When decoding AV1, the application may be required to pass in at least 239 * #AOM_MAXIMUM_WORK_BUFFERS external frame 240 * buffers. 241 */ 242 typedef aom_codec_err_t (*aom_codec_set_fb_fn_t)( 243 aom_codec_alg_priv_t *ctx, aom_get_frame_buffer_cb_fn_t cb_get, 244 aom_release_frame_buffer_cb_fn_t cb_release, void *cb_priv); 245 246 typedef aom_codec_err_t (*aom_codec_encode_fn_t)(aom_codec_alg_priv_t *ctx, 247 const aom_image_t *img, 248 aom_codec_pts_t pts, 249 unsigned long duration, 250 aom_enc_frame_flags_t flags); 251 typedef const aom_codec_cx_pkt_t *(*aom_codec_get_cx_data_fn_t)( 252 aom_codec_alg_priv_t *ctx, aom_codec_iter_t *iter); 253 254 typedef aom_codec_err_t (*aom_codec_enc_config_set_fn_t)( 255 aom_codec_alg_priv_t *ctx, const aom_codec_enc_cfg_t *cfg); 256 typedef aom_fixed_buf_t *(*aom_codec_get_global_headers_fn_t)( 257 aom_codec_alg_priv_t *ctx); 258 259 typedef aom_image_t *(*aom_codec_get_preview_frame_fn_t)( 260 aom_codec_alg_priv_t *ctx); 261 262 typedef aom_codec_err_t (*aom_codec_enc_mr_get_mem_loc_fn_t)( 263 const aom_codec_enc_cfg_t *cfg, void **mem_loc); 264 265 /*!\brief usage configuration mapping 266 * 267 * This structure stores the mapping between usage identifiers and 268 * configuration structures. Each algorithm provides a list of these 269 * mappings. This list is searched by the aom_codec_enc_config_default() 270 * wrapper function to determine which config to return. The special value 271 * {-1, {0}} is used to indicate end-of-list, and must be present. At least 272 * one mapping must be present, in addition to the end-of-list. 273 * 274 */ 275 typedef const struct aom_codec_enc_cfg_map { 276 int usage; 277 aom_codec_enc_cfg_t cfg; 278 } aom_codec_enc_cfg_map_t; 279 280 /*!\brief Decoder algorithm interface interface 281 * 282 * All decoders \ref MUST expose a variable of this type. 283 */ 284 struct aom_codec_iface { 285 const char *name; /**< Identification String */ 286 int abi_version; /**< Implemented ABI version */ 287 aom_codec_caps_t caps; /**< Decoder capabilities */ 288 aom_codec_init_fn_t init; /**< \copydoc ::aom_codec_init_fn_t */ 289 aom_codec_destroy_fn_t destroy; /**< \copydoc ::aom_codec_destroy_fn_t */ 290 aom_codec_ctrl_fn_map_t *ctrl_maps; /**< \copydoc ::aom_codec_ctrl_fn_map_t */ 291 struct aom_codec_dec_iface { 292 aom_codec_peek_si_fn_t peek_si; /**< \copydoc ::aom_codec_peek_si_fn_t */ 293 aom_codec_get_si_fn_t get_si; /**< \copydoc ::aom_codec_get_si_fn_t */ 294 aom_codec_decode_fn_t decode; /**< \copydoc ::aom_codec_decode_fn_t */ 295 aom_codec_get_frame_fn_t 296 get_frame; /**< \copydoc ::aom_codec_get_frame_fn_t */ 297 aom_codec_set_fb_fn_t set_fb_fn; /**< \copydoc ::aom_codec_set_fb_fn_t */ 298 } dec; 299 struct aom_codec_enc_iface { 300 int cfg_map_count; 301 aom_codec_enc_cfg_map_t 302 *cfg_maps; /**< \copydoc ::aom_codec_enc_cfg_map_t */ 303 aom_codec_encode_fn_t encode; /**< \copydoc ::aom_codec_encode_fn_t */ 304 aom_codec_get_cx_data_fn_t 305 get_cx_data; /**< \copydoc ::aom_codec_get_cx_data_fn_t */ 306 aom_codec_enc_config_set_fn_t 307 cfg_set; /**< \copydoc ::aom_codec_enc_config_set_fn_t */ 308 aom_codec_get_global_headers_fn_t 309 get_glob_hdrs; /**< \copydoc ::aom_codec_get_global_headers_fn_t */ 310 aom_codec_get_preview_frame_fn_t 311 get_preview; /**< \copydoc ::aom_codec_get_preview_frame_fn_t */ 312 aom_codec_enc_mr_get_mem_loc_fn_t 313 mr_get_mem_loc; /**< \copydoc ::aom_codec_enc_mr_get_mem_loc_fn_t */ 314 } enc; 315 }; 316 317 /*!\brief Callback function pointer / user data pair storage */ 318 typedef struct aom_codec_priv_cb_pair { 319 union { 320 aom_codec_put_frame_cb_fn_t put_frame; 321 aom_codec_put_slice_cb_fn_t put_slice; 322 } u; 323 void *user_priv; 324 } aom_codec_priv_cb_pair_t; 325 326 /*!\brief Instance private storage 327 * 328 * This structure is allocated by the algorithm's init function. It can be 329 * extended in one of two ways. First, a second, algorithm specific structure 330 * can be allocated and the priv member pointed to it. Alternatively, this 331 * structure can be made the first member of the algorithm specific structure, 332 * and the pointer cast to the proper type. 333 */ 334 struct aom_codec_priv { 335 const char *err_detail; 336 aom_codec_flags_t init_flags; 337 struct { 338 aom_codec_priv_cb_pair_t put_frame_cb; 339 aom_codec_priv_cb_pair_t put_slice_cb; 340 } dec; 341 struct { 342 aom_fixed_buf_t cx_data_dst_buf; 343 unsigned int cx_data_pad_before; 344 unsigned int cx_data_pad_after; 345 aom_codec_cx_pkt_t cx_data_pkt; 346 unsigned int total_encoders; 347 } enc; 348 }; 349 350 /* 351 * Multi-resolution encoding internal configuration 352 */ 353 struct aom_codec_priv_enc_mr_cfg { 354 unsigned int mr_total_resolutions; 355 unsigned int mr_encoder_id; 356 struct aom_rational mr_down_sampling_factor; 357 void *mr_low_res_mode_info; 358 }; 359 360 #undef AOM_CTRL_USE_TYPE 361 #define AOM_CTRL_USE_TYPE(id, typ) \ 362 static AOM_INLINE typ id##__value(va_list args) { return va_arg(args, typ); } 363 364 #undef AOM_CTRL_USE_TYPE_DEPRECATED 365 #define AOM_CTRL_USE_TYPE_DEPRECATED(id, typ) \ 366 static AOM_INLINE typ id##__value(va_list args) { return va_arg(args, typ); } 367 368 #define CAST(id, arg) id##__value(arg) 369 370 /* CODEC_INTERFACE convenience macro 371 * 372 * By convention, each codec interface is a struct with extern linkage, where 373 * the symbol is suffixed with _algo. A getter function is also defined to 374 * return a pointer to the struct, since in some cases it's easier to work 375 * with text symbols than data symbols (see issue #169). This function has 376 * the same name as the struct, less the _algo suffix. The CODEC_INTERFACE 377 * macro is provided to define this getter function automatically. 378 */ 379 #define CODEC_INTERFACE(id) \ 380 aom_codec_iface_t *id(void) { return &id##_algo; } \ 381 aom_codec_iface_t id##_algo 382 383 /* Internal Utility Functions 384 * 385 * The following functions are intended to be used inside algorithms as 386 * utilities for manipulating aom_codec_* data structures. 387 */ 388 struct aom_codec_pkt_list { 389 unsigned int cnt; 390 unsigned int max; 391 struct aom_codec_cx_pkt pkts[1]; 392 }; 393 394 #define aom_codec_pkt_list_decl(n) \ 395 union { \ 396 struct aom_codec_pkt_list head; \ 397 struct { \ 398 struct aom_codec_pkt_list head; \ 399 struct aom_codec_cx_pkt pkts[n]; \ 400 } alloc; \ 401 } 402 403 #define aom_codec_pkt_list_init(m) \ 404 (m)->alloc.head.cnt = 0, \ 405 (m)->alloc.head.max = sizeof((m)->alloc.pkts) / sizeof((m)->alloc.pkts[0]) 406 407 int aom_codec_pkt_list_add(struct aom_codec_pkt_list *, 408 const struct aom_codec_cx_pkt *); 409 410 const aom_codec_cx_pkt_t *aom_codec_pkt_list_get( 411 struct aom_codec_pkt_list *list, aom_codec_iter_t *iter); 412 413 #include <stdio.h> 414 #include <setjmp.h> 415 416 struct aom_internal_error_info { 417 aom_codec_err_t error_code; 418 int has_detail; 419 char detail[80]; 420 int setjmp; // Boolean: whether 'jmp' is valid. 421 jmp_buf jmp; 422 }; 423 424 #define CLANG_ANALYZER_NORETURN 425 #if defined(__has_feature) 426 #if __has_feature(attribute_analyzer_noreturn) 427 #undef CLANG_ANALYZER_NORETURN 428 #define CLANG_ANALYZER_NORETURN __attribute__((analyzer_noreturn)) 429 #endif 430 #endif 431 432 void aom_internal_error(struct aom_internal_error_info *info, 433 aom_codec_err_t error, const char *fmt, 434 ...) CLANG_ANALYZER_NORETURN; 435 436 void aom_merge_corrupted_flag(int *corrupted, int value); 437 #ifdef __cplusplus 438 } // extern "C" 439 #endif 440 441 #endif // AOM_AOM_INTERNAL_AOM_CODEC_INTERNAL_H_ 442