1 /*!\page usage Usage 2 3 The vpx multi-format codec SDK provides a unified interface amongst its 4 supported codecs. This abstraction allows applications using this SDK to 5 easily support multiple video formats with minimal code duplication or 6 "special casing." This section describes the interface common to all codecs. 7 For codec-specific details, see the \ref codecs page. 8 9 The following sections are common to all codecs: 10 - \ref usage_types 11 - \ref usage_features 12 - \ref usage_init 13 - \ref usage_errors 14 15 Fore more information on decoder and encoder specific usage, see the 16 following pages: 17 \if decoder 18 - \subpage usage_decode 19 \endif 20 \if decoder 21 - \subpage usage_encode 22 \endif 23 24 \section usage_types Important Data Types 25 There are two important data structures to consider in this interface. 26 27 \subsection usage_ctxs Contexts 28 A context is a storage area allocated by the calling application that the 29 codec may write into to store details about a single instance of that codec. 30 Most of the context is implementation specific, and thus opaque to the 31 application. The context structure as seen by the application is of fixed 32 size, and thus can be allocated with automatic storage or dynamically 33 on the heap. 34 35 Most operations require an initialized codec context. Codec context 36 instances are codec specific. That is, the codec to be used for the encoded 37 video must be known at initialization time. See #vpx_codec_ctx_t for further 38 information. 39 40 \subsection usage_ifaces Interfaces 41 A codec interface is an opaque structure that controls how function calls 42 into the generic interface are dispatched to their codec-specific 43 implementations. Applications \ref MUSTNOT attempt to examine or override 44 this storage, as it contains internal implementation details likely to 45 change from release to release. 46 47 Each supported codec will expose an interface structure to the application 48 as an <code>extern</code> reference to a structure of the incomplete type 49 #vpx_codec_iface_t. 50 51 \section usage_features Features 52 Several "features" are defined that are optionally implemented by codec 53 algorithms. Indeed, the same algorithm may support different features on 54 different platforms. The purpose of defining these features is that when 55 they are implemented, they conform to a common interface. The features, or 56 capabilities, of an algorithm can be queried from it's interface by using 57 the vpx_codec_get_caps() method. Attempts to invoke features not supported 58 by an algorithm will generally result in #VPX_CODEC_INCAPABLE. 59 60 Currently defined features available in both encoders and decoders include: 61 - \subpage usage_xma 62 63 \if decoder 64 Currently defined decoder features include: 65 - \ref usage_cb 66 - \ref usage_postproc 67 \endif 68 69 \section usage_init Initialization 70 To initialize a codec instance, the address of the codec context 71 and interface structures are passed to an initialization function. Depending 72 on the \ref usage_features that the codec supports, the codec could be 73 initialized in different modes. Most notably, the application may choose to 74 use \ref usage_xma mode to gain fine grained control over how and where 75 memory is allocated for the codec. 76 77 To prevent cases of confusion where the ABI of the library changes, 78 the ABI is versioned. The ABI version number must be passed at 79 initialization time to ensure the application is using a header file that 80 matches the library. The current ABI version number is stored in the 81 preprocessor macros #VPX_CODEC_ABI_VERSION, #VPX_ENCODER_ABI_VERSION, and 82 #VPX_DECODER_ABI_VERSION. For convenience, each initialization function has 83 a wrapper macro that inserts the correct version number. These macros are 84 named like the initialization methods, but without the _ver suffix. 85 86 87 The available initialization methods are: 88 \if encoder - #vpx_codec_enc_init (calls vpx_codec_enc_init_ver()) \endif 89 \if multi-encoder - #vpx_codec_enc_init_multi (calls vpx_codec_enc_init_multi_ver()) \endif 90 \if decoder - #vpx_codec_dec_init (calls vpx_codec_dec_init_ver()) \endif 91 92 93 94 \section usage_errors Error Handling 95 Almost all codec functions return an error status of type #vpx_codec_err_t. 96 The semantics of how each error condition should be processed is clearly 97 defined in the definitions of each enumerated value. Error values can be 98 converted into ASCII strings with the vpx_codec_error() and 99 vpx_codec_err_to_string() methods. The difference between these two methods is 100 that vpx_codec_error() returns the error state from an initialized context, 101 whereas vpx_codec_err_to_string() can be used in cases where an error occurs 102 outside any context. The enumerated value returned from the last call can be 103 retrieved from the <code>err</code> member of the decoder context as well. 104 Finally, more detailed error information may be able to be obtained by using 105 the vpx_codec_error_detail() method. Not all errors produce detailed error 106 information. 107 108 In addition to error information, the codec library's build configuration 109 is available at runtime on some platforms. This information can be returned 110 by calling vpx_codec_build_config(), and is formatted as a base64 coded string 111 (comprised of characters in the set [a-z_a-Z0-9+/]). This information is not 112 useful to an application at runtime, but may be of use to vpx for support. 113 114 115 \section usage_deadline Deadline 116 Both the encoding and decoding functions have a <code>deadline</code> 117 parameter. This parameter indicates the amount of time, in microseconds 118 (us), that the application wants the codec to spend processing before 119 returning. This is a soft deadline -- that is, the semantics of the 120 requested operation take precedence over meeting the deadline. If, for 121 example, an application sets a <code>deadline</code> of 1000us, and the 122 frame takes 2000us to decode, the call to vpx_codec_decode() will return 123 after 2000us. In this case the deadline is not met, but the semantics of the 124 function are preserved. If, for the same frame, an application instead sets 125 a <code>deadline</code> of 5000us, the decoder will see that it has 3000us 126 remaining in its time slice when decoding completes. It could then choose to 127 run a set of \ref usage_postproc filters, and perhaps would return after 128 4000us (instead of the allocated 5000us). In this case the deadline is met, 129 and the semantics of the call are preserved, as before. 130 131 The special value <code>0</code> is reserved to represent an infinite 132 deadline. In this case, the codec will perform as much processing as 133 possible to yield the highest quality frame. 134 135 By convention, the value <code>1</code> is used to mean "return as fast as 136 possible." 137 138 */ 139 140 141 /*! \page usage_xma External Memory Allocation 142 Applications that wish to have fine grained control over how and where 143 decoders allocate memory \ref MAY make use of the eXternal Memory Allocation 144 (XMA) interface. Not all codecs support the XMA \ref usage_features. 145 146 To use a decoder in XMA mode, the decoder \ref MUST be initialized with the 147 vpx_codec_xma_init_ver() function. The amount of memory a decoder needs to 148 allocate is heavily dependent on the size of the encoded video frames. The 149 size of the video must be known before requesting the decoder's memory map. 150 This stream information can be obtained with the vpx_codec_peek_stream_info() 151 function, which does not require a constructed decoder context. If the exact 152 stream is not known, a stream info structure can be created that reflects 153 the maximum size that the decoder instance is required to support. 154 155 Once the decoder instance has been initialized and the stream information 156 determined, the application calls the vpx_codec_get_mem_map() iterator 157 repeatedly to get a list of the memory segments requested by the decoder. 158 The iterator value should be initialized to NULL to request the first 159 element, and the function will return #VPX_CODEC_LIST_END to signal the end of 160 the list. 161 162 After each segment is identified, it must be passed to the codec through the 163 vpx_codec_set_mem_map() function. Segments \ref MUST be passed in the same 164 order as they are returned from vpx_codec_get_mem_map(), but there is no 165 requirement that vpx_codec_get_mem_map() must finish iterating before 166 vpx_codec_set_mem_map() is called. For instance, some applications may choose 167 to get a list of all requests, construct an optimal heap, and then set all 168 maps at once with one call. Other applications may set one map at a time, 169 allocating it immediately after it is returned from vpx_codec_get_mem_map(). 170 171 After all segments have been set using vpx_codec_set_mem_map(), the codec may 172 be used as it would be in normal internal allocation mode. 173 174 \section usage_xma_seg_id Segment Identifiers 175 Each requested segment is identified by an identifier unique to 176 that decoder type. Some of these identifiers are private, while others are 177 enumerated for application use. Identifiers not enumerated publicly are 178 subject to change. Identifiers are non-consecutive. 179 180 \section usage_xma_seg_szalign Segment Size and Alignment 181 The sz (size) and align (alignment) parameters describe the required size 182 and alignment of the requested segment. Alignment will always be a power of 183 two. Applications \ref MUST honor the alignment requested. Failure to do so 184 could result in program crashes or may incur a speed penalty. 185 186 \section usage_xma_seg_flags Segment Flags 187 The flags member of the segment structure indicates any requirements or 188 desires of the codec for the particular segment. The #VPX_CODEC_MEM_ZERO flag 189 indicates that the segment \ref MUST be zeroed by the application prior to 190 passing it to the application. The #VPX_CODEC_MEM_WRONLY flag indicates that 191 the segment will only be written into by the decoder, not read. If this flag 192 is not set, the application \ref MUST insure that the memory segment is 193 readable. On some platforms, framebuffer memory is writable but not 194 readable, for example. The #VPX_CODEC_MEM_FAST flag indicates that the segment 195 will be frequently accessed, and that it should be placed into fast memory, 196 if any is available. The application \ref MAY choose to place other segments 197 in fast memory as well, but the most critical segments will be identified by 198 this flag. 199 200 \section usage_xma_seg_basedtor Segment Base Address and Destructor 201 For each requested memory segment, the application must determine the 202 address of a memory segment that meets the requirements of the codec. This 203 address is set in the <code>base</code> member of the #vpx_codec_mmap 204 structure. If the application requires processing when the segment is no 205 longer used by the codec (for instance to deallocate it or close an 206 associated file descriptor) the <code>dtor</code> and <code>priv</code> 207 members can be set. 208 */ 209
