V4L2UserPtrSourceOp

V4L2UserPtrSourceOp captures single-plane RG10 Bayer frames through V4L2 USERPTR buffers backed by CUDA-mapped pinned host memory. The camera writes the same allocation that downstream CUDA operators read through a device alias, avoiding a host-to-device copy in this operator.

Camera integration

To adapt V4L2 capture for CUDA processing and assess where frame copies can be reduced, contact RidgeRun.

Input arguments

Argument	Default and meaning
`device`	V4L2 device path, for example `/dev/video0`.
`width`, `height`	Positive RG10 capture dimensions.
`fps`	Requested capture rate; defaults to `30`.
`cuda_device`	Device used for mapped aliases; defaults to `0`.
`sensor_gain`	Sensor gain setting; defaults to `8,000,000` in the source API.
`exposure_us`	Exposure setting; defaults to `15,649` microseconds.
`frame_limit`, `start_gate`	Optional application controls for bounded runs and synchronized starts.

Ports and data contract

Port	Memory	Queue	Trigger	Contract
`frame`	CUDA-visible mapped host memory	N/A	`OnClock` at `fps`	U16 tensor with shape `[height, width, 1]` containing unpacked RG10 values. Frame IDs and usable capture timestamps are forwarded.

V4L2UserPtrSourceOp -> RawBayerToBgraOp -> X11DisplayOp
V4L2UserPtrSourceOp -> RawBayerToBgraOp -> DrmBgraDisplayOp
V4L2UserPtrSourceOp -> RawBayerToYoloTensorOp -> TensorRtInferenceOp -> FakesinkOp

Build

Follow Holoscan RidgeRun Build and Installation for the module build and installation. The operator-specific include, target, and runtime requirements are listed below.

Include v4l2_userptr_source/v4l2_userptr_source.hpp and link holoscan::v4l2_userptr_source. The camera driver must support single-plane V4L2_MEMORY_USERPTR buffers for the requested RG10 mode.

Example

The source can feed either the display-oriented or fused inference-oriented path:

auto camera = graph.op<V4L2UserPtrSourceOp>(
    "camera", "/dev/video0", 1920, 1080, 60, 0,
    8000000, 15649);
auto preprocess = graph.op<RawBayerToYoloTensorOp>(
    "preprocess", 1920, 1080, 640, 640);
graph.add_flow(camera->frame, preprocess->input);

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

The constructor validates positive dimensions, an even width, positive gain and exposure, a supported CUDA device and a frame-rate period representable by the Holoscan clock. On startup the operator negotiates the exact RG10 format, applies the configured sensor controls when the driver exposes them, allocates CUDA-mapped host slots with cudaHostAllocMapped, obtains device aliases with cudaHostGetDevicePointer, queues them as USERPTR and starts streaming.

Capture requirements

The camera/driver must support single-plane RAW10 USERPTR capture and the selected dimensions. A CUDA-visible mapping reduces copies but does not make the capture allocation device VRAM or guarantee that every downstream operation is copy-free.

Source reference

You can find the source code at V4L2UserPtrSourceOp.

Related pages

RawBayerToBgraOp performs display preprocessing.
RawBayerToYoloTensorOp performs inference preprocessing.
V4L2SourceOp documents the driver-MMAP alternative.

❯