FormatConverter C++ library

v1.0.0

Table of contents

• Overview
• Versions
• Library files
• FormatConverter class description
  • FormatConverter class declaration
  • getVersion method
  • convert method
• Build and connect to your project

Overview

FormatConverter library is designed to convert pixel formats of images between each other. FormatConverter supports all uncompressed pixel formats (conversion between each other) listed in Fourcc enum (RGB24, BGR24, YUYV, UYVY, GRAY, YUV24, NV12, NV21, YU12, YV12) of Frame library (defines video frame object and pixel formats). FormatConverter library doesn’t have third-party dependencies. Main file FormatConverter.h contains declaration of FormatConverter class. The library uses C++17 standard and is compatible with Linux and Windows. The test application and benchmark application depend on FormatConverterOpenCv (for performance comparison) and OpenCV (for user interface). Pixel formats visualization:

Table 1 - Bytes layout of supported pixel formats. Example of 4x4 pixels image.

RGB24	BGR24
YUV24	GRAY
YUYV	UYVY
NV12	NV21
YU12	YV12

Versions

Table 1 - Library versions.

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

Library files

The library is supplied only by source code. The user is given 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 source code.
src ------------------------------ Folder with library source code.
    CMakeLists.txt --------------- CMake file of the library.
    FormatConverter.cpp ---------- C++ implementation file.
    FormatConverter.h ------------ Main library header file.
    FormatConverterVersion.h ----- Header file with library version.
    FormatConverterVersion.h.in -- Service CMake file to generate version file.
test ----------------------------- Folder for test application.
    CMakeLists.txt --------------- CMake file of the test application.
    main.cpp --------------------- Source C++ file of the test application.
benchmark ------------------------ Folder for benchmark application.
    3rdparty --------------------- Folder with third-party libraries.
        CMakeLists.txt ----------- CMake file to include third-party libraries.
        FormatConverterOpenCv ---- Source code of FormatConverterOpenCv library.
    CMakeLists.txt --------------- CMake file of the test application.
    main.cpp --------------------- Source C++ file of the test application.

FormatConverter class description

FormatConverter class declaration

FormatConverter.h file contains FormatConverter class declaration. Class declaration:

namespace cr
{
namespace video
{
/**
 * @brief Frame pixel format converter class.
 */
class FormatConverter
{
public:

    /// Get version string of FormatConverter class.
    static std::string getVersion();

    /// Convert pixel format.
    bool convert(Frame& src, Frame& dst);
};
}
}

getVersion method

The getVersion() method returns string of current version of FormatConverter class. Method declaration:

static std::string getVersion();

Method can be used without FormatConverter class instance. Example:

std::cout << "FormatConverter class version: " << cr::video::FormatConverter::getVersion();

Console output:

FormatConverter class version: 1.0.0

convert method

The convert(…) method intended to convert Frame class data between pixel formats. The method understands which pixel format to convert from based on the fourcc field of the Frame class objects. Method declaration:

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

Parameter	Description
src	Source Frame object. Method doesn’t support H264, HEVC and JPEG pixel formats.
dst	Destination Frame object. User must at least initialize fourcc field of destination Frame object. Method doesn’t support H264, HEVC and JPEG pixel formats.

Returns: TRUE if pixel format converted or FALSE if not.

Example:

// Init frame converter.
FormatConverter converter;

// Init source image filled by 0.
Frame src(640, 480, Fourcc::BGR24);

// Init output image.
Frame dst;
dst.fourcc = Fourcc::YUV24; // Inform converter about destination format.

// Convert.
converter.convert(src, dst);

Build and connect to your project

Before building, the user should install OpenCV library (used only for test application and benchmark) and additional libraries to build the project. Typical install commands for Linux:

sudo apt-get install build-essential cmake libopencv-dev

Typical commands to build FormatConverter library:

cd FormatConverter
mkdir build
cd build
cmake ..
make

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

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

Create folder 3rdparty in your repository folder and copy FormatConverter repository folder there. The new structure of your repository will be as follows:

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

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

File 3rdparty/CMakeLists.txt adds folder FormatConverter to your project and automatically excludes test application from compiling. The new structure of your repository will be:

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

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 have to include FormatConverter library in your src/CMakeLists.txt file:

target_link_libraries(${PROJECT_NAME} FormatConverter)

Done!

---

Table of contents