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_CODEC_INTERNAL_H 45 #define VPX_CODEC_INTERNAL_H 46 #include "../vpx_decoder.h" 47 #include "../vpx_encoder.h" 48 #include <stdarg.h> 49 50 51 /*!\brief Current ABI version number 52 * 53 * \internal 54 * If this file is altered in any way that changes the ABI, this value 55 * must be bumped. Examples include, but are not limited to, changing 56 * types, removing or reassigning enums, adding/removing/rearranging 57 * fields to structures 58 */ 59 #define VPX_CODEC_INTERNAL_ABI_VERSION (4) /**<\hideinitializer*/ 60 61 typedef struct vpx_codec_alg_priv vpx_codec_alg_priv_t; 62 typedef struct vpx_codec_priv_enc_mr_cfg vpx_codec_priv_enc_mr_cfg_t; 63 64 /*!\brief init function pointer prototype 65 * 66 * Performs algorithm-specific initialization of the decoder context. This 67 * function is called by the generic vpx_codec_init() wrapper function, so 68 * plugins implementing this interface may trust the input parameters to be 69 * properly initialized. 70 * 71 * \param[in] ctx Pointer to this instance's context 72 * \retval #VPX_CODEC_OK 73 * The input stream was recognized and decoder initialized. 74 * \retval #VPX_CODEC_MEM_ERROR 75 * Memory operation failed. 76 */ 77 typedef vpx_codec_err_t (*vpx_codec_init_fn_t)(vpx_codec_ctx_t *ctx, 78 vpx_codec_priv_enc_mr_cfg_t *data); 79 80 /*!\brief destroy function pointer prototype 81 * 82 * Performs algorithm-specific destruction of the decoder context. This 83 * function is called by the generic vpx_codec_destroy() wrapper function, 84 * so plugins implementing this interface may trust the input parameters 85 * to be properly initialized. 86 * 87 * \param[in] ctx Pointer to this instance's context 88 * \retval #VPX_CODEC_OK 89 * The input stream was recognized and decoder initialized. 90 * \retval #VPX_CODEC_MEM_ERROR 91 * Memory operation failed. 92 */ 93 typedef vpx_codec_err_t (*vpx_codec_destroy_fn_t)(vpx_codec_alg_priv_t *ctx); 94 95 /*!\brief parse stream info function pointer prototype 96 * 97 * Performs high level parsing of the bitstream. This function is called by the 98 * generic vpx_codec_peek_stream_info() wrapper function, so plugins 99 * implementing this interface may trust the input parameters to be properly 100 * initialized. 101 * 102 * \param[in] data Pointer to a block of data to parse 103 * \param[in] data_sz Size of the data buffer 104 * \param[in,out] si Pointer to stream info to update. The size member 105 * \ref MUST be properly initialized, but \ref MAY be 106 * clobbered by the algorithm. This parameter \ref MAY 107 * be NULL. 108 * 109 * \retval #VPX_CODEC_OK 110 * Bitstream is parsable and stream information updated 111 */ 112 typedef vpx_codec_err_t (*vpx_codec_peek_si_fn_t)(const uint8_t *data, 113 unsigned int data_sz, 114 vpx_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. The size member 122 * \ref MUST be properly initialized, but \ref MAY be 123 * clobbered by the algorithm. This parameter \ref MAY 124 * be NULL. 125 * 126 * \retval #VPX_CODEC_OK 127 * Bitstream is parsable and stream information updated 128 */ 129 typedef vpx_codec_err_t (*vpx_codec_get_si_fn_t)(vpx_codec_alg_priv_t *ctx, 130 vpx_codec_stream_info_t *si); 131 132 /*!\brief control function pointer prototype 133 * 134 * This function is used to exchange algorithm specific data with the decoder 135 * instance. This can be used to implement features specific to a particular 136 * algorithm. 137 * 138 * This function is called by the generic vpx_codec_control() wrapper 139 * function, so plugins implementing this interface may trust the input 140 * parameters to be properly initialized. However, this interface does not 141 * provide type safety for the exchanged data or assign meanings to the 142 * control codes. Those details should be specified in the algorithm's 143 * header file. In particular, the ctrl_id parameter is guaranteed to exist 144 * in the algorithm's control mapping table, and the data parameter may be NULL. 145 * 146 * 147 * \param[in] ctx Pointer to this instance's context 148 * \param[in] ctrl_id Algorithm specific control identifier 149 * \param[in,out] data Data to exchange with algorithm instance. 150 * 151 * \retval #VPX_CODEC_OK 152 * The internal state data was deserialized. 153 */ 154 typedef vpx_codec_err_t (*vpx_codec_control_fn_t)(vpx_codec_alg_priv_t *ctx, 155 int ctrl_id, 156 va_list ap); 157 158 /*!\brief control function pointer mapping 159 * 160 * This structure stores the mapping between control identifiers and 161 * implementing functions. Each algorithm provides a list of these 162 * mappings. This list is searched by the vpx_codec_control() wrapper 163 * function to determine which function to invoke. The special 164 * value {0, NULL} is used to indicate end-of-list, and must be 165 * present. The special value {0, <non-null>} can be used as a catch-all 166 * mapping. This implies that ctrl_id values chosen by the algorithm 167 * \ref MUST be non-zero. 168 */ 169 typedef const struct vpx_codec_ctrl_fn_map { 170 int ctrl_id; 171 vpx_codec_control_fn_t fn; 172 } vpx_codec_ctrl_fn_map_t; 173 174 /*!\brief decode data function pointer prototype 175 * 176 * Processes a buffer of coded data. If the processing results in a new 177 * decoded frame becoming available, #VPX_CODEC_CB_PUT_SLICE and 178 * #VPX_CODEC_CB_PUT_FRAME events are generated as appropriate. This 179 * function is called by the generic vpx_codec_decode() wrapper function, 180 * so plugins implementing this interface may trust the input parameters 181 * to be properly initialized. 182 * 183 * \param[in] ctx Pointer to this instance's context 184 * \param[in] data Pointer to this block of new coded data. If 185 * NULL, a #VPX_CODEC_CB_PUT_FRAME event is posted 186 * for the previously decoded frame. 187 * \param[in] data_sz Size of the coded data, in bytes. 188 * 189 * \return Returns #VPX_CODEC_OK if the coded data was processed completely 190 * and future pictures can be decoded without error. Otherwise, 191 * see the descriptions of the other error codes in ::vpx_codec_err_t 192 * for recoverability capabilities. 193 */ 194 typedef vpx_codec_err_t (*vpx_codec_decode_fn_t)(vpx_codec_alg_priv_t *ctx, 195 const uint8_t *data, 196 unsigned int data_sz, 197 void *user_priv, 198 long deadline); 199 200 /*!\brief Decoded frames iterator 201 * 202 * Iterates over a list of the frames available for display. The iterator 203 * storage should be initialized to NULL to start the iteration. Iteration is 204 * complete when this function returns NULL. 205 * 206 * The list of available frames becomes valid upon completion of the 207 * vpx_codec_decode call, and remains valid until the next call to vpx_codec_decode. 208 * 209 * \param[in] ctx Pointer to this instance's context 210 * \param[in out] iter Iterator storage, initialized to NULL 211 * 212 * \return Returns a pointer to an image, if one is ready for display. Frames 213 * produced will always be in PTS (presentation time stamp) order. 214 */ 215 typedef vpx_image_t *(*vpx_codec_get_frame_fn_t)(vpx_codec_alg_priv_t *ctx, 216 vpx_codec_iter_t *iter); 217 218 219 /*\brief eXternal Memory Allocation memory map get iterator 220 * 221 * Iterates over a list of the memory maps requested by the decoder. The 222 * iterator storage should be initialized to NULL to start the iteration. 223 * Iteration is complete when this function returns NULL. 224 * 225 * \param[in out] iter Iterator storage, initialized to NULL 226 * 227 * \return Returns a pointer to an memory segment descriptor, or NULL to 228 * indicate end-of-list. 229 */ 230 typedef vpx_codec_err_t (*vpx_codec_get_mmap_fn_t)(const vpx_codec_ctx_t *ctx, 231 vpx_codec_mmap_t *mmap, 232 vpx_codec_iter_t *iter); 233 234 235 /*\brief eXternal Memory Allocation memory map set iterator 236 * 237 * Sets a memory descriptor inside the decoder instance. 238 * 239 * \param[in] ctx Pointer to this instance's context 240 * \param[in] mmap Memory map to store. 241 * 242 * \retval #VPX_CODEC_OK 243 * The memory map was accepted and stored. 244 * \retval #VPX_CODEC_MEM_ERROR 245 * The memory map was rejected. 246 */ 247 typedef vpx_codec_err_t (*vpx_codec_set_mmap_fn_t)(vpx_codec_ctx_t *ctx, 248 const vpx_codec_mmap_t *mmap); 249 250 251 typedef vpx_codec_err_t (*vpx_codec_encode_fn_t)(vpx_codec_alg_priv_t *ctx, 252 const vpx_image_t *img, 253 vpx_codec_pts_t pts, 254 unsigned long duration, 255 vpx_enc_frame_flags_t flags, 256 unsigned long deadline); 257 typedef const vpx_codec_cx_pkt_t *(*vpx_codec_get_cx_data_fn_t)(vpx_codec_alg_priv_t *ctx, 258 vpx_codec_iter_t *iter); 259 260 typedef vpx_codec_err_t 261 (*vpx_codec_enc_config_set_fn_t)(vpx_codec_alg_priv_t *ctx, 262 const vpx_codec_enc_cfg_t *cfg); 263 typedef vpx_fixed_buf_t * 264 (*vpx_codec_get_global_headers_fn_t)(vpx_codec_alg_priv_t *ctx); 265 266 typedef vpx_image_t * 267 (*vpx_codec_get_preview_frame_fn_t)(vpx_codec_alg_priv_t *ctx); 268 269 typedef vpx_codec_err_t 270 (*vpx_codec_enc_mr_get_mem_loc_fn_t)(const vpx_codec_enc_cfg_t *cfg, 271 void **mem_loc); 272 273 /*!\brief usage configuration mapping 274 * 275 * This structure stores the mapping between usage identifiers and 276 * configuration structures. Each algorithm provides a list of these 277 * mappings. This list is searched by the vpx_codec_enc_config_default() 278 * wrapper function to determine which config to return. The special value 279 * {-1, {0}} is used to indicate end-of-list, and must be present. At least 280 * one mapping must be present, in addition to the end-of-list. 281 * 282 */ 283 typedef const struct vpx_codec_enc_cfg_map { 284 int usage; 285 vpx_codec_enc_cfg_t cfg; 286 } vpx_codec_enc_cfg_map_t; 287 288 #define NOT_IMPLEMENTED 0 289 290 /*!\brief Decoder algorithm interface interface 291 * 292 * All decoders \ref MUST expose a variable of this type. 293 */ 294 struct vpx_codec_iface { 295 const char *name; /**< Identification String */ 296 int abi_version; /**< Implemented ABI version */ 297 vpx_codec_caps_t caps; /**< Decoder capabilities */ 298 vpx_codec_init_fn_t init; /**< \copydoc ::vpx_codec_init_fn_t */ 299 vpx_codec_destroy_fn_t destroy; /**< \copydoc ::vpx_codec_destroy_fn_t */ 300 vpx_codec_ctrl_fn_map_t *ctrl_maps; /**< \copydoc ::vpx_codec_ctrl_fn_map_t */ 301 vpx_codec_get_mmap_fn_t get_mmap; /**< \copydoc ::vpx_codec_get_mmap_fn_t */ 302 vpx_codec_set_mmap_fn_t set_mmap; /**< \copydoc ::vpx_codec_set_mmap_fn_t */ 303 struct vpx_codec_dec_iface { 304 vpx_codec_peek_si_fn_t peek_si; /**< \copydoc ::vpx_codec_peek_si_fn_t */ 305 vpx_codec_get_si_fn_t get_si; /**< \copydoc ::vpx_codec_get_si_fn_t */ 306 vpx_codec_decode_fn_t decode; /**< \copydoc ::vpx_codec_decode_fn_t */ 307 vpx_codec_get_frame_fn_t get_frame; /**< \copydoc ::vpx_codec_get_frame_fn_t */ 308 } dec; 309 struct vpx_codec_enc_iface { 310 vpx_codec_enc_cfg_map_t *cfg_maps; /**< \copydoc ::vpx_codec_enc_cfg_map_t */ 311 vpx_codec_encode_fn_t encode; /**< \copydoc ::vpx_codec_encode_fn_t */ 312 vpx_codec_get_cx_data_fn_t get_cx_data; /**< \copydoc ::vpx_codec_get_cx_data_fn_t */ 313 vpx_codec_enc_config_set_fn_t cfg_set; /**< \copydoc ::vpx_codec_enc_config_set_fn_t */ 314 vpx_codec_get_global_headers_fn_t get_glob_hdrs; /**< \copydoc ::vpx_codec_get_global_headers_fn_t */ 315 vpx_codec_get_preview_frame_fn_t get_preview; /**< \copydoc ::vpx_codec_get_preview_frame_fn_t */ 316 vpx_codec_enc_mr_get_mem_loc_fn_t mr_get_mem_loc; /**< \copydoc ::vpx_codec_enc_mr_get_mem_loc_fn_t */ 317 } enc; 318 }; 319 320 /*!\brief Callback function pointer / user data pair storage */ 321 typedef struct vpx_codec_priv_cb_pair { 322 union { 323 vpx_codec_put_frame_cb_fn_t put_frame; 324 vpx_codec_put_slice_cb_fn_t put_slice; 325 } u; 326 void *user_priv; 327 } vpx_codec_priv_cb_pair_t; 328 329 330 /*!\brief Instance private storage 331 * 332 * This structure is allocated by the algorithm's init function. It can be 333 * extended in one of two ways. First, a second, algorithm specific structure 334 * can be allocated and the priv member pointed to it. Alternatively, this 335 * structure can be made the first member of the algorithm specific structure, 336 * and the pointer cast to the proper type. 337 */ 338 struct vpx_codec_priv { 339 unsigned int sz; 340 vpx_codec_iface_t *iface; 341 struct vpx_codec_alg_priv *alg_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 int tbd; 350 struct vpx_fixed_buf cx_data_dst_buf; 351 unsigned int cx_data_pad_before; 352 unsigned int cx_data_pad_after; 353 vpx_codec_cx_pkt_t cx_data_pkt; 354 unsigned int total_encoders; 355 } enc; 356 }; 357 358 /* 359 * Multi-resolution encoding internal configuration 360 */ 361 struct vpx_codec_priv_enc_mr_cfg 362 { 363 unsigned int mr_total_resolutions; 364 unsigned int mr_encoder_id; 365 struct vpx_rational mr_down_sampling_factor; 366 void* mr_low_res_mode_info; 367 }; 368 369 #undef VPX_CTRL_USE_TYPE 370 #define VPX_CTRL_USE_TYPE(id, typ) \ 371 static typ id##__value(va_list args) {return va_arg(args, typ);} \ 372 static typ id##__convert(void *x)\ 373 {\ 374 union\ 375 {\ 376 void *x;\ 377 typ d;\ 378 } u;\ 379 u.x = x;\ 380 return u.d;\ 381 } 382 383 384 #undef VPX_CTRL_USE_TYPE_DEPRECATED 385 #define VPX_CTRL_USE_TYPE_DEPRECATED(id, typ) \ 386 static typ id##__value(va_list args) {return va_arg(args, typ);} \ 387 static typ id##__convert(void *x)\ 388 {\ 389 union\ 390 {\ 391 void *x;\ 392 typ d;\ 393 } u;\ 394 u.x = x;\ 395 return u.d;\ 396 } 397 398 #define CAST(id, arg) id##__value(arg) 399 #define RECAST(id, x) id##__convert(x) 400 401 402 /* CODEC_INTERFACE convenience macro 403 * 404 * By convention, each codec interface is a struct with extern linkage, where 405 * the symbol is suffixed with _algo. A getter function is also defined to 406 * return a pointer to the struct, since in some cases it's easier to work 407 * with text symbols than data symbols (see issue #169). This function has 408 * the same name as the struct, less the _algo suffix. The CODEC_INTERFACE 409 * macro is provided to define this getter function automatically. 410 */ 411 #define CODEC_INTERFACE(id)\ 412 vpx_codec_iface_t* id(void) { return &id##_algo; }\ 413 vpx_codec_iface_t id##_algo 414 415 416 /* Internal Utility Functions 417 * 418 * The following functions are intended to be used inside algorithms as 419 * utilities for manipulating vpx_codec_* data structures. 420 */ 421 struct vpx_codec_pkt_list { 422 unsigned int cnt; 423 unsigned int max; 424 struct vpx_codec_cx_pkt pkts[1]; 425 }; 426 427 #define vpx_codec_pkt_list_decl(n)\ 428 union {struct vpx_codec_pkt_list head;\ 429 struct {struct vpx_codec_pkt_list head;\ 430 struct vpx_codec_cx_pkt pkts[n];} alloc;} 431 432 #define vpx_codec_pkt_list_init(m)\ 433 (m)->alloc.head.cnt = 0,\ 434 (m)->alloc.head.max = sizeof((m)->alloc.pkts) / sizeof((m)->alloc.pkts[0]) 435 436 int 437 vpx_codec_pkt_list_add(struct vpx_codec_pkt_list *, 438 const struct vpx_codec_cx_pkt *); 439 440 const vpx_codec_cx_pkt_t * 441 vpx_codec_pkt_list_get(struct vpx_codec_pkt_list *list, 442 vpx_codec_iter_t *iter); 443 444 445 #include <stdio.h> 446 #include <setjmp.h> 447 struct vpx_internal_error_info { 448 vpx_codec_err_t error_code; 449 int has_detail; 450 char detail[80]; 451 int setjmp; 452 jmp_buf jmp; 453 }; 454 455 static void vpx_internal_error(struct vpx_internal_error_info *info, 456 vpx_codec_err_t error, 457 const char *fmt, 458 ...) { 459 va_list ap; 460 461 info->error_code = error; 462 info->has_detail = 0; 463 464 if (fmt) { 465 size_t sz = sizeof(info->detail); 466 467 info->has_detail = 1; 468 va_start(ap, fmt); 469 vsnprintf(info->detail, sz - 1, fmt, ap); 470 va_end(ap); 471 info->detail[sz - 1] = '\0'; 472 } 473 474 if (info->setjmp) 475 longjmp(info->jmp, info->error_code); 476 } 477 478 //------------------------------------------------------------------------------ 479 // mmap interface 480 481 typedef struct { 482 unsigned int id; 483 unsigned long sz; 484 unsigned int align; 485 unsigned int flags; 486 unsigned long (*calc_sz)(const vpx_codec_dec_cfg_t *, vpx_codec_flags_t); 487 } mem_req_t; 488 489 // Allocates mmap.priv and sets mmap.base based on mmap.sz/align/flags 490 // requirements. 491 // Returns #VPX_CODEC_OK on success, #VPX_CODEC_MEM_ERROR otherwise. 492 vpx_codec_err_t vpx_mmap_alloc(vpx_codec_mmap_t *mmap); 493 494 // Frees mmap.base allocated by a call to vpx_mmap_alloc(). 495 void vpx_mmap_dtor(vpx_codec_mmap_t *mmap); 496 497 // Checks each mmap has the size requirement specificied by mem_reqs. 498 // Returns #VPX_CODEC_OK on success, #VPX_CODEC_MEM_ERROR otherwise. 499 vpx_codec_err_t vpx_validate_mmaps(const vpx_codec_stream_info_t *si, 500 const vpx_codec_mmap_t *mmaps, 501 const mem_req_t *mem_reqs, int nreqs, 502 vpx_codec_flags_t init_flags); 503 #endif 504
