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 (3) /**<\hideinitializer*/ 60 61 typedef struct vpx_codec_alg_priv vpx_codec_alg_priv_t; 62 63 /*!\brief init function pointer prototype 64 * 65 * Performs algorithm-specific initialization of the decoder context. This 66 * function is called by the generic vpx_codec_init() wrapper function, so 67 * plugins implementing this interface may trust the input parameters to be 68 * properly initialized. 69 * 70 * \param[in] ctx Pointer to this instance's context 71 * \retval #VPX_CODEC_OK 72 * The input stream was recognized and decoder initialized. 73 * \retval #VPX_CODEC_MEM_ERROR 74 * Memory operation failed. 75 */ 76 typedef vpx_codec_err_t (*vpx_codec_init_fn_t)(vpx_codec_ctx_t *ctx); 77 78 /*!\brief destroy function pointer prototype 79 * 80 * Performs algorithm-specific destruction of the decoder context. This 81 * function is called by the generic vpx_codec_destroy() wrapper function, 82 * so plugins implementing this interface may trust the input parameters 83 * to be properly initialized. 84 * 85 * \param[in] ctx Pointer to this instance's context 86 * \retval #VPX_CODEC_OK 87 * The input stream was recognized and decoder initialized. 88 * \retval #VPX_CODEC_MEM_ERROR 89 * Memory operation failed. 90 */ 91 typedef vpx_codec_err_t (*vpx_codec_destroy_fn_t)(vpx_codec_alg_priv_t *ctx); 92 93 /*!\brief parse stream info function pointer prototype 94 * 95 * Performs high level parsing of the bitstream. This function is called by 96 * the generic vpx_codec_parse_stream() wrapper function, so plugins implementing 97 * this interface may trust the input parameters to be properly initialized. 98 * 99 * \param[in] data Pointer to a block of data to parse 100 * \param[in] data_sz Size of the data buffer 101 * \param[in,out] si Pointer to stream info to update. The size member 102 * \ref MUST be properly initialized, but \ref MAY be 103 * clobbered by the algorithm. This parameter \ref MAY 104 * be NULL. 105 * 106 * \retval #VPX_CODEC_OK 107 * Bitstream is parsable and stream information updated 108 */ 109 typedef vpx_codec_err_t (*vpx_codec_peek_si_fn_t)(const uint8_t *data, 110 unsigned int data_sz, 111 vpx_codec_stream_info_t *si); 112 113 /*!\brief Return information about the current stream. 114 * 115 * Returns information about the stream that has been parsed during decoding. 116 * 117 * \param[in] ctx Pointer to this instance's context 118 * \param[in,out] si Pointer to stream info to update. The size member 119 * \ref MUST be properly initialized, but \ref MAY be 120 * clobbered by the algorithm. This parameter \ref MAY 121 * be NULL. 122 * 123 * \retval #VPX_CODEC_OK 124 * Bitstream is parsable and stream information updated 125 */ 126 typedef vpx_codec_err_t (*vpx_codec_get_si_fn_t)(vpx_codec_alg_priv_t *ctx, 127 vpx_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 vpx_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 codes. 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 #VPX_CODEC_OK 149 * The internal state data was deserialized. 150 */ 151 typedef vpx_codec_err_t (*vpx_codec_control_fn_t)(vpx_codec_alg_priv_t *ctx, 152 int ctrl_id, 153 va_list ap); 154 155 /*!\brief control function pointer mapping 156 * 157 * This structure stores the mapping between control identifiers and 158 * implementing functions. Each algorithm provides a list of these 159 * mappings. This list is searched by the vpx_codec_control() wrapper 160 * function to determine which function to invoke. The special 161 * value {0, NULL} is used to indicate end-of-list, and must be 162 * present. The special value {0, <non-null>} can be used as a catch-all 163 * mapping. This implies that ctrl_id values chosen by the algorithm 164 * \ref MUST be non-zero. 165 */ 166 typedef const struct 167 { 168 int ctrl_id; 169 vpx_codec_control_fn_t fn; 170 } vpx_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, #VPX_CODEC_CB_PUT_SLICE and 176 * #VPX_CODEC_CB_PUT_FRAME events are generated as appropriate. This 177 * function is called by the generic vpx_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 #VPX_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 #VPX_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 ::vpx_codec_err_t 190 * for recoverability capabilities. 191 */ 192 typedef vpx_codec_err_t (*vpx_codec_decode_fn_t)(vpx_codec_alg_priv_t *ctx, 193 const uint8_t *data, 194 unsigned int data_sz, 195 void *user_priv, 196 long deadline); 197 198 /*!\brief Decoded frames iterator 199 * 200 * Iterates over a list of the frames available for display. The iterator 201 * storage should be initialized to NULL to start the iteration. Iteration is 202 * complete when this function returns NULL. 203 * 204 * The list of available frames becomes valid upon completion of the 205 * vpx_codec_decode call, and remains valid until the next call to vpx_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 vpx_image_t*(*vpx_codec_get_frame_fn_t)(vpx_codec_alg_priv_t *ctx, 214 vpx_codec_iter_t *iter); 215 216 217 /*\brief eXternal Memory Allocation memory map get iterator 218 * 219 * Iterates over a list of the memory maps requested by the decoder. The 220 * iterator storage should be initialized to NULL to start the iteration. 221 * Iteration is complete when this function returns NULL. 222 * 223 * \param[in out] iter Iterator storage, initialized to NULL 224 * 225 * \return Returns a pointer to an memory segment descriptor, or NULL to 226 * indicate end-of-list. 227 */ 228 typedef vpx_codec_err_t (*vpx_codec_get_mmap_fn_t)(const vpx_codec_ctx_t *ctx, 229 vpx_codec_mmap_t *mmap, 230 vpx_codec_iter_t *iter); 231 232 233 /*\brief eXternal Memory Allocation memory map set iterator 234 * 235 * Sets a memory descriptor inside the decoder instance. 236 * 237 * \param[in] ctx Pointer to this instance's context 238 * \param[in] mmap Memory map to store. 239 * 240 * \retval #VPX_CODEC_OK 241 * The memory map was accepted and stored. 242 * \retval #VPX_CODEC_MEM_ERROR 243 * The memory map was rejected. 244 */ 245 typedef vpx_codec_err_t (*vpx_codec_set_mmap_fn_t)(vpx_codec_ctx_t *ctx, 246 const vpx_codec_mmap_t *mmap); 247 248 249 typedef vpx_codec_err_t (*vpx_codec_encode_fn_t)(vpx_codec_alg_priv_t *ctx, 250 const vpx_image_t *img, 251 vpx_codec_pts_t pts, 252 unsigned long duration, 253 vpx_enc_frame_flags_t flags, 254 unsigned long deadline); 255 typedef const vpx_codec_cx_pkt_t*(*vpx_codec_get_cx_data_fn_t)(vpx_codec_alg_priv_t *ctx, 256 vpx_codec_iter_t *iter); 257 258 typedef vpx_codec_err_t 259 (*vpx_codec_enc_config_set_fn_t)(vpx_codec_alg_priv_t *ctx, 260 const vpx_codec_enc_cfg_t *cfg); 261 typedef vpx_fixed_buf_t * 262 (*vpx_codec_get_global_headers_fn_t)(vpx_codec_alg_priv_t *ctx); 263 264 typedef vpx_image_t * 265 (*vpx_codec_get_preview_frame_fn_t)(vpx_codec_alg_priv_t *ctx); 266 267 /*!\brief usage configuration mapping 268 * 269 * This structure stores the mapping between usage identifiers and 270 * configuration structures. Each algorithm provides a list of these 271 * mappings. This list is searched by the vpx_codec_enc_config_default() 272 * wrapper function to determine which config to return. The special value 273 * {-1, {0}} is used to indicate end-of-list, and must be present. At least 274 * one mapping must be present, in addition to the end-of-list. 275 * 276 */ 277 typedef const struct 278 { 279 int usage; 280 vpx_codec_enc_cfg_t cfg; 281 } vpx_codec_enc_cfg_map_t; 282 283 #define NOT_IMPLEMENTED 0 284 285 /*!\brief Decoder algorithm interface interface 286 * 287 * All decoders \ref MUST expose a variable of this type. 288 */ 289 struct vpx_codec_iface 290 { 291 const char *name; /**< Identification String */ 292 int abi_version; /**< Implemented ABI version */ 293 vpx_codec_caps_t caps; /**< Decoder capabilities */ 294 vpx_codec_init_fn_t init; /**< \copydoc ::vpx_codec_init_fn_t */ 295 vpx_codec_destroy_fn_t destroy; /**< \copydoc ::vpx_codec_destroy_fn_t */ 296 vpx_codec_ctrl_fn_map_t *ctrl_maps; /**< \copydoc ::vpx_codec_ctrl_fn_map_t */ 297 vpx_codec_get_mmap_fn_t get_mmap; /**< \copydoc ::vpx_codec_get_mmap_fn_t */ 298 vpx_codec_set_mmap_fn_t set_mmap; /**< \copydoc ::vpx_codec_set_mmap_fn_t */ 299 struct 300 { 301 vpx_codec_peek_si_fn_t peek_si; /**< \copydoc ::vpx_codec_peek_si_fn_t */ 302 vpx_codec_get_si_fn_t get_si; /**< \copydoc ::vpx_codec_peek_si_fn_t */ 303 vpx_codec_decode_fn_t decode; /**< \copydoc ::vpx_codec_decode_fn_t */ 304 vpx_codec_get_frame_fn_t get_frame; /**< \copydoc ::vpx_codec_get_frame_fn_t */ 305 } dec; 306 struct 307 { 308 vpx_codec_enc_cfg_map_t *cfg_maps; /**< \copydoc ::vpx_codec_enc_cfg_map_t */ 309 vpx_codec_encode_fn_t encode; /**< \copydoc ::vpx_codec_encode_fn_t */ 310 vpx_codec_get_cx_data_fn_t get_cx_data; /**< \copydoc ::vpx_codec_get_cx_data_fn_t */ 311 vpx_codec_enc_config_set_fn_t cfg_set; /**< \copydoc ::vpx_codec_enc_config_set_fn_t */ 312 vpx_codec_get_global_headers_fn_t get_glob_hdrs; /**< \copydoc ::vpx_codec_enc_config_set_fn_t */ 313 vpx_codec_get_preview_frame_fn_t get_preview; /**< \copydoc ::vpx_codec_get_preview_frame_fn_t */ 314 } enc; 315 }; 316 317 /*!\brief Callback function pointer / user data pair storage */ 318 typedef struct vpx_codec_priv_cb_pair 319 { 320 union 321 { 322 vpx_codec_put_frame_cb_fn_t put_frame; 323 vpx_codec_put_slice_cb_fn_t put_slice; 324 } u; 325 void *user_priv; 326 } vpx_codec_priv_cb_pair_t; 327 328 329 /*!\brief Instance private storage 330 * 331 * This structure is allocated by the algorithm's init function. It can be 332 * extended in one of two ways. First, a second, algorithm specific structure 333 * can be allocated and the priv member pointed to it. Alternatively, this 334 * structure can be made the first member of the algorithm specific structure, 335 * and the pointer cast to the proper type. 336 */ 337 struct vpx_codec_priv 338 { 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 { 346 vpx_codec_priv_cb_pair_t put_frame_cb; 347 vpx_codec_priv_cb_pair_t put_slice_cb; 348 } dec; 349 struct 350 { 351 int tbd; 352 struct vpx_fixed_buf cx_data_dst_buf; 353 unsigned int cx_data_pad_before; 354 unsigned int cx_data_pad_after; 355 vpx_codec_cx_pkt_t cx_data_pkt; 356 } enc; 357 }; 358 359 #undef VPX_CTRL_USE_TYPE 360 #define VPX_CTRL_USE_TYPE(id, typ) \ 361 static typ id##__value(va_list args) {return va_arg(args, typ);} \ 362 static typ id##__convert(void *x)\ 363 {\ 364 union\ 365 {\ 366 void *x;\ 367 typ d;\ 368 } u;\ 369 u.x = x;\ 370 return u.d;\ 371 } 372 373 374 #undef VPX_CTRL_USE_TYPE_DEPRECATED 375 #define VPX_CTRL_USE_TYPE_DEPRECATED(id, typ) \ 376 static typ id##__value(va_list args) {return va_arg(args, typ);} \ 377 static typ id##__convert(void *x)\ 378 {\ 379 union\ 380 {\ 381 void *x;\ 382 typ d;\ 383 } u;\ 384 u.x = x;\ 385 return u.d;\ 386 } 387 388 #define CAST(id, arg) id##__value(arg) 389 #define RECAST(id, x) id##__convert(x) 390 391 392 /* CODEC_INTERFACE convenience macro 393 * 394 * By convention, each codec interface is a struct with extern linkage, where 395 * the symbol is suffixed with _algo. A getter function is also defined to 396 * return a pointer to the struct, since in some cases it's easier to work 397 * with text symbols than data symbols (see issue #169). This function has 398 * the same name as the struct, less the _algo suffix. The CODEC_INTERFACE 399 * macro is provided to define this getter function automatically. 400 */ 401 #define CODEC_INTERFACE(id)\ 402 vpx_codec_iface_t* id(void) { return &id##_algo; }\ 403 vpx_codec_iface_t id##_algo 404 405 406 /* Internal Utility Functions 407 * 408 * The following functions are intended to be used inside algorithms as 409 * utilities for manipulating vpx_codec_* data structures. 410 */ 411 struct vpx_codec_pkt_list 412 { 413 unsigned int cnt; 414 unsigned int max; 415 struct vpx_codec_cx_pkt pkts[1]; 416 }; 417 418 #define vpx_codec_pkt_list_decl(n)\ 419 union {struct vpx_codec_pkt_list head;\ 420 struct {struct vpx_codec_pkt_list head;\ 421 struct vpx_codec_cx_pkt pkts[n];} alloc;} 422 423 #define vpx_codec_pkt_list_init(m)\ 424 (m)->alloc.head.cnt = 0,\ 425 (m)->alloc.head.max = sizeof((m)->alloc.pkts) / sizeof((m)->alloc.pkts[0]) 426 427 int 428 vpx_codec_pkt_list_add(struct vpx_codec_pkt_list *, 429 const struct vpx_codec_cx_pkt *); 430 431 const vpx_codec_cx_pkt_t* 432 vpx_codec_pkt_list_get(struct vpx_codec_pkt_list *list, 433 vpx_codec_iter_t *iter); 434 435 436 #include <stdio.h> 437 #include <setjmp.h> 438 struct vpx_internal_error_info 439 { 440 vpx_codec_err_t error_code; 441 int has_detail; 442 char detail[80]; 443 int setjmp; 444 jmp_buf jmp; 445 }; 446 447 static void vpx_internal_error(struct vpx_internal_error_info *info, 448 vpx_codec_err_t error, 449 const char *fmt, 450 ...) 451 { 452 va_list ap; 453 454 info->error_code = error; 455 info->has_detail = 0; 456 457 if (fmt) 458 { 459 size_t sz = sizeof(info->detail); 460 461 info->has_detail = 1; 462 va_start(ap, fmt); 463 vsnprintf(info->detail, sz - 1, fmt, ap); 464 va_end(ap); 465 info->detail[sz-1] = '\0'; 466 } 467 468 if (info->setjmp) 469 longjmp(info->jmp, info->error_code); 470 } 471 #endif 472
