1@TEMPLATE encoder_tmpl.c 2Simple Encoder 3============== 4~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ INTRODUCTION 5This is an example of a simple encoder loop. It takes an input file in 6YV12 format, passes it through the encoder, and writes the compressed 7frames to disk in IVF format. Other decoder examples build upon this 8one. 9 10The details of the IVF format have been elided from this example for 11simplicity of presentation, as IVF files will not generally be used by 12your application. In general, an IVF file consists of a file header, 13followed by a variable number of frames. Each frame consists of a frame 14header followed by a variable length payload. The length of the payload 15is specified in the first four bytes of the frame header. The payload is 16the raw compressed data. 17~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ INTRODUCTION 18 19 20Standard Includes 21----------------- 22For encoders, you only have to include `vpx_encoder.h` and then any 23header files for the specific codecs you use. In this case, we're using 24vp8. The `VPX_CODEC_DISABLE_COMPAT` macro can be defined to ensure 25strict compliance with the latest SDK by disabling some backwards 26compatibility features. Defining this macro is encouraged. 27~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ENC_INCLUDES 28@DEFAULT 29~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ENC_INCLUDES 30 31 32Getting The Default Configuration 33--------------------------------- 34Encoders have the notion of "usage profiles." For example, an encoder 35may want to publish default configurations for both a video 36conferencing appliction and a best quality offline encoder. These 37obviously have very different default settings. Consult the 38documentation for your codec to see if it provides any default 39configurations. All codecs provide a default configuration, number 0, 40which is valid for material in the vacinity of QCIF/QVGA. 41~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ENC_DEF_CFG 42@DEFAULT 43~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ENC_DEF_CFG 44 45 46Updating The Configuration 47--------------------------------- 48Almost all applications will want to update the default configuration 49with settings specific to their usage. Here we set the width and height 50of the video file to that specified on the command line. We also scale 51the default bitrate based on the ratio between the default resolution 52and the resolution specified on the command line. 53~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ENC_SET_CFG 54@DEFAULT 55~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ENC_SET_CFG 56 57 58Initializing The Codec 59---------------------- 60The encoder is initialized by the following code. 61~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ENC_INIT 62@DEFAULT 63~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ENC_INIT 64 65 66Encoding A Frame 67---------------- 68The frame is read as a continuous block (size width * height * 3 / 2) 69from the input file. If a frame was read (the input file has not hit 70EOF) then the frame is passed to the encoder. Otherwise, a NULL 71is passed, indicating the End-Of-Stream condition to the encoder. The 72`frame_cnt` is reused as the presentation time stamp (PTS) and each 73frame is shown for one frame-time in duration. The flags parameter is 74unused in this example. The deadline is set to VPX_DL_REALTIME to 75make the example run as quickly as possible. 76~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ENCODE_FRAME 77@DEFAULT 78~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ENCODE_FRAME 79 80Processing The Encoded Data 81--------------------------- 82Each packet of type `VPX_CODEC_CX_FRAME_PKT` contains the encoded data 83for this frame. We write a IVF frame header, followed by the raw data. 84~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ PROCESS_FRAME 85@DEFAULT 86~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ PROCESS_FRAME 87 88 89Cleanup 90------- 91The `vpx_codec_destroy` call frees any memory allocated by the codec. 92~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ DESTROY 93@DEFAULT 94~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ DESTROY 95 96 97Error Handling 98-------------- 99This example does not special case any error return codes. If there was 100an error, a descriptive message is printed and the program exits. With 101few exeptions, vpx_codec functions return an enumerated error status, 102with the value `0` indicating success. 103~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ DIE_CODEC 104@DEFAULT 105~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ DIE_CODEC 106