VSourceFile C++ library

v1.1.0

Table of contents

• Overview
• Versions
• Library files
• VSourceFile class description
  • VSourceFile class declaration
  • getVersion method
  • openVSource method
  • initVSource method
  • isVSourceOpen method
  • closeVSource method
  • getFrame method
  • setParam method
  • getParam method
  • getParams method
  • executeCommand method
  • encodeSetParamCommand method of VSource interface class
  • encodeCommand method of VSource interface class
  • decodeCommand method of VSource interface class
  • decodeAndExecuteCommand method
• Data structures
  • VSourceCommand enum
  • VSourceParam enum
• VSourceParams class description
  • VSourceParams class declaration
  • Serialize video source params
  • Deserialize video source params
  • Read params from JSON file and write to JSON file
• Build and connect to your project
• Simple example

Overview

VSourceFile C++ library provides compressed video frame capture from encoded H264, HEVC and JPEG (*.h264, *.hevc, *.mjpeg) video files. The library inherits interface from the open source VSource interface class. The VSource.h file contains data structures: VSourceParams class, VSourceCommand enum, VSourceParam enum and includes VSource class declaration. The VSourceParams class contains video source parameters and methods to encode (serialize) and decode (deserialize) video source params. The VSourceCommand enum contains IDs of commands supported by the VSource class. The VSourceParam enum contains IDs of parameters supported by the VSource class. VSourceFile depends on libraries: VSource interface class (provides interface for video sources, source code included, Apache 2.0 license) and the open source Logger library (provides methods to write logs, source code included, Apache 2.0 license). The library supports the C++17 standard and automatically loops video files when reaching the end.

Versions

Table 1 - Library versions.

Version	Release date	What’s new
1.0.0	29.11.2023	First version
1.0.1	15.01.2024	- Submodules updated.
1.0.2	20.03.2024	- VSource class updated. - Logger class updated. - Documentation updated.
1.0.3	20.05.2024	- VSource class updated. - Logger class updated. - Documentation updated.
1.0.4	15.07.2024	- VSource class updated. - Logger class updated. - CMake updated. - Example added.
1.0.5	03.04.2025	- Logger submodule update.
1.0.6	25.07.2025	- Fix frame interval initialization in openVSource method.
1.1.0	16.09.2025	- Add JPEG support.

Library files

The library is supplied as source code only. The user will be 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 which includes third-party libraries.
    Logger ------------------- Folder with Logger library source code.
    VSource ------------------ Folder with VSource library source code.
example ---------------------- Folder with example application.
    CMakeLists.txt ----------- CMake file for example application.
    main.cpp ----------------- Source code of example application.
src -------------------------- Folder with source code of the library.
    CMakeLists.txt ----------- CMake file of the library.
    VSourceFile.cpp ---------- C++ implementation file.
    VSourceFile.h ------------ Main library header file.
    VSourceFileVersion.h ----- Header file which includes version of the library.
    VSourceFileVersion.h.in -- CMake service file to generate version header.

VSourceFile class description

VSourceFile class declaration

VSourceFile class is declared in VSourceFile.h file. Class declaration:

namespace cr
{
namespace video
{
/// Video capture from encoded video files class.
class VSourceFile : public VSource
{
public:

    /// Class constructor.
    VSourceFile();

    /// Class destructor.
    ~VSourceFile();

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

    /// Open video source.
    bool openVSource(std::string& initString) override;

    /// Init video source.
    bool initVSource(VSourceParams& params) override;

    /// Get open status.
    bool isVSourceOpen() override;

    /// Close video source.
    void closeVSource() override;

    /// Get new video frame.
    bool getFrame(Frame& frame, int32_t timeoutMsec = 0) override;

    /// Set video source parameter.
    bool setParam(VSourceParam id, float value) override;

    /// Get video source param value.
    float getParam(VSourceParam id) override;

    /// Get video source params structure.
    void getParams(VSourceParams& params) override;

