ref: d9ca52452bff9481ec1ed4684985a86fb7fc3c3e
dir: /examples/simple_encoder.txt/
@TEMPLATE encoder_tmpl.c Simple Encoder ============== ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ INTRODUCTION This is an example of a simple encoder loop. It takes an input file in YV12 format, passes it through the encoder, and writes the compressed frames to disk in IVF format. 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 encoders, you only have to include `vpx_encoder.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. ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ENC_INCLUDES @DEFAULT ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ENC_INCLUDES Getting The Default Configuration --------------------------------- Encoders have the notion of "usage profiles." For example, an encoder may want to publish default configurations for both a video conferencing appliction and a best quality offline encoder. These obviously have very different default settings. Consult the documentation for your codec to see if it provides any default configurations. All codecs provide a default configuration, number 0, which is valid for material in the vacinity of QCIF/QVGA. ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ENC_DEF_CFG @DEFAULT ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ENC_DEF_CFG Updating The Configuration --------------------------------- Almost all applications will want to update the default configuration with settings specific to their usage. Here we set the width and height of the video file to that specified on the command line. We also scale the default bitrate based on the ratio between the default resolution and the resolution specified on the command line. ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ENC_SET_CFG @DEFAULT ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ENC_SET_CFG Initializing The Codec ---------------------- The encoder is initialized by the following code. ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ENC_INIT @DEFAULT ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ENC_INIT Encoding A Frame ---------------- The frame is read as a continuous block (size width * height * 3 / 2) from the input file. If a frame was read (the input file has not hit EOF) then the frame is passed to the encoder. Otherwise, a NULL is passed, indicating the End-Of-Stream condition to the encoder. The `frame_cnt` is reused as the presentation time stamp (PTS) and each frame is shown for one frame-time in duration. The flags parameter is unused in this example. The deadline is set to VPX_DL_REALTIME to make the example run as quickly as possible. ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ENCODE_FRAME @DEFAULT ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ENCODE_FRAME Processing The Encoded Data --------------------------- Each packet of type `VPX_CODEC_CX_FRAME_PKT` contains the encoded data for this frame. We write a IVF frame header, followed by the raw data. ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ PROCESS_FRAME @DEFAULT ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ PROCESS_FRAME 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