Outputs and HDR

Physical display policy belongs in ~/.config/aqueous/outputs.toml. Aqueous stages accepted changes and commits the complete multi-output state atomically; if the backend rejects the transaction, it restores the last working state.

Discover outputs

aqueousctl outputs
aqueousctl outputs --json

The output snapshot includes connector identity, make/model/serial, physical size, every advertised mode, current and preferred modes, logical position, transform, scale, adaptive-sync state, and a stable sha256: EDID identity when the required metadata is available.

Declarative output policy

[display]
apply_on_start = true
apply_on_reload = true
fallback_profile = "internal-only"

[[output]]
name = "eDP-1"
enabled = true
mode = "1920x1200@60"
scale = 1.25
transform = "normal"
position = [0, 0]
adaptive_sync = false
primary = true

[[output]]
name = "DP-*"
enabled = true
mode = "2560x1440@144"
scale = 1.0
position = [1536, 0]
adaptive_sync = true

name accepts connector globs. Use edid = "sha256:..." when a connector name is not stable. Later matching entries override earlier entries, making it possible to define a broad dock policy followed by one specific monitor.

• mode uses WIDTHxHEIGHT@HZ.
• scale accepts 0.5 through 3.0.
• position is in logical output-layout coordinates; negative X/Y values place a display to the left of or above the origin.
• transform accepts normal, 90, 180, 270, flipped, and the three rotated flipped variants.
• primary is a deterministic action/focus fallback. It does not steal focus from an explicitly selected output.
• mirror_of names a source connector; "" clears an inherited mirror. Mirroring currently requires one SDR pair on the same backend/device with normal transforms. See Screen mirroring.

When position is absent, Aqueous arranges otherwise unconfigured outputs in a non-overlapping horizontal row. A first output-management transaction that places every still-automatic output at (0, 0) is treated as uninitialized; its mode and scale updates are retained while positions are recomputed.

rotate_output_clockwise (default Super+Ctrl+R) rotates only the enabled output directly beneath the pointer. This is a runtime transaction and does not rewrite outputs.toml, so a later reload may restore the configured transform.

Adaptive sync

[[output]]
name = "DP-1"
adaptive_sync = true
fullscreen_only_adaptive_sync = true

adaptive_sync is the master VRR request. The optional fullscreen_only_adaptive_sync modifier defaults to false. When both are true, VRR is requested only while a visible fullscreen application occupies that monitor’s active workspace. Focusing another monitor does not disable it; overview and session lock do.

Native display observations distinguish the configured policy from effective_adaptive_sync (the runtime target), actual_vrr (backend status), and adaptive_sync_error (null, unsupported, or commit_failed). A saved VRR request alone does not establish that the hardware enabled it.

Named profiles

Profiles contain the same fields as ordinary output blocks:

[[display.profile]]
name = "internal-only"

[[display.profile.output]]
name = "eDP-1"
enabled = true
position = [0, 0]
primary = true

[[display.profile.output]]
name = "DP-*"
enabled = false

The embedded output service can apply a profile at runtime. A fallback_profile is attempted after a normal configured transaction is rejected.

Output specifications are validated independently. Valid settings for one monitor can still apply when another connector or mode is unavailable, while the accepted visible changes remain one atomic backend commit. Service replies distinguish complete success, partial application, and per-spec rejection.

HDR10 output

Use aqueousctl outputs to find the connector for your HDR display, then edit its matching block in ~/.config/aqueous/outputs.toml. Replace DP-1 below with that connector. Set apply_on_reload = true in the file’s [display] section to apply saved changes through configuration hot reload.

[[output]]
name = "DP-1"
hdr = true
hdr_level = "auto" # auto | 100 | 400 | 1000 cd/m²
sdr_white_level = 200 # 80–1000 cd/m²
auto_hdr = false # Optional SDR highlight expansion; see Auto HDR below.

Alternatively, use a compatible settings frontend such as Pearl to enable HDR, preview the change, and confirm it before saving. Run aqueousctl outputs --json afterward and check that the intended output reports hdr: true. hdr_capable: true reports support; it does not mean HDR is active. Enable the output before launching an HDR application.

hdr = true requests 10-bit scanout, BT.2020 primaries, and the ST 2084 PQ transfer function with static HDR10 mastering metadata. Aqueous rejects it unless the connector, renderer color transform, and primary scanout path expose the required capabilities. Disabling HDR restores the normal 8-bit sRGB profile.

hdr_level chooses the mastering/target peak. auto selects the nearest 100/400/1000 preset from the display’s EDID desired-content peak and falls back to 1000 when unavailable. sdr_white_level maps SDR diffuse white on the HDR output; the Windows-scRGB protocol description retains its defined 1.0 = 80 cd/m² scale independently.

Aqueous exposes Windows-scRGB and Windows-BT.2100 color descriptions through color-management-v1 for Wine/Proton when the renderer supports the complete encodings. SDR outputs continue to report SDR luminance, preventing false HDR detection.

HDR in Steam games with Proton-CachyOS

