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_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 * res = vpx_codec_init(&algo, &my_codec); 37 * } 38 * </pre> 39 * 40 * Once initialized, the instance is manged using other functions from 41 * the vpx_codec_* family. 42 */ 43 #ifndef VPX_VPX_INTERNAL_VPX_CODEC_INTERNAL_H_ 44 #define VPX_VPX_INTERNAL_VPX_CODEC_INTERNAL_H_ 45 46 #define INLINE __inline 47 48 #include <stdint.h> 49 #include "prob.h" 50 #include "vpx_codec.h" 51 52 #ifdef __cplusplus 53 extern "C" { 54 #endif 55 56 /*!\brief Current ABI version number 57 * 58 * \internal 59 * If this file is altered in any way that changes the ABI, this value 60 * must be bumped. Examples include, but are not limited to, changing 61 * types, removing or reassigning enums, adding/removing/rearranging 62 * fields to structures 63 */ 64 #define VPX_CODEC_INTERNAL_ABI_VERSION (5) /**<\hideinitializer*/ 65 66 typedef struct vpx_codec_alg_priv vpx_codec_alg_priv_t; 67 typedef struct vpx_codec_priv_enc_mr_cfg vpx_codec_priv_enc_mr_cfg_t; 68 #if 0 69 /*!\brief init function pointer prototype 70 * 71 * Performs algorithm-specific initialization of the decoder context. This 72 * function is called by the generic vpx_codec_init() wrapper function, so 73 * plugins implementing this interface may trust the input parameters to be 74 * properly initialized. 75 * 76 * \param[in] ctx Pointer to this instance's context 77 * \retval #VPX_CODEC_OK 78 * The input stream was recognized and decoder initialized. 79 * \retval #VPX_CODEC_MEM_ERROR 80 * Memory operation failed. 81 */ 82 typedef vpx_codec_err_t (*vpx_codec_init_fn_t)( 83 vpx_codec_ctx_t *ctx, vpx_codec_priv_enc_mr_cfg_t *data); 84 85 /*!\brief destroy function pointer prototype 86 * 87 * Performs algorithm-specific destruction of the decoder context. This 88 * function is called by the generic vpx_codec_destroy() wrapper function, 89 * so plugins implementing this interface may trust the input parameters 90 * to be properly initialized. 91 * 92 * \param[in] ctx Pointer to this instance's context 93 * \retval #VPX_CODEC_OK 94 * The input stream was recognized and decoder initialized. 95 * \retval #VPX_CODEC_MEM_ERROR 96 * Memory operation failed. 97 */ 98 typedef vpx_codec_err_t (*vpx_codec_destroy_fn_t)(vpx_codec_alg_priv_t *ctx); 99 100 /*!\brief parse stream info function pointer prototype 101 * 102 * Performs high level parsing of the bitstream. This function is called by the 103 * generic vpx_codec_peek_stream_info() wrapper function, so plugins 104 * implementing this interface may trust the input parameters to be properly 105 * initialized. 106 * 107 * \param[in] data Pointer to a block of data to parse 108 * \param[in] data_sz Size of the data buffer 109 * \param[in,out] si Pointer to stream info to update. The size member 110 * \ref MUST be properly initialized, but \ref MAY be 111 * clobbered by the algorithm. This parameter \ref MAY 112 * be NULL. 113 * 114 * \retval #VPX_CODEC_OK 115 * Bitstream is parsable and stream information updated 116 */ 117 typedef vpx_codec_err_t (*vpx_codec_peek_si_fn_t)(const uint8_t *data, 118 unsigned int data_sz, 119 vpx_codec_stream_info_t *si); 120 121 /*!\brief Return information about the current stream. 122 * 123 * Returns information about the stream that has been parsed during decoding. 124 * 125 * \param[in] ctx Pointer to this instance's context 126 * \param[in,out] si Pointer to stream info to update. The size member 127 * \ref MUST be properly initialized, but \ref MAY be 128 * clobbered by the algorithm. This parameter \ref MAY 129 * be NULL. 130 * 131 * \retval #VPX_CODEC_OK 132 * Bitstream is parsable and stream information updated 133 */ 134 typedef vpx_codec_err_t (*vpx_codec_get_si_fn_t)(vpx_codec_alg_priv_t *ctx, 135 vpx_codec_stream_info_t *si); 136 137 /*!\brief control function pointer prototype 138 * 139 * This function is used to exchange algorithm specific data with the decoder 140 * instance. This can be used to implement features specific to a particular 141 * algorithm. 142 * 143 * This function is called by the generic vpx_codec_control() wrapper 144 * function, so plugins implementing this interface may trust the input 145 * parameters to be properly initialized. However, this interface does not 146 * provide type safety for the exchanged data or assign meanings to the 147 * control codes. Those details should be specified in the algorithm's 148 * header file. In particular, the ctrl_id parameter is guaranteed to exist 149 * in the algorithm's control mapping table, and the data parameter may be NULL. 150 * 151 * 152 * \param[in] ctx Pointer to this instance's context 153 * \param[in] ctrl_id Algorithm specific control identifier 154 * \param[in,out] data Data to exchange with algorithm instance. 155 * 156 * \retval #VPX_CODEC_OK 157 * The internal state data was deserialized. 158 */ 159 typedef vpx_codec_err_t (*vpx_codec_control_fn_t)(vpx_codec_alg_priv_t *ctx, 160 va_list ap); 161 162 /*!\brief control function pointer mapping 163 * 164 * This structure stores the mapping between control identifiers and 165 * implementing functions. Each algorithm provides a list of these 166 * mappings. This list is searched by the vpx_codec_control() wrapper 167 * function to determine which function to invoke. The special 168 * value {0, NULL} is used to indicate end-of-list, and must be 169 * present. The special value {0, <non-null>} can be used as a catch-all 170 * mapping. This implies that ctrl_id values chosen by the algorithm 171 * \ref MUST be non-zero. 172 */ 173 typedef const struct vpx_codec_ctrl_fn_map { 174 int ctrl_id; 175 vpx_codec_control_fn_t fn; 176 } vpx_codec_ctrl_fn_map_t; 177 178 /*!\brief decode data function pointer prototype 179 * 180 * Processes a buffer of coded data. If the processing results in a new 181 * decoded frame becoming available, #VPX_CODEC_CB_PUT_SLICE and 182 * #VPX_CODEC_CB_PUT_FRAME events are generated as appropriate. This 183 * function is called by the generic vpx_codec_decode() wrapper function, 184 * so plugins implementing this interface may trust the input parameters 185 * 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, a #VPX_CODEC_CB_PUT_FRAME event is posted 190 * for 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 long deadline); 203 204 /*!\brief Decoded frames iterator 205 * 206 * Iterates over a list of the frames available for display. The iterator 207 * storage should be initialized to NULL to start the iteration. Iteration is 208 * complete when this function returns NULL. 209 * 210 * The list of available frames becomes valid upon completion of the 211 * vpx_codec_decode call, and remains valid until the next call to 212 * vpx_codec_decode. 213 * 214 * \param[in] ctx Pointer to this instance's context 215 * \param[in out] iter Iterator storage, initialized to NULL 216 * 217 * \return Returns a pointer to an image, if one is ready for display. Frames 218 * produced will always be in PTS (presentation time stamp) order. 219 */ 220 typedef vpx_image_t *(*vpx_codec_get_frame_fn_t)(vpx_codec_alg_priv_t *ctx, 221 vpx_codec_iter_t *iter); 222 223 /*!\brief Pass in external frame buffers for the decoder to use. 224 * 225 * Registers functions to be called when libvpx needs a frame buffer 226 * to decode the current frame and a function to be called when libvpx does 227 * not internally reference the frame buffer. This set function must 228 * be called before the first call to decode or libvpx will assume the 229 * default behavior of allocating frame buffers internally. 230 * 231 * \param[in] ctx Pointer to this instance's context 232 * \param[in] cb_get Pointer to the get callback function 233 * \param[in] cb_release Pointer to the release callback function 234 * \param[in] cb_priv Callback's private data 235 * 236 * \retval #VPX_CODEC_OK 237 * External frame buffers will be used by libvpx. 238 * \retval #VPX_CODEC_INVALID_PARAM 239 * One or more of the callbacks were NULL. 240 * \retval #VPX_CODEC_ERROR 241 * Decoder context not initialized, or algorithm not capable of 242 * using external frame buffers. 243 * 244 * \note 245 * When decoding VP9, the application may be required to pass in at least 246 * #VP9_MAXIMUM_REF_BUFFERS + #VPX_MAXIMUM_WORK_BUFFERS external frame 247 * buffers. 248 */ 249 typedef vpx_codec_err_t (*vpx_codec_set_fb_fn_t)( 250 vpx_codec_alg_priv_t *ctx, vpx_get_frame_buffer_cb_fn_t cb_get, 251 vpx_release_frame_buffer_cb_fn_t cb_release, void *cb_priv); 252 253 typedef vpx_codec_err_t (*vpx_codec_encode_fn_t)(vpx_codec_alg_priv_t *ctx, 254 const vpx_image_t *img, 255 vpx_codec_pts_t pts, 256 unsigned long duration, 257 vpx_enc_frame_flags_t flags, 258 unsigned long deadline); 259 typedef const vpx_codec_cx_pkt_t *(*vpx_codec_get_cx_data_fn_t)( 260 vpx_codec_alg_priv_t *ctx, vpx_codec_iter_t *iter); 261 262 typedef vpx_codec_err_t (*vpx_codec_enc_config_set_fn_t)( 263 vpx_codec_alg_priv_t *ctx, const vpx_codec_enc_cfg_t *cfg); 264 typedef vpx_fixed_buf_t *(*vpx_codec_get_global_headers_fn_t)( 265 vpx_codec_alg_priv_t *ctx); 266 267 typedef vpx_image_t *(*vpx_codec_get_preview_frame_fn_t)( 268 vpx_codec_alg_priv_t *ctx); 269 270 typedef vpx_codec_err_t (*vpx_codec_enc_mr_get_mem_loc_fn_t)( 271 const vpx_codec_enc_cfg_t *cfg, 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 /*!\brief Decoder algorithm interface interface 289 * 290 * All decoders \ref MUST expose a variable of this type. 291 */ 292 struct vpx_codec_iface { 293 const char *name; /**< Identification String */ 294 int abi_version; /**< Implemented ABI version */ 295 vpx_codec_caps_t caps; /**< Decoder capabilities */ 296 vpx_codec_init_fn_t init; /**< \copydoc ::vpx_codec_init_fn_t */ 297 vpx_codec_destroy_fn_t destroy; /**< \copydoc ::vpx_codec_destroy_fn_t */ 298 vpx_codec_ctrl_fn_map_t *ctrl_maps; /**< \copydoc ::vpx_codec_ctrl_fn_map_t */ 299 struct vpx_codec_dec_iface { 300 vpx_codec_peek_si_fn_t peek_si; /**< \copydoc ::vpx_codec_peek_si_fn_t */ 301 vpx_codec_get_si_fn_t get_si; /**< \copydoc ::vpx_codec_get_si_fn_t */ 302 vpx_codec_decode_fn_t decode; /**< \copydoc ::vpx_codec_decode_fn_t */ 303 vpx_codec_get_frame_fn_t 304 get_frame; /**< \copydoc ::vpx_codec_get_frame_fn_t */ 305 vpx_codec_set_fb_fn_t set_fb_fn; /**< \copydoc ::vpx_codec_set_fb_fn_t */ 306 } dec; 307 struct vpx_codec_enc_iface { 308 int cfg_map_count; 309 vpx_codec_enc_cfg_map_t 310 *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 313 get_cx_data; /**< \copydoc ::vpx_codec_get_cx_data_fn_t */ 314 vpx_codec_enc_config_set_fn_t 315 cfg_set; /**< \copydoc ::vpx_codec_enc_config_set_fn_t */ 316 vpx_codec_get_global_headers_fn_t 317 get_glob_hdrs; /**< \copydoc ::vpx_codec_get_global_headers_fn_t */ 318 vpx_codec_get_preview_frame_fn_t 319 get_preview; /**< \copydoc ::vpx_codec_get_preview_frame_fn_t */ 320 vpx_codec_enc_mr_get_mem_loc_fn_t 321 mr_get_mem_loc; /**< \copydoc ::vpx_codec_enc_mr_get_mem_loc_fn_t */ 322 } enc; 323 }; 324 325 /*!\brief Callback function pointer / user data pair storage */ 326 typedef struct vpx_codec_priv_cb_pair { 327 union { 328 vpx_codec_put_frame_cb_fn_t put_frame; 329 vpx_codec_put_slice_cb_fn_t put_slice; 330 } u; 331 void *user_priv; 332 } vpx_codec_priv_cb_pair_t; 333 334 /*!\brief Instance private storage 335 * 336 * This structure is allocated by the algorithm's init function. It can be 337 * extended in one of two ways. First, a second, algorithm specific structure 338 * can be allocated and the priv member pointed to it. Alternatively, this 339 * structure can be made the first member of the algorithm specific structure, 340 * and the pointer cast to the proper type. 341 */ 342 struct vpx_codec_priv { 343 const char *err_detail; 344 vpx_codec_flags_t init_flags; 345 struct { 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 vpx_fixed_buf_t 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 unsigned int mr_total_resolutions; 363 unsigned int mr_encoder_id; 364 struct vpx_rational mr_down_sampling_factor; 365 void *mr_low_res_mode_info; 366 }; 367 368 #undef VPX_CTRL_USE_TYPE 369 #define VPX_CTRL_USE_TYPE(id, typ) \ 370 static VPX_INLINE typ id##__value(va_list args) { return va_arg(args, typ); } 371 372 #undef VPX_CTRL_USE_TYPE_DEPRECATED 373 #define VPX_CTRL_USE_TYPE_DEPRECATED(id, typ) \ 374 static VPX_INLINE typ id##__value(va_list args) { return va_arg(args, typ); } 375 376 #define CAST(id, arg) id##__value(arg) 377 378 /* CODEC_INTERFACE convenience macro 379 * 380 * By convention, each codec interface is a struct with extern linkage, where 381 * the symbol is suffixed with _algo. A getter function is also defined to 382 * return a pointer to the struct, since in some cases it's easier to work 383 * with text symbols than data symbols (see issue #169). This function has 384 * the same name as the struct, less the _algo suffix. The CODEC_INTERFACE 385 * macro is provided to define this getter function automatically. 386 */ 387 #define CODEC_INTERFACE(id) \ 388 vpx_codec_iface_t *id(void) { return &id##_algo; } \ 389 vpx_codec_iface_t id##_algo 390 391 /* Internal Utility Functions 392 * 393 * The following functions are intended to be used inside algorithms as 394 * utilities for manipulating vpx_codec_* data structures. 395 */ 396 struct vpx_codec_pkt_list { 397 unsigned int cnt; 398 unsigned int max; 399 struct vpx_codec_cx_pkt pkts[1]; 400 }; 401 402 #define vpx_codec_pkt_list_decl(n) \ 403 union { \ 404 struct vpx_codec_pkt_list head; \ 405 struct { \ 406 struct vpx_codec_pkt_list head; \ 407 struct vpx_codec_cx_pkt pkts[n]; \ 408 } alloc; \ 409 } 410 411 #define vpx_codec_pkt_list_init(m) \ 412 (m)->alloc.head.cnt = 0, \ 413 (m)->alloc.head.max = sizeof((m)->alloc.pkts) / sizeof((m)->alloc.pkts[0]) 414 415 int vpx_codec_pkt_list_add(struct vpx_codec_pkt_list *, 416 const struct vpx_codec_cx_pkt *); 417 418 const vpx_codec_cx_pkt_t *vpx_codec_pkt_list_get( 419 struct vpx_codec_pkt_list *list, vpx_codec_iter_t *iter); 420 #endif 421 #include <stdio.h> 422 #include <setjmp.h> 423 #if 0 424 struct vpx_internal_error_info { 425 vpx_codec_err_t error_code; 426 int has_detail; 427 char detail[80]; 428 int setjmp; 429 jmp_buf jmp; 430 }; 431 #endif 432 433 #define CLANG_ANALYZER_NORETURN 434 #if defined(__has_feature) 435 #if __has_feature(attribute_analyzer_noreturn) 436 #undef CLANG_ANALYZER_NORETURN 437 #define CLANG_ANALYZER_NORETURN __attribute__((analyzer_noreturn)) 438 #endif 439 #endif 440 #if 0 441 void vpx_internal_error(struct vpx_internal_error_info *info, 442 vpx_codec_err_t error, const char *fmt, 443 ...) CLANG_ANALYZER_NORETURN; 444 #endif 445 #ifdef __cplusplus 446 } // extern "C" 447 #endif 448 449 #endif // VPX_VPX_INTERNAL_VPX_CODEC_INTERNAL_H_ 450