usage.dox 6.57 KB
 John Koleszar committed May 18, 2010 1 2 /*!\page usage Usage  James Zern committed Mar 15, 2012 3  The vpx multi-format codec SDK provides a unified interface amongst its  John Koleszar committed May 18, 2010 4 5 6 7 8 9 10 11 12 13 14  supported codecs. This abstraction allows applications using this SDK to easily support multiple video formats with minimal code duplication or "special casing." This section describes the interface common to all codecs. For codec-specific details, see the \ref codecs page. The following sections are common to all codecs: - \ref usage_types - \ref usage_features - \ref usage_init - \ref usage_errors  James Zern committed Mar 14, 2015 15  For more information on decoder and encoder specific usage, see the  John Koleszar committed May 18, 2010 16  following pages:  James Zern committed Mar 15, 2012 17  \if decoder  James Zern committed Mar 14, 2015 18  \li \subpage usage_decode  James Zern committed Mar 15, 2012 19  \endif  James Zern committed Mar 14, 2015 20 21  \if encoder \li \subpage usage_encode  James Zern committed Mar 15, 2012 22  \endif  John Koleszar committed May 18, 2010 23 24 25 26 27 28 29 30 31  \section usage_types Important Data Types There are two important data structures to consider in this interface. \subsection usage_ctxs Contexts A context is a storage area allocated by the calling application that the codec may write into to store details about a single instance of that codec. Most of the context is implementation specific, and thus opaque to the application. The context structure as seen by the application is of fixed  James Zern committed Feb 17, 2011 32  size, and thus can be allocated with automatic storage or dynamically  John Koleszar committed May 18, 2010 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69  on the heap. Most operations require an initialized codec context. Codec context instances are codec specific. That is, the codec to be used for the encoded video must be known at initialization time. See #vpx_codec_ctx_t for further information. \subsection usage_ifaces Interfaces A codec interface is an opaque structure that controls how function calls into the generic interface are dispatched to their codec-specific implementations. Applications \ref MUSTNOT attempt to examine or override this storage, as it contains internal implementation details likely to change from release to release. Each supported codec will expose an interface structure to the application as an extern reference to a structure of the incomplete type #vpx_codec_iface_t. \section usage_features Features Several "features" are defined that are optionally implemented by codec algorithms. Indeed, the same algorithm may support different features on different platforms. The purpose of defining these features is that when they are implemented, they conform to a common interface. The features, or capabilities, of an algorithm can be queried from it's interface by using the vpx_codec_get_caps() method. Attempts to invoke features not supported by an algorithm will generally result in #VPX_CODEC_INCAPABLE. \if decoder Currently defined decoder features include: - \ref usage_cb - \ref usage_postproc \endif \section usage_init Initialization To initialize a codec instance, the address of the codec context and interface structures are passed to an initialization function. Depending on the \ref usage_features that the codec supports, the codec could be  James Zern committed Aug 12, 2014 70  initialized in different modes.  John Koleszar committed May 18, 2010 71 72 73 74 75  To prevent cases of confusion where the ABI of the library changes, the ABI is versioned. The ABI version number must be passed at initialization time to ensure the application is using a header file that matches the library. The current ABI version number is stored in the  James Zern committed Feb 17, 2011 76  preprocessor macros #VPX_CODEC_ABI_VERSION, #VPX_ENCODER_ABI_VERSION, and  John Koleszar committed May 18, 2010 77 78 79 80 81 82  #VPX_DECODER_ABI_VERSION. For convenience, each initialization function has a wrapper macro that inserts the correct version number. These macros are named like the initialization methods, but without the _ver suffix. The available initialization methods are:  Yaowu Xu committed Jan 15, 2015 83  \if encoder  James Zern committed Mar 14, 2015 84 85 86 87 88  \li #vpx_codec_enc_init (calls vpx_codec_enc_init_ver()) \li #vpx_codec_enc_init_multi (calls vpx_codec_enc_init_multi_ver()) \endif \if decoder \li #vpx_codec_dec_init (calls vpx_codec_dec_init_ver())  Yaowu Xu committed Jan 15, 2015 89  \endif  John Koleszar committed May 18, 2010 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130  \section usage_errors Error Handling Almost all codec functions return an error status of type #vpx_codec_err_t. The semantics of how each error condition should be processed is clearly defined in the definitions of each enumerated value. Error values can be converted into ASCII strings with the vpx_codec_error() and vpx_codec_err_to_string() methods. The difference between these two methods is that vpx_codec_error() returns the error state from an initialized context, whereas vpx_codec_err_to_string() can be used in cases where an error occurs outside any context. The enumerated value returned from the last call can be retrieved from the err member of the decoder context as well. Finally, more detailed error information may be able to be obtained by using the vpx_codec_error_detail() method. Not all errors produce detailed error information. In addition to error information, the codec library's build configuration is available at runtime on some platforms. This information can be returned by calling vpx_codec_build_config(), and is formatted as a base64 coded string (comprised of characters in the set [a-z_a-Z0-9+/]). This information is not useful to an application at runtime, but may be of use to vpx for support. \section usage_deadline Deadline Both the encoding and decoding functions have a deadline parameter. This parameter indicates the amount of time, in microseconds (us), that the application wants the codec to spend processing before returning. This is a soft deadline -- that is, the semantics of the requested operation take precedence over meeting the deadline. If, for example, an application sets a deadline of 1000us, and the frame takes 2000us to decode, the call to vpx_codec_decode() will return after 2000us. In this case the deadline is not met, but the semantics of the function are preserved. If, for the same frame, an application instead sets a deadline of 5000us, the decoder will see that it has 3000us remaining in its time slice when decoding completes. It could then choose to run a set of \ref usage_postproc filters, and perhaps would return after 4000us (instead of the allocated 5000us). In this case the deadline is met, and the semantics of the call are preserved, as before. The special value 0 is reserved to represent an infinite deadline. In this case, the codec will perform as much processing as  James Zern committed Feb 17, 2011 131  possible to yield the highest quality frame.  John Koleszar committed May 18, 2010 132 133 134 135 136  By convention, the value 1 is used to mean "return as fast as possible." */