vsource_v4l2_web_logo

VSourceV4L2 C++ library

v2.3.4

Table of contents

Overview

VSourceV4L2 C++ library provides video capture and video source (V4L2 compatible video sources) control function based on V4L2 API. The library supports stepwise and discrete devices. The library inherits interface from the VSource interface class. VSource.h file contains data structures VSourceParams class (contains video source params and provides methods for serialization / deserialization params), VSourceCommand enum (describes video source action commands) and VSourceParam enum (describes video source params). VSourceV4L2.h file contains VSourceV4L2 class declaration and includes VSource.h. VSourceV4L2 depends on VSource interface class (provides interface for video sources, depends on the Frame and ConfigReader libraries) and the Logger library (provides method to write logs). The source code of these libraries is not included in the repository (see Build and connect to your project). The library provides auto detection of supported resolution, format and fps. If a device doesn’t support the requested pixel format, resolution or fps, the library sets the most appropriate parameters. The library is optimized for minimum capture latency: it always delivers the newest captured frame and drops outdated ones (see Capture behaviour). The library supports C++17 standard and requires Linux.

VSourceV4L2 is general-purpose software: it is not tied to any sector or application, and the developer of a program decides what the program does with it.

Versions

Table 1 - Library versions.

Version Release date What’s new
1.0.0 13.01.2022 - First version
1.1.0 20.06.2023 - Fixed bugs.
- Documentation updated.
1.2.0 29.06.2023 - Added new parameters.
- Documentation updated.
2.0.0 20.08.2023 - Added example and updated test application.
- Interface update according to VSource class.
- Added automatic detection supported format and automatic choosing right format during initialization.
2.0.1 29.08.2023 - Fixed stepwise camera support issue.
- Documentation updated.
2.0.2 30.08.2023 - Fixed stepwise camera pixel format setting.
2.0.3 17.11.2023 - Frame class updated.
2.0.4 17.11.2023 - Fixed initialization with string.
2.1.0 22.12.2023 - Region of interest support added.
2.1.1 27.12.2023 - Mistakes in ROI fixed.
2.1.2 09.01.2024 - Documentation updated.
2.1.3 24.04.2024 - Documentation updated.
- Submodules updated.
2.1.4 20.05.2024 - Documentation updated.
- Submodules updated.
2.1.5 16.07.2024 - CMake updated.
- Submodules updated.
2.1.6 13.11.2024 - Fix device initialization in test application.
2.2.0 03.03.2025 - Multi planar camera support is added.
- Direct resolution initialization support is added in case auto detection fails because of camera driver.
2.2.1 03.04.2025 - Logger submodule update.
2.2.2 30.04.2026 - Fixed MPLANE plane offset bug.
- Increased requested buffer count.
2.2.3 22.05.2026 - Fixed format check loop.
- Fixed log level indexes usage.
2.2.4 06.06.2026 - Fixed timeouts.
- Fixed first frame capture logic.
2.2.5 12.07.2026 - Fixed V4L2 structures reset.
2.3.0 28.08.2026 - Low latency frame delivery mechanism implemented.
- Fixed capture buffer handling for multi planar formats (per plane mapping).
- Added read back of format and frame rate granted by driver.
- Fixed output buffer overflow on format mismatch.
- Fixed payload size reporting for compressed formats.
- Fixed region of interest clamping and chroma plane cropping.
- Fixed endless wait mode of getFrame(…).
- Added WIDTH, HEIGHT, FPS params and RESTART command support.
- Control methods are no longer blocked by frame waiting.
- Fixed capture buffer loss on VIDIOC_QBUF failure which silently emptied the capture queue.
- Added device reinitialization after repeated frame waiting timeouts.
- Added rejection of truncated frames (payload shorter than the negotiated image size).
- Added support of padded luma plane height for planar formats in a single memory region.
- The frame captured during initialization is no longer delivered as the first frame.
- Added CUSTOM_1 (age of the last captured frame), CUSTOM_2 (capture queue depth) and CUSTOM_3 (number of lost frames) params.
2.3.1 05.10.2026 - Removed OpenCV from the test application, the user interface is based on the SimpleUI library.
- Added JPEG video display to the test application (VDecoderJPEG library).
- Test application converts all pixel formats to BGR24 by the FormatConverter library.
- Documentation updated.
2.3.2 12.10.2026 - Submodules updated.
2.3.3 19.10.2026 - Sub-repositories removed: the dependencies are cloned next to the repository or added by the parent project.
- Fixed undefined behaviour for NaN, infinite and out of range values of setParam(…), decodeAndExecuteCommand(…) and of the frame rate.
- decodeAndExecuteCommand(…) rejects null data and messages of a wrong size.
- Fixed integer overflows for large frame sizes granted by the driver: width and height are limited to 16384, odd sizes of 4:2:0 formats are rejected.
- Fixed chroma plane offset when the driver reports an image size larger than the image.
- Fixed data races of concurrent getFrame(…) calls with region of interest and of initVSource(…).
- Limited the drain of the capture queue to the number of buffers.
- Fixed getFrame(…) with a positive timeout: the last part of a millisecond was not waited, a timeout of 1 ms never checked new data and caused device reinitialization.
- Fixed “MJPEG” pixel format name for devices with enumeration.
- Fixed exposure mode returned by getParam(…) (V4L2 value was returned).
- Requested parameters are applied directly if the device does not enumerate formats or frame sizes.
- Device is opened with close-on-exec flag, only character devices are accepted.
- Compiler warnings and exploit mitigation flags added to CMake files.
- Test application lists video devices without external programs.
- Documentation updated.
2.3.4 25.10.2026 - The library links the thread library (CMake target Threads::Threads): programs built on a C library older than glibc 2.34 no longer need -pthread.

