125 lines
6.0 KiB
Markdown
125 lines
6.0 KiB
Markdown
<!-- Generated from the Runi source repository at v0.4.0. -->
|
|
<!-- Edit the original there, not this copy. -->
|
|
|
|
# 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.
|