VCodec interface C++ library

v2.2.1

Table of contents

• Overview
• Versions
• Library files
• VCodec interface class description
  • VCodec interface class declaration
  • transcode method
  • setParam method
  • getParam method
  • executeCommand method
• Data structures
  • VCodecCommand enum
  • VCodecParam enum
• Build and connect to your project

Overview

The VCodec C++ library provides a standard interface and defines data structures and rules for different video codecs (video encoding and decoding). The VCodec interface class does nothing; it just provides an interface. Different video codec classes inherit the interface from the VCodec C++ class. The VCodec.h file contains the VCodecCommand enum, VCodecParam enum, and VCodec class declaration. The VCodecCommand enum contains IDs of commands supported by VCodec class. The VCodecParam enum contains IDs of parameters supported by VCodec class. All video codecs should include all parameters and commands listed in the VCodec.h file. The VCodec class depends on the Frame class, which determines video frame structures. The video codec interface supports only 8-bit depth input pixel formats. It uses the C++17 standard. The library is licensed under the Apache 2.0 license.

Versions

Table 1 - Library versions.

Version	Release date	What’s new
1.0.0	14.06.2023	First version.
1.1.0	20.06.2023	- Added new parameter.
1.1.1	28.06.2023	- Frame submodule updated. - Documentation updated. - License added. - Repository made public. - Added new parameters.
1.1.2	02.08.2023	- Frame submodule updated.
2.1.1	14.12.2023	- Virtual destructor added. - Frame submodule updated.
2.1.2	14.12.2023	- Frame submodule updated. - Documentation updated.
2.1.3	25.04.2024	- Documentation updated.
2.1.4	16.05.2024	- Documentation updated. - Frame submodule updated.
2.1.5	06.07.2024	- Frame class updated. - CMake updated.
2.2.0	30.10.2024	- Add new bitrate parameters.
2.2.1	02.11.2025	- Fix code mistakes. - Fix documentation mistakes.

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.
    Frame --------------- Folder with Frame library files.
src --------------------- Folder with library source code.
    CMakeLists.txt ------ CMake file of the library.
    VCodec.h ------------ Main library header file.
    VCodecVersion.h ----- Header file with library version.
    VCodecVersion.h.in -- File for CMake to generate version header.
    VCodec.cpp ---------- C++ implementation file.

VCodec interface class description

VCodec interface class declaration

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

class VCodec
{
public:

    /// Class destructor.
    virtual ~VCodec();

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

    /// Encode/decode.
    virtual bool transcode(Frame& src, Frame& dst) = 0;

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

    /// Get parameter.
    virtual float getParam(VCodecParam id) = 0;

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

getVersion method

The getVersion() method returns a string of the current version of the VCodec class. A particular video codec class can have its own getVersion() method. Method declaration:

static std::string getVersion();

This method can be used without a VCodec class instance:

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

Console output:

VCodec class version: 2.2.1

transcode method

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

virtual bool transcode(Frame& src, Frame& dst) = 0;

Parameter	Value
src	Source video frame (see Frame class description). To encode video data, the src frame must have RAW pixel data (field fourcc of Frame class): RGB24, BGR24, YUYV, UYVY, GRAY, YUV24, NV12 (default format for codec), NV21, YU12, or YV12. To decode video data, the src frame must have compressed pixel format (field fourcc of Frame class): JPEG, H264, or HEVC. A particular video codec can support a limited RAW input pixel format or only one (usually only NV12). When possible, the video codec should accept all supported RAW pixel formats and should do pixel format conversion internally if necessary. Also, a particular video codec can support all, few, or just one compressed pixel format. When possible, the video codec should support all compressed pixel formats to encode/decode.
dst	Result video frame (see Frame class description). For decoding, the output pixel format can be set automatically by the particular video codec. To encode a video frame, the user must set the fourcc field of the dst frame to the necessary output compressed format: JPEG, H264, or HEVC. The method will write decoded frame data (RAW pixel format) to the data field of the dst frame in case of decoding or will write compressed data in case of encoding.

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

setParam method

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

virtual bool setParam(VCodecParam id, float value) = 0;

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

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

getParam method

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

virtual float getParam(VCodecParam id) = 0;

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

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:

virtual bool executeCommand(VCodecCommand id) = 0;

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

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

Data structures

VCodec.h file defines IDs for parameters (VCodecParam enum) and IDs for commands (VCodecCommand enum).

VCodecCommand enum

Enum declaration:

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

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

Command	Description
RESET	Reset video codec.
MAKE_KEY_FRAME	Command to generate key frame for H264 or H265(HEVC) codecs.

VCodecParam enum

Enum 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,
    /// [read/write] Custom parameter 1. Depends on implementation.
    CUSTOM_1,
    /// [read/write] Custom parameter 2. Depends on implementation.
    CUSTOM_2,
    /// [read/write] Custom parameter 3. Depends on implementation.
    CUSTOM_3
};
}
}

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

Parameter	Access	Description
LOG_LEVEL	read / write	Logging mode. Default values: 0 - Disable. 1 - Only file. 2 - Only terminal. 3 - File and terminal.
BITRATE_KBPS	read / write	Bitrate, 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	Minimum bitrate, kbps. For variable bitrate mode. For H264 and H265(HEVC) encoding.
MAX_BITRATE_KBPS	read / write	Maximum bitrate, kbps. For variable bitrate mode. For H264 and H265(HEVC) encoding.
BITRATE_MODE	read / write	Bitrate mode: 0 - constant bitrate, 1 - variable bitrate.
QUALITY	read / write	Quality 0(low quality)-100%(maximum quality). For JPEG encoding.
FPS	read / write	FPS. For H264 and H265 codecs. According to this value, FPS, and GOP size, the video codec calculates parameters for H264 or H265(HEVC) encoding.
GOP	read / write	GOP size (Period of key frames) for H264 or 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	Codec type. Depends on implementation. It can be type of backend. Some codecs may not support this parameter.
CUSTOM_1	read / write	Custom parameter. Depends on particular implementation.
CUSTOM_2	read / write	Custom parameter. Depends on particular implementation.
CUSTOM_3	read / write	Custom parameter. Depends on particular implementation.

Build and connect to your project

Typical commands to build VCodec library:

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

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

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

You can add the VCodec repository as a submodule with the following commands:

cd <your respository folder>
git submodule add https://github.com/ConstantRobotics-Ltd/VCodec.git 3rdparty/VCodec
git submodule update --init --recursive

In your repository folder, a 3rdparty/VCodec folder will be created, which contains files of the VCodec repository with the Frame sub-repository. Alternatively, you can copy the VCodec repository folder to the 3rdparty folder of your repository. The new structure of your repository:

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

Create a CMakeLists.txt file in the 3rdparty folder. The CMakeLists.txt file 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(VCodec)

The 3rdparty/CMakeLists.txt file adds the VCodec folder to your project. Your repository’s new structure will be:

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

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

target_link_libraries(${PROJECT_NAME} VCodec)

Done!

---

Table of contents