VCodecLibva C++ library

v1.0.0

Table of contents

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

Overview

The VCodecLibva C++ library provides hardware video encoding for H264, HEVC and JPEG codecs based on the LibVA Intel library (Hardware accelerated encoding based on VAAPI interface) on Linux only. The VCodecLibva video codec class inherits interface and data structures from the VCodec interface library. The library depends on the open-source VCodec library (provides codec interface, source code included, Apache 2.0 license), the open-source LibVA library, and the open-source Logger (provides functions to print logs, source code included, Apache 2.0 license). The library uses the C++17 standard.

Versions

Table 1 - Library versions.

Version	Release date	What’s new
1.0.0	18.03.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.
    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.
    VCodecLibva.h ------------ Main library header file.
    VCodecLibvaVersion.h ----- Header file with library version.
    VCodecLibvaVersion.h.in -- File for CMake to generate version header.
    VCodecLibva.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.

VCodecLibva class description

VCodecLibva class declaration

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

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

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

    /// Class constructor.
    VCodecLibva();

    /// Class destructor.
    ~VCodecLibva();

    /// 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 VCodecLibva class. Method declaration:

static std::string getVersion();

This method can be used without a VCodecLibva class instance:

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

Console output:

VCodecLibva class version: 1.0.0

transcode method

The transcode(…) method is intended to encode and decode video frames (Frame class). The video codec encodes/decodes video frames 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 a compressed pixel format (field fourcc of Frame class): JPEG, H264, or HEVC. The user must specify the output pixel format in advance.

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 VCodecLibva 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. For H264 and H265 (HEVC) encoding. According to this value, FPS, and GOP size, the video codec calculates parameters for H264 or H265 (HEVC) encoding.
MIN_BITRATE_KBPS	read / write	Not supported by VCodecLibva library.
MAX_BITRATE_KBPS	read / write	Not supported by VCodecLibva library.
BITRATE_MODE	read / write	Bitrate mode for H264 and H265 (HEVC) codecs only. Values: 0 - constant bitrate (default), 1 - variable bitrate depends on content.
QUALITY	read / write	Quality 0 (low quality) - 100% (maximum quality).
FPS	read / write	Frames per second. Default value is 30. For H264 and H265 (HEVC) encoding only. According to this value, bitrate, and GOP size, the video codec calculates parameters for H264 and H265 (HEVC) encoding.
GOP	read / write	GOP size (period of key frames) for H264 and H265 (HEVC) encoding. 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 VCodecLibva library.
CUSTOM_1	read / write	Not supported by VCodecLibva library.
CUSTOM_2	read / write	Not supported by VCodecLibva library.
CUSTOM_3	read / write	Not supported by VCodecLibva 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 key frame for H264 and HEVC codecs. The next frame will be a key frame for H264 and HEVC codecs.

Build and connect to your project

Before compiling, you must install or compile LibVA packages for your system.

The install command of the necessary libraries for Ubuntu Linux:

sudo apt install libva2 libva-drm2 libva-dev
sudo apt install intel-media-va-driver-non-free

If you use Windows WSL, you must activate the vgem Linux module before encoding:

sudo modprobe vgem

Build and connect to project

Typical commands to build the VCodecLibva library:

cd VCodecLibva
mkdir build
cd build
cmake ..
make

If you want to connect the VCodecLibva 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 VCodecLibva repository folder to the 3rdparty folder. The new structure of your repository:

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

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
################################################################################
if (${PARENT}_SUBMODULE_VCODEC_LIBVA)
    add_subdirectory(VCodecLibva)
endif()

The 3rdparty/CMakeLists.txt file adds the VCodecLibva folder to your project and excludes the test application and example (by default, the test application and example are excluded from compilation if VCodecLibva is included as a sub-repository). Your repository’s new structure will be:

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

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 VCodecLibva library in your src/CMakeLists.txt file:

target_link_libraries(${PROJECT_NAME} VCodecLibva)

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 "VCodecLibva.h"

int main(void)
{
    // Create codec object and set params.
    cr::video::VCodec* encoder = new cr::video::VCodecLibva();
    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;
    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 (VCodecLibva/test/main.cpp) for the VCodecLibva C++ library demonstrates how the library works on Intel platforms. The test application generates artificial video, compresses it according to user parameters (codec type, bitrate or JPEG quality, GOP size, and H264 profile), writes results to binary files “out.h264”, “out.hevc”, or “out.mjpeg”. The application shows encoding time for each video frame. To run the application, perform the following commands on Linux:

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

After starting, you will see the following output:

====================================
VCodecLibva v1.0.0 test
====================================

Enter Encoder type (0 - JPEG, 1 - H264, 2 - HEVC) :

Choose the codec type (0 - JPEG, 1 - H264, 2 - HEVC). If the H264 codec is chosen, you will see the following message:

====================================
VCodecLibva v1.0.0 test
====================================

Enter Encoder type (0 - JPEG, 1 - H264, 2 - HEVC) : 1
Default params:
Bitrate, kbps 5000
Bitrate mode (0 - constant, 1 - variable) 0
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: 6  
Set noise mode (0 - no noise, 1 - noise) : 0

The user can set custom parameters. When parameters are chosen, the test application will start writing encoded frames until stopped (if the user sets a number of frames). During encoding, the application shows the encoded data size, encoding time:

Data size 1382400 / 7006   encoding time  478369 us
Data size 1382400 / 229   encoding time  13089 us
Data size 1382400 / 624   encoding time  15115 us
Data size 1382400 / 598   encoding time  14369 us
Data size 1382400 / 574   encoding time  15241 us
Data size 1382400 / 576   encoding time  15318 us

---

Table of contents