1/*! \page usage_decode Decoding 2 3 The aom_codec_decode() function is at the core of the decode loop. It 4 processes packets of compressed data passed by the application, producing 5 decoded images. The decoder expects packets to comprise exactly one image 6 frame of data. Packets \ref MUST be passed in decode order. If the 7 application wishes to associate some data with the frame, the 8 <code>user_priv</code> member may be set. 9 10 \ref samples 11 12 13 \section usage_cb Callback Based Decoding 14 There are two methods for the application to access decoded frame data. Some 15 codecs support asynchronous (callback-based) decoding \ref usage_features 16 that allow the application to register a callback to be invoked by the 17 decoder when decoded data becomes available. Decoders are not required to 18 support this feature, however. Like all \ref usage_features, support can be 19 determined by calling aom_codec_get_caps(). Callbacks are available in both 20 frame-based and slice-based variants. Frame based callbacks conform to the 21 signature of #aom_codec_put_frame_cb_fn_t and are invoked once the entire 22 frame has been decoded. Slice based callbacks conform to the signature of 23 #aom_codec_put_slice_cb_fn_t and are invoked after a subsection of the frame 24 is decoded. For example, a slice callback could be issued for each 25 macroblock row. However, the number and size of slices to return is 26 implementation specific. Also, the image data passed in a slice callback is 27 not necessarily in the same memory segment as the data will be when it is 28 assembled into a full frame. For this reason, the application \ref MUST 29 examine the rectangles that describe what data is valid to access and what 30 data has been updated in this call. For all their additional complexity, 31 slice based decoding callbacks provide substantial speed gains to the 32 overall application in some cases, due to improved cache behavior. 33 34 35 \section usage_frame_iter Frame Iterator Based Decoding 36 If the codec does not support callback based decoding, or the application 37 chooses not to make use of that feature, decoded frames are made available 38 through the aom_codec_get_frame() iterator. The application initializes the 39 iterator storage (of type #aom_codec_iter_t) to NULL, then calls 40 aom_codec_get_frame repeatedly until it returns NULL, indicating that all 41 images have been returned. This process may result in zero, one, or many 42 frames that are ready for display, depending on the codec. 43 44 45 \section usage_postproc Postprocessing 46 Postprocessing is a process that is applied after a frame is decoded to 47 enhance the image's appearance by removing artifacts introduced in the 48 compression process. It is not required to properly decode the frame, and 49 is generally done only when there is enough spare CPU time to execute 50 the required filters. Codecs may support a number of different 51 postprocessing filters, and the available filters may differ from platform 52 to platform. Embedded devices often do not have enough CPU to implement 53 postprocessing in software. The filter selection is generally handled 54 automatically by the codec. 55 56 57*/ 58