Skip to content

NVIDIA and Wayland

Automatic rendering now applies the verified NVIDIA/Wayland configuration before Qt starts when exactly one GPU drives connected displays, that GPU is NVIDIA, both driver manifests exist, and no explicit graphics overrides are present. On that setup, launch normally with uv run brecon; New 3D Frame needs no additional terminal settings. A saved software preference remains respected: select View > 3D Rendering > Automatic (GPU) and restart to use hardware rendering. Connected hybrid/multiple-GPU displays, non-Wayland sessions, and explicit backend settings are left untouched rather than guessed.

nvidia-smi confirms the NVIDIA driver is running, but Qt and its embedded browser must also select compatible graphics backends. On the tested Ubuntu Wayland host with a Quadro RTX 4000 and driver 580.178.04, automatic EGL selection chose Mesa llvmpipe, causing WebGL2 to be blocklisted. Selecting NVIDIA EGL alone enabled WebGL but left Qt unable to create its OpenGL context. Selecting NVIDIA EGL and Vulkan together rendered the frame with GPU compositing enabled:

env -u QT_OPENGL -u QT_QUICK_BACKEND -u QTWEBENGINE_CHROMIUM_FLAGS \
  QSG_RHI_BACKEND=vulkan \
  __EGL_VENDOR_LIBRARY_FILENAMES=/usr/share/glvnd/egl_vendor.d/10_nvidia.json \
  VK_DRIVER_FILES=/usr/share/vulkan/icd.d/nvidia_icd.json \
  VK_LOADER_LAYERS_DISABLE='*MESA*' \
  uv run brecon --graphics=auto

Run from the project directory after saving and closing the existing app. These environment settings apply only to this process; no system graphics configuration or browser blocklist/sandbox is changed. --graphics=auto overrides a saved software preference for this launch. The driver JSON paths must exist on your distribution. Use the uv-managed environment from the setup instructions above; the stale Conda-based environment on the test host has been replaced. On this host, the managed-Python launch also required disabling Mesa Vulkan layers: without that setting, the native Vulkan loader crashed during vkCreateInstance. The layer setting is launch-scoped, not a system-wide change, preserves unrelated layers, and does not disable the Chromium sandbox or GPU blocklist.

For diagnostics, add QT_LOGGING_RULES='qt.webenginecontext=true;qt.webengine.compositor=true' to the command. Successful hardware rendering should report the Quadro as the QSG RHI Device, NVIDIA in GL Renderer, and GPU Compositing: Enabled; viewing the model must also succeed. A working context alone does not prove Qt can display it. Use software rendering if this configuration does not work on another machine.

On GNOME Wayland, Qt currently omits its own client-side decorations for Vulkan windows. Brecon supplies a compact title bar for affected main windows and its own box/form-layout dialogs, with close, minimize/maximize where applicable, title dragging and double-click maximize. Closing still uses the existing unsaved-work confirmation. Other platforms/backends retain their native controls. See Qt's Vulkan decoration limitation.

References: Qt NVIDIA graphics integration, NVIDIA EGL vendor selection, and Vulkan driver selection. See also Vulkan layer filtering.

View > 3D Rendering > Diagnostics shows the observed WebGL renderer, vendor, WebGL/shader versions and information source. Driver details may be masked by the platform; unavailable values stay explicit. Startup preference, next-launch preference and requested environment overrides are listed separately from the observed Qt window surface and WebGL driver. Selecting Automatic is not proof of hardware rendering, and Software describes requested compositing, not a guarantee about the platform's chosen WebGL driver. Refresh rechecks the active 3D viewport; a missing/failed viewport does not invent GPU details. This panel does not query the compositor's physical GPU or a driver package version.

Source: GUIDE.md. This manual follows the current repository; the published rc1 wheel has a smaller feature set.