VCodecImxVpu C++ library

v1.0.0

Table of contents

• Overview
• Versions
• Library files
• VCodecImxVpu class description
  • VCodecImxVpu class declaration
  • getVersion method
  • transcode method
  • setParam method
  • getParam method
  • executeCommand method
• Build and connect to your project
• Simple example
• Test application

Overview

The VCodecImxVpu C++ library provides hardware video encoding for the H264 codec on NXP i.MX8M Mini-class boards using the Hantro H1 VPU encoder directly. The library is written using the C++17 standard and is supplied as source code only. It is a CMake project. The library supports only Linux and was tested on the i.MX8M Mini. The VCodecImxVpu video codec class inherits the interface and data structures from the VCodec interface library. The library depends on the open-source VCodec library (provides the codec interface, source code included, Apache 2.0 license).

Versions

Table 1 - Library versions.

Version	Release date	What’s new
1.0.0	14.07.2026	First version.

Library files

The library is supplied as source code only. The user is provided with a set of files in the form of a CMake project (repository). The repository structure is shown below:

CMakeLists.txt ---------------- Main CMake file of the library.
3rdparty ---------------------- Folder with third-party libraries.
    CMakeLists.txt ------------ CMake file to include third-party libraries.
    H1Encoder ----------------- Folder with H1Encoder library files.
    VCodec -------------------- Folder with VCodec interface library files.
    Logger -------------------- Folder with Logger library files.
src --------------------------- Folder with library source code.
    CMakeLists.txt ------------ CMake file of the library.
    VCodecImxVpu.h ------------ Main library header file.
    VCodecImxVpuVersion.h ----- Header file with library version.
    VCodecImxVpuVersion.h.in -- File for CMake to generate version header.
    VCodecImxVpu.cpp ---------- C++ implementation file.
test -------------------------- Folder for test application.
    CMakeLists.txt ------------ CMake file for test application.
    main.cpp ------------------ Source C++ file of test application.
example ----------------------- Folder for simple example.
    CMakeLists.txt ------------ CMake file of example.
    main.cpp ------------------ Source C++ file of example.

VCodecImxVpu class description

VCodecImxVpu class declaration

The VCodecImxVpu class is declared in the VCodecImxVpu.h file. Class declaration:

namespace cr
{
namespace video
{
class VCodecImxVpu : public VCodec
{
public:

    /// Get library version.
    static std::string getVersion();

    /// Class constructor.
    VCodecImxVpu();

    /// Class destructor.
    ~VCodecImxVpu();

    /// Encode video frame.
    bool transcode(Frame& src, Frame& dst);

    /// Set parameter value.
    bool setParam(VCodecParam id, float value);

    /// Get parameter value.
    float getParam(VCodecParam id);

    /// Execute command.
    bool executeCommand(VCodecCommand id);
};
}
}

getVersion method

The getVersion() method returns a string of the current version of the VCodecImxVpu class. Method declaration:

static std::string getVersion();

This method can be used without a VCodecImxVpu class instance:

std::cout << "VCodecImxVpu class version: " << VCodecImxVpu::getVersion() << std::endl;

Console output:

VCodecImxVpu class version: 1.0.0

transcode method

The transcode(…) method is intended to encode video frames (Frame class). The video codec encodes video frame-by-frame. Method declaration:

bool transcode(Frame& src, Frame& dst);

Parameter	Value
src	Source video frame (see Frame class description). To encode video data, the src frame must have NV12 pixel format.
dst	Result video frame (see Frame class description). To encode video data, the dst frame must have H264 compressed format.

Returns: TRUE if the frame was encoded successfully or FALSE if not.

setParam method

The setParam(…) method is designed to set new video codec parameter values. Method declaration:

bool setParam(VCodecParam id, float value);

Parameter	Description
id	Video codec parameter ID according to the VCodecParam enum.
value	Video codec parameter value. Valid values depend on the parameter ID.

Returns: TRUE if the parameter was set successfully or FALSE if not.

The VCodec.h file of the VCodec library defines IDs for parameters (VCodecParam enum) and IDs for commands (VCodecCommand enum). VCodecParam declaration:

