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 97