    /// Execute command.
    bool executeCommand(VSourceCommand id) override;
            
    /// Decode and execute command.
    bool decodeAndExecuteCommand(uint8_t* data, int size) override;
};
}
}

getVersion method

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

static std::string getVersion();

Method can be used without VSourceFile class instance:

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

Console output:

VSourceFile class version: 1.1.0

openVSource method

The openVSource(…) method initializes video source. Instead of openVSource(…) method user can call initVSource(…) method. Method declaration:

bool openVSource(std::string& initString) override;

Parameter	Value
initString	Initialization string. Valid formats: ;;; ;; (by default fps == 30) (by default width == 1280, height == 720, fps == 30). Supported file extensions: .h264, .264, .h265, .hevc, .jpg, .jpeg, .mjpg, .mjpeg

Returns: TRUE if the video source open or FALSE if not.

initVSource method

The initVSource(…) method initializes video source by a set of parameters. Instead of initVSource(…) method user can call openVSource(…) method. Method declaration:

bool initVSource(VSourceParams& params) override;

Parameter	Value
params	VSourceParams class object. The video source should set parameters according to the params structure. The source field must contain the full name of the video file. The method will combine fields source, width, height and fps to create an initialization string and will call the openVSource(…) method.

Returns: TRUE if the video source initialized or FALSE if not.

isVSourceOpen method

The isVSourceOpen() method returns video source initialization status. The initialization status is also included in the VSourceParams class. Method declaration:

bool isVSourceOpen() override;

Returns: TRUE if the video source open (initialized) or FALSE if not.

closeVSource method

The closeVSource() method is intended to close the video source. Method declaration:

void closeVSource() override;

getFrame method

The getFrame(…) method is intended to get input video frames. The video source automatically restarts from the beginning when reaching the end of the file, creating a continuous loop. Method declaration:

bool getFrame(Frame& frame, int32_t timeoutMsec = 0) override;

Parameter	Value
frame	Output video frame (see Frame class description). Depending on the file format (.h264/.264 / .h265/.hevc / .jpg/.jpeg/.mjpg/.mjpeg), the output pixel format will be H264, HEVC or JPEG. The resolution of the output video frame will be equivalent to the width and height parameters set by the user in the openVSource(…) or initVSource(…) methods.
timeoutMsec	Timeout to wait for new frame data: - timeoutMsec == -1 - Method will wait endlessly until new data arrives. - timeoutMsec == 0 - Method will only check if new data exists. - timeoutMsec > 0 - Method will wait for new data for the specified time. The frame period will be equivalent to the fps parameter set by the user in the openVSource(…) or initVSource(…) methods. Note: The library implements frame rate control internally by sleeping between frames to maintain the desired FPS.

Returns: TRUE if new data exists and is copied or FALSE if not.

setParam method

The setParam(…) method is designed to set new video source parameter values. The method will set parameters to the device. The method can be used only after video source initialization. Note: the library supports only the LOG_LEVEL parameter to set. Method declaration:

bool setParam(VSourceParam id, float value) override;

Parameter	Description
id	Video source parameter ID according to VSourceParam enum.
value	Video source parameter value.

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

getParam method

The getParam(…) method returns video source parameter values. The method will request parameters from the device. The method can be used only after video source initialization. Method declaration:

float getParam(VSourceParam id) override;

Parameter	Description
id	Video source parameter ID according to the VSourceParam enum. The library supports only parameters to obtain: LOG_LEVEL, WIDTH, HEIGHT, CYCLE_TIME_MKS, FPS and IS_OPEN.

Returns: parameter value or -1 if the parameter is not supported.

getParams method

The getParams(…) method returns all video source parameters in the form of a VSourceParams class object. The getParams(…) method call is thread-safe. This means that the getParams(…) method is thread-safe and can be safely called from any thread. Method declaration:

virtual void getParams(VSourceParams& params) = 0;

Parameter	Description
params	VSourceParams class object.

executeCommand method

