V4L2CaptureOp

V4l2CaptureOp reads packed YUYV frames from a Linux V4L2 device and publishes one image payload when a frame is ready. Use it when the camera already exposes the mode your application needs through a video device node.

Include <v4l2_capture_op/v4l2_capture_op.hpp> and link holoscan::v4l2_capture_op. Build the module with Build and Installation before adding the operator to your graph.

Input arguments

The constructor fixes the requested device mode and output placement before compilation.

Argument	Default	Meaning
`device`	`/dev/video0`	V4L2 device node.
`width`, `height`	`640`, `480`	Requested image dimensions. Width must be even for packed YUYV.
`fps`	`30`	Requested frame rate.
`frame_id`	`camera_optical_frame`	Coordinate-frame name carried by the image metadata.
`memory_kind`	`holoscan::MemoryKind::kHost`	Output placement. The operator accepts `kHost`, `kPinnedHost`, or `kCudaDevice`. See the SDK's MemoryKind definition.

The device must negotiate the requested YUYV format, dimensions, progressive field order, and rate. The operator does not decode compressed video or convert another pixel format into YUYV.

Ports and data contract

The output type is the SDK's ImageT schema. It describes the image while the Tensor backing stores the packed row bytes.

Port	Memory	Queue	Trigger	Contract
`frame`	Selected by `memory_kind`: host, pinned host, or CUDA device.	One frame emission per activation. Device buffering remains driver-managed.	Notification when a captured device buffer is ready.	Rank-2 unsigned-byte Tensor with shape `[height, 2 * width]`, width and height in the image descriptor, and `ImageEncoding_YUYV`. Each two-pixel group uses four bytes.

The memory placement controls where the published Tensor is allocated. The device source is still read through the V4L2 capture path, so selecting CUDA memory does not make the capture path copy-free. For kCudaDevice, bind the output to a CUDA device in the compile options. Do not add that binding for host or pinned-host output.

holoscan::CompileOptions options{};
options.deployment.bind_tensor_output_device(
    holoscan::TensorOutputDevicePlacement{
        .operator_path = "camera",
        .output_port = "frame",
        .device = holoscan::DeviceId{0}});

The SDK declaration of bind_tensor_output_device applies only to CUDA-device Tensor outputs. The same call is rejected for host placement.

Capture quality and timing

The operator reports capture quality independently from whether the process is still running. The SDK SampleFlags carry these cases:

Observation	Published result
A sequence gap, sequence regression, or short frame	`SampleFlags::kDegraded`. A short frame is zero-filled after the bytes that arrived.
The driver marks the buffer with an error flag	`SampleFlags::kInvalid`. Treat the image as unusable for measurements.
The driver timestamp is not monotonic, is not start-of-exposure, or cannot be projected to the graph clock	No capture time is published. This is separate from the quality flags.

Use the numeric device sequence to identify a captured frame. The image metadata's frame_id names a coordinate frame, not a unique capture. Downstream code can inspect degraded samples for diagnostics and reject invalid samples when reliable measurements are required.

Example

This graph fragment requests host output for a consumer that reads the image on the CPU:

#include <holoscan/core/graph.hpp>
#include <v4l2_capture_op/v4l2_capture_op.hpp>

holoscan::Graph graph{"camera"};
auto camera = graph.op<holoscan::holoscan_camera::V4l2CaptureOp>(
    "camera", "/dev/video0", 1280, 720, 30, "camera_optical_frame",
    holoscan::MemoryKind::kHost);

For a graph-only validation path, run the V4L2 reference application without a device capture:

./holoscan_camera run holoscan_camera_v4l2

For hardware capture, pass the device to the reference application and review its frame count, timing, and quality counters:

./holoscan_camera run holoscan_camera_v4l2 capture --language cpp --docker-opts '--device /dev/video0' --run-args '--device /dev/video0 --frames 60 --timeout 30'

Build

Follow Build and Installation for the module build and runtime prerequisites. Include the V4L2 operator header and link holoscan::v4l2_capture_op.

Source reference

You can find the source code at V4L2CaptureOp.

Related material

Holoscan Camera Overview compares the V4L2 and SIPL paths.
Sensor Payloads and Schemas introduces typed image payloads.
V4L2 reference application contains the complete graph.
NVIDIA Holoscan SDK User Guide provides the official application and API documentation.

❯