Wayland (KDE Plasma/KWin) direct scanout info/guide

direct_scanout.md

Direct Scanout

What is it?

Direct scanout is a feature where the window manager configures the display controller to read the swapchain image buffer of a fullscreen window directly, without compositing. This reduces click-to-photon latency and may improve performance.

This will focus on KDE Plasma Wayland/KWin Wayland, but direct scanout is available on other compositors as well (like gnome, niri, cosmic, etc.). X11 might behave differently.

Requirements

Direct scanout will be enabled automatically for a window once it becomes compatible and theres nothing blocking direct scanout.

For a window to be compatible, it generally needs to fulfill these criteria:

• Fullscreen, or effectively fullscreen (display-filling borderless windowed)
• Renders using a compatible texture format (usually fine)
• Completely opaque, no transparency
• Nothing rendered on top, no external overlay

Testing direct scanout support

NEW! KWin Script to tell you whats currently visible, and enabled showcompositing easily: https://store.kde.org/p/2380491/

To check whether your system or application supports direct scanout, follow these steps:

1. Make sure you're on a recent KDE Plasma, and have mpv and ffmpeg installed.
2. Run qdbus org.kde.KWin /Effects org.kde.kwin.Effects.toggleEffect showcompositing in a terminal
3. Now, all windows should have a red border. This shows they're being composited.
4. Run mpv --no-config --fullscreen --vo=gpu-next "av://lavfi:color=c=black:s=1920x1080:r=60:d=60"
5. This should open a fullscreen mpv video player which shows a black screen.
6. If the red borders are shown, direct scanout does not work. If there are no red borders, direct scanout is working.
7. Run qdbus org.kde.KWin /Effects org.kde.kwin.Effects.toggleEffect showcompositing again to disable the red borders.

Always test with the mpv command first, as its a known-good application to test direct scanout. Once mpv works, once it has no red borders while fullscreen, move on to the actual application/game.

Help! Direct scanout doesn't work!

I've collected a list of things to check which are known to interfere with direct scanout, causing it to not work.

Items marked with a ? are unclear, they may or may not help get.

• in Display Settings, set:
  • ? Scale: 100%
  • Color profile: None
  • HDR: off
  • Color accuracy: prefer efficiency
  • ? Brightness: control hardware brightness with DDC/CI and/or 100%
• ? Allow tearing in fullscreen windows: on
• Disable "Night Light" (set to "always off"
• Ensure echo $KWIN_DRM_NO_DIRECT_SCANOUT does NOT return any value. Override by editing /etc/environment and rebooting.
• Currently displaying/active Desktop Effects can cause issues, known culprits:
  • Dim Inactive
  • Highlight Screen Edges and Hot Corners

Other applications and Overlays

Generally, any visible or invidisble overlay app can cause issues.

Broken or cause issues:

• ? Gamescope: untested, see ValveSoftware/gamescope#1423
• mangoapp: overlay, usually breaks direct-scanout
• Battle.net launcher: Causes issues if running https://bugs.kde.org/show_bug.cgi?id=513203
• Plasmazones (up to version 3.5.3): fuddlesworth/PlasmaZones#1169
• Sunshine KMS capture: LizardByte/Sunshine#4982
• Steam overlay: No direct scanout while open, can leave behind stray invisible windows, disabling direct scanout for the session.

Tested working, sometimes suspected to cause issues:

• Mangohud: No issue using MANGOHUD=1 in native Vulkan, dxvk not tested. Prefer DXVK_HUD for dxvk.
• OBS Studio: No issue with a Vulkan application being captured by PipeWire or obs-vkcapture plugin.