Library files

The repository structure is shown below:

CMakeLists.txt --------------- Main CMake file of the library.
src -------------------------- Folder with library source code.
    CMakeLists.txt ----------- CMake file of the library.
    VSourceV4L2.h ------------ Main library header file.
    VSourceV4L2Version.h ----- Header file with library version.
    VSourceV4L2Version.h.in -- File for CMake to generate version header.
    VSourceV4L2.cpp ---------- C++ implementation file.
test ------------------------- Folder for test application files.
    CMakeLists.txt ----------- CMake file for test application.
    main.cpp ----------------- Source C++ file of test application.
example ---------------------- Folder for example application files.
    CMakeLists.txt ----------- CMake file for example application.
    main.cpp ----------------- Source C++ file of example application.
static ----------------------- Folder with images of the documentation.

Capture behaviour

This section describes the runtime behaviour of the library which is not obvious from the interface declaration.

Low latency frame delivery

The library is optimized for minimum capture latency. It requests a deep capture queue (8 buffers by default, configurable through the CUSTOM_2 param) from the driver, because a shallow queue makes some drivers (for example imx8mp ISI) drop sensor frames while the application is busy processing the previous frame. However, the V4L2 VIDIOC_DQBUF call always returns the oldest queued buffer, so a deep queue alone would mean that a consumer which fell behind once stays a full queue behind forever (up to 8 frames, ~266 ms at 30 fps).

To avoid this, getFrame(…) drains the capture queue on every call:

  1. The method waits until at least one buffer is ready.
  2. It dequeues buffers until the queue is empty, returning every intermediate buffer to the driver immediately. One call dequeues at most as many buffers as the capture queue has, so a driver which refills buffers immediately can’t keep the call running.
  3. Only the newest buffer is copied into the output Frame object.

Consequences of this behaviour:

  • Capture latency never exceeds one frame period, regardless of how fast or slow the caller reads frames, as long as the driver still owns a free buffer. If the caller stops calling getFrame(…) for longer than about buffers / fps seconds (~266 ms for the default 8 buffers at 30 fps) the whole queue fills up, the driver has nowhere to write and stops capturing. The newest queued frame then stops being refreshed and ages by the remaining stall time. Raising CUSTOM_2 extends the stall the queue can absorb; it does not change the latency in steady state.
  • The real age of every delivered frame is available through the CUSTOM_1 param, so a stale frame after a long stall can be detected.
  • Frames are dropped if the caller reads slower than the video source produces frames. The library never buffers frames for the caller. Reading every frame is the responsibility of the library user: getFrame(…) must be called in a dedicated loop at a rate not lower than the video source frame rate, and heavy processing must be done outside that loop.
  • Frame IDs (Frame::frameId) are assigned by the library and increment by 1 for every delivered frame. They do not indicate dropped frames: the number of frames lost since the previous call is reported by the CUSTOM_3 param instead.
  • Draining does not reduce the number of buffers available to the driver. The application holds exactly one buffer while the frame is being copied (two for a short moment inside the drain loop), all other buffers stay in the driver queue. Drivers which require a deep queue to keep their DMA chain running (for example imx8mp ISI) are not affected.

This behaviour is always enabled and can’t be switched off.

Driver memory layout

Many capture drivers align the line stride of the captured image to a hardware requirement, so the line stride reported by the driver (bytesperline) can be larger than the payload of one image line. Multi planar formats may additionally place planes in unrelated memory regions.

The library reads the real layout during initialization and repacks the captured image into the tightly packed layout expected by the Frame class: line padding is removed and separately mapped planes are joined. If the layout is already tightly packed and occupies a single memory region (the most common case) the image is copied without any intermediate buffer.

A driver may also align the height of the luma plane. This padding is invisible in bytesperline while it does shift every chroma plane of a planar format carried in a single memory region (NV12, NV21, YV12, YU12 captured as a single planar buffer). The library detects it from the image size granted by the driver: if the size is exactly the size of the planes with a padded luma height (luma line stride * padded luma height * 3 / 2), the chroma planes are read at their real offsets. Any other size larger than the image (for example a size rounded up to a memory page) is padding after the image.

Format negotiation

The library enumerates formats, resolutions and frame rates supported by the video device and chooses the closest match to the requested parameters. Some drivers do not support enumeration; in this case the library applies the requested parameters directly.

In both cases the driver is allowed to adjust the requested pixel format, frame size and frame rate. After configuration, the library reads back the format actually granted by the driver (VIDIOC_G_FMT and VIDIOC_G_PARM) and updates width, height, fourcc and fps fields of VSourceParams. After a successful initialization these fields always describe the real capture format, which may differ from the requested one. Initialization fails if the driver grants a pixel format not supported by the library, a frame width or height outside of 1 - 16384 pixels, or an odd width or height for NV12, NV21, YU12 and YV12. The frame rate is requested from the driver as an integer number of frames per second.

Both single planar (V4L2_BUF_TYPE_VIDEO_CAPTURE) and multi planar (V4L2_BUF_TYPE_VIDEO_CAPTURE_MPLANE) capture devices are supported. For multi planar formats every plane is mapped separately and joined into a single contiguous image in the output frame (see Driver memory layout).

Compressed formats

