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 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 * vpx_codec_iface_t my_codec = { 24 * "My Codec v1.0", 25 * VPX_CODEC_ALG_ABI_VERSION, 26 * ... 27 * }; 28 * </pre> 29 * 30 * An application instantiates a specific decoder instance by using 31 * vpx_codec_init() and a pointer to the algorithm's interface structure: 32 * <pre> 33 * my_app.c: 34 * extern vpx_codec_iface_t my_codec; 35 * { 36 * vpx_codec_ctx_t algo; 37 * res = vpx_codec_init(&algo, &my_codec); 38 * } 39 * </pre> 40 * 41 * Once initialized, the instance is manged using other functions from 42 * the vpx_codec_* family. 43 */ 44 #ifndef VPX_INTERNAL_VPX_CODEC_INTERNAL_H_ 45 #define VPX_INTERNAL_VPX_CODEC_INTERNAL_H_ 46 #include "../vpx_decoder.h" 47 #include "../vpx_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 VPX_CODEC_INTERNAL_ABI_VERSION (5) /**<\hideinitializer*/ 63 64 typedef struct vpx_codec_alg_priv vpx_codec_alg_priv_t; 65 typedef struct vpx_codec_priv_enc_mr_cfg vpx_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 vpx_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 #VPX_CODEC_OK 76 * The input stream was recognized and decoder initialized. 77 * \retval #VPX_CODEC_MEM_ERROR 78 * Memory operation failed. 79 */ 80 typedef vpx_codec_err_t (*vpx_codec_init_fn_t)(vpx_codec_ctx_t *ctx, 81 vpx_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 vpx_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 #VPX_CODEC_OK 92 * The input stream was recognized and decoder initialized. 93 * \retval #VPX_CODEC_MEM_ERROR 94 * Memory operation failed. 95 */ 96 typedef vpx_codec_err_t (*vpx_codec_destroy_fn_t)(vpx_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 vpx_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 size member 108 * \ref MUST be properly initialized, but \ref MAY be 109 * clobbered by the algorithm. This parameter \ref MAY 110 * be NULL. 111 * 112 * \retval #VPX_CODEC_OK 113 * Bitstream is parsable and stream information updated 114 */ 115 typedef vpx_codec_err_t (*vpx_codec_peek_si_fn_t)(const uint8_t *data, 116 unsigned int data_sz, 117 vpx_codec_stream_info_t *si); 118 119 /*!\brief Return information about the current stream. 120 * 121 * Returns information about the stream that has been parsed during decoding. 122 * 123 * \param[in] ctx Pointer to this instance's context 124 * \param[in,out] si Pointer to stream info to update. The size member 125 * \ref MUST be properly initialized, but \ref MAY be 126 * clobbered by the algorithm. This parameter \ref MAY 127 * be NULL. 128 * 129 * \retval #VPX_CODEC_OK 130 * Bitstream is parsable and stream information updated 131 */ 132 typedef vpx_codec_err_t (*vpx_codec_get_si_fn_t)(vpx_codec_alg_priv_t *ctx, 133 vpx_codec_stream_info_t *si); 134 135 /*!\brief control function pointer prototype 136 * 137 * This function is used to exchange algorithm specific data with the decoder 138 * instance. This can be used to implement features specific to a particular 139 * algorithm. 140 * 141 * This function is called by the generic vpx_codec_control() wrapper 142 * function, so plugins implementing this interface may trust the input 143 * parameters to be properly initialized. However, this interface does not 144 * provide type safety for the exchanged data or assign meanings to the 145 * control codes. Those details should be specified in the algorithm's 146 * header file. In particular, the ctrl_id parameter is guaranteed to exist 147 * in the algorithm's control mapping table, and the data parameter may be NULL. 148 * 149 * 150 * \param[in] ctx Pointer to this instance's context 151 * \param[in] ctrl_id Algorithm specific control identifier 152 * \param[in,out] data Data to exchange with algorithm instance. 153 * 154 * \retval #VPX_CODEC_OK 155 * The internal state data was deserialized. 156 */ 157 typedef vpx_codec_err_t (*vpx_codec_control_fn_t)(vpx_codec_alg_priv_t *ctx, 158 int ctrl_id, 159 va_list ap); 160 161 /*!\brief control function pointer mapping 162 * 163 * This structure stores the mapping between control identifiers and 164 * implementing functions. Each algorithm provides a list of these 165 * mappings. This list is searched by the vpx_codec_control() wrapper 166 * function to determine which function to invoke. The special 167 * value {0, NULL} is used to indicate end-of-list, and must be 168 * present. The special value {0, <non-null>} can be used as a catch-all 169 * mapping. This implies that ctrl_id values chosen by the algorithm 170 * \ref MUST be non-zero. 171 */ 172 typedef const struct vpx_codec_ctrl_fn_map { 173 int ctrl_id; 174 vpx_codec_control_fn_t fn; 175 } vpx_codec_ctrl_fn_map_t; 176 177 /*!\brief decode data function pointer prototype 178 * 179 * Processes a buffer of coded data. If the processing results in a new 180 * decoded frame becoming available, #VPX_CODEC_CB_PUT_SLICE and 181 * #VPX_CODEC_CB_PUT_FRAME events are generated as appropriate. This 182 * function is called by the generic vpx_codec_decode() wrapper function, 183 * so plugins implementing this interface may trust the input parameters 184 * to be properly initialized. 185 * 186 * \param[in] ctx Pointer to this instance's context 187 * \param[in] data Pointer to this block of new coded data. If 188 * NULL, a #VPX_CODEC_CB_PUT_FRAME event is posted 189 * for the previously decoded frame. 190 * \param[in] data_sz Size of the coded data, in bytes. 191 * 192 * \return Returns #VPX_CODEC_OK if the coded data was processed completely 193 * and future pictures can be decoded without error. Otherwise, 194 * see the descriptions of the other error codes in ::vpx_codec_err_t 195 * for recoverability capabilities. 196 */ 197 typedef vpx_codec_err_t (*vpx_codec_decode_fn_t)(vpx_codec_alg_priv_t *ctx, 198 const uint8_t *data, 199 unsigned int data_sz, 200 void *user_priv, 201 long deadline); 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 vpx_codec_decode. 211 * 212 * \param[in] ctx Pointer to this instance's context 213 * \param[in out] iter Iterator storage, initialized to NULL 214 * 215 * \return Returns a pointer to an image, if one is ready for display. Frames 216 * produced will always be in PTS (presentation time stamp) order. 217 */ 218 typedef vpx_image_t *(*vpx_codec_get_frame_fn_t)(vpx_codec_alg_priv_t *ctx, 219 vpx_codec_iter_t *iter); 220 221 /*!\brief Pass in external frame buffers for the decoder to use. 222 * 223 * Registers functions to be called when libvpx needs a frame buffer 224 * to decode the current frame and a function to be called when libvpx does 225 * not internally reference the frame buffer. This set function must 226 * be called before the first call to decode or libvpx 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 #VPX_CODEC_OK 235 * External frame buffers will be used by libvpx. 236 * \retval #VPX_CODEC_INVALID_PARAM 237 * One or more of the callbacks were NULL. 238 * \retval #VPX_CODEC_ERROR 239 * Decoder context not initialized, or algorithm not capable of 240 * using external frame buffers. 241 * 242 * \note 243 * When decoding VP9, the application may be required to pass in at least 244 * #VP9_MAXIMUM_REF_BUFFERS + #VPX_MAXIMUM_WORK_BUFFERS external frame 245 * buffers. 246 */ 247 typedef vpx_codec_err_t (*vpx_codec_set_fb_fn_t)( 248 vpx_codec_alg_priv_t *ctx, 249 vpx_get_frame_buffer_cb_fn_t cb_get, 250 vpx_release_frame_buffer_cb_fn_t cb_release, void *cb_priv); 251 252 /*\brief eXternal Memory Allocation memory map get iterator 253 * 254 * Iterates over a list of the memory maps requested by the decoder. The 255 * iterator storage should be initialized to NULL to start the iteration. 256 * Iteration is complete when this function returns NULL. 257 * 258 * \param[in out] iter Iterator storage, initialized to NULL 259 * 260 * \return Returns a pointer to an memory segment descriptor, or NULL to 261 * indicate end-of-list. 262 */ 263 typedef vpx_codec_err_t (*vpx_codec_get_mmap_fn_t)(const vpx_codec_ctx_t *ctx, 264 vpx_codec_mmap_t *mmap, 265 vpx_codec_iter_t *iter); 266 267 268 /*\brief eXternal Memory Allocation memory map set iterator 269 * 270 * Sets a memory descriptor inside the decoder instance. 271 * 272 * \param[in] ctx Pointer to this instance's context 273 * \param[in] mmap Memory map to store. 274 * 275 * \retval #VPX_CODEC_OK 276 * The memory map was accepted and stored. 277 * \retval #VPX_CODEC_MEM_ERROR 278 * The memory map was rejected. 279 */ 280 typedef vpx_codec_err_t (*vpx_codec_set_mmap_fn_t)(vpx_codec_ctx_t *ctx, 281 const vpx_codec_mmap_t *mmap); 282 283 284 typedef vpx_codec_err_t (*vpx_codec_encode_fn_t)(vpx_codec_alg_priv_t *ctx, 285 const vpx_image_t *img, 286 vpx_codec_pts_t pts, 287 unsigned long duration, 288 vpx_enc_frame_flags_t flags, 289 unsigned long deadline); 290 typedef const vpx_codec_cx_pkt_t *(*vpx_codec_get_cx_data_fn_t)(vpx_codec_alg_priv_t *ctx, 291 vpx_codec_iter_t *iter); 292 293 typedef vpx_codec_err_t 294 (*vpx_codec_enc_config_set_fn_t)(vpx_codec_alg_priv_t *ctx, 295 const vpx_codec_enc_cfg_t *cfg); 296 typedef vpx_fixed_buf_t * 297 (*vpx_codec_get_global_headers_fn_t)(vpx_codec_alg_priv_t *ctx); 298 299 typedef vpx_image_t * 300 (*vpx_codec_get_preview_frame_fn_t)(vpx_codec_alg_priv_t *ctx); 301 302 typedef vpx_codec_err_t 303 (*vpx_codec_enc_mr_get_mem_loc_fn_t)(const vpx_codec_enc_cfg_t *cfg, 304 void **mem_loc); 305 306 /*!\brief usage configuration mapping 307 * 308 * This structure stores the mapping between usage identifiers and 309 * configuration structures. Each algorithm provides a list of these 310 * mappings. This list is searched by the vpx_codec_enc_config_default() 311 * wrapper function to determine which config to return. The special value 312 * {-1, {0}} is used to indicate end-of-list, and must be present. At least 313 * one mapping must be present, in addition to the end-of-list. 314 * 315 */ 316 typedef const struct vpx_codec_enc_cfg_map { 317 int usage; 318 vpx_codec_enc_cfg_t cfg; 319 } vpx_codec_enc_cfg_map_t; 320 321 #define NOT_IMPLEMENTED 0 322 323 /*!\brief Decoder algorithm interface interface 324 * 325 * All decoders \ref MUST expose a variable of this type. 326 */ 327 struct vpx_codec_iface { 328 const char *name; /**< Identification String */ 329 int abi_version; /**< Implemented ABI version */ 330 vpx_codec_caps_t caps; /**< Decoder capabilities */ 331 vpx_codec_init_fn_t init; /**< \copydoc ::vpx_codec_init_fn_t */ 332 vpx_codec_destroy_fn_t destroy; /**< \copydoc ::vpx_codec_destroy_fn_t */ 333 vpx_codec_ctrl_fn_map_t *ctrl_maps; /**< \copydoc ::vpx_codec_ctrl_fn_map_t */ 334 vpx_codec_get_mmap_fn_t get_mmap; /**< \copydoc ::vpx_codec_get_mmap_fn_t */ 335 vpx_codec_set_mmap_fn_t set_mmap; /**< \copydoc ::vpx_codec_set_mmap_fn_t */ 336 struct vpx_codec_dec_iface { 337 vpx_codec_peek_si_fn_t peek_si; /**< \copydoc ::vpx_codec_peek_si_fn_t */ 338 vpx_codec_get_si_fn_t get_si; /**< \copydoc ::vpx_codec_get_si_fn_t */ 339 vpx_codec_decode_fn_t decode; /**< \copydoc ::vpx_codec_decode_fn_t */ 340 vpx_codec_get_frame_fn_t get_frame; /**< \copydoc ::vpx_codec_get_frame_fn_t */ 341 vpx_codec_set_fb_fn_t set_fb_fn; /**< \copydoc ::vpx_codec_set_fb_fn_t */ 342 } dec; 343 struct vpx_codec_enc_iface { 344 vpx_codec_enc_cfg_map_t *cfg_maps; /**< \copydoc ::vpx_codec_enc_cfg_map_t */ 345 vpx_codec_encode_fn_t encode; /**< \copydoc ::vpx_codec_encode_fn_t */ 346 vpx_codec_get_cx_data_fn_t get_cx_data; /**< \copydoc ::vpx_codec_get_cx_data_fn_t */ 347 vpx_codec_enc_config_set_fn_t cfg_set; /**< \copydoc ::vpx_codec_enc_config_set_fn_t */ 348 vpx_codec_get_global_headers_fn_t get_glob_hdrs; /**< \copydoc ::vpx_codec_get_global_headers_fn_t */ 349 vpx_codec_get_preview_frame_fn_t get_preview; /**< \copydoc ::vpx_codec_get_preview_frame_fn_t */ 350 vpx_codec_enc_mr_get_mem_loc_fn_t mr_get_mem_loc; /**< \copydoc ::vpx_codec_enc_mr_get_mem_loc_fn_t */ 351 } enc; 352 }; 353 354 /*!\brief Callback function pointer / user data pair storage */ 355 typedef struct vpx_codec_priv_cb_pair { 356 union { 357 vpx_codec_put_frame_cb_fn_t put_frame; 358 vpx_codec_put_slice_cb_fn_t put_slice; 359 } u; 360 void *user_priv; 361 } vpx_codec_priv_cb_pair_t; 362 363 364 /*!\brief Instance private storage 365 * 366 * This structure is allocated by the algorithm's init function. It can be 367 * extended in one of two ways. First, a second, algorithm specific structure 368 * can be allocated and the priv member pointed to it. Alternatively, this 369 * structure can be made the first member of the algorithm specific structure, 370 * and the pointer cast to the proper type. 371 */ 372 struct vpx_codec_priv { 373 unsigned int sz; 374 vpx_codec_iface_t *iface; 375 struct vpx_codec_alg_priv *alg_priv; 376 const char *err_detail; 377 vpx_codec_flags_t init_flags; 378 struct { 379 vpx_codec_priv_cb_pair_t put_frame_cb; 380 vpx_codec_priv_cb_pair_t put_slice_cb; 381 } dec; 382 struct { 383 int tbd; 384 struct vpx_fixed_buf cx_data_dst_buf; 385 unsigned int cx_data_pad_before; 386 unsigned int cx_data_pad_after; 387 vpx_codec_cx_pkt_t cx_data_pkt; 388 unsigned int total_encoders; 389 } enc; 390 }; 391 392 /* 393 * Multi-resolution encoding internal configuration 394 */ 395 struct vpx_codec_priv_enc_mr_cfg 396 { 397 unsigned int mr_total_resolutions; 398 unsigned int mr_encoder_id; 399 struct vpx_rational mr_down_sampling_factor; 400 void* mr_low_res_mode_info; 401 }; 402 403 #undef VPX_CTRL_USE_TYPE 404 #define VPX_CTRL_USE_TYPE(id, typ) \ 405 static typ id##__value(va_list args) {return va_arg(args, typ);} \ 406 static typ id##__convert(void *x)\ 407 {\ 408 union\ 409 {\ 410 void *x;\ 411 typ d;\ 412 } u;\ 413 u.x = x;\ 414 return u.d;\ 415 } 416 417 418 #undef VPX_CTRL_USE_TYPE_DEPRECATED 419 #define VPX_CTRL_USE_TYPE_DEPRECATED(id, typ) \ 420 static typ id##__value(va_list args) {return va_arg(args, typ);} \ 421 static typ id##__convert(void *x)\ 422 {\ 423 union\ 424 {\ 425 void *x;\ 426 typ d;\ 427 } u;\ 428 u.x = x;\ 429 return u.d;\ 430 } 431 432 #define CAST(id, arg) id##__value(arg) 433 #define RECAST(id, x) id##__convert(x) 434 435 436 /* CODEC_INTERFACE convenience macro 437 * 438 * By convention, each codec interface is a struct with extern linkage, where 439 * the symbol is suffixed with _algo. A getter function is also defined to 440 * return a pointer to the struct, since in some cases it's easier to work 441 * with text symbols than data symbols (see issue #169). This function has 442 * the same name as the struct, less the _algo suffix. The CODEC_INTERFACE 443 * macro is provided to define this getter function automatically. 444 */ 445 #define CODEC_INTERFACE(id)\ 446 vpx_codec_iface_t* id(void) { return &id##_algo; }\ 447 vpx_codec_iface_t id##_algo 448 449 450 /* Internal Utility Functions 451 * 452 * The following functions are intended to be used inside algorithms as 453 * utilities for manipulating vpx_codec_* data structures. 454 */ 455 struct vpx_codec_pkt_list { 456 unsigned int cnt; 457 unsigned int max; 458 struct vpx_codec_cx_pkt pkts[1]; 459 }; 460 461 #define vpx_codec_pkt_list_decl(n)\ 462 union {struct vpx_codec_pkt_list head;\ 463 struct {struct vpx_codec_pkt_list head;\ 464 struct vpx_codec_cx_pkt pkts[n];} alloc;} 465 466 #define vpx_codec_pkt_list_init(m)\ 467 (m)->alloc.head.cnt = 0,\ 468 (m)->alloc.head.max = sizeof((m)->alloc.pkts) / sizeof((m)->alloc.pkts[0]) 469 470 int 471 vpx_codec_pkt_list_add(struct vpx_codec_pkt_list *, 472 const struct vpx_codec_cx_pkt *); 473 474 const vpx_codec_cx_pkt_t * 475 vpx_codec_pkt_list_get(struct vpx_codec_pkt_list *list, 476 vpx_codec_iter_t *iter); 477 478 479 #include <stdio.h> 480 #include <setjmp.h> 481 482 struct vpx_internal_error_info { 483 vpx_codec_err_t error_code; 484 int has_detail; 485 char detail[80]; 486 int setjmp; 487 jmp_buf jmp; 488 }; 489 490 static void vpx_internal_error(struct vpx_internal_error_info *info, 491 vpx_codec_err_t error, 492 const char *fmt, 493 ...) { 494 va_list ap; 495 496 info->error_code = error; 497 info->has_detail = 0; 498 499 if (fmt) { 500 size_t sz = sizeof(info->detail); 501 502 info->has_detail = 1; 503 va_start(ap, fmt); 504 vsnprintf(info->detail, sz - 1, fmt, ap); 505 va_end(ap); 506 info->detail[sz - 1] = '\0'; 507 } 508 509 if (info->setjmp) 510 longjmp(info->jmp, info->error_code); 511 } 512 513 //------------------------------------------------------------------------------ 514 // mmap interface 515 516 typedef struct { 517 unsigned int id; 518 unsigned long sz; 519 unsigned int align; 520 unsigned int flags; 521 unsigned long (*calc_sz)(const vpx_codec_dec_cfg_t *, vpx_codec_flags_t); 522 } mem_req_t; 523 524 // Allocates mmap.priv and sets mmap.base based on mmap.sz/align/flags 525 // requirements. 526 // Returns #VPX_CODEC_OK on success, #VPX_CODEC_MEM_ERROR otherwise. 527 vpx_codec_err_t vpx_mmap_alloc(vpx_codec_mmap_t *mmap); 528 529 // Frees mmap.base allocated by a call to vpx_mmap_alloc(). 530 void vpx_mmap_dtor(vpx_codec_mmap_t *mmap); 531 532 // Checks each mmap has the size requirement specificied by mem_reqs. 533 // Returns #VPX_CODEC_OK on success, #VPX_CODEC_MEM_ERROR otherwise. 534 vpx_codec_err_t vpx_validate_mmaps(const vpx_codec_stream_info_t *si, 535 const vpx_codec_mmap_t *mmaps, 536 const mem_req_t *mem_reqs, int nreqs, 537 vpx_codec_flags_t init_flags); 538 #ifdef __cplusplus 539 } // extern "C" 540 #endif 541 542 #endif // VPX_INTERNAL_VPX_CODEC_INTERNAL_H_ 543
