1 /* 2 * Copyright (c) 2010 The WebM project authors. All Rights Reserved. 3 * 4 * Use of this source code is governed by a BSD-style license 5 * that can be found in the LICENSE file in the root of the source 6 * tree. An additional intellectual property rights grant can be found 7 * in the file PATENTS. All contributing project authors may 8 * be found in the AUTHORS file in the root of the source tree. 9 */ 10 11 /*!\file 12 * \brief Describes the decoder algorithm interface for algorithm 13 * implementations. 14 * 15 * This file defines the private structures and data types that are only 16 * relevant to implementing an algorithm, as opposed to using it. 17 * 18 * To create a decoder algorithm class, an interface structure is put 19 * into the global namespace: 20 * <pre> 21 * my_codec.c: 22 * vpx_codec_iface_t my_codec = { 23 * "My Codec v1.0", 24 * VPX_CODEC_ALG_ABI_VERSION, 25 * ... 26 * }; 27 * </pre> 28 * 29 * An application instantiates a specific decoder instance by using 30 * vpx_codec_dec_init() and a pointer to the algorithm's interface structure: 31 * <pre> 32 * my_app.c: 33 * extern vpx_codec_iface_t my_codec; 34 * { 35 * vpx_codec_ctx_t algo; 36 * int threads = 4; 37 * vpx_codec_dec_cfg_t cfg = { threads, 0, 0 }; 38 * res = vpx_codec_dec_init(&algo, &my_codec, &cfg, 0); 39 * } 40 * </pre> 41 * 42 * Once initialized, the instance is manged using other functions from 43 * the vpx_codec_* family. 44 */ 45 #ifndef VPX_VPX_INTERNAL_VPX_CODEC_INTERNAL_H_ 46 #define VPX_VPX_INTERNAL_VPX_CODEC_INTERNAL_H_ 47 #include "../vpx_decoder.h" 48 #include "../vpx_encoder.h" 49 #include <stdarg.h> 50 51 #include "vpx_config.h" 52 53 #ifdef __cplusplus 54 extern "C" { 55 #endif 56 57 /*!\brief Current ABI version number 58 * 59 * \internal 60 * If this file is altered in any way that changes the ABI, this value 61 * must be bumped. Examples include, but are not limited to, changing 62 * types, removing or reassigning enums, adding/removing/rearranging 63 * fields to structures 64 */ 65 #define VPX_CODEC_INTERNAL_ABI_VERSION (5) /**<\hideinitializer*/ 66 67 typedef struct vpx_codec_alg_priv vpx_codec_alg_priv_t; 68 typedef struct vpx_codec_priv_enc_mr_cfg vpx_codec_priv_enc_mr_cfg_t; 69 70 /*!\brief init function pointer prototype 71 * 72 * Performs algorithm-specific initialization of the decoder context. This 73 * function is called by vpx_codec_dec_init() and vpx_codec_enc_init(), so 74 * plugins implementing this interface may trust the input parameters to be 75 * properly initialized. 76 * 77 * \param[in] ctx Pointer to this instance's context 78 * \retval #VPX_CODEC_OK 79 * The input stream was recognized and decoder initialized. 80 * \retval #VPX_CODEC_MEM_ERROR 81 * Memory operation failed. 82 */ 83 typedef vpx_codec_err_t (*vpx_codec_init_fn_t)( 84 vpx_codec_ctx_t *ctx, vpx_codec_priv_enc_mr_cfg_t *data); 85 86 /*!\brief destroy function pointer prototype 87 * 88 * Performs algorithm-specific destruction of the decoder context. This 89 * function is called by the generic vpx_codec_destroy() wrapper function, 90 * so plugins implementing this interface may trust the input parameters 91 * to be properly initialized. 92 * 93 * \param[in] ctx Pointer to this instance's context 94 * \retval #VPX_CODEC_OK 95 * The input stream was recognized and decoder initialized. 96 * \retval #VPX_CODEC_MEM_ERROR 97 * Memory operation failed. 98 */ 99 typedef vpx_codec_err_t (*vpx_codec_destroy_fn_t)(vpx_codec_alg_priv_t *ctx); 100 101 /*!\brief parse stream info function pointer prototype 102 * 103 * Performs high level parsing of the bitstream. This function is called by the 104 * generic vpx_codec_peek_stream_info() wrapper function, so plugins 105 * implementing this interface may trust the input parameters to be properly 106 * initialized. 107 * 108 * \param[in] data Pointer to a block of data to parse 109 * \param[in] data_sz Size of the data buffer 110 * \param[in,out] si Pointer to stream info to update. The size member 111 * \ref MUST be properly initialized, but \ref MAY be 112 * clobbered by the algorithm. This parameter \ref MAY 113 * be NULL. 114 * 115 * \retval #VPX_CODEC_OK 116 * Bitstream is parsable and stream information updated 117 */ 118 typedef vpx_codec_err_t (*vpx_codec_peek_si_fn_t)(const uint8_t *data, 119 unsigned int data_sz, 120 vpx_codec_stream_info_t *si); 121 122 /*!\brief Return information about the current stream. 123 * 124 * Returns information about the stream that has been parsed during decoding. 125 * 126 * \param[in] ctx Pointer to this instance's context 127 * \param[in,out] si Pointer to stream info to update. The size member 128 * \ref MUST be properly initialized, but \ref MAY be 129 * clobbered by the algorithm. This parameter \ref MAY 130 * be NULL. 131 * 132 * \retval #VPX_CODEC_OK 133 * Bitstream is parsable and stream information updated 134 */ 135 typedef vpx_codec_err_t (*vpx_codec_get_si_fn_t)(vpx_codec_alg_priv_t *ctx, 136 vpx_codec_stream_info_t *si); 137 138 /*!\brief control function pointer prototype 139 * 140 * This function is used to exchange algorithm specific data with the decoder 141 * instance. This can be used to implement features specific to a particular 142 * algorithm. 143 * 144 * This function is called by the generic vpx_codec_control() wrapper 145 * function, so plugins implementing this interface may trust the input 146 * parameters to be properly initialized. However, this interface does not 147 * provide type safety for the exchanged data or assign meanings to the 148 * control codes. Those details should be specified in the algorithm's 149 * header file. In particular, the ctrl_id parameter is guaranteed to exist 150 * in the algorithm's control mapping table, and the data parameter may be NULL. 151 * 152 * 153 * \param[in] ctx Pointer to this instance's context 154 * \param[in] ctrl_id Algorithm specific control identifier 155 * \param[in,out] data Data to exchange with algorithm instance. 156 * 157 * \retval #VPX_CODEC_OK 158 * The internal state data was deserialized. 159 */ 160 typedef vpx_codec_err_t (*vpx_codec_control_fn_t)(vpx_codec_alg_priv_t *ctx, 161 va_list ap); 162 163 /*!\brief control function pointer mapping 164 * 165 * This structure stores the mapping between control identifiers and 166 * implementing functions. Each algorithm provides a list of these 167 * mappings. This list is searched by the vpx_codec_control() wrapper 168 * function to determine which function to invoke. The special 169 * value {0, NULL} is used to indicate end-of-list, and must be 170 * present. The special value {0, <non-null>} can be used as a catch-all 171 * mapping. This implies that ctrl_id values chosen by the algorithm 172 * \ref MUST be non-zero. 173 */ 174 typedef const struct vpx_codec_ctrl_fn_map { 175 int ctrl_id; 176 vpx_codec_control_fn_t fn; 177 } vpx_codec_ctrl_fn_map_t; 178 179 /*!\brief decode data function pointer prototype 180 * 181 * Processes a buffer of coded data. If the processing results in a new 182 * decoded frame becoming available, put_slice and put_frame callbacks 183 * are invoked as appropriate. This function is called by the generic 184 * vpx_codec_decode() wrapper function, so plugins implementing this 185 * interface may trust the input parameters to be properly initialized. 186 * 187 * \param[in] ctx Pointer to this instance's context 188 * \param[in] data Pointer to this block of new coded data. If 189 * NULL, the put_frame callback is invoked for 190 * the previously decoded frame. 191 * \param[in] data_sz Size of the coded data, in bytes. 192 * 193 * \return Returns #VPX_CODEC_OK if the coded data was processed completely 194 * and future pictures can be decoded without error. Otherwise, 195 * see the descriptions of the other error codes in ::vpx_codec_err_t 196 * for recoverability capabilities. 197 */ 198 typedef vpx_codec_err_t (*vpx_codec_decode_fn_t)(vpx_codec_alg_priv_t *ctx, 199 const uint8_t *data, 200 unsigned int data_sz, 201 void *user_priv); 202 203 /*!\brief Decoded frames iterator 204 * 205 * Iterates over a list of the frames available for display. The iterator 206 * storage should be initialized to NULL to start the iteration. Iteration is 207 * complete when this function returns NULL. 208 * 209 * The list of available frames becomes valid upon completion of the 210 * vpx_codec_decode call, and remains valid until the next call to 211 * vpx_codec_decode. 212 * 213 * \param[in] ctx Pointer to this instance's context 214 * \param[in out] iter Iterator storage, initialized to NULL 215 * 216 * \return Returns a pointer to an image, if one is ready for display. Frames 217 * produced will always be in PTS (presentation time stamp) order. 218 */ 219 typedef vpx_image_t *(*vpx_codec_get_frame_fn_t)(vpx_codec_alg_priv_t *ctx, 220 vpx_codec_iter_t *iter); 221 222 /*!\brief Pass in external frame buffers for the decoder to use. 223 * 224 * Registers functions to be called when libvpx needs a frame buffer 225 * to decode the current frame and a function to be called when libvpx does 226 * not internally reference the frame buffer. This set function must 227 * be called before the first call to decode or libvpx will assume the 228 * default behavior of allocating frame buffers internally. 229 * 230 * \param[in] ctx Pointer to this instance's context 231 * \param[in] cb_get Pointer to the get callback function 232 * \param[in] cb_release Pointer to the release callback function 233 * \param[in] cb_priv Callback's private data 234 * 235 * \retval #VPX_CODEC_OK 236 * External frame buffers will be used by libvpx. 237 * \retval #VPX_CODEC_INVALID_PARAM 238 * One or more of the callbacks were NULL. 239 * \retval #VPX_CODEC_ERROR 240 * Decoder context not initialized, or algorithm not capable of 241 * using external frame buffers. 242 * 243 * \note 244 * When decoding VP9, the application may be required to pass in at least 245 * #VP9_MAXIMUM_REF_BUFFERS + #VPX_MAXIMUM_WORK_BUFFERS external frame 246 * buffers. 247 */ 248 typedef vpx_codec_err_t (*vpx_codec_set_fb_fn_t)( 249 vpx_codec_alg_priv_t *ctx, vpx_get_frame_buffer_cb_fn_t cb_get, 250 vpx_release_frame_buffer_cb_fn_t cb_release, void *cb_priv); 251 252 typedef vpx_codec_err_t (*vpx_codec_encode_fn_t)(vpx_codec_alg_priv_t *ctx, 253 const vpx_image_t *img, 254 vpx_codec_pts_t pts, 255 unsigned long duration, 256 vpx_enc_frame_flags_t flags, 257 vpx_enc_deadline_t deadline); 258 typedef const vpx_codec_cx_pkt_t *(*vpx_codec_get_cx_data_fn_t)( 259 vpx_codec_alg_priv_t *ctx, vpx_codec_iter_t *iter); 260 261 typedef vpx_codec_err_t (*vpx_codec_enc_config_set_fn_t)( 262 vpx_codec_alg_priv_t *ctx, const vpx_codec_enc_cfg_t *cfg); 263 typedef vpx_fixed_buf_t *(*vpx_codec_get_global_headers_fn_t)( 264 vpx_codec_alg_priv_t *ctx); 265 266 typedef vpx_image_t *(*vpx_codec_get_preview_frame_fn_t)( 267 vpx_codec_alg_priv_t *ctx); 268 269 typedef vpx_codec_err_t (*vpx_codec_enc_mr_get_mem_loc_fn_t)( 270 const vpx_codec_enc_cfg_t *cfg, void **mem_loc); 271 272 /*!\brief usage configuration mapping 273 * 274 * This structure stores the mapping between usage identifiers and 275 * configuration structures. Each algorithm provides a list of these 276 * mappings. This list is searched by the vpx_codec_enc_config_default() 277 * wrapper function to determine which config to return. The special value 278 * {-1, {0}} is used to indicate end-of-list, and must be present. At least 279 * one mapping must be present, in addition to the end-of-list. 280 * 281 */ 282 typedef const struct vpx_codec_enc_cfg_map { 283 int usage; 284 vpx_codec_enc_cfg_t cfg; 285 } vpx_codec_enc_cfg_map_t; 286 287 /*!\brief Decoder algorithm interface 288 * 289 * All decoders \ref MUST expose a variable of this type. 290 */ 291 struct vpx_codec_iface { 292 const char *name; /**< Identification String */ 293 int abi_version; /**< Implemented ABI version */ 294 vpx_codec_caps_t caps; /**< Decoder capabilities */ 295 vpx_codec_init_fn_t init; /**< \copydoc ::vpx_codec_init_fn_t */ 296 vpx_codec_destroy_fn_t destroy; /**< \copydoc ::vpx_codec_destroy_fn_t */ 297 vpx_codec_ctrl_fn_map_t *ctrl_maps; /**< \copydoc ::vpx_codec_ctrl_fn_map_t */ 298 struct vpx_codec_dec_iface { 299 vpx_codec_peek_si_fn_t peek_si; /**< \copydoc ::vpx_codec_peek_si_fn_t */ 300 vpx_codec_get_si_fn_t get_si; /**< \copydoc ::vpx_codec_get_si_fn_t */ 301 vpx_codec_decode_fn_t decode; /**< \copydoc ::vpx_codec_decode_fn_t */ 302 vpx_codec_get_frame_fn_t 303 get_frame; /**< \copydoc ::vpx_codec_get_frame_fn_t */ 304 vpx_codec_set_fb_fn_t set_fb_fn; /**< \copydoc ::vpx_codec_set_fb_fn_t */ 305 } dec; 306 struct vpx_codec_enc_iface { 307 int cfg_map_count; 308 vpx_codec_enc_cfg_map_t 309 *cfg_maps; /**< \copydoc ::vpx_codec_enc_cfg_map_t */ 310 vpx_codec_encode_fn_t encode; /**< \copydoc ::vpx_codec_encode_fn_t */ 311 vpx_codec_get_cx_data_fn_t 312 get_cx_data; /**< \copydoc ::vpx_codec_get_cx_data_fn_t */ 313 vpx_codec_enc_config_set_fn_t 314 cfg_set; /**< \copydoc ::vpx_codec_enc_config_set_fn_t */ 315 vpx_codec_get_global_headers_fn_t 316 get_glob_hdrs; /**< \copydoc ::vpx_codec_get_global_headers_fn_t */ 317 vpx_codec_get_preview_frame_fn_t 318 get_preview; /**< \copydoc ::vpx_codec_get_preview_frame_fn_t */ 319 vpx_codec_enc_mr_get_mem_loc_fn_t 320 mr_get_mem_loc; /**< \copydoc ::vpx_codec_enc_mr_get_mem_loc_fn_t */ 321 } enc; 322 }; 323 324 /*!\brief Callback function pointer / user data pair storage */ 325 typedef struct vpx_codec_priv_cb_pair { 326 union { 327 vpx_codec_put_frame_cb_fn_t put_frame; 328 vpx_codec_put_slice_cb_fn_t put_slice; 329 } u; 330 void *user_priv; 331 } vpx_codec_priv_cb_pair_t; 332 333 /*!\brief Instance private storage 334 * 335 * This structure is allocated by the algorithm's init function. It can be 336 * extended in one of two ways. First, a second, algorithm specific structure 337 * can be allocated and the priv member pointed to it. Alternatively, this 338 * structure can be made the first member of the algorithm specific structure, 339 * and the pointer cast to the proper type. 340 */ 341 struct vpx_codec_priv { 342 const char *err_detail; 343 vpx_codec_flags_t init_flags; 344 struct { 345 vpx_codec_priv_cb_pair_t put_frame_cb; 346 vpx_codec_priv_cb_pair_t put_slice_cb; 347 } dec; 348 struct { 349 vpx_fixed_buf_t cx_data_dst_buf; 350 unsigned int cx_data_pad_before; 351 unsigned int cx_data_pad_after; 352 vpx_codec_cx_pkt_t cx_data_pkt; 353 unsigned int total_encoders; 354 } enc; 355 }; 356 357 /* 358 * Multi-resolution encoding internal configuration 359 */ 360 struct vpx_codec_priv_enc_mr_cfg { 361 unsigned int mr_total_resolutions; 362 unsigned int mr_encoder_id; 363 struct vpx_rational mr_down_sampling_factor; 364 void *mr_low_res_mode_info; 365 }; 366 367 #undef VPX_CTRL_USE_TYPE 368 #define VPX_CTRL_USE_TYPE(id, typ) \ 369 static VPX_INLINE typ id##__value(va_list args) { return va_arg(args, typ); } 370 371 #undef VPX_CTRL_USE_TYPE_DEPRECATED 372 #define VPX_CTRL_USE_TYPE_DEPRECATED(id, typ) \ 373 static VPX_INLINE typ id##__value(va_list args) { return va_arg(args, typ); } 374 375 #define CAST(id, arg) id##__value(arg) 376 377 /* CODEC_INTERFACE convenience macro 378 * 379 * By convention, each codec interface is a struct with extern linkage, where 380 * the symbol is suffixed with _algo. A getter function is also defined to 381 * return a pointer to the struct, since in some cases it's easier to work 382 * with text symbols than data symbols (see issue #169). This function has 383 * the same name as the struct, less the _algo suffix. The CODEC_INTERFACE 384 * macro is provided to define this getter function automatically. 385 */ 386 #define CODEC_INTERFACE(id) \ 387 vpx_codec_iface_t *id(void) { return &id##_algo; } \ 388 vpx_codec_iface_t id##_algo 389 390 /* Internal Utility Functions 391 * 392 * The following functions are intended to be used inside algorithms as 393 * utilities for manipulating vpx_codec_* data structures. 394 */ 395 struct vpx_codec_pkt_list { 396 unsigned int cnt; 397 unsigned int max; 398 struct vpx_codec_cx_pkt pkts[1]; 399 }; 400 401 #define vpx_codec_pkt_list_decl(n) \ 402 union { \ 403 struct vpx_codec_pkt_list head; \ 404 struct { \ 405 struct vpx_codec_pkt_list head; \ 406 struct vpx_codec_cx_pkt pkts[n]; \ 407 } alloc; \ 408 } 409 410 #define vpx_codec_pkt_list_init(m) \ 411 (m)->alloc.head.cnt = 0, \ 412 (m)->alloc.head.max = sizeof((m)->alloc.pkts) / sizeof((m)->alloc.pkts[0]) 413 414 int vpx_codec_pkt_list_add(struct vpx_codec_pkt_list *, 415 const struct vpx_codec_cx_pkt *); 416 417 const vpx_codec_cx_pkt_t *vpx_codec_pkt_list_get( 418 struct vpx_codec_pkt_list *list, vpx_codec_iter_t *iter); 419 420 #include <stdio.h> 421 #include <setjmp.h> 422 423 struct vpx_internal_error_info { 424 vpx_codec_err_t error_code; 425 int has_detail; 426 char detail[80]; 427 int setjmp; 428 jmp_buf jmp; 429 }; 430 431 #if CONFIG_DEBUG 432 #define CHECK_MEM_ERROR(error, lval, expr) \ 433 do { \ 434 assert((error)->setjmp); \ 435 (lval) = (expr); \ 436 if (!(lval)) \ 437 vpx_internal_error(error, VPX_CODEC_MEM_ERROR, \ 438 "Failed to allocate " #lval " at %s:%d", __FILE__, \ 439 __LINE__); \ 440 } while (0) 441 #else 442 #define CHECK_MEM_ERROR(error, lval, expr) \ 443 do { \ 444 assert((error)->setjmp); \ 445 (lval) = (expr); \ 446 if (!(lval)) \ 447 vpx_internal_error(error, VPX_CODEC_MEM_ERROR, \ 448 "Failed to allocate " #lval); \ 449 } while (0) 450 #endif 451 452 #define CLANG_ANALYZER_NORETURN 453 #if defined(__has_feature) 454 #if __has_feature(attribute_analyzer_noreturn) 455 #undef CLANG_ANALYZER_NORETURN 456 #define CLANG_ANALYZER_NORETURN __attribute__((analyzer_noreturn)) 457 #endif 458 #endif 459 460 // Tells the compiler to perform `printf` format string checking if the 461 // compiler supports it; see the 'format' attribute in 462 // <https://gcc.gnu.org/onlinedocs/gcc/Common-Function-Attributes.html>. 463 #define LIBVPX_FORMAT_PRINTF(string_index, first_to_check) 464 #if defined(__has_attribute) 465 #if __has_attribute(format) 466 #undef LIBVPX_FORMAT_PRINTF 467 #define LIBVPX_FORMAT_PRINTF(string_index, first_to_check) \ 468 __attribute__((__format__(__printf__, string_index, first_to_check))) 469 #endif 470 #endif 471 472 void vpx_internal_error(struct vpx_internal_error_info *info, 473 vpx_codec_err_t error, const char *fmt, ...) 474 LIBVPX_FORMAT_PRINTF(3, 4) CLANG_ANALYZER_NORETURN; 475 476 #ifdef __cplusplus 477 } // extern "C" 478 #endif 479 480 #endif // VPX_VPX_INTERNAL_VPX_CODEC_INTERNAL_H_ 481