For JPEG, H264 and HEVC formats the payload size varies from frame to frame. The library allocates the output frame buffer according to frame size and sets the Frame::size field to the actual payload size of the delivered frame on every getFrame(…) call. The caller must use Frame::size and must not assume that the buffer is fully filled.

Region of interest

If ROI_WIDTH and ROI_HEIGHT params are set to non zero values, the output frame contains only the cropped region and has the size of the region of interest. Cropping is performed in software after capture; the full frame is still transferred from the video device.

The requested region is not modified by the library. On every getFrame(…) call it is:

  • clamped to the image borders, so a region which is partially outside the image is reduced instead of being rejected;
  • aligned to even coordinates and even size for chroma subsampled formats (NV12, NV21, YU12, YV12 - x, y, width and height; YUYV, UYVY - x and width).

Cropping is not available for compressed formats (JPEG, H264, HEVC); for them the ROI params are ignored. To disable cropping set ROI_WIDTH and ROI_HEIGHT to 0.

Thread safety

All public methods are thread safe. The library uses two levels of locking:

  • device lifecycle lock - taken exclusively by initVSource(…), closeVSource(), RESTART command and by WIDTH / HEIGHT / FPS param setting;
  • params lock - taken for short periods to read and write VSourceParams fields.

Frame waiting inside getFrame(…) does not block getParam(…), setParam(…), getParams(…) and isVSourceOpen() calls from other threads. closeVSource() interrupts a getFrame(…) call which is waiting endlessly (timeoutMsec == -1).

Error recovery

If a video device error is detected (device disconnected, driver error) the library closes the device and reopens it transparently on the next getFrame(…) call. After an explicit closeVSource() call the device is never reopened automatically: initVSource(…), openVSource(…) or the RESTART command must be used.

Buffers with the V4L2_BUF_FLAG_ERROR flag, buffers with an index outside of the buffers of the library and multi planar buffers with a data offset outside of the buffer are returned to the driver and never delivered to the caller.

Two failures do not raise a device error but still stop the stream, so they trigger the same transparent reopen:

  • A buffer which the driver refuses to take back (VIDIOC_QBUF failure) is lost from the rotation for good. Every such failure makes the capture queue one slot shallower, and an empty queue means the driver simply stops reporting new data without ever raising an error flag.
  • A stream which silently stopped delivering buffers. After 3 consecutive getFrame(…) calls with a non-zero timeout expiring without data the device is reinitialized. Calls with timeoutMsec = 0 are non-blocking presence checks and are not counted.

When the image is delivered as a single tightly packed memory region (the most common case, see Driver memory layout) the library compares the payload size reported by the driver with the negotiated image size and rejects a truncated frame instead of delivering it: the missing tail of such a buffer still holds the previous frame captured into it. Drivers which report no payload size are not affected by this check.

VSourceV4L2 class description

VSourceV4L2 class declaration

VSourceV4L2 class declared in VSourceV4L2.h file. Class declaration:

namespace rapidpixel
{
/// Video source class based on V4L2 API.
class VSourceV4L2 : public VSource
{
public:

    /// Class constructor.
    VSourceV4L2();

    /// Class destructor.
    ~VSourceV4L2() override;

    /// Copy and move are deleted: the object owns the video device.
    VSourceV4L2(const VSourceV4L2&) = delete;
    VSourceV4L2(VSourceV4L2&&) = delete;
    VSourceV4L2& operator= (const VSourceV4L2&) = delete;
    VSourceV4L2& operator= (VSourceV4L2&&) = delete;

