libvpx: Pull from upstream

source/libvpx/examples/simple_decoder.txt

-@TEMPLATE decoder_tmpl.c
-Simple Decoder
-==============
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ INTRODUCTION
-This is an example of a simple decoder loop. It takes an input file
-containing the compressed data (in IVF format), passes it through the
-decoder, and writes the decompressed frames to disk. Other decoder
-examples build upon this one.
-
-The details of the IVF format have been elided from this example for
-simplicity of presentation, as IVF files will not generally be used by
-your application. In general, an IVF file consists of a file header,
-followed by a variable number of frames. Each frame consists of a frame
-header followed by a variable length payload. The length of the payload
-is specified in the first four bytes of the frame header. The payload is
-the raw compressed data.
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ INTRODUCTION
-
-
-Standard Includes
------------------
-For decoders, you only have to include `vpx_decoder.h` and then any
-header files for the specific codecs you use. In this case, we're using
-vp8. The `VPX_CODEC_DISABLE_COMPAT` macro can be defined to ensure
-strict compliance with the latest SDK by disabling some backwards
-compatibility features. Defining this macro is encouraged.
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ DEC_INCLUDES
-@DEFAULT
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ DEC_INCLUDES
-
-
-Initializing The Codec
-----------------------
-The decoder is initialized by the following code. This is an example for
-the VP8 decoder, but the code is analogous for all algorithms. Replace
-`vpx_codec_vp8_dx()` with a pointer to the interface exposed by the
-algorithm you want to use. The `cfg` argument is left as NULL in this
-example, because we want the algorithm to determine the stream
-configuration (width/height) and allocate memory automatically. This
-parameter is generally only used if you need to preallocate memory,
-particularly in External Memory Allocation mode.
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ DEC_INIT
-@DEFAULT
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ DEC_INIT
-
-
-Decoding A Frame
-----------------
-Once the frame has been read into memory, it is decoded using the
-`vpx_codec_decode` function. The call takes a pointer to the data
-(`frame`) and the length of the data (`frame_sz`). No application data
-is associated with the frame in this example, so the `user_priv`
-parameter is NULL. The `deadline` parameter is left at zero for this
-example. This parameter is generally only used when doing adaptive
-postprocessing.
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ DECODE
-@DEFAULT
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ DECODE
-
-Codecs may produce a variable number of output frames for every call to
-`vpx_codec_decode`. These frames are retrieved by the
-`vpx_codec_get_frame` iterator function. The iterator variable `iter` is
-initialized to NULL each time `vpx_codec_decode` is called.
-`vpx_codec_get_frame` is called in a loop, returning a pointer to a
-decoded image or NULL to indicate the end of list.
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ GET_FRAME
-@DEFAULT
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ GET_FRAME
-
-
-Processing The Decoded Data
----------------------------
-In this example, we simply write the encoded data to disk. It is
-important to honor the image's `stride` values.
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ PROCESS_DX
-@DEFAULT
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ PROCESS_DX
-
-
-Cleanup
--------
-The `vpx_codec_destroy` call frees any memory allocated by the codec.
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ DESTROY
-@DEFAULT
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ DESTROY
-
-
-Error Handling
---------------
-This example does not special case any error return codes. If there was
-an error, a descriptive message is printed and the program exits. With
-few exeptions, vpx_codec functions return an enumerated error status,
-with the value `0` indicating success.
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ DIE_CODEC
-@DEFAULT
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ DIE_CODEC