| @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 |