The display, Proton, and the game each need HDR enabled. After enabling HDR10 output in Aqueous:

1. Open the game’s Properties → Compatibility in Steam and select Proton-CachyOS. These instructions apply to its native Wayland path, including Proton-cachyos-11.0-20260703 (Steam Linux Runtime).

2. Under General → Launch Options, enter this as one line:

   PROTON_ENABLE_WAYLAND=1 DXVK_HDR=1 %command%

3. Fully exit and relaunch the game on the HDR-enabled display, then enable HDR in the game’s own display settings. The game must support native HDR.

PROTON_ENABLE_WAYLAND=1 selects Wine’s native Wayland driver. DXVK_HDR=1 exposes HDR to the game through DXVK’s DXGI implementation, which is also used by Direct3D 12 games such as Stellar Blade.

The CachyOS HDR variable changed

Current Proton-CachyOS releases have retired PROTON_ENABLE_HDR in favor of DXVK_HDR. Replace PROTON_ENABLE_HDR=1 in older launch options with DXVK_HDR=1; the old variable has no effect in the build above. See the upstream retired-variable list. Other Proton distributions may use different options; check their documentation.

If the HDR option is missing

• Check aqueousctl outputs --json again for the display running the game. A rejected HDR output change leaves the previous working state active.

• Confirm Steam is using the selected Proton-CachyOS build and that both variables precede %command% in the game’s launch options.

• Capture a fresh Proton log with:

  PROTON_ENABLE_WAYLAND=1 DXVK_HDR=1 PROTON_LOG=1 %command%

  The log defaults to ~/steam-<APPID>.log; Stellar Blade uses ~/steam-3489700.log. Check the Proton version at the top and look for the game process loading winewayland.drv. Remove PROTON_LOG=1 after troubleshooting.

• An EDID or Failed to parse display metadata + colorimetry info error alone does not prove HDR is unavailable. DXVK can use fallback display metadata; check the output state and launch options before treating it as the cause.

Auto HDR

Auto HDR is optional SDR highlight expansion. Native HDR games do not require it, and enabling it does not unlock a game’s HDR setting. To use it, set auto_hdr = true in the HDR output’s block and optionally set auto_hdr_boost = 0.5 (range 0.0–1.0).

Auto HDR expands eligible SDR highlights toward the output’s configured peak. By default, fullscreen windows and windows declaring content_type = "game" are eligible. Override that choice with a window rule:

[[window]]
app_id = "steam_app_*"
hdr_expand = true

Native PQ, Windows-scRGB/BT.2100, layer-shell, and lock-screen content is never expanded. Auto HDR requires the Vulkan effects build; auto_hdr_boost = 0 reduces it to the configured SDR white level without highlight expansion.

Display previews

Compatible settings frontends can preview an entire output change before saving it. Aqueous tests the target set and keeps at least one enabled, non-mirrored output. The confirmation interval begins only after the participating enabled outputs have presented the new state. Select Keep within 15 seconds to confirm, or revert. An unconfirmed preview writes no candidate configuration.

Production DRM previews support advertised SDR modes, HDR, VRR, HDR with VRR, and Auto HDR when capability and preflight checks pass. Physical mirroring and custom modes remain blocked in this protected path. Nested backends are unsupported. These limits are distinct from the compositor’s ordinary mirroring configuration.

Locking, output removal, or a failed presentation can invalidate a preview. Restoration and persistence have separate reported outcomes; inspect an error rather than assuming a failed save or timed-out response completed a rollback. Changing apply_on_reload does not bypass protected helper validation.

See the display-preview contract for exact state, recovery, and hardware qualification details.

Hotplug and output ownership

Connecting or removing an output creates or destroys its native compositor object, reapplies configured policy, updates workspace/output protocols, and prunes stale per-output layout state. A floating drag crossing an output’s logical rectangle transfers the window to that output’s active workspace. If the source disappears, Aqueous recovers the window to the nearest enabled output and keeps a reachable portion visible.

Transient output commit failures schedule retries with a capped backoff delay so presentation can recover. This does not guarantee recovery from every GPU or driver failure.

Embedded output service

Aqueous hosts a same-user Unix socket at:

$XDG_RUNTIME_DIR/aqueous/outputd.sock

It preserves the display-panel JSON contract without a separate aqueous-outputd process. Operations include list, set, reload, apply_profile, and save_profile. The set and profile operations support mode, position, transform, scale, adaptive sync, primary selection, HDR level, SDR white, Auto HDR, and mirror_of fields. Listed outputs also report HDR capability, active state, render format, EDID luminance, supported primaries and transfer functions, and Auto HDR capability.

When this service is available, aqueousctl outputs --json also includes mirror_of, mirror_status, and mirror_error. Standard output-management discovery remains available without the service.

The settings application consumes this service for its connected-output canvas while writing persistent overrides to outputs.toml only when you select Apply.

Note

HDR, adaptive sync, and overlay promotion remain hardware- and driver- dependent. A rejected capability is reported instead of being silently presented as active.