The executeCommand(…) method is designed to execute video source action commands. The library does not support commands. Method declaration:

bool executeCommand(VSourceCommand id) override;

Parameter	Description
id	Video source command ID according to VSourceCommand enum.

Returns: always returns FALSE.

encodeSetParamCommand method of VSource interface class

The encodeSetParamCommand(…) static method is designed to encode commands to change any parameter in a remote video source. To control a video source remotely, the developer has to design his own protocol and according to it encode the command and deliver it over the communication channel. To simplify this, the VSource class contains static methods for encoding the control commands. The VSource class provides two types of commands: a parameter change command (SET_PARAM) and an action command (COMMAND). encodeSetParamCommand(…) is designed to encode SET_PARAM commands. Method declaration:

static void encodeSetParamCommand(uint8_t* data, int& size, VSourceParam id, float value);

Parameter	Description
data	Pointer to data buffer for encoded command. Must have size >= 11 bytes.
size	Size of encoded data. Will be 11 bytes.
id	Parameter ID according to VSourceParam enum.
value	Parameter value.

encodeSetParamCommand(…) is static and used without a VSource class instance. This method is used on the client side (control system). Command encoding example:

// Buffer for encoded data.
uint8_t data[11];
// Size of encoded data.
int size = 0;
// Random parameter value.
float outValue = (float)(rand() % 20);
// Encode command.
VSource::encodeSetParamCommand(data, size, VSourceParam::EXPOSURE, outValue);

encodeCommand method of VSource interface class

The encodeCommand(…) static method is designed to encode commands to perform action commands in a remote video source. To control a video source remotely, the developer has to design his own protocol and according to it encode the command and deliver it over the communication channel. To simplify this, the VSource class contains static methods for encoding the control commands. The VSource class provides two types of commands: a parameter change command (SET_PARAM) and an action command (COMMAND). encodeCommand(…) is designed to encode COMMAND (action commands). Method declaration:

static void encodeCommand(uint8_t* data, int& size, VSourceCommand id);

Parameter	Description
data	Pointer to data buffer for encoded command. Must have size >= 7 bytes.
size	Size of encoded data. Will be 7 bytes.
id	Command ID according to VSourceCommand enum.

encodeCommand(…) is static and used without a VSource class instance. This method is used on the client side (control system). Command encoding example:

// Buffer for encoded data.
uint8_t data[11];
// Size of encoded data.
int size = 0;
// Encode command.
VSource::encodeCommand(data, size, VSourceCommand::RESTART);

decodeCommand method of VSource interface class

The decodeCommand(…) static method is designed to decode action commands on the video source side (edge device). Method declaration:

static int decodeCommand(uint8_t* data, int size, VSourceParam& paramId, VSourceCommand& commandId, float& value);

Parameter	Description
data	Pointer to input command.
size	Size of command. Should be 11 bytes for SET_PARAM and 7 bytes for COMMAND.
paramId	Parameter ID according to VSourceParam enum. After decoding a SET_PARAM command the method will return the parameter ID.
commandId	Command ID according to VSourceCommand enum. After decoding a COMMAND the method will return the command ID.
value	Parameter value (after decoding a SET_PARAM command).

Returns: 0 - in case of decoding a COMMAND, 1 - in case of decoding a SET_PARAM command or -1 in case of errors.

decodeAndExecuteCommand method

The decodeAndExecuteCommand(…) method decodes and executes commands on the video source side. The library doesn’t support decoding and executing commands. Method declaration:

bool decodeAndExecuteCommand(uint8_t* data, int size) override;

Parameter	Description
data	Pointer to input command.
size	Size of command. Must be 11 bytes for SET_PARAM and 7 bytes for COMMAND.

Returns: always returns FALSE.

Data structures

The VSource.h file defines IDs for parameters (VSourceParam enum) and IDs for commands (VSourceCommand enum).

VSourceCommand enum

Enum declaration:

enum class VSourceCommand
{
    /// Restart.
    RESTART = 1
};

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

