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