CudaCompositorOp

CudaCompositorOp composites a CUDA BGRA overlay over a CUDA BGRA base frame. The latest overlay is latched in device memory, so an overlay update does not need to arrive at the same time as every base frame.

Overlay integration

Combine camera images with overlays that update at a different rate. Contact RidgeRun for custom composition operators and application integration.

Input arguments

Argument	Meaning
`width`, `height`	Positive dimensions shared by the base, overlay and output tensors.
`cuda_device`	CUDA device used by the latch and kernels; defaults to device `0`.

The operator allocates a device-resident overlay latch during start() and releases it during stop(). Startup therefore requires the selected CUDA device to be available.

Ports and data contract

Port	Memory	Queue	Trigger	Contract
`base`	CUDA device, contiguous	SDK default	`OnAnyInput`	U8 BGRA tensor with shape `[height, width, 4]`. A base sample produces output.
`overlay`	CUDA device, contiguous	SDK default	`OnAnyInput`	Same shape as `base`. A selected overlay refreshes the latest overlay.
`output`	CUDA device, runtime pool	N/A	Same activation	New U8 BGRA tensor with the configured shape, emitted when a base sample is available.

The empty input contract is lowered to an any-input trigger. An overlay-only activation updates the latch and emits nothing. A base-only activation composites using the most recently latched overlay. Before the first overlay, the latch is transparent, so the base image is forwarded unchanged.

Blend behavior

The kernel copies the base frame to the output and applies standard per-pixel alpha-over blending from the overlay. Alpha zero keeps the base pixel, alpha 255 replaces its RGB values, and intermediate alpha values blend the two colors. The output alpha channel is set to 255.

base image  -----> CudaCompositorOp -----> composited BGRA image
overlay image ----^        |
                         latest overlay is latched

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 cuda_compositor/cuda_compositor.hpp and link holoscan::cuda_compositor.

Example

The two inputs are independent. The overlay branch may publish less frequently than the base branch; the compositor keeps the most recent valid overlay:

auto compositor = graph.op<CudaCompositorOp>("compositor", width, height, 0);
graph.add_flow(camera->frame, compositor->base);
graph.add_flow(depth_colorizer->output, compositor->overlay);
graph.add_flow(compositor->output, display->input);

Both input tensors must be contiguous CUDA-device uint8 tensors with the same [height, width, 4] BGRA shape and the same configured CUDA device. The output is a new runtime-pool tensor; the operator copies the base frame device-to-device and then blends the latched overlay in place.

Memory and synchronization

The overlay is copied device-to-device into the latch, and the base is copied into a runtime-pool output before blending. Inputs must be on the configured CUDA device and the execution context must provide a CUDA stream.

Source reference

You can find the source code at CudaCompositorOp.

Related pages

DrmBgraDisplayOp consumes composited CUDA BGRA frames through DRM/KMS.
HolovizOp is the SDK-owned alternative for visualization.

❯