VCodecOneVpl C++ library

v2.1.3

Table of contents

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

Overview

The VCodecOneVpl C++ library provides hardware video encoding/decoding (H264, HEVC, and JPEG) for Intel HD Graphics based on the oneVPL API. The VCodecOneVpl class inherits interface and data structures from the open-source VCodec library (provides interface for video codecs, source code included, Apache 2.0 license) and also includes the Logger open-source library (provides functions to print logs, source code included, Apache 2.0 license). The library provides a simple interface to be implemented in different C++ projects and is compatible with Linux and Windows. It is written with the C++17 standard. The library is supplied as source code only in the form of a CMake project.

Encoding time for 11th Gen Intel(R) Core(TM) i5-1145G7E on Ubuntu 22.04 LTS:

codec / resolution	2560x1440	1920x1080	1280x720	640x512
H264	11.6 msec	8.6 msec	4.4 msec	2.6 msec
HEVC	23.4 msec	15.2 msec	9.3 msec	5.2 msec
JPEG	8.2 msec	4.8 msec	2.5 msec	1.2 msec

Decoding time for 11th Gen Intel(R) Core(TM) i5-1145G7E on Ubuntu 22.04 LTS:

codec / resolution	2560x1440	1920x1080	1280x720	640x512
H264	7.3 msec	4.8 msec	2.5 msec	1.3 msec
HEVC	7.4 msec	4.3 msec	2.2 msec	1.3 msec
JPEG	8.7 msec	5.2 msec	2.6 msec	1.3 msec

Versions

Table 1 - Library versions.

Version	Release date	What’s new
1.0.0	01.12.2022	First version.
2.0.0	29.09.2023	- Interface changes to VCodec. - Added decoding support. - Added JPEG support.
2.0.1	12.11.2023	- Frame class updated.
2.0.2	10.01.2023	- VCodec interface updated. - Examples updated. - Documentation updated.
2.0.3	25.04.2024	- Test application updated. - Documentation updated.
2.0.4	17.06.2024	- Documentation updated. - VCodec submodule updated.
2.1.0	10.07.2024	- CMake updated. - VCodec submodule updated. - Repository structure changed.
2.1.1	04.11.2024	- Updated VCodec interface with variable bitrate params.
2.1.2	03.04.2025	- Logger submodule update.
2.1.3	02.11.2025	- VCodec submodule update. - Documentation update.

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 which includes third-party libraries.
    Logger -------------------- Folder with Logger library source code.
    VCodec -------------------- Folder with VCodec library source code.
example ----------------------- Folder with simple example of VCodecOneVpl usage.
    CMakeLists.txt ------------ CMake file for example application.
    main.cpp ------------------ Source code file of example application.
test -------------------------- Folder with codec test application.
    CMakeLists.txt ------------ CMake file for transcode test application.
    main.cpp ------------------ Source code file of transcode test application.
src --------------------------- Folder with source code of the library.
    Impl ---------------------- Folder with implementation of video codec.
        VCodecOneVplImpl.cpp -- C++ implementation file.
        VCodecOneVplImpl.h ---- Header file which includes VCodecOneVplImpl class declaration.
    CMakeLists.txt ------------ CMake file of the library.
    VCodecOneVpl.cpp ---------- C++ implementation file.
    VCodecOneVpl.h ------------ Header file which includes VCodecOneVpl class declaration.
    VCodecOneVplVersion.h ----- Header file which includes version of the library.
    VCodecOneVplVersion.h.in -- CMake service file to generate version file.

VCodecOneVpl class description

VCodecOneVpl class declaration

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

namespace cr
{
namespace video
{
/**
 * @brief VCodecOneVpl class.
 */
class VCodecOneVplImpl : public VCodec
{
public:

    /// Class constructor.
    VCodecOneVplImpl();