namespace cr
{
namespace video
{
enum class VCodecParam
{
    /// [read/write] Log level: 0-Disable, 1-Console, 2-File, 3-Console and file.
    LOG_LEVEL = 1,
    /// [read/write] Bitrate, kbps. For H264 and H265 codecs.
    BITRATE_KBPS,
    /// [read/write] Minimum bitrate, kbps. For variable bitrate mode.
    MIN_BITRATE_KBPS,
    /// [read/write] Maximum bitrate, kbps. For variable bitrate mode.
    MAX_BITRATE_KBPS,
    /// [read/write] Bitrate mode: 0 - constant bitrate, 1 - variable bitrate.
    BITRATE_MODE,
    /// [read/write] Quality 0-100%. For JPEG codecs.
    QUALITY,
    /// [read/write] FPS. For H264 and H265 codecs.
    FPS,
    /// [read/write] GOP size. For H264 and H265 codecs.
    GOP,
    /// [read/write] H264 profile: 0 - Baseline, 1 - Main, 2 - High.
    H264_PROFILE,
    /// [read/write] Codec type. Depends on implementation.
    TYPE,
    /// Custom 1. Depends on implementation.
    CUSTOM_1,
    /// Custom 2. Depends on implementation.
    CUSTOM_2,
    /// Custom 3. Depends on implementation.
    CUSTOM_3
};
}
}

Table 2 - Video codec parameters description. Some parameters are not supported by the VCodecImxVpu library.

Parameter	Access	Description
LOG_LEVEL	read / write	Logging mode. Values: 0 - Disable. 1 - Only terminal (console). 2 - Only file. 3 - File and terminal.
BITRATE_KBPS	read / write	Bitrate, kbps. Default: 5000 kbps. According to this value, FPS, and GOP size, the video codec calculates parameters for H264 encoding.
MIN_BITRATE_KBPS	read / write	Not supported by the VCodecImxVpu library.
MAX_BITRATE_KBPS	read / write	Not supported by the VCodecImxVpu library.
BITRATE_MODE	read / write	Not supported by the VCodecImxVpu library.
QUALITY	read / write	Not supported by the VCodecImxVpu library.
FPS	read / write	Frames per second. Default value is 30. According to this value, bitrate, and GOP size, the video codec calculates parameters for H264 encoding.
GOP	read / write	GOP size (period of key frames). Value: 1 - each output frame is a key frame, 20 - each 20th frame is a key frame, etc.
H264_PROFILE	read / write	H264 profile for H264 encoding: 0 - Baseline. 1 - Main. 2 - High.
TYPE	read / write	Not supported by the VCodecImxVpu library.
CUSTOM_1	read / write	Not supported by the VCodecImxVpu library.
CUSTOM_2	read / write	Not supported by the VCodecImxVpu library.
CUSTOM_3	read / write	Not supported by the VCodecImxVpu library.

getParam method

The getParam(…) method is designed to obtain video codec parameter values. Method declaration:

float getParam(VCodecParam id);

Parameter	Description
id	Video codec parameter ID according to the VCodecParam enum (see Table 2).

Returns: Parameter value or -1 if the parameter doesn’t exist in the particular video codec class.

executeCommand method

The executeCommand(…) method is designed to execute video codec commands. Method declaration:

bool executeCommand(VCodecCommand id);

Parameter	Description
id	Video codec command ID according to the VCodecCommand enum.

Returns: TRUE if the command was executed successfully or FALSE if not.

The VCodec.h file of the VCodec library defines IDs for parameters (VCodecParam enum) and IDs for commands (VCodecCommand enum). VCodecCommand declaration:

enum class VCodecCommand
{
    /// Reset.
    RESET = 1,
    /// Generate key frame. For H264 and H265 codecs.
    MAKE_KEY_FRAME
};

Table 3 - Video codec commands description. Some commands may be unsupported by particular video codec classes.

Command	Description
RESET	Reset codec.
MAKE_KEY_FRAME	Generate a key frame for the H264 codec. The next frame will be a key frame for the H264 codec.

Build and connect to your project

Typical commands to build the VCodecImxVpu library:

cd VCodecImxVpu
mkdir build
cd build
cmake ..
make

If you want to connect the VCodecImxVpu library to your CMake project as source code, you can follow these steps. For example, if your repository has the following structure:

CMakeLists.txt
src
    CMakeLists.txt
    yourLib.h
    yourLib.cpp

Create a 3rdparty folder in your repository and copy the VCodecImxVpu repository folder to the 3rdparty folder. The new structure of your repository:

CMakeLists.txt
src
    CMakeLists.txt
    yourLib.h
    yourLib.cpp
3rdparty
    VCodecImxVpu

Create a CMakeLists.txt file in the 3rdparty folder. The CMakeLists.txt should contain:

cmake_minimum_required(VERSION 3.13)

################################################################################
## 3RD-PARTY
## dependencies for the project
################################################################################
project(3rdparty LANGUAGES CXX)

