usage_dx.dox

   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 */