Command	Description
RESTART	Not supported by the library.

VSourceParam enum

Enum declaration:

enum class VSourceParam
{
    /// [read/write] Logging mode. Values: 0 - Disable, 1 - Only file,
    /// 2 - Only terminal, 3 - File and terminal.
    LOG_LEVEL = 1,
    /// [read/write] Frame width. User can set frame width before initialization
    /// or after. Some video source classes may set width automatically.
    WIDTH,
    /// [read/write] Frame height. User can set frame height before
    /// initialization or after. Some video source classes may set height
    /// automatically.
    HEIGHT,
    /// [read/write] Gain mode. Value depends on implementation but it is
    /// recommended to keep default values: 0 - Manual control, 1 - Auto.
    GAIN_MODE,
    /// [read/write] Gain value. Value: 0(min for particular video source class)
    /// - 65535(max for particular video source class).
    GAIN,
    /// [read/write] Exposure mode. Value depends on implementation but it is
    /// recommended to keep default values: 0 - Manual control, 1 - Auto.
    EXPOSURE_MODE,
    /// [read/write] Exposure value. Value: 0(min for particular video source
    /// class) - 65535(max for particular video source class).
    EXPOSURE,
    /// [read/write] Focus mode. Value depends on implementation but it is
    /// recommended to keep default values: 0 - Manual control, 1 - Auto.
    FOCUS_MODE,
    /// [read/write] Focus position. Value: 0(full near) - 65535(full far).
    FOCUS_POS,
    /// [read only] Video capture cycle time. **VSource** class sets this value
    /// automatically. This parameter means time interval between two captured
    /// video frame.
    CYCLE_TIME_MKS,
    /// [read/write] FPS. User can set frame FPS before initialization or after.
    /// Some video source classes may set FPS automatically.
    FPS,
    /// [read only] Open flag. 0 - not open, 1 - open.
    IS_OPEN,
    /// Region of interest upper left corner x coordinate.
    ROI_X,
    /// Region of interest upper left corner x coordinate.
    ROI_Y,
    /// Region of interest upper left corner x coordinate.
    ROI_WIDTH,
    /// Region of interest upper left corner x coordinate.
    ROI_HEIGHT,
    /// [read/write] Custom parameter. Depends on implementation.
    CUSTOM_1,
    /// [read/write] Custom parameter. Depends on implementation.
    CUSTOM_2,
    /// [read/write] Custom parameter. Depends on implementation.
    CUSTOM_3
};

Table 3 - Video source params description. Some params may be unsupported by particular video source classes.

Parameter	Access	Description
LOG_LEVEL	read / write	Logging mode. Values: 0 - Disable, 1 - Only file, 2 - Only terminal, 3 - File and terminal.
WIDTH	read / write	Not supported by the library to set, only read.
HEIGHT	read / write	Not supported by the library to set, only read.
GAIN_MODE	read / write	Not supported by the library.
GAIN	read / write	Not supported by the library.
EXPOSURE_MODE	read / write	Not supported by the library.
EXPOSURE	read / write	Not supported by the library.
FOCUS_MODE	read / write	Not supported by the library.
FOCUS_POS	read / write	Not supported by the library.
CYCLE_TIME_MKS	read only	Frame cycle time, microseconds. The frame period will be equivalent to the fps parameter set by the user in the openVSource(…) or initVSource(…) methods. This value is calculated based on the actual frame delivery timing.
FPS	read / write	Not supported by the library to set, only read. The library maintains the FPS set during initialization.
IS_OPEN	read only	Open flag. 0 - not open, 1 - open.
ROI_X	read / write	Not supported by the library.
ROI_Y	read / write	Not supported by the library.
ROI_WIDTH	read / write	Not supported by the library.
ROI_HEIGHT	read / write	Not supported by the library.
CUSTOM_1	read / write	Not supported by the library.
CUSTOM_2	read / write	Not supported by the library.
CUSTOM_3	read / write	Not supported by the library.

VSourceParams class description

VSourceParams class declaration

VSourceParams class is used for video source initialization (initVSource(…) method) or to get all actual params (getParams(…) method). Also VSourceParams provides structure to write/read params from JSON files (JSON_READABLE macro, see ConfigReader class description) and provides methods to encode and decode params. Class declaration:

class VSourceParams
{
public:
    /// Logging mode. Values: 0 - Disable, 1 - Only file,
    /// 2 - Only terminal, 3 - File and terminal.
    int logLevel{0};
    /// Video source: file, video stream, video device, camera num, etc.
    std::string source{"/dev/video0"};
    /// FOURCC: RGB24, BGR24, YUYV, UYVY, GRAY, YUV24, NV12, NV21, YU12, YV12.
    /// Value says to video source class which pixel format preferable for
    /// output video frame. Particular video source class can ignore this params
    /// during initialization. Parameters should be set before initialization.
    std::string fourcc{"YUYV"};
    /// Frame width. User can set frame width before initialization
    /// or after. Some video source classes may set width automatically.
    int width{1920};
    /// Frame height. User can set frame height before
    /// initialization or after. Some video source classes may set height
    /// automatically.
    int height{1080};
    /// Gain mode. Value depends on implementation but it is
    /// recommended to keep default values: 0 - Manual control, 1 - Auto.
    int gainMode{1};
    /// Gain value. Value: 0(min for particular video source class)
    /// - 65535(max for particular video source class).
    int gain{0};
    /// Exposure mode. Value depends on implementation but it is
    /// recommended to keep default values: 0 - Manual control, 1 - Auto.
    int exposureMode{1};
    /// Exposure value. Value: 0(min for particular video source
    /// class) - 65535(max for particular video source class).
    int exposure{1};
    /// Focus mode. Focus mode. Value depends on implementation but it is
    /// recommended to keep default values: 0 - Manual control, 1 - Auto.
    int focusMode{1};
    /// Focus position. Value: 0(full near) - 65535(full far).
    int focusPos{0};
    /// Video capture cycle time. **VSource** class sets this value
    /// automatically. This parameter means time interval between two captured
    /// video frame.
    int cycleTimeMks{0};
    /// FPS. User can set frame FPS before initialization or after.
    /// Some video source classes may set FPS automatically.
    float fps{0};
    /// Open flag. 0 - not open, 1 - open.
    bool isOpen{false};
    /// Region of interest upper left corner x coordinate.
    int roiX{0};
    /// Region of interest upper left corner y coordinate.
    int roiY{0};
    /// Region of interest width.
    int roiWidth{0};
    /// Region of interest height.
    int roiHeight{0};
    /// Custom parameter. Depends on implementation.
    float custom1{0.0f};
    /// Custom parameter. Depends on implementation.
    float custom2{0.0f};
    /// Custom parameter. Depends on implementation.
    float custom3{0.0f};

    JSON_READABLE(VSourceParams, logLevel, source, fourcc,
                  width, height, gainMode, exposureMode,
                  focusMode, fps, custom1, custom2, custom3);

    /// operator =
    VSourceParams& operator= (const VSourceParams& src);

    /// Encode params.
    bool encode(uint8_t* data, int bufferSize, int& size,
                VSourceParamsMask* mask = nullptr);

    /// Decode params.
    bool decode(uint8_t* data, int dataSize);
};

Table 4 - VSourceParams class fields description.

Field	type	Description
logLevel	int	Logging mode. Values: 0 - Disable, 1 - Only file, 2 - Only terminal, 3 - File and terminal.
source	string	Video file name with extensions .h264, .264, .h265, .hevc, .jpg, .jpeg, .mjpg, or .mjpeg.
fourcc	string	Not supported by the library.
width	int	Frame width. User can set frame width before initialization.
height	int	Frame height. User can set frame height before initialization.
gainMode	int	Not supported by the library.
gain	int	Not supported by the library.
exposureMode	int	Not supported by the library.
exposure	int	Not supported by the library.
focusMode	int	Not supported by the library.
focusPos	int	Not supported by the library.
cycleTimeMks	int	Frame cycle time, microseconds. The frame period will be equivalent to the fps parameter set by the user in the openVSource(…) or initVSource(…) methods. This value is calculated based on the actual frame delivery timing.
fps	float	FPS (frames per second). User can set frame FPS before initialization. The library uses this value to control frame delivery timing.
isOpen	bool	Open flag. false - not open, true - open.
roiX	int	Not supported by the library.
roiY	int	Not supported by the library.
roiWidth	int	Not supported by the library.
roiHeight	int	Not supported by the library.
custom1	float	Not supported by the library.
custom2	float	Not supported by the library.
custom3	float	Not supported by the library.

Note: VSourceParams class fields listed in Table 4 must reflect params set/get by methods setParam(…) and getParam(…).

Serialize video source params

VSourceParams class provides method encode(…) to serialize video source params (fields of VSourceParams class, see Table 4). Serialization of video source params is necessary in case when you need to send video source params via communication channels. The method doesn’t encode fields: initString and fourcc. The method provides options to exclude particular parameters from serialization. To do this the method inserts a binary mask (2 bytes) where each bit represents a particular parameter and the decode(…) method recognizes it. Method declaration:

bool encode(uint8_t* data, int bufferSize, int& size, VSourceParamsMask* mask = nullptr);

Parameter	Value
data	Pointer to data buffer.
size	Size of encoded data. 79 bytes by default.
bufferSize	Data buffer size. If buffer size is smaller than required, the buffer will be filled with fewer parameters.
mask	Parameters mask - pointer to VSourceParamsMask structure. VSourceParamsMask (declared in VSource.h file) determines flags for each field (parameter) declared in VSourceParams class. If the user wants to exclude any parameters from serialization, he can put a pointer to the mask. If the user wants to exclude a particular parameter from serialization, he should set the corresponding flag in the VSourceParamsMask structure.

VSourceParamsMask structure declaration:

struct VSourceParamsMask
{
    bool logLevel{true};
    bool width{true};
    bool height{true};
    bool gainMode{true};
    bool gain{true};
    bool exposureMode{true};
    bool exposure{true};
    bool focusMode{true};
    bool focusPos{true};
    bool cycleTimeMks{true};
    bool fps{true};
    bool isOpen{true};
    bool roiX{true};
    bool roiY{true};
    bool roiWidth{true};
    bool roiHeight{true};
    bool custom1{true};
    bool custom2{true};
    bool custom3{true};
};

Example without parameters mask:

// Prepare random params.
VSourceParams in;
in.initString = "any string";
in.logLevel = 0;

// Encode data.
uint8_t data[1024];
int size = 0;
in.encode(data, 1024, size);
cout << "Encoded data size: " << size << " bytes" << endl;

Example with parameters mask:

// Prepare random params.
VSourceParams in;
in.initString = "any string";
in.logLevel = 0;

// Prepare params mask.
VSourceParamsMask mask;
mask.logLevel = false; // Exclude logLevel. Others by default.

// Encode data.
uint8_t data[1024];
int size = 0;
in.encode(data, 1024, size, &mask);
cout << "Encoded data size: " << size << " bytes" << endl;

Deserialize video source params

VSourceParams class provides method decode(…) to deserialize video source params (fields of VSourceParams class, see Table 4). Deserialization of video source params is necessary in case when you need to receive video source params via communication channels. The method doesn’t decode fields: initString and fourcc. The method automatically recognizes which parameters were serialized by the encode(…) method. Method declaration:

bool decode(uint8_t* data, int dataSize);

Parameter	Value
data	Pointer to encoded data buffer. Data size should be at least 62 bytes.
dataSize	Size of data.

Returns: TRUE if data decoded (deserialized) or FALSE if not.

Example:

// Encode data.
VSourceParams in;
uint8_t data[1024];
int size = 0;
in.encode(data, 1024, size);

cout << "Encoded data size: " << size << " bytes" << endl;

// Decode data.
VSourceParams out;
if (!out.decode(data, size))
    cout << "Can't decode data" << endl;

Read params from JSON file and write to JSON file

VSource library depends on the ConfigReader library which provides methods to read params from JSON files and to write params to JSON files. Example of writing and reading params to JSON file:

// Write params to file.
VSourceParams in;
cr::utils::ConfigReader inConfig;
inConfig.set(in, "vSourceParams");
inConfig.writeToFile("TestVSourceParams.json");

// Read params from file.
cr::utils::ConfigReader outConfig;
if(!outConfig.readFromFile("TestVSourceParams.json"))
{
    cout << "Can't open config file" << endl;
    return false;
}

TestVSourceParams.json will look like:

{
    "vSourceParams": {
        "custom1": 150.0,
        "custom2": 252.0,
        "custom3": 30.0,
        "exposureMode": 226,
        "focusMode": 89,
        "fourcc": "skdfjhvk",
        "fps": 206.0,
        "gainMode": 180,
        "height": 61,
        "logLevel": 17,
        "roiHeight": 249,
        "roiWidth": 167,
        "roiX": 39,
        "roiY": 223,
        "source": "alsfghljb",
        "width": 35
    }
}

Build and connect to your project

Typical commands to build VSourceFile library:

cd VSourceFile
mkdir build
cd build
cmake ..
make

If you want to connect the VSourceFile 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 3rdparty folder in your repository and copy VSourceFile repository folder there. New structure of your repository:

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

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)

################################################################################
## CONFIGURATION
## 3rd-party submodules configuration
################################################################################
SET(${PARENT}_SUBMODULE_VSOURCE_FILE                    ON  CACHE BOOL "" FORCE)
if (${PARENT}_SUBMODULE_VSOURCE_FILE )
    SET(${PARENT}_VSOURCE_FILE                          ON  CACHE BOOL "" FORCE)
    SET(${PARENT}_VSOURCE_FILE_EXAMPLE                  OFF CACHE BOOL "" FORCE)
endif()

################################################################################
## INCLUDING SUBDIRECTORIES
## Adding subdirectories according to the 3rd-party configuration
################################################################################
if (${PARENT}_SUBMODULE_VSOURCE_FILE )
    add_subdirectory(VSourceFile)
endif()

File 3rdparty/CMakeLists.txt adds folder VSourceFile to your project and excludes the example from compiling (by default the example is excluded from compiling if VSourceFile is included as a sub-repository). Your repository new structure will be:

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

Next you need to include folder 3rdparty in the main CMakeLists.txt file of your repository. Add string at the end of your main CMakeLists.txt:

add_subdirectory(3rdparty)

Next you have to include the VSourceFile library in your src/CMakeLists.txt file:

target_link_libraries(${PROJECT_NAME} VSourceFile)

Done!

Simple example

Example shows how to initialize a video source with generic VSource interface and how to capture video frames in a loop. Also the example shows how to get parameter values (video capture cycle time). Example:

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

int main(void)
{
    // Init video source.
    std::string initString = "test.h264;1280;720;30";
    cr::video::VSource* source = new cr::video::VSourceFile();
    if (!source->openVSource(initString))
        return -1;

    // Main loop.
    cr::video::Frame frame;
    while (true)
    {
        // Wait new frame 1 sec.
        if (!source->getFrame(frame, 1000))
        {
            std::cout << "No input frame" << std::endl;
            continue;
        }

        std::cout << "New frame " << frame.frameId <<
        " (" << frame.width << "x" << frame.height << ") " <<
        frame.size << " bytes cycle time " <<
        (int)source->getParam(cr::video::VSourceParam::CYCLE_TIME_MKS) <<
        " us" << std::endl; 
    }

    return 1;
}

---

Table of contents