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 /*!\defgroup decoder Common Decoder Algorithm Interface 13 * This abstraction allows applications using this decoder to easily support 14 * multiple video formats with minimal code duplication. This section describes 15 * the interface common to all codecs. 16 * @{ 17 */ 18 19 /*!\file vpx_decoder_compat.h 20 * \brief Provides a compatibility layer between version 1 and 2 of this API. 21 * 22 * This interface has been deprecated. Only existing code should make use 23 * of this interface, and therefore, it is only thinly documented. Existing 24 * code should be ported to the vpx_codec_* API. 25 */ 26 #ifdef __cplusplus 27 extern "C" { 28 #endif 29 30 #ifndef VPX_DECODER_COMPAT_H 31 #define VPX_DECODER_COMPAT_H 32 33 /*!\brief Decoder algorithm return codes */ 34 typedef enum { 35 /*!\brief Operation completed without error */ 36 VPX_DEC_OK = VPX_CODEC_OK, 37 38 /*!\brief Unspecified error */ 39 VPX_DEC_ERROR = VPX_CODEC_ERROR, 40 41 /*!\brief Memory operation failed */ 42 VPX_DEC_MEM_ERROR = VPX_CODEC_MEM_ERROR, 43 44 /*!\brief ABI version mismatch */ 45 VPX_DEC_ABI_MISMATCH = VPX_CODEC_ABI_MISMATCH, 46 47 /*!\brief The given bitstream is not supported. 48 * 49 * The bitstream was unable to be parsed at the highest level. The decoder 50 * is unable to proceed. This error \ref SHOULD be treated as fatal to the 51 * stream. */ 52 VPX_DEC_UNSUP_BITSTREAM = VPX_CODEC_UNSUP_BITSTREAM, 53 54 /*!\brief Encoded bitstream uses an unsupported feature 55 * 56 * The decoder does not implement a feature required by the encoder. This 57 * return code should only be used for features that prevent future 58 * pictures from being properly decoded. This error \ref MAY be treated as 59 * fatal to the stream or \ref MAY be treated as fatal to the current GOP. 60 */ 61 VPX_DEC_UNSUP_FEATURE = VPX_CODEC_UNSUP_FEATURE, 62 63 /*!\brief The coded data for this stream is corrupt or incomplete 64 * 65 * There was a problem decoding the current frame. This return code 66 * should only be used for failures that prevent future pictures from 67 * being properly decoded. This error \ref MAY be treated as fatal to the 68 * stream or \ref MAY be treated as fatal to the current GOP. If decoding 69 * is continued for the current GOP, artifacts may be present. 70 */ 71 VPX_DEC_CORRUPT_FRAME = VPX_CODEC_CORRUPT_FRAME, 72 73 /*!\brief An application-supplied parameter is not valid. 74 * 75 */ 76 VPX_DEC_INVALID_PARAM = VPX_CODEC_INVALID_PARAM, 77 78 /*!\brief An iterator reached the end of list. 79 * 80 */ 81 VPX_DEC_LIST_END = VPX_CODEC_LIST_END, 82 83 } 84 vpx_dec_err_t; 85 86 /*! \brief Decoder capabilities bitfield 87 * 88 * Each decoder advertises the capabilities it supports as part of its 89 * ::vpx_dec_iface_t interface structure. Capabilities are extra interfaces 90 * or functionality, and are not required to be supported by a decoder. 91 * 92 * The available flags are specifiedby VPX_DEC_CAP_* defines. 93 */ 94 typedef int vpx_dec_caps_t; 95 #define VPX_DEC_CAP_PUT_SLICE 0x0001 /**< Will issue put_slice callbacks */ 96 #define VPX_DEC_CAP_PUT_FRAME 0x0002 /**< Will issue put_frame callbacks */ 97 #define VPX_DEC_CAP_XMA 0x0004 /**< Supports e_xternal Memory Allocation */ 98 99 /*!\brief Stream properties 100 * 101 * This structure is used to query or set properties of the decoded 102 * stream. Algorithms may extend this structure with data specific 103 * to their bitstream by setting the sz member appropriately. 104 */ 105 #if 1 106 typedef vpx_codec_stream_info_t vpx_dec_stream_info_t; 107 #else 108 typedef struct 109 { 110 unsigned int sz; /**< Size of this structure */ 111 unsigned int w; /**< Width (or 0 for unknown/default) */ 112 unsigned int h; /**< Height (or 0 for unknown/default) */ 113 unsigned int is_kf; /**< Current frame is a keyframe */ 114 } vpx_dec_stream_info_t; 115 #endif 116 117 118 /*!\brief Decoder interface structure. 119 * 120 * Contains function pointers and other data private to the decoder 121 * implementation. This structure is opaque to the application. 122 */ 123 typedef const struct vpx_codec_iface vpx_dec_iface_t; 124 typedef struct vpx_codec_priv vpx_dec_priv_t; 125 126 /*!\brief Iterator 127 * 128 * Opaque storage used for iterating over lists. 129 */ 130 typedef vpx_codec_iter_t vpx_dec_iter_t; 131 132 /*!\brief Decoder context structure 133 * 134 * All decoders \ref MUST support this context structure fully. In general, 135 * this data should be considered private to the decoder algorithm, and 136 * not be manipulated or examined by the calling application. Applications 137 * may reference the 'name' member to get a printable description of the 138 * algorithm. 139 */ 140 #if 1 141 typedef vpx_codec_ctx_t vpx_dec_ctx_t; 142 #else 143 typedef struct 144 { 145 const char *name; /**< Printable interface name */ 146 vpx_dec_iface_t *iface; /**< Interface pointers */ 147 vpx_dec_err_t err; /**< Last returned error */ 148 vpx_dec_priv_t *priv; /**< Algorithm private storage */ 149 } vpx_dec_ctx_t; 150 #endif 151 152 153 /*!\brief Return the build configuration 154 * 155 * Returns a printable string containing an encoded version of the build 156 * configuration. This may be useful to vpx support. 157 * 158 */ 159 const char *vpx_dec_build_config(void) DEPRECATED; 160 161 /*!\brief Return the name for a given interface 162 * 163 * Returns a human readable string for name of the given decoder interface. 164 * 165 * \param[in] iface Interface pointer 166 * 167 */ 168 const char *vpx_dec_iface_name(vpx_dec_iface_t *iface) DEPRECATED; 169 170 171 /*!\brief Convert error number to printable string 172 * 173 * Returns a human readable string for the last error returned by the 174 * algorithm. The returned error will be one line and will not contain 175 * any newline characters. 176 * 177 * 178 * \param[in] err Error number. 179 * 180 */ 181 const char *vpx_dec_err_to_string(vpx_dec_err_t err) DEPRECATED; 182 183 184 /*!\brief Retrieve error synopsis for decoder context 185 * 186 * Returns a human readable string for the last error returned by the 187 * algorithm. The returned error will be one line and will not contain 188 * any newline characters. 189 * 190 * 191 * \param[in] ctx Pointer to this instance's context. 192 * 193 */ 194 const char *vpx_dec_error(vpx_dec_ctx_t *ctx) DEPRECATED; 195 196 197 /*!\brief Retrieve detailed error information for decoder context 198 * 199 * Returns a human readable string providing detailed information about 200 * the last error. 201 * 202 * \param[in] ctx Pointer to this instance's context. 203 * 204 * \retval NULL 205 * No detailed information is available. 206 */ 207 const char *vpx_dec_error_detail(vpx_dec_ctx_t *ctx) DEPRECATED; 208 209 210 /* REQUIRED FUNCTIONS 211 * 212 * The following functions are required to be implemented for all decoders. 213 * They represent the base case functionality expected of all decoders. 214 */ 215 216 217 /*!\brief Initialize a decoder instance 218 * 219 * Initializes a decoder context using the given interface. Applications 220 * should call the vpx_dec_init convenience macro instead of this 221 * function directly, to ensure that the ABI version number parameter 222 * is properly initialized. 223 * 224 * \param[in] ctx Pointer to this instance's context. 225 * \param[in] iface Pointer to the alogrithm interface to use. 226 * \param[in] ver ABI version number. Must be set to 227 * VPX_DECODER_ABI_VERSION 228 * \retval #VPX_DEC_OK 229 * The decoder algorithm initialized. 230 * \retval #VPX_DEC_MEM_ERROR 231 * Memory allocation failed. 232 */ 233 vpx_dec_err_t vpx_dec_init_ver(vpx_dec_ctx_t *ctx, 234 vpx_dec_iface_t *iface, 235 int ver) DEPRECATED; 236 #define vpx_dec_init(ctx, iface) \ 237 vpx_dec_init_ver(ctx, iface, VPX_DECODER_ABI_VERSION) 238 239 240 /*!\brief Destroy a decoder instance 241 * 242 * Destroys a decoder context, freeing any associated memory buffers. 243 * 244 * \param[in] ctx Pointer to this instance's context 245 * 246 * \retval #VPX_DEC_OK 247 * The decoder algorithm initialized. 248 * \retval #VPX_DEC_MEM_ERROR 249 * Memory allocation failed. 250 */ 251 vpx_dec_err_t vpx_dec_destroy(vpx_dec_ctx_t *ctx) DEPRECATED; 252 253 254 /*!\brief Get the capabilities of an algorithm. 255 * 256 * Retrieves the capabliities bitfield from the algorithm's interface. 257 * 258 * \param[in] iface Pointer to the alogrithm interface 259 * 260 */ 261 vpx_dec_caps_t vpx_dec_get_caps(vpx_dec_iface_t *iface) DEPRECATED; 262 263 264 /*!\brief Parse stream info from a buffer 265 * 266 * Performs high level parsing of the bitstream. Construction of a decoder 267 * context is not necessary. Can be used to determine if the bitstream is 268 * of the proper format, and to extract information from the stream. 269 * 270 * \param[in] iface Pointer to the alogrithm interface 271 * \param[in] data Pointer to a block of data to parse 272 * \param[in] data_sz Size of the data buffer 273 * \param[in,out] si Pointer to stream info to update. The size member 274 * \ref MUST be properly initialized, but \ref MAY be 275 * clobbered by the algorithm. This parameter \ref MAY 276 * be NULL. 277 * 278 * \retval #VPX_DEC_OK 279 * Bitstream is parsable and stream information updated 280 */ 281 vpx_dec_err_t vpx_dec_peek_stream_info(vpx_dec_iface_t *iface, 282 const uint8_t *data, 283 unsigned int data_sz, 284 vpx_dec_stream_info_t *si) DEPRECATED; 285 286 287 /*!\brief Return information about the current stream. 288 * 289 * Returns information about the stream that has been parsed during decoding. 290 * 291 * \param[in] ctx Pointer to this instance's context 292 * \param[in,out] si Pointer to stream info to update. The size member 293 * \ref MUST be properly initialized, but \ref MAY be 294 * clobbered by the algorithm. This parameter \ref MAY 295 * be NULL. 296 * 297 * \retval #VPX_DEC_OK 298 * Bitstream is parsable and stream information updated 299 */ 300 vpx_dec_err_t vpx_dec_get_stream_info(vpx_dec_ctx_t *ctx, 301 vpx_dec_stream_info_t *si) DEPRECATED; 302 303 304 /*!\brief Control algorithm 305 * 306 * This function is used to exchange algorithm specific data with the decoder 307 * instance. This can be used to implement features specific to a particular 308 * algorithm. 309 * 310 * This wrapper function dispatches the request to the helper function 311 * associated with the given ctrl_id. It tries to call this function 312 * transparantly, but will return #VPX_DEC_ERROR if the request could not 313 * be dispatched. 314 * 315 * \param[in] ctx Pointer to this instance's context 316 * \param[in] ctrl_id Algorithm specific control identifier 317 * \param[in,out] data Data to exchange with algorithm instance. 318 * 319 * \retval #VPX_DEC_OK 320 * The control request was processed. 321 * \retval #VPX_DEC_ERROR 322 * The control request was not processed. 323 * \retval #VPX_DEC_INVALID_PARAM 324 * The data was not valid. 325 */ 326 vpx_dec_err_t vpx_dec_control(vpx_dec_ctx_t *ctx, 327 int ctrl_id, 328 void *data) DEPRECATED; 329 330 /*!\brief Decode data 331 * 332 * Processes a buffer of coded data. If the processing results in a new 333 * decoded frame becoming available, #VPX_DEC_CB_PUT_SLICE and 334 * #VPX_DEC_CB_PUT_FRAME events may be generated, as appropriate. Encoded data 335 * \ref MUST be passed in DTS (decode time stamp) order. Frames produced will 336 * always be in PTS (presentation time stamp) order. 337 * 338 * \param[in] ctx Pointer to this instance's context 339 * \param[in] data Pointer to this block of new coded data. If 340 * NULL, a VPX_DEC_CB_PUT_FRAME event is posted 341 * for the previously decoded frame. 342 * \param[in] data_sz Size of the coded data, in bytes. 343 * \param[in] user_priv Application specific data to associate with 344 * this frame. 345 * \param[in] rel_pts PTS relative to the previous frame, in us. If 346 * unknown or unavailable, set to zero. 347 * 348 * \return Returns #VPX_DEC_OK if the coded data was processed completely 349 * and future pictures can be decoded without error. Otherwise, 350 * see the descriptions of the other error codes in ::vpx_dec_err_t 351 * for recoverability capabilities. 352 */ 353 vpx_dec_err_t vpx_dec_decode(vpx_dec_ctx_t *ctx, 354 uint8_t *data, 355 unsigned int data_sz, 356 void *user_priv, 357 int rel_pts) DEPRECATED; 358 359 360 /*!\brief Decoded frames iterator 361 * 362 * Iterates over a list of the frames available for display. The iterator 363 * storage should be initialized to NULL to start the iteration. Iteration is 364 * complete when this function returns NULL. 365 * 366 * The list of available frames becomes valid upon completion of the 367 * vpx_dec_decode call, and remains valid until the next call to vpx_dec_decode. 368 * 369 * \param[in] ctx Pointer to this instance's context 370 * \param[in out] iter Iterator storage, initialized to NULL 371 * 372 * \return Returns a pointer to an image, if one is ready for display. Frames 373 * produced will always be in PTS (presentation time stamp) order. 374 */ 375 vpx_image_t *vpx_dec_get_frame(vpx_dec_ctx_t *ctx, 376 vpx_dec_iter_t *iter) DEPRECATED; 377 378 379 /*!\defgroup cap_put_frame Frame-Based Decoding Functions 380 * 381 * The following functions are required to be implemented for all decoders 382 * that advertise the VPX_DEC_CAP_PUT_FRAME capability. Calling these functions 383 * for codecs that don't advertise this capability will result in an error 384 * code being returned, usually VPX_DEC_ERROR 385 * @{ 386 */ 387 388 /*!\brief put frame callback prototype 389 * 390 * This callback is invoked by the decoder to notify the application of 391 * the availability of decoded image data. 392 */ 393 typedef void (*vpx_dec_put_frame_cb_fn_t)(void *user_priv, 394 const vpx_image_t *img); 395 396 397 /*!\brief Register for notification of frame completion. 398 * 399 * Registers a given function to be called when a decoded frame is 400 * available. 401 * 402 * \param[in] ctx Pointer to this instance's context 403 * \param[in] cb Pointer to the callback function 404 * \param[in] user_priv User's private data 405 * 406 * \retval #VPX_DEC_OK 407 * Callback successfully registered. 408 * \retval #VPX_DEC_ERROR 409 * Decoder context not initialized, or algorithm not capable of 410 * posting slice completion. 411 */ 412 vpx_dec_err_t vpx_dec_register_put_frame_cb(vpx_dec_ctx_t *ctx, 413 vpx_dec_put_frame_cb_fn_t cb, 414 void *user_priv) DEPRECATED; 415 416 417 /*!@} - end defgroup cap_put_frame */ 418 419 /*!\defgroup cap_put_slice Slice-Based Decoding Functions 420 * 421 * The following functions are required to be implemented for all decoders 422 * that advertise the VPX_DEC_CAP_PUT_SLICE capability. Calling these functions 423 * for codecs that don't advertise this capability will result in an error 424 * code being returned, usually VPX_DEC_ERROR 425 * @{ 426 */ 427 428 /*!\brief put slice callback prototype 429 * 430 * This callback is invoked by the decoder to notify the application of 431 * the availability of partially decoded image data. The 432 */ 433 typedef void (*vpx_dec_put_slice_cb_fn_t)(void *user_priv, 434 const vpx_image_t *img, 435 const vpx_image_rect_t *valid, 436 const vpx_image_rect_t *update); 437 438 439 /*!\brief Register for notification of slice completion. 440 * 441 * Registers a given function to be called when a decoded slice is 442 * available. 443 * 444 * \param[in] ctx Pointer to this instance's context 445 * \param[in] cb Pointer to the callback function 446 * \param[in] user_priv User's private data 447 * 448 * \retval #VPX_DEC_OK 449 * Callback successfully registered. 450 * \retval #VPX_DEC_ERROR 451 * Decoder context not initialized, or algorithm not capable of 452 * posting slice completion. 453 */ 454 vpx_dec_err_t vpx_dec_register_put_slice_cb(vpx_dec_ctx_t *ctx, 455 vpx_dec_put_slice_cb_fn_t cb, 456 void *user_priv) DEPRECATED; 457 458 459 /*!@} - end defgroup cap_put_slice*/ 460 461 /*!\defgroup cap_xma External Memory Allocation Functions 462 * 463 * The following functions are required to be implemented for all decoders 464 * that advertise the VPX_DEC_CAP_XMA capability. Calling these functions 465 * for codecs that don't advertise this capability will result in an error 466 * code being returned, usually VPX_DEC_ERROR 467 * @{ 468 */ 469 470 /*!\brief Memory Map Entry 471 * 472 * This structure is used to contain the properties of a memory segment. It 473 * is populated by the decoder in the request phase, and by the calling 474 * application once the requested allocation has been performed. 475 */ 476 #if 1 477 #define VPX_DEC_MEM_ZERO 0x1 /**< Segment must be zeroed by allocation */ 478 #define VPX_DEC_MEM_WRONLY 0x2 /**< Segment need not be readable */ 479 #define VPX_DEC_MEM_FAST 0x4 /**< Place in fast memory, if available */ 480 typedef struct vpx_codec_mmap vpx_dec_mmap_t; 481 #else 482 typedef struct vpx_dec_mmap 483 { 484 /* 485 * The following members are set by the codec when requesting a segment 486 */ 487 unsigned int id; /**< identifier for the segment's contents */ 488 unsigned long sz; /**< size of the segment, in bytes */ 489 unsigned int align; /**< required alignment of the segment, in bytes */ 490 unsigned int flags; /**< bitfield containing segment properties */ 491 #define VPX_DEC_MEM_ZERO 0x1 /**< Segment must be zeroed by allocation */ 492 #define VPX_DEC_MEM_WRONLY 0x2 /**< Segment need not be readable */ 493 #define VPX_DEC_MEM_FAST 0x4 /**< Place in fast memory, if available */ 494 495 /* The following members are to be filled in by the allocation function */ 496 void *base; /**< pointer to the allocated segment */ 497 void (*dtor)(struct vpx_dec_mmap *map); /**< destructor to call */ 498 void *priv; /**< allocator private storage */ 499 } vpx_dec_mmap_t; 500 #endif 501 502 /*!\brief Initialize a decoder instance in external allocation mode 503 * 504 * Initializes a decoder context using the given interface. Applications 505 * should call the vpx_dec_xma_init convenience macro instead of this 506 * function directly, to ensure that the ABI version number parameter 507 * is properly initialized. 508 * 509 * \param[in] ctx Pointer to this instance's context. 510 * \param[in] iface Pointer to the alogrithm interface to use. 511 * \param[in] ver ABI version number. Must be set to 512 * VPX_DECODER_ABI_VERSION 513 * \retval #VPX_DEC_OK 514 * The decoder algorithm initialized. 515 * \retval #VPX_DEC_ERROR 516 * Decoder does not support XMA mode. 517 */ 518 vpx_dec_err_t vpx_dec_xma_init_ver(vpx_dec_ctx_t *ctx, 519 vpx_dec_iface_t *iface, 520 int ver) DEPRECATED; 521 #define vpx_dec_xma_init(ctx, iface) \ 522 vpx_dec_xma_init_ver(ctx, iface, VPX_DECODER_ABI_VERSION) 523 524 525 /*!\brief Iterate over the list of segments to allocate. 526 * 527 * Iterates over a list of the segments to allocate. The iterator storage 528 * should be initialized to NULL to start the iteration. Iteration is complete 529 * when this function returns VPX_DEC_LIST_END. The amount of memory needed to 530 * allocate is dependant upon the size of the encoded stream. This means that 531 * the stream info structure must be known at allocation time. It can be 532 * populated with the vpx_dec_peek_stream_info() function. In cases where the 533 * stream to be decoded is not available at allocation time, a fixed size must 534 * be requested. The decoder will not be able to decode streams larger than 535 * the size used at allocation time. 536 * 537 * \param[in] ctx Pointer to this instance's context. 538 * \param[out] mmap Pointer to the memory map entry to populate. 539 * \param[in] si Pointer to the stream info. 540 * \param[in out] iter Iterator storage, initialized to NULL 541 * 542 * \retval #VPX_DEC_OK 543 * The memory map entry was populated. 544 * \retval #VPX_DEC_ERROR 545 * Decoder does not support XMA mode. 546 * \retval #VPX_DEC_MEM_ERROR 547 * Unable to determine segment size from stream info. 548 */ 549 vpx_dec_err_t vpx_dec_get_mem_map(vpx_dec_ctx_t *ctx, 550 vpx_dec_mmap_t *mmap, 551 const vpx_dec_stream_info_t *si, 552 vpx_dec_iter_t *iter) DEPRECATED; 553 554 555 /*!\brief Identify allocated segments to decoder instance 556 * 557 * Stores a list of allocated segments in the decoder. Segments \ref MUST be 558 * passed in the order they are read from vpx_dec_get_mem_map(), but may be 559 * passed in groups of any size. Segments \ref MUST be set only once. The 560 * allocation function \ref MUST ensure that the vpx_dec_mmap_t::base member 561 * is non-NULL. If the segment requires cleanup handling (eg, calling free() 562 * or close()) then the vpx_dec_mmap_t::dtor member \ref MUST be populated. 563 * 564 * \param[in] ctx Pointer to this instance's context. 565 * \param[in] mmaps Pointer to the first memory map entry in the list. 566 * \param[in] num_maps Number of entries being set at this time 567 * 568 * \retval #VPX_DEC_OK 569 * The segment was stored in the decoder context. 570 * \retval #VPX_DEC_ERROR 571 * Decoder does not support XMA mode. 572 * \retval #VPX_DEC_MEM_ERROR 573 * Segment base address was not set, or segment was already stored. 574 575 */ 576 vpx_dec_err_t vpx_dec_set_mem_map(vpx_dec_ctx_t *ctx, 577 vpx_dec_mmap_t *mmaps, 578 unsigned int num_maps) DEPRECATED; 579 580 /*!@} - end defgroup cap_xma*/ 581 /*!@} - end defgroup decoder*/ 582 583 584 #endif 585 #ifdef __cplusplus 586 } 587 #endif 588
