docs(adr): ADR-044 — the colour contract, per backend and swapchain format

[dfattal]

Summary

The rule. The swapchain's format says what its bytes mean, and the runtime believes it:

• _SRGB holds encoded colour;
• UNORM and float hold linear values, and the runtime sRGB-encodes them.

This is OpenXR's rule, and the CTS judges it (GradientFormatsLinearVsNonLinear, SourceAlphaBlending*, #1589/#1610). Every native compositor except Metal has followed it since v2.21.0–v2.21.7.

The app rule: write encoded colour into _SRGB or linear into UNORM; prefer _SRGB, and make the choice the same way on every platform leg.

This PR adds ADR-044, which puts that into one table and amends ADR-021.

What ADR-044 contains

• Per-backend table:
  • backends: D3D11, the D3D11 service, D3D12, GL, vk_native (Windows / Linux / macOS / Android), Metal;
  • for each: enumerated format order, the _SRGB vs UNORM/float handling, where layers blend, the DP handoff, and the release that shipped it.
• App write rules: what the app must write per format, plus clears and alpha.
• Layers: the §10.6.2 blend and opaque-cover rules.
• DP side: set_atlas_encoding, Model B, and the Leia CNSDK Android DP.
• Capture: the encoded PNG, DXR_ATLAS_CAPTURE_RAW_ALPHA, and trigger paths.
• What guards each row:
  • CTS arms, including the human-judged interactive composition runs;
  • structural ctests;
  • vk_srgb_blend_probe;
  • the per-leg app lint (fix(app-rules): INV-4.6 — UNORM swapchains are linear since #1589; lint the _SRGB choice per leg #1760).
• Coverage gaps, stated explicitly: vk_native on macOS and Android, and Metal, are not CTS-covered.
• Open rows (recorded, not fixed here):
  • Metal is still pre-CTS composition: UNORM (linear) swapchains are passed through un-encoded on every backend — GradientFormatsLinearVsNonLinear FAIL; ADR-021 Model A vs OpenXR format semantics #1589 passthrough;
  • the IPC comp_multi paths are unaudited;
  • the displayxr-common Windows window-space HUD swapchain is UNORM holding display-referred bytes.

Also in this PR

• ADR-021 gets an "amended by" note. Its principles stand. "Model A" now means "the atlas is encoded", not "UNORM passes through".
• Pointers to ADR-044 from INV-4.6 and from compositor-pipeline.md.
• The ADR index is regenerated.

Why now

On 2026-09-28 the demos were washed out:

• every demo's Android leg, on the tablet running runtime v2.21.11;
• avatar on macOS.

Each of those legs picked UNORM and wrote display-referred bytes, which v2.21.7+ encodes a second time. Fixed app-side in:

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

The guide text and per-leg linter fix is #1760 (separate PR, independent of this one).

Checks run locally

• gen_adr_index.py --check: OK.
• check_doc_paths.py: 894 links, OK.

Docs-only, so CI short-circuits.

🤖 Generated with Claude Code