################################################################################
## SETTINGS
## basic 3rd-party settings before use
################################################################################
# To inherit the top-level architecture when the project is used as a submodule.
SET(PARENT ${PARENT}_YOUR_PROJECT_3RDPARTY)
# Disable self-overwriting of parameters inside included subdirectories.
SET(${PARENT}_SUBMODULE_CACHE_OVERWRITE OFF CACHE BOOL "" FORCE)

################################################################################
## INCLUDING SUBDIRECTORIES
## Adding subdirectories according to the 3rd-party configuration
################################################################################
add_subdirectory(VCodecImxVpu)

The 3rdparty/CMakeLists.txt file adds the VCodecImxVpu folder to your project. By default, the test application and example are excluded from compilation when VCodecImxVpu is included as a submodule. Your repository’s new structure will be:

CMakeLists.txt
src
    CMakeLists.txt
    yourLib.h
    yourLib.cpp
3rdparty
    CMakeLists.txt
    VCodecImxVpu

Next, you need to include the 3rdparty folder in the main CMakeLists.txt file of your repository. Add the following line at the end of your main CMakeLists.txt:

add_subdirectory(3rdparty)

Next, you need to include the VCodecImxVpu library in your src/CMakeLists.txt file:

target_link_libraries(${PROJECT_NAME} VCodecImxVpu)

Done!

Simple example

This simple example generates random frames in NV12 pixel format (required for the codec) and encodes them. Source code:

#include <iostream>
#include "VCodecImxVpu.h"

int main(void)
{
    // Create codec object and set params.
    cr::video::VCodec* encoder = new cr::video::VCodecImxVpu();
    encoder->setParam(cr::video::VCodecParam::BITRATE_KBPS, 10000);
    encoder->setParam(cr::video::VCodecParam::FPS, 20);
    encoder->setParam(cr::video::VCodecParam::GOP, 30);
    encoder->setParam(cr::video::VCodecParam::H264_PROFILE, 0);
    // Image size.
    const int width = 640;
    const int height = 480;
    // Source frame.
    cr::video::Frame srcFrame(width, height, cr::video::Fourcc::NV12);
    // Result frame H264.
    cr::video::Frame dstFrame(width, height, cr::video::Fourcc::H264);

    // Main loop.
    uint8_t valueOffset = 0;
    while (true)
    {
        // Generate random data for source frame. Fill NV12 frame data.
        for (int i = 0; i < srcFrame.size; ++i)
            srcFrame.data[i] = (uint8_t)i + valueOffset;
        valueOffset++;

        // Encode data.
        if (!encoder->transcode(srcFrame, dstFrame))
        {
            std::cout << "Can't encode frame" << std::endl;
            continue;
        }

        // Show info.
        std::cout << "[" << dstFrame.frameId << "] Size " <<
        dstFrame.size << " Compression ratio : %" <<
        (int)(100.0f * ((float)dstFrame.size / (float)srcFrame.size)) <<
        std::endl;
    }
}

Test application

The test application (VCodecImxVpu/test/main.cpp) for the VCodecImxVpu C++ library demonstrates how the library works. The test application generates artificial video, compresses it according to user parameters (bitrate, GOP size, and H264 profile), and writes the results to a binary file “out.h264”. The application shows the encoding time for each video frame. To run the application, perform the following commands on Linux:

cd <application folder>
sudo chmod +x VCodecImxVpuTest
sudo ./VCodecImxVpuTest

After starting, you will see the following output:

====================================
VCodecImxVpu v1.0.0 test
====================================

Codec: H264
Default params:
Bitrate, kbps 5000
FPS: 30
GOP size: 30
Video width 1280
Video height 720
H264 Profile: 0
Use default params (0 - no, 1 - yes) : 1
Set number frames: 600
Set noise mode (0 - no noise, 1 - noise) : 1

The user can set custom parameters. When the parameters are chosen, the test application starts writing encoded frames until it is stopped or until the specified number of frames is reached. During encoding, the application shows the encoded data size and encoding time:

Data size 3110400 / 794210   encoding time  70305 us
Data size 3110400 / 364976   encoding time  23352 us
Data size 3110400 / 244956   encoding time  17361 us
Data size 3110400 / 162957   encoding time  18809 us
Data size 3110400 / 108687   encoding time  16044 us
Data size 3110400 / 74601   encoding time  15782 us
Data size 3110400 / 56436   encoding time  17350 us
Data size 3110400 / 52852   encoding time  16523 us

---

Table of contents