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