    /// Class destructor.
    ~VCodecOneVplImpl();

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

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

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

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

getVersion method

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

static std::string getVersion();

This method can be used without a VCodecOneVpl class instance:

cout << "VCodecOneVpl class version: " << VCodecOneVpl::getVersion() << endl;

Console output:

VCodecOneVpl class version: 2.1.3

transcode method

The transcode(…) method encodes and decodes 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 Frame class object. To encode video, the src frame must have NV12 raw pixel format. To decode video data, the src frame must have a compressed pixel format (field fourcc of Frame class): HEVC, JPEG, or H264.
dst	Result Frame class object. To encode video data, the dst frame must have a compressed pixel format (field fourcc of Frame class): HEVC, JPEG, or H264. Conversely, when decoding, the dst frame must be NV12.

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

setParam method

The setParam(…) method sets new video codec parameter values. Method declaration:

bool setParam(VCodecParam id, float value) override;

Parameter	Description
id	Video codec parameter ID according to the VCodecParam enum.
value	Video codec parameter value.

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 VCodecOneVpl library.

Parameter	Access	Description
LOG_LEVEL	read / write	Logging mode. Values: 0 - Disable. 1 - Only file. 2 - Only terminal (console). 3 - File and terminal.
BITRATE_KBPS	read / write	Bitrate, kbps. Range: 10-1,000,000 kbps. Default: 5000 kbps. For H264 and H265 (HEVC) encoding.
MIN_BITRATE_KBPS	read / write	Not supported by the VCodecOneVpl library.
MAX_BITRATE_KBPS	read / write	Not supported by the VCodecOneVpl library.
BITRATE_MODE	read / write	Not supported by the VCodecOneVpl library.
QUALITY	read / write	Quality 0 (low quality) - 100 (maximum quality). Range: 0-100. Default: 50. For JPEG encoding.
FPS	read / write	Frames per second. Range: 1-1000. Default: 30. For H264 and H265 (HEVC) encoding.
GOP	read / write	GOP size (period of key frames). Range: 1-10,000. Default: 30. 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. Range: 0-2. Default: 0. Values: 0 - Baseline. 1 - Main. 2 - High.
TYPE	read / write	Not supported by the VCodecOneVpl library. Hardware encoding only.
CUSTOM_1	read / write	Not supported by the VCodecOneVpl library.
CUSTOM_2	read / write	Not supported by the VCodecOneVpl library.
CUSTOM_3	read / write	Not supported by the VCodecOneVpl library.

getParam method

The getParam(…) method returns the video codec parameter value. 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 is not supported.

executeCommand method

The executeCommand(…) method executes video codec commands. Version 2.1.3 doesn’t support commands. The method will return FALSE. Method declaration:

bool executeCommand(VCodecCommand id);

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

Returns: The method returns FALSE in any case.

The VCodec.h file of the VCodec library defines IDs for parameters (VCodecParam enum, table 2) 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	Not supported by the VCodecOneVpl library.
MAKE_KEY_FRAME	Not supported by the VCodecOneVpl library.

Build and connect to your project

Before building, you must install OneVPL on your system. Follow the Installation on Linux or Installation on Windows instructions. Typical commands to build the VCodecOneVpl library:

cd VCodecOneVpl
git submodule update --init --recursive
mkdir build
cd build
cmake ..
make

If you want to connect the VCodecOneVpl 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
    CMakeList.txt
    yourLib.h
    yourLib.cpp

Create a 3rdparty folder in your repository. Copy the VCodecOneVpl repository folder to the 3rdparty folder. The new structure of your repository:

CMakeLists.txt
src
    CMakeList.txt
    yourLib.h
    yourLib.cpp
3rdparty
    VCodecOneVpl

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(VCodecOneVpl)

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

CMakeLists.txt
src
    CMakeList.txt
    yourLib.h
    yourLib.cpp
3rdparty
    CMakeLists.txt
    VCodecOneVpl

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

target_link_libraries(${PROJECT_NAME} VCodecOneVpl)

Done!

Installation on Linux

There are several steps to launch VCodecOneVpl on Linux (tested on Ubuntu 22.04 LTS):

1. Install Ubuntu with the latest updates:

   sudo apt-get update
   sudo apt-get upgrade
   sudo reboot
   

2. Install LibVA:

   sudo apt-get install git cmake pkg-config meson libdrm-dev automake libtool
   cd Downloads
   git clone https://github.com/intel/libva.git
   cd libva
   ./autogen.sh --prefix=/usr --libdir=/usr/lib/x86_64-linux-gnu
   make
   sudo make install
   

3. Install gmmlib:

   cd Downloads
   git clone https://github.com/intel/gmmlib.git
   cd gmmlib
   mkdir build
   cd build
   cmake -DCMAKE_BUILD_TYPE=Release ..
   make -j"$(nproc)"
   sudo make install
   

4. Install intel media driver for VAAPI:

   cd Downloads
   git clone https://github.com/intel/media-driver.git
   mkdir build_media && cd build_media
   cmake ../media-driver
   make -j"$(nproc)"
   sudo make install
   

5. Install oneVPL-intel-gpu:

   cd Downloads
   git clone https://github.com/oneapi-src/oneVPL-intel-gpu onevpl-gpu
   cd onevpl-gpu
   mkdir build && cd build
   cmake ..
   make -j"$(nproc)"
   sudo make install
   

6. Install additional packages for oneVPL-intel-gpu:

   sudo apt update
   sudo apt install -y gpg-agent wget
   wget -qO - https://repositories.intel.com/gpu/intel-graphics.key | sudo gpg --dearmor --output /usr/share/keyrings/intel-graphics.gpg
   echo "deb [arch=amd64 signed-by=/usr/share/keyrings/intel-graphics.gpg] https://repositories.intel.com/gpu/ubuntu jammy/production/2328 unified" | sudo tee /etc/apt/sources.list.d/intel-gpu-jammy.list
   sudo apt update
   sudo apt install -y linux-headers-$(uname -r) flex bison intel-fw-gpu intel-i915-dkms xpu-smi
   sudo reboot 
   sudo apt install -y intel-opencl-icd intel-level-zero-gpu level-zero intel-media-va-driver-non-free libmfx1 libmfxgen1 libvpl2 libegl-mesa0 libegl1-mesa libegl1-mesa-dev libgbm1 libgl1-mesa-dev libgl1-mesa-dri libglapi-mesa libgles2-mesa-dev libglx-mesa0 libigdgmm12 libxatracker2 mesa-va-drivers mesa-vdpau-drivers mesa-vulkan-drivers va-driver-all vainfo hwinfo clinfo
   sudo apt install -y libigc-dev intel-igc-cm libigdfcl-dev libigfxcmrt-dev level-zero-dev
   

7. Install oneVPL:

   cd Downloads
   git clone https://github.com/oneapi-src/oneVPL.git
   cd oneVPL
   sudo script/bootstrap
   script/build
   sudo script/install
   

Installation on Windows

1. Install oneVPL:

   git clone https://github.com/oneapi-src/oneVPL.git
   cd oneVPL
   script/bootstrap.bat
   script/build.bat
   script/install.bat
   

Simple example

This example application generates an image color pattern with a moving rectangle, encodes it with the HEVC codec, and writes the compressed data to a binary file “out.hevc”. The example shows how to create codec objects and how to encode video frames:

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

int main(void)
{
    // Set codec parameters.
    cr::video::VCodec* videoCodec = new cr::video::VCodecOneVpl();
    videoCodec->setParam(cr::video::VCodecParam::BITRATE_KBPS, 7500);
    videoCodec->setParam(cr::video::VCodecParam::GOP, 30);
    videoCodec->setParam(cr::video::VCodecParam::FPS, 30);

    // Create NV12 frame and fill color planes by random values.
    const int width = 1280;
    const int height = 720;
    cr::video::Frame frameNv12(width, height, cr::video::Fourcc::NV12);
    for (uint32_t i = 0; i < frameNv12.size; ++i)
        frameNv12.data[i] = (uint8_t)i;

    // Create output HEVC frame.
    cr::video::Frame frameHEVC(width, height, cr::video::Fourcc::HEVC);

    // Create output file.
    FILE *outputFile = fopen("out.hevc", "w+b");

    // Params for moving object.
    int objectWidth = 128;
    int objectHeight = 128;
    int directionX = 1;
    int directionY = 1;
    int objectX = width / 4;
    int objectY = height / 2;

    // Encode and record 200 frames.
    for (uint32_t n = 0; n < 200; ++n)
    {
        // Draw moving object.
        memset(frameNv12.data, 128, width * height);
        for (int y = objectY; y < objectY + objectHeight; ++y)
            for (int x = objectX; x < objectX + objectHeight; ++x)
                frameNv12.data[y * width + x] = 255;
        objectX += directionX;
        objectY += directionY;
        if (objectX >= width - objectWidth - 5 || objectX <= objectWidth + 5)
            directionX = -directionX;
        if (objectY >= height - objectHeight - 5 || objectY <= objectHeight + 5)
            directionY = -directionY;

        // Encode.
        if (!videoCodec->transcode(frameNv12, frameHEVC))
        {
            std::cout << "Can't encode frame" << std::endl;
            continue;
        }

        // Write to file.
        fwrite(frameHEVC.data, frameHEVC.size, 1, outputFile);  
    }

    // Close file.
    fclose(outputFile);

    return 1;
}

Test application

The test application (VCodecOneVpl/test/main.cpp) for the VCodecOneVpl 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”, and decompresses them. The application shows encoding and decoding time for each video frame. To run the application, perform the following commands on Linux or simply run VCodecOneVplTest.exe on Windows:

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

After starting, you will see the following output:

====================================
VCodecOneVpl v2.1.1 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:

====================================
VCodecOneVpl v2.1.1 test
====================================

Enter Encoder type (0 - JPEG, 1 - H264, 2 - HEVC) : 1
Default params:
Bitrate, kbps 6000
FPS: 30
GOP size: 30
Video width 1920
Video height 1080
H264 Profile: BASELINE
Use default params (0 - no, 1 - yes) :

When parameters are chosen, the test application will create an out.h264 file and start writing encoded frames until stopped. The user can set custom parameters (video resolution, bitrate, GOP size, and H264 profile). If the JPEG codec is chosen, you will see the following message:

Enter Encoder type (0 - JPEG, 1 - H264, 2 - HEVC) : 1
Default params:
Bitrate, kbps 6000
FPS: 30
GOP size: 30
Video width 1920
Video height 1080
H264 Profile: 0
Use default params (0 - no, 1 - yes) : 0
Set video width : 1280
Set video height : 720
Set bitrate, kbps : 2000
Set GOP size : 30
Set FPS : 30
Set profile (0 - BASELINE, 1 - MAIN, 2 - HIGH): 0
Set number frames: 100

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, and decoding time:

Data size 1382400 / 6579   encoding time  578601 us / decoding time 411758 us
Data size 1382400 / 157   encoding time  8536 us / decoding time 6739 us
Data size 1382400 / 160   encoding time  6291 us / decoding time 2202 us
Data size 1382400 / 167   encoding time  3667 us / decoding time 3988 us
Data size 1382400 / 166   encoding time  4124 us / decoding time 3744 us
Data size 1382400 / 161   encoding time  2970 us / decoding time 4891 us
Data size 1382400 / 186   encoding time  3133 us / decoding time 1781 us

---

Table of contents