fix(app-rules): INV-4.6 — UNORM swapchains are linear since #1589; lint the _SRGB choice per leg

[dfattal]

Why

The Gaussian-splat demo looks washed out on the Leia Android tablet running runtime v2.21.11 but looks right on macOS.

The runtime is right. The app, and this repo's app guide, were wrong.

• Since the format-honest colour model (CTS composition: UNORM (linear) swapchains are passed through un-encoded on every backend — GradientFormatsLinearVsNonLinear FAIL; ADR-021 Model A vs OpenXR format semantics #1589/compositor blends layers in sRGB-encoded space; OpenXR expects linear-space blending (CTS SourceAlphaBlending) #1610; vk_native in v2.21.7, 748b540), an UNORM swapchain is read as linear, as OpenXR specifies ("All other formats will be treated as linear values"), and is sRGB-encoded on the way to the panel. Up to v2.20.1 it was a byte passthrough.
• The demo's Android leg prefers {R8G8B8A8_UNORM, B8G8R8A8_UNORM} and stores display-referred bytes in it, so those bytes are now encoded twice. Its macOS and Linux legs had already moved to _SRGB, which is why the Mac looked right.
• The INV-4.6 text in docs/guides/displayxr-app-rules.md still said the old thing: "a linear / UNORM swapchain is NOT color-managed … passes the bytes straight through".
• check_displayxr_app.py couldn't catch it: INV-4.6 passed if an sRGB token appeared anywhere in the app, and the desktop legs supplied one.

The app fix is in the demo repo: DisplayXR/displayxr-demo-gaussiansplat (linked below).

What this changes

• Guide (INV-4.6):

  • States the current model: _SRGB holds encoded colour; UNORM is linear and gets encoded, so display-referred bytes in UNORM wash out.
  • Lists which release made each backend format-honest: D3D11 v2.21.0, D3D12 v2.21.1, GL v2.21.2, vk_native v2.21.7. Metal still passes UNORM through.
  • Says every leg of a multi-platform app must make the same _SRGB-first choice.
  • Documents the on-device A/B: adb shell setprop debug.xrt.DXR_COLOR_LEGACY_UNORM_ENCODED 1.
  • Updates the checklist line to match.

• Linter, INV-4.6 is now checked per leg. Shared (non-platform) code counts toward every leg. In any file that calls xrEnumerateSwapchainFormats it WARNs on:

  • a format preference list naming only UNORM formats;
  • a scan loop that breaks on the first UNORM.

  The "no sRGB format anywhere" warning is now issued per leg. .claude/ (agent worktrees) is no longer scanned.

• Tests: scripts/tests/test_check_displayxr_app_color.py has 8 hermetic cases and is wired into lint.yml. 3 of them fail against the previous linter (mutation check).

Evidence

Setup: macOS M1 Pro, MoltenVK, vk_native, sim_display. Gauss demo using GsAdrenoRenderer, the same renderer the Android leg uses, with the Android leg's UNORM choice forced. Values are atlas-capture pixels:

runtime	swapchain	pixel A	pixel B
v2.21.11	_SRGB	(229,182,127)	(225,123,128)
v2.21.11	UNORM	(243,220,187)	(241,185,188)
v2.20.1	UNORM	(229,182,127)	(225,123,128)
v2.21.11	UNORM + DXR_COLOR_LEGACY_UNORM_ENCODED=1	(229,182,127)	(225,123,128)

• The UNORM row is exactly the sRGB encode of the authored value.
• The other three atlases are byte-identical over the whole 1280×1440 frame.

Linter results

• In-tree test_apps: INV-4.6 findings are unchanged, old vs new, on every app.
• Demo repos: it flags the Android leg of all five demos (gauss, modelviewer, mediaplayer, earthview, avatar). For avatar it also flags the macOS and Linux legs, which break on UNORM first.

Not in this PR: the runtime itself. It stays spec-correct, and CTS depends on it.

🤖 Generated with Claude Code

[dfattal]

Every demo had the same app-side bug, and each now has its own fix PR:

• gaussiansplat fix(android,color): choose an _SRGB swapchain on every leg — splats were encoded twice on the tablet displayxr-demo-gaussiansplat#138
• avatar fix(color): macOS, Linux and Android take an _SRGB swapchain (washed-out avatar on runtime >= v2.21.7) displayxr-demo-avatar#113 (macOS, Linux and Android legs)
• earthview fix(android): take an _SRGB atlas swapchain so tile colour is not encoded twice displayxr-demo-earthview#76
• modelviewer fix(android): prefer an _SRGB atlas swapchain (washed-out colour on runtime >= v2.21.7) displayxr-demo-modelviewer#154
• mediaplayer fix(android): prefer an _SRGB atlas + HUD swapchain (runtime v2.21.7+ washed-out colour) displayxr-demo-mediaplayer#89 (atlas and HUD swapchains)

The linter from this PR flags every current main of those repos on the legs that pick UNORM first, and passes all five fix branches clean on INV-4.6.

The second commit narrows the per-leg "no sRGB" warning to legs that enumerate formats themselves. It was firing on avatar's Windows zone swapchain, which reuses the format displayxr-common already negotiated.

🤖 Generated with Claude Code