Enable exclusive display

By default a Holoscan visualization application renders into a window that the desktop’s window manager composites with everything else on the screen. Compositing adds at least one frame of latency and lets other applications compete for the panel. Exclusive display mode removes the window system from the path: HolovizOp acquires a display that no desktop session owns, sets a video mode, and scans out to it directly through the NVIDIA driver.

This page covers the supported configuration, how to select a display from an application, and the errors you will see when a prerequisite is missing. The visualization module’s README in the SDK source tree (public/modules/visualization/README.md, section “Exclusive display”) documents the implementation.

Prerequisites

• Linux with an NVIDIA GPU and driver. No libdrm is required: HoloViz talks to the kernel DRM interface directly, so the Tegra libdrm shim shipped on NVIDIA IGX systems does not affect it.

• No display server owning the GPU. The application must become DRM master, which fails while an X server or Wayland compositor holds the device. Stop the display manager and run from a text console (Ctrl-Alt-F3) or an SSH session:

  sudo systemctl stop gdm     # gdm3, sddm, or lightdm, whichever your system uses
  # ... run the application ...
  sudo systemctl start gdm    # hands the panels back to the desktop

• Access to the DRM device nodes. The user must belong to the video and render groups, which own /dev/dri/card* and /dev/dri/renderD*:

  sudo usermod -aG video,render "$USER"   # log out and back in afterwards

• In a container, pass the device nodes and the group ids, and use the NVIDIA runtime with NVIDIA_DRIVER_CAPABILITIES=all so the Vulkan ICD and the display libraries are mounted:

  docker run --rm --runtime=nvidia -e NVIDIA_DRIVER_CAPABILITIES=all \
      --device /dev/dri \
      --group-add "$(getent group video | cut -d: -f3)" \
      --group-add "$(getent group render | cut -d: -f3)" \
      <image> <application>

  The SDK’s ./run launch helper adds the group ids and the NVIDIA runtime for you; append --device /dev/dri if ls /dev/dri is empty inside the container.

Find the display name

Display names are the DRM connector names (DP-2, HDMI-A-1). They are not the names an X11 session shows in xrandr or in the desktop display settings for the same panels: a monitor listed as DP-0 under X may be DP-2 here. The holoviz_direct_display example, built with the SDK examples, lists what is connected and who owns it:

holoviz_direct_display --list

Adapter: <your GPU>
  Display: "DP-2" - available for direct display, current mode 2560x1440 180 Hz, VRR/G-Sync: advertised by EDID (floor 48 Hz)
    Best mode: 2560x1440 180 Hz (12 modes total, --all-modes to list)
  Display: "DP-3" - compositor-owned, current mode 1920x1080 144 Hz
    Best mode: 1920x1080 144 Hz (9 modes total, --all-modes to list)

Names, modes, and the VRR marker depend on your hardware. A display reported as compositor-owned is still held by a desktop session; only available for direct display panels can be acquired. Add --display DP-2 --frames 600 to render a color sweep to the panel and confirm the path works before wiring up an application.

Select the display in an application

Pass an ExclusiveDisplaySinkDesc instead of a WindowSinkDesc when constructing HolovizOp. Everything else about the operator (layers, inputs, trigger) is unchanged.

#include <holoscan/visualization/holoviz_op.hpp>
using namespace holoscan::visualization;
holoscan::Graph graph{"exclusive-display-app"};
// ... add the operator that produces the frames and connect it to "holoviz" below ...
LayerStack stack;
stack.add_image_layer("video",
                      ImageLayerDesc{.format = ImageFormat::kR8G8B8A8Unorm,
                                     .max_width = 1920,
                                     .max_height = 1080});
// Exclusive scanout to the panel whose DRM connector name contains "DP-2", at its largest,
// fastest mode.
// The default LayerTrigger presents each frame as it arrives on the "video" layer; pass
// ClockTrigger{std::chrono::nanoseconds{16'666'667}} instead to present at a fixed 60 Hz.
const auto viz = graph.op<HolovizOp>("holoviz",
                                     std::move(stack),
                                     ExclusiveDisplaySinkDesc{.display_name = "DP-2"});

ExclusiveDisplaySinkDesc fields:

The surface keeps the chosen mode for the life of the operator: it never resizes, and layers are scaled to it. The display is released when the graph stops.

Troubleshooting

Variable refresh (G-SYNC / Adaptive-Sync) is reported for a panel that advertises it but is not controlled from this path; whether the driver engages it is the driver’s decision. For fullscreen windows on a desktop, see Enable G-SYNC.