    /// 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 param.
    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 VSourceV4L2 class. Method declaration:

static std::string getVersion();

Method can be used without VSourceV4L2 class instance:

std::cout << "VSourceV4L2 v: " << rapidpixel::VSourceV4L2::getVersion() << std::endl;

Console output:

VSourceV4L2 v: 2.3.4

openVSource method

The openVSource(…) method initializes video source. Width, height and fps missing in the initialization string are set to 0 (auto detection) and a missing pixel format to YUYV, the other video source parameters (VSourceParams class) keep their current values. Instead of openVSource(…) method user can call initVSource(…) method. Method declaration:

bool openVSource(std::string& initString) override;
Parameter Value
initString Initialization string. Valid formats:
[full device name];[width];[height];[fps];[fourcc] or
[full device name];[width];[height];[fps] or
[full device name];[width];[height] or
[full device name]
Initialization string parameters:
[full device name] - Full name of video device in Linux OS. Default name format: /dev/video0, /dev/video1 etc. or can be /dev/v4l/by-id/… in case UVC compatible cameras.
[width] - Video frame width, integer >= 0. Video frame height must be set as well. The library will try set this value in video capture hardware parameters. If set to 0 the library will detect frame width automatically according to existing video device parameters.
[height] - Video frame height, integer >= 0. Video frame width must be set as well. The library will try set this value in video capture hardware parameters. If set to 0 the library will detect frame height automatically according to existing video device parameters.
[fps] - FPS, number from 0 to 10000 (for example 30 or 29.97). The library will try set this value in video capture hardware parameters. If set to 0 the library will detect fps automatically according to existing video device parameters.
[fourcc] - Pixel format. Valid values: BGR24, RGB24, GRAY, YUV24, YUYV, UYVY, NV12, NV21, YV12, YU12, JPEG (or MJPEG), H264, HEVC. If the device does not support the pixel format the library chooses appropriate format according to existing video device parameters.
Spaces around the numbers are allowed, empty parts between ‘;’ are skipped. Any other character in a number makes the string invalid.
Auto detection feature may not be supported by some camera drivers. If auto detection fails, library will try to use direct parameters provided by initString. It is caller's responsibility to provide proper parameters of camera.

Returns: TRUE if the video source open or FALSE if not (invalid initialization string or the video device can’t be initialized).

initVSource method

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

bool initVSource(VSourceParams& params) override;
Parameter Value
params VSourceParams class object. The video source will set parameters according to params structure. A log level outside of 0 - 3 is replaced by 0 (no log) and a frame rate which is not a number from 0 to 10000 by 0 (auto detection). Exposure, gain, focus and region of interest are set by setParam(…) after the device is open: values which the device does not accept are skipped. The object is not changed by the method.

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

isVSourceOpen method

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

bool isVSourceOpen() override;

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

closeVSource method

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

void closeVSource() override;

getFrame method

The getFrame(…) method returns video frame. The method always returns the newest frame available and drops all older frames from the capture queue (see Low latency frame delivery). Method declaration:

bool getFrame(Frame& frame, int32_t timeoutMsec = 0) override;
Parameter Value
frame Output video frame (see Frame class description). Video source class determines output pixel format. Pixel format can be set in initVSource(…) or openVSource(…) methods but if specified pixel format not supported by hardware the library can return Frame object with different pixel format. The library supports RAW pixel formats: BGR24, RGB24, GRAY, YUV24, YUYV, UYVY, NV12, NV21, YV12, YU12 and compressed formats JPEG, H264, HEVC (for compressed formats Frame::size holds the payload size of the delivered frame). The method allocates or reallocates the frame automatically when frame size or pixel format changes or the frame has no data. Otherwise the buffer of the frame is reused: it must have the size which Frame(width, height, fourcc) allocates (width * height * 4 bytes for compressed formats). A raw frame with another Frame::size is reallocated, the buffer size of a compressed frame can’t be checked by the library. If the method returns FALSE the content of the frame must not be used.
timeoutMsec Timeout to wait new frame data, milliseconds:
- timeoutMsec < 0 (for example -1) - Method will wait endlessly until new data arrive. The wait is interrupted by closeVSource().
- timeoutMsec == 0 - Method will only check if new data exist.
- timeoutMsec > 0 - Method will wait new data specified time, new data is checked at least once.

Returns: TRUE if new frame exists and copied or FALSE if not (wait timeout expired, corrupted, truncated or invalid frame received, video source not initialized or closed).

The age of the delivered frame is available through the CUSTOM_1 param and the number of frames lost since the previous call through the CUSTOM_3 param (see VSourceParam enum).

setParam method

The setParam(…) method designed to set new video source parameters value. Gain, exposure and focus params (modes and values) are controls of the video device: they can be set only when the video device is open. The other params are stored by the library. Setting WIDTH, HEIGHT or FPS params restarts an open video device with the new capture format. Setting CUSTOM_2 (capture queue depth) does not restart the device: the new value is applied on the next initialization of the video device. WIDTH, HEIGHT, FPS and region of interest params set before initVSource(…) or openVSource(…) are replaced by the params of these methods. 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. The value is converted to an integer (the fraction is dropped), except FPS. NaN, infinite and out of range values are rejected.

Returns: TRUE if the parameter was set or FALSE if not (not valid value, read only or not supported parameter, device control not supported).

getParam method

The getParam(…) method designed to obtain video source parameter value. Gain, exposure and focus params are read from the video device, so they can be read only when the video device is open. The other params are returned by the library. Method declaration:

float getParam(VSourceParam id) override;
Parameter Description
id Video source parameter ID according to VSourceParam enum.

Returns: parameter value or -1 if the parameter is not supported or the device control can’t be read.

getParams method

The getParams(…) method designed to obtain video source params class. Method declaration:

void getParams(VSourceParams& params) override;
Parameter Description
params VSourceParams class object.

executeCommand method

The executeCommand(…) method executes video source command. Method declaration:

bool executeCommand(VSourceCommand id) override;
Parameter Description
id Video source action command ID according to VSourceCommand enum.

Returns: TRUE if the command was executed or FALSE if not (command not supported or video device restart failed).

decodeAndExecuteCommand method

The decodeAndExecuteCommand(…) method decodes and executes command on video source side. Method will decode commands which encoded by encodeCommand(…) and encodeSetParamCommand(…) methods of VSource interface class. If command decoded the method will call setParam(…) or executeCommand(…) methods. decodeAndExecuteCommand(…) is thread-safe. This means that the method can be safely called from any thread. Method declaration:

bool decodeAndExecuteCommand(uint8_t* data, int size) override;
Parameter Description
data Pointer to input command. nullptr is rejected.
size Size of command. Must be 11 bytes for SET_PARAM and 7 bytes for COMMAND: data of another size is rejected.

Returns: TRUE if command decoded (SET_PARAM or COMMAND) and executed or FALSE if not.

encodeSetParamCommand method of VSource interface class

The encodeSetParamCommand(…) static method designed to encode command to change any parameter in remote video source. To control 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 command. The VSource class provides two types of commands: a parameter change command (SET_PARAM) and an action command (COMMAND). encodeSetParamCommand(…) designed to encode SET_PARAM command. 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.
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 VSource class instance. This method used on client side (control system). Command encoding example:

// Buffer for encoded data.
uint8_t data[11];
// Size of encoded data.
int size = 0;
// Parameter value.
float outValue = 10.0f;
// Encode command.
rapidpixel::VSource::encodeSetParamCommand(data, size, rapidpixel::VSourceParam::EXPOSURE, outValue);

encodeCommand method of VSource interface class

The encodeCommand(…) static method designed to encode command to perform action command in 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 command. The VSource class provides two types of commands: a parameter change command (SET_PARAM) and an action command (COMMAND). encodeCommand(…) designed to encode COMMAND (action command). 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 VSource class instance. This method used on client side (control system). Command encoding example:

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

decodeCommand method of VSource interface class

The decodeCommand(…) static method designed to decode command on 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. Must be exactly 11 bytes for SET_PARAM and exactly 7 bytes for COMMAND (other sizes give -1).
paramId Parameter ID according to VSourceParam enum. After decoding SET_PARAM command the method will return parameter ID. An ID that is not a value of the enum gives -1.
commandId Command ID according to VSourceCommand enum. After decoding COMMAND the method will return command ID. An ID that is not a value of the enum gives -1.
value Parameter value (after decoding SET_PARAM command).

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

Data structures

VSource.h file of VSource interface class defines IDs for parameters (VSourceParam enum) and IDs for action commands (VSourceCommand enum).

VSourceCommand enum

Enum declaration:

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

Table 2 - Video source commands description.

Command Description
RESTART Closes and reopens the video device with current params. Also clears the flag set by closeVSource() which blocks automatic device reopening.

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,
    /// [read/write] Region of interest upper left corner x coordinate.
    ROI_X,
    /// [read/write] Region of interest upper left corner y coordinate.
    ROI_Y,
    /// [read/write] Region of interest width.
    ROI_WIDTH,
    /// [read/write] Region of interest height.
    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 are not supported in VSourceV4L2 implementation.

Parameter Access Description
LOG_LEVEL read / write Logging mode. Specifies the log output mode. Values:
0 - Disable,
1 - Only file,
2 - Only terminal (console),
3 - File and terminal.
WIDTH read / write Frame width. Setting this param restarts the video device. After initialization the param holds the width actually granted by the driver, which may differ from the requested one.
HEIGHT read / write Frame height. Setting this param restarts the video device. After initialization the param holds the height actually granted by the driver, which may differ from the requested one.
GAIN_MODE read / write Gain mode. Values: 0 - Manual control, 1 - Auto. Some V4l2 video source may not support this parameter to control.
GAIN read / write Gain value. Value: 0(min) - 65535(max). The value is passed to the device control as is. Some V4l2 video source may not support this parameter to control.
EXPOSURE_MODE read / write Exposure mode. Values: 0 - Manual mode, 1 - Auto mode, 2 - Shutter priority, 3 - Aperture priority. Some V4l2 video source may not support this parameter to control.
EXPOSURE read / write Exposure value. Value: 0(min) - 65535(max). The value is passed to the device control as is. Some V4l2 video source may not support this parameter to control.
FOCUS_MODE read / write Focus mode. Values: 0 - Manual control, 1 - Auto. Some V4l2 video source may not support this parameter to control.
FOCUS_POS read / write Focus position. Value: 0(full near) - 65535(full far). The value is passed to the device control as is. Some V4l2 video source may not support this parameter to control.
CYCLE_TIME_MKS read only Video capture cycle time, microseconds. The library class sets this value automatically. This parameter means time interval between two captured video frame.
FPS read / write FPS, from 0 to 10000. Setting this param restarts the video device. After initialization the param holds the frame rate actually granted by the driver, which may differ from the requested one.
IS_OPEN read only Open flag. 0 - not open, 1 - open.
ROI_X read / write Region of interest top-left corner horizontal coordinate. If ROI set the output frame will have size equal to ROI size. See Region of interest.
ROI_Y read / write Region of interest top-left corner vertical coordinate. If ROI set the output frame will have size equal to ROI size. See Region of interest.
ROI_WIDTH read / write Region of interest width, pixels. 0 disables cropping. If ROI set the output frame will have size equal to ROI size. See Region of interest.
ROI_HEIGHT read / write Region of interest height, pixels. 0 disables cropping. If ROI set the output frame will have size equal to ROI size. See Region of interest.
CUSTOM_1 read only Age of the last captured frame, microseconds: time from the driver capture timestamp to the moment getFrame(…) returned. 0 if the video device does not timestamp buffers with the monotonic clock. See Low latency frame delivery.
CUSTOM_2 read / write Number of capture buffers requested from the video device. Values: 1 - 32, default 8. Applied on next initialization of the video device. See Low latency frame delivery.
CUSTOM_3 read only Number of frames the video device captured but the caller never received since the previous getFrame(…) call: dropped by the driver or discarded by the newest-frame policy. 0 if the video device does not maintain the buffer sequence counter.

VSourceParams class description

VSourceParams class declaration

VSourceParams class used for video source initialization (initVSource(…) method) or to get all actual params (getParams(…) method). Also VSourceParams provide structure to write/read params from JSON files (JSON_READABLE macro, see ConfigReader class description) and provide methos 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. 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.0f};
    /// Open flag. false - not open, true - 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, roiX, roiY, roiWidth,
                  roiHeight, custom1, custom2, custom3)

    /// Default constructor.
    VSourceParams() = default;

    /// Copy constructor.
    VSourceParams(const VSourceParams& src) = default;

    /// Move constructor.
    VSourceParams(VSourceParams&& src) = default;

    /// Copy assignment operator.
    VSourceParams& operator= (const VSourceParams& src) = default;

    /// Move assignment operator.
    VSourceParams& operator= (VSourceParams&& src) = default;

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

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

Table 4 - VSourceParams class fields description.

Field type Description
logLevel int Logging mode. Specifies the log output mode. Values:
0 - Disable,
1 - Only file,
2 - Only terminal (console),
3 - File and terminal.
source string Full name of video device in Linux OS. Default name format: /dev/video0, /dev/video1 etc. or can be /dev/v4l/by-id/… in case UVC compatible cameras. The name must be the name of a character device.
fourcc string Pixel format. Valid values: BGR24, RGB24, GRAY, YUV24, YUYV, UYVY, NV12, NV21, YV12, YU12, JPEG (or MJPEG), H264, HEVC. An unknown value means YUYV. If the device does not support the pixel format the library chooses appropriate format according to existing video device parameters. Value says to video source class which pixel format preferable for output video frame.
width int Video frame width. Video frame height must be set as well. The library will try set this value in video capture hardware parameters. If set to 0 the library will detect frame width automatically according to existing video device parameters. Some camera drivers may not support this feature.
height int Video frame height. Video frame width must be set as well. The library will try set this value in video capture hardware parameters. If set to 0 the library will detect frame height automatically according to existing video device parameters. Some camera drivers may not support this feature.
gainMode int Gain mode. Values: 0 - Manual control, 1 - Auto. Some V4l2 video source may not support this parameter to control.
gain int Gain value. Value: 0(min) - 65535(max). Some V4l2 video source may not support this parameter to control.
exposureMode int Exposure mode. Values: 0 - Manual mode, 1 - Auto mode, 2 - Shutter priority, 3 - Aperture priority. Some V4l2 video source may not support this parameter to control.
exposure int Exposure value. Value: 0(min) - 65535(max). Some V4l2 video source may not support this parameter to control.
focusMode int Focus mode. Values: 0 - Manual control, 1 - Auto. Some V4l2 video source may not support this parameter to control.
focusPos int Focus position. Value: 0(full near) - 65535(full far). Some V4l2 video source may not support this parameter to control.
cycleTimeMks int Video capture cycle time. The library class sets this value automatically. This parameter means time interval between two captured video frame.
fps float FPS, from 0 to 10000. 0 - auto detection. Setting it by setParam(…) restarts the video device. After initialization the field holds the frame rate granted by the driver.
isOpen bool Open flag. false - not open, true - open.
roiX int Region of interest top-left corner horizontal coordinate. If ROI set the output frame will have size equal to ROI size.
roiY int Region of interest top-left corner vertical coordinate. If ROI set the output frame will have size equal to ROI size.
roiWidth int Region of interest width, pixels. If ROI set the output frame will have size equal to ROI size.
roiHeight int Region of interest height, pixels. If ROI set the output frame will have size equal to ROI size.
custom1 float Not supported. Can have any value.
custom2 float Not supported. Can have any value.
custom3 float Not supported. Can have any value.

Note: VSourceParams class fields listed in Table 4 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 necessary in case when you need to send video source params via communication channels. Method doesn’t encode fields: source and fourcc. Method provides options to exclude particular parameters from serialization. To do this method inserts binary mask (3 bytes) where each bit represents particular parameter and 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 smaller than required, 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 params.
rapidpixel::VSourceParams in;
in.source = "any string";
in.logLevel = 0;

// Encode data.
uint8_t data[1024];
int size = 0;
if (!in.encode(data, 1024, size))
{
    std::cout << "Can't encode params" << std::endl;
    return false;
}
std::cout << "Encoded data size: " << size << " bytes" << std::endl;

Example with parameters mask:

// Prepare params.
rapidpixel::VSourceParams in;
in.source = "any string";
in.logLevel = 0;

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

// Encode data.
uint8_t data[1024];
int size = 0;
if (!in.encode(data, 1024, size, &mask))
{
    std::cout << "Can't encode params" << std::endl;
    return false;
}
std::cout << "Encoded data size: " << size << " bytes" << std::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 necessary in case when you need to receive video source params via communication channels. Method doesn’t decode fields: source and fourcc. Method automatically recognizes which parameters were serialized by encode(…) method. Method declaration:

bool decode(uint8_t* data, int dataSize);
Parameter Value
data Pointer to encode data buffer.
dataSize Size of data. It must not be smaller than the size of the encoded data (79 bytes if all params are encoded).

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

Example:

// Encode data.
rapidpixel::VSourceParams in;
uint8_t data[1024];
int size = 0;
if (!in.encode(data, 1024, size))
{
    std::cout << "Can't encode params" << std::endl;
    return false;
}
std::cout << "Encoded data size: " << size << " bytes" << std::endl;

// Decode data.
rapidpixel::VSourceParams out;
if (!out.decode(data, size))
{
    std::cout << "Can't decode data" << std::endl;
    return false;
}

Read params from JSON file and write to JSON file

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

// Write params to file.
rapidpixel::VSourceParams in;
rapidpixel::ConfigReader inConfig;
if (!inConfig.set(in, "vSourceParams") || !inConfig.writeToFile("TestVSourceParams.json"))
{
    std::cout << "Can't write config file" << std::endl;
    return false;
}

// Read params from file.
rapidpixel::ConfigReader outConfig;
rapidpixel::VSourceParams out;
if (!outConfig.readFromFile("TestVSourceParams.json") || !outConfig.get(out, "vSourceParams"))
{
    std::cout << "Can't read config file" << std::endl;
    return false;
}

TestVSourceParams.json with the default params will look like:

{
    "vSourceParams": {
        "logLevel": 0,
        "source": "/dev/video0",
        "fourcc": "YUYV",
        "width": 1920,
        "height": 1080,
        "gainMode": 1,
        "exposureMode": 1,
        "focusMode": 1,
        "fps": 0.0,
        "roiX": 0,
        "roiY": 0,
        "roiWidth": 0,
        "roiHeight": 0,
        "custom1": 0.0,
        "custom2": 0.0,
        "custom3": 0.0
    }
}

Build and connect to your project

Build stand alone

The repository does not contain sub-repositories. The libraries VSourceV4L2 depends on (Frame, ConfigReader, VSource, Logger) and the libraries the test application uses (FormatConverter, SimpleUI, VCodec, VDecoderJPEG) must be placed in the same folder as VSourceV4L2: copy their folders, for example from the folder modules of the RapidPixel SDK. The folder structure must be:

<work folder>
    VSourceV4L2
    Frame
    ConfigReader
    VSource
    Logger
    FormatConverter
    SimpleUI
    VCodec
    VDecoderJPEG

Typical commands to build the library, the test application and the example:

cd VSourceV4L2
mkdir build
cd build
cmake ..
make

If VSourceV4L2 is the top-level CMake project, the main CMakeLists.txt file adds the folders ../Frame, ../ConfigReader, ../VSource and ../Logger (in this order) before the library itself and the folders ../FormatConverter, ../SimpleUI, ../VCodec and ../VDecoderJPEG before the test application. If a folder does not exist CMake stops with an error. To build the library and the example without the test application (FormatConverter, SimpleUI, VCodec and VDecoderJPEG are not needed then) use cmake .. -D_SUBMODULE_CACHE_OVERWRITE=OFF -D_VSOURCE_V4L2_TEST=OFF instead of cmake ... The library requires Linux: on other systems CMake stops with an error.

CMake options

Table 5 - CMake options of the repository. In the options below ${PARENT} is the prefix defined by the top-level project (empty if VSourceV4L2 is the top-level project).

Option Default Description
${PARENT}_VSOURCE_V4L2 ON Build the library.
${PARENT}_VSOURCE_V4L2_TEST ON (stand alone), OFF (included in other project) Build the test application.
${PARENT}_VSOURCE_V4L2_EXAMPLE ON (stand alone), OFF (included in other project) Build the example.
${PARENT}_SUBMODULE_CACHE_OVERWRITE ON Forced rewriting of the options above in the CMake cache. The top-level project sets it to OFF when it includes VSourceV4L2 as a sub-repository.
CMAKE_BUILD_TYPE Release (if not specified) Build type.

Connect to your project

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

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

Create folder 3rdparty in your repository and copy the folders of the libraries Frame, ConfigReader, VSource, Logger and VSourceV4L2 there (for example from the folder modules of the RapidPixel SDK). The new structure of your repository:

CMakeLists.txt
src
    CMakeLists.txt
    yourLib.h
    yourLib.cpp
3rdparty
    Frame
    ConfigReader
    VSource
    Logger
    VSourceV4L2

Create a CMakeLists.txt file in the 3rdparty folder. VSourceV4L2 does not add its dependencies when it is included in another project: the file adds them in dependency order (Frame, ConfigReader, VSource, Logger) and then the library. The test application and the example of VSourceV4L2 are not built when it is included in another project. 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)

################################################################################
## CONFIGURATION
## 3rd-party submodules configuration
################################################################################
SET(${PARENT}_SUBMODULE_FRAME                           ON  CACHE BOOL "" FORCE)
if (${PARENT}_SUBMODULE_FRAME)
    SET(${PARENT}_FRAME                                 ON  CACHE BOOL "" FORCE)
    SET(${PARENT}_FRAME_TEST                            OFF CACHE BOOL "" FORCE)
endif()

SET(${PARENT}_SUBMODULE_CONFIG_READER                   ON  CACHE BOOL "" FORCE)
if (${PARENT}_SUBMODULE_CONFIG_READER)
    SET(${PARENT}_CONFIG_READER                         ON  CACHE BOOL "" FORCE)
    SET(${PARENT}_CONFIG_READER_EXAMPLES                OFF CACHE BOOL "" FORCE)
endif()

SET(${PARENT}_SUBMODULE_VSOURCE                         ON  CACHE BOOL "" FORCE)
if (${PARENT}_SUBMODULE_VSOURCE)
    SET(${PARENT}_VSOURCE                               ON  CACHE BOOL "" FORCE)
    SET(${PARENT}_VSOURCE_TEST                          OFF CACHE BOOL "" FORCE)
    SET(${PARENT}_VSOURCE_EXAMPLE                       OFF CACHE BOOL "" FORCE)
endif()

SET(${PARENT}_SUBMODULE_LOGGER                          ON  CACHE BOOL "" FORCE)
if (${PARENT}_SUBMODULE_LOGGER)
    SET(${PARENT}_LOGGER                                ON  CACHE BOOL "" FORCE)
    SET(${PARENT}_LOGGER_EXAMPLE                        OFF CACHE BOOL "" FORCE)
endif()

SET(${PARENT}_SUBMODULE_VSOURCE_V4L2                    ON  CACHE BOOL "" FORCE)
if (${PARENT}_SUBMODULE_VSOURCE_V4L2)
    SET(${PARENT}_VSOURCE_V4L2                          ON  CACHE BOOL "" FORCE)
    SET(${PARENT}_VSOURCE_V4L2_TEST                     OFF CACHE BOOL "" FORCE)
    SET(${PARENT}_VSOURCE_V4L2_EXAMPLE                  OFF CACHE BOOL "" FORCE)
endif()

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

if (${PARENT}_SUBMODULE_CONFIG_READER)
    add_subdirectory(ConfigReader)
endif()

if (${PARENT}_SUBMODULE_VSOURCE)
    add_subdirectory(VSource)
endif()

if (${PARENT}_SUBMODULE_LOGGER)
    add_subdirectory(Logger)
endif()

if (${PARENT}_SUBMODULE_VSOURCE_V4L2)
    add_subdirectory(VSourceV4L2)
endif()

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 VSourceV4L2 library in your src/CMakeLists.txt file (VSource, Logger, Frame and ConfigReader are linked with it):

target_link_libraries(${PROJECT_NAME} VSourceV4L2)

Include the public header in your code:

#include "VSourceV4L2.h"

If your project does not add the Frame, ConfigReader, VSource and Logger libraries, the build of VSourceV4L2 stops with compile errors such as VSource.h: No such file or directory.

Simple example

Example shows how to initialize video source with generic VSource interface and how to capture video in loop. Also example show how to get parameter value (video capture cycle time). The loop ends after 10 frame requests in a row without a frame. Example:

#include <iostream>
#include <memory>
#include <string>
#include "VSourceV4L2.h"



namespace
{
/// Timeout to wait for a new frame, milliseconds.
constexpr int FRAME_TIMEOUT_MSEC{1000};
/// The example stops after this number of getFrame() calls in a row without
/// a frame.
constexpr int MAX_FAILURES{10};
}



int main()
{
    // Init video source through the generic VSource interface.
    std::unique_ptr<rapidpixel::VSource> source = std::make_unique<rapidpixel::VSourceV4L2>();
    std::string initString = "/dev/video0";
    if (!source->openVSource(initString))
    {
        std::cout << "Can't open video source" << std::endl;
        return -1;
    }

    // Main loop. It ends after MAX_FAILURES frame requests in a row without a
    // frame.
    rapidpixel::Frame frame;
    int failures = 0;
    while (failures < MAX_FAILURES)
    {
        // Wait new frame 1 sec.
        if (!source->getFrame(frame, FRAME_TIMEOUT_MSEC))
        {
            ++failures;
            continue;
        }
        failures = 0;

        std::cout << "New frame " << frame.frameId <<
        " (" << frame.width << "x" << frame.height << ") cycle time : " <<
        static_cast<int>(source->getParam(rapidpixel::VSourceParam::CYCLE_TIME_MKS)) <<
        " usec" << std::endl;
    }

    std::cout << "No frames from video source" << std::endl;
    return -1;
}

Test application

Test application VSourceV4L2Test designed to check how VSourceV4L2 library works. The application allows user to set the resolution, fps and pixel format for video source initialization. If the user has selected video display mode, the application allows to control the exposure mode (manual, auto, shutter priority, aperture priority), focus mode (manual, auto) and gain mode (manual, auto) using the keyboard. The user can also control exposure level, gain level and focus position by sliders if the video source supports such functions. The application shows the exposure mode, exposure level, gain mode, gain level, focus mode and focus position on the video. If the mode without video display is selected, the application shows the frame index, frame sizes, the time between two video frames, and current fps. For instance:

[35] 1280x720 | 33.589 msec | fps : 29.7717
[36] 1280x720 | 34.416 msec | fps : 29.0563
[37] 1280x720 | 36.439 msec | fps : 27.4431

The application uses the SimpleUI library to show video. On Linux the video window requires the libx11-dev and libxext-dev packages. If they are not installed when the project is configured by CMake, SimpleUI is built with the headless stub window backend and the video is not shown. To install the packages:

sudo apt install libx11-dev libxext-dev

To run application use command:

./VSourceV4L2Test

After start the application shows information about available video devices in the system (device name, card name and bus of every /dev/video0 - /dev/video63 device):

========================================
VSourceV4L2 v2.3.4 test
========================================
DEVICES:
/dev/video0: mmal service 16.1 (platform:bcm2835_v4l2-0)
/dev/video10: bcm2835-codec-decode (platform:bcm2835-codec)
...
/dev/video19: rpivid (platform:rpivid)

Afterwards user should set device name, video width, video height, fps, pixel format and display mode (y/n):

========================================
Set device name (1 - for default /dev/video0): /dev/video0
Set frame width (0 for auto detection): 1280
Set frame height (0 for auto detection): 720
Set fps (0 for auto detection): 30
Set pixel format (BGR24,RGB24,YUV24,GRAY,UYVY,YUYV,NV12,NV21,YV12,YU12,JPEG): YUYV
Enter ROI x coordinate : 0
Enter ROI y coordinate : 0
Enter ROI width coordinate ( 0 for no roi) : 0
Enter ROI height coordinate ( 0 for no roi) : 0
Show video (y/n):

A value outside of its range (frame size 0 - 16384, fps 0 - 10000, ROI coordinates and size >= 0) ends the application. The application also ends after 10 frame requests in a row without a frame, after the ESC button or when the video window is closed.

If display video mode chose the user can control video source parameters by keyboard:

Table 6 - Control buttons. English layout should be active without CapsLock mode.

Button Description
ESC Exit application.
1 Set manual exposure mode.
2 Set auto exposure mode.
3 Set shutter priority exposure mode.
4 Set aperture priority exposure mode.
5 Set manual gain mode.
6 Set auto gain mode.
7 Set manual focus mode.
8 Set auto focus mode.

Portability

The library requires Linux (V4L2 API): CMake stops with an error on other systems. The code is C++17 without CPU specific instructions, and frames are copied as the driver delivers them, so the byte order of the CPU does not matter. The repository is built with GCC 12 and 13 and Clang 15 and 18 for x86-64 and aarch64.


Table of contents