examples/simple_decoder.txt

   1 @TEMPLATE decoder_tmpl.c
   2 Simple Decoder
   3 ==============
   4 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ INTRODUCTION
   5 This is an example of a simple decoder loop. It takes an input file
   6 containing the compressed data (in IVF format), passes it through the
   7 decoder, and writes the decompressed frames to disk. Other decoder
   8 examples build upon this one.
   9
  10 The details of the IVF format have been elided from this example for
  11 simplicity of presentation, as IVF files will not generally be used by
  12 your application. In general, an IVF file consists of a file header,
  13 followed by a variable number of frames. Each frame consists of a frame
  14 header followed by a variable length payload. The length of the payload
  15 is specified in the first four bytes of the frame header. The payload is
  16 the raw compressed data.
  17 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ INTRODUCTION
  18
  19
  20 Standard Includes
  21 -----------------
  22 For decoders, you only have to include `vpx_decoder.h` and then any
  23 header files for the specific codecs you use. In this case, we're using
  24 vp8. The `VPX_CODEC_DISABLE_COMPAT` macro can be defined to ensure
  25 strict compliance with the latest SDK by disabling some backwards
  26 compatibility features. Defining this macro is encouraged.
  27 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ DEC_INCLUDES
  28 @DEFAULT
  29 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ DEC_INCLUDES
  30
  31
  32 Initializing The Codec
  33 ----------------------
  34 The decoder is initialized by the following code. This is an example for
  35 the VP8 decoder, but the code is analogous for all algorithms. Replace
  36 `vpx_codec_vp8_dx()` with a pointer to the interface exposed by the
  37 algorithm you want to use. The `cfg` argument is left as NULL in this
  38 example, because we want the algorithm to determine the stream
  39 configuration (width/height) and allocate memory automatically. This
  40 parameter is generally only used if you need to preallocate memory,
  41 particularly in External Memory Allocation mode.
  42 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ DEC_INIT
  43 @DEFAULT
  44 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ DEC_INIT
  45
  46
  47 Decoding A Frame
  48 ----------------
  49 Once the frame has been read into memory, it is decoded using the
  50 `vpx_codec_decode` function. The call takes a pointer to the data
  51 (`frame`) and the length of the data (`frame_sz`). No application data
  52 is associated with the frame in this example, so the `user_priv`
  53 parameter is NULL. The `deadline` parameter is left at zero for this
  54 example. This parameter is generally only used when doing adaptive
  55 postprocessing.
  56 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ DECODE
  57 @DEFAULT
  58 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ DECODE
  59
  60 Codecs may produce a variable number of output frames for every call to
  61 `vpx_codec_decode`. These frames are retrieved by the
  62 `vpx_codec_get_frame` iterator function. The iterator variable `iter` is
  63 initialized to NULL each time `vpx_codec_decode` is called.
  64 `vpx_codec_get_frame` is called in a loop, returning a pointer to a
  65 decoded image or NULL to indicate the end of list.
  66 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ GET_FRAME
  67 @DEFAULT
  68 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ GET_FRAME
  69
  70
  71 Processing The Decoded Data
  72 ---------------------------
  73 In this example, we simply write the encoded data to disk. It is
  74 important to honor the image's `stride` values.
  75 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ PROCESS_DX
  76 @DEFAULT
  77 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ PROCESS_DX
  78
  79
  80 Cleanup
  81 -------
  82 The `vpx_codec_destroy` call frees any memory allocated by the codec.
  83 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ DESTROY
  84 @DEFAULT
  85 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ DESTROY
  86
  87
  88 Error Handling
  89 --------------
  90 This example does not special case any error return codes. If there was
  91 an error, a descriptive message is printed and the program exits. With
  92 few exeptions, vpx_codec functions return an enumerated error status,
  93 with the value `0` indicating success.
  94 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ DIE_CODEC
  95 @DEFAULT
  96 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ DIE_CODEC