vcodec_web_logo

VCodec interface C++ library

v2.2.1

Overview
Versions
Library files
VCodec interface class description
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