docs: user-facing documentation and signing key
This commit is contained in:
+124
@@ -0,0 +1,124 @@
|
||||
<!-- 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.
|
||||
Reference in New Issue
Block a user