runi-dist/docs/hdr.md

Native HDR

Runi can enable native HDR for one Windows game without changing KDE, KWin, the monitor, or global Gamescope configuration. The player remains responsible for enabling HDR/WCG on the intended desktop output before launch.

Requirements

• a Wayland session with HDR enabled on the intended output;
• Gamescope already enabled and configured for the game under Runtime;
• a Gamescope build exposing --hdr-enabled;
• a Gamescope WSI Vulkan layer matching the game's PE architecture;
• a Vulkan stack exposing VK_EXT_swapchain_colorspace;
• a game with native HDR support and HDR enabled in its own settings.

The HDR tab reports Ready, Unverified, or Not ready. Confirmed missing prerequisites block an HDR launch. If Runi cannot query the desktop output state, it reports Unverified and permits an explicit launch; this is a warning, not proof that the display pipeline is correct. Mixed HDR/SDR outputs and a non-primary HDR output are also reported.

Runi deliberately does not enable Gamescope automatically. Existing output and render resolutions are per-game choices, so silently activating the wrapper could select an inappropriate mode.

Display and OS guidance

The HDR tab also shows the calibration metadata that KDE exposes for the selected output, including peak luminance, reference white, colour profile, gamut preference, RGB range and bit depth where available. These values are read-only guidance: Runi does not change KWin, KScreen or monitor state.

Use the display peak as the starting point for an in-game Max Nits control and the display reference white as the starting point for an in-game Paper White control. The game remains authoritative because slider names and tone mapping differ between engines. A correct transport can still look wrong when the game's midpoint, contrast or saturation is poorly calibrated.

Optional community game settings

When explicitly enabled in Preferences, Runi can make a bounded OpenAI Responses API request to research HDR sliders for the current game. Research is never automatic: the player must click Research Settings or Refresh and approve the privacy/cost preview. The request sends only the canonical game title, Steam AppID when known, platform and optional game version. When a matching HDR Game Analysis entry exists, its public guide text and up to four public images are also included in the OpenAI request; the approval dialog discloses this additional image-input cost before every request.

The researcher uses gpt-5.6-terra with medium reasoning, at most three web searches, structured output and an audited allowlist:

• PCGamingWiki;
• KoKlusz HDR Gaming Database discussions;
• r/HDR_Den;
• r/OLED_Gaming;
• HDR Game Analysis, through a dedicated author-restricted adapter.

The HDR Game Analysis adapter reads one audited index through FxTwitter, matches only PC entries against the canonical game title, follows at most three links owned by HDRgameAnalysis and supplies at most four guide images. It does not add x.com to the web-search domain allowlist. Canonical source validation accepts only https://x.com/HDRgameAnalysis/status/<id> links, and an adapter or mirror outage degrades to the remaining sources instead of failing the research request.

Returned values keep the sources' original numbers and citations. Runi may show a local display-specific suggestion beside Max Nits or Paper White, but never applies either value to the game. Conflicting or insufficient evidence is shown as such instead of being converted into a false consensus.

Successful findings are stored by canonical Runi Game ID in ~/.local/share/runi/knowledge.sqlite3, shared by registrations of the same game and retained after removal/re-import. The latest three successful runs are kept. Results become stale after 30 days but remain readable; a failed refresh never replaces the latest successful result.

The feature is disabled by default and requires the ai optional dependency. The OpenAI API key is read from the system keyring, OPENAI_API_KEY, or session-only memory. It is never written to Runi configuration, logs, the knowledge database, backups or Git.

Launch composition

When [hdr].enabled = true, the main Play action receives:

• Gamescope --hdr-enabled;
• ENABLE_GAMESCOPE_WSI=1;
• PROTON_ENABLE_HDR=1 when the selected runner advertises that path, or DXVK_HDR=1 as the compatibility fallback.

Auxiliary actions do not inherit HDR. Raw [env] values for the managed HDR keys are rejected to avoid two competing sources of truth. Use runi hdr status <game-id> --json to inspect the resolved pipeline and runi run <game-id> --dry-run --json to inspect the final launch.

Lossless Scaling

The HDR tab is authoritative when Lossless Scaling frame generation is also enabled. Runi maps the same value to the lsfg-vk 1.x HDR shader mode. lsfg-vk 2.x has no equivalent separate control, so the UI reports that limit instead of inventing one.

Validation

A valid acceptance pass uses a game known to expose native PC HDR, checks a disabled control launch, enables Gamescope and HDR, reviews the dry-run, then confirms both the in-game HDR option and the display's HDR indication. A successful launch alone is not sufficient evidence of correct HDR output.

DOOM: The Dark Ages is the current acceptance target. Atomic Heart is not used for this check because its PC HDR path depends on external AutoHDR/mod behavior rather than providing the clean native control required by this test.

The DOOM acceptance pass completed on 2026-08-11 with GE-Proton11-5, Gamescope 3.16.25, RADV and KDE Wayland. Gamescope exposed an A2B10G10R10 swapchain using HDR10_ST2084, reported HDR formats to the client and ran the display at 120 Hz. The validated display calibration was 1015-nit peak and 240-nit reference white. The game's defaults were not a useful calibration: the confirmed starting values were 1000 max nits, 20.30 mid point, 1.00 brightness, 0.90 contrast, 240 paper white and 1.00 saturation.