Color management: define one systematic encoding-state model across in-process / IPC / workspace compositors

[dfattal]

Why this issue

The recent sRGB/gamma fixes (#407 GL, #408 D3D11/D3D12/VK/Metal) corrected a real bug, but they also surfaced that runtime color handling has grown ad-hoc — each of the three compositor paths uses a different colorspace strategy, tuned reactively to whatever apps it happened to meet. The in-process path simply hadn't met an sRGB-swapchain app until the GL viewer, which is why the gamma bug sat undetected.

This issue proposes a common mental model and invites input before we commit to a direction. No code decision is being made here yet — looking for opinions from folks who've touched the service/workspace paths and the Leia weaver.

The one thing to track: encoding state

Every texture holds pixels in one of two states:

• Linear (scene-referred / radiance) — proportional to light. Blending, filtering, MSAA resolve, mipmap gen are only correct here.
• Encoded (display-referred, sRGB/gamma) — in the panel's transfer function; what the display physically wants.

A texture's format declares which (*_SRGB ⟹ encoded, GPU auto-decodes on sample / auto-encodes on RT write; UNORM/float ⟹ linear). The whole problem reduces to one invariant:

Colorspace conversions must come in matched pairs (decode … encode) or not at all (passthrough) — never half.

The bug we chased across five compositors was always the same half-conversion: decode-on-sample (format said sRGB) with no encode-on-write (atlas was UNORM) → ~2.2× too dark.

Two canonical spaces define the whole pipeline

app render → [swapchain] → sample → [compose / atlas] → DP handoff → panel
                         ^^^^^^               ^^^^^^^^^^^^
                      COMPOSE space        DP-HANDOFF space

• Compose space — linear (correct blend math) vs encoded (simpler, wrong blending).
• DP-handoff space — what the Leia weaver expects. Empirically: encoded (display-referred) bytes. (The older "DP wants linear" note described a service-path intermediate, not the handoff.)

Pin those two and every compositor's job is just: get bytes from the swapchain's declared space into compose space, then into DP-handoff space, with matched conversions.

Current state — three paths, three strategies (the ad-hoc-ness)

Path	Compose strategy
In-process (handle/hosted/texture → per-API native comp → DP)	Passthrough (after #407/#408): no decode, no encode; atlas opaque UNORM. Now consistent across GL/D3D11/D3D12/VK/Metal. Single-layer zero-copy = passthrough by construction.
IPC / multi-compositor (service, WebXR bridge)	Linearize-on-write: sRGB SRV decode into the per-client atlas.
Workspace / shell	Track-and-reinterpret-on-read: raw byte copy + dual UNORM/sRGB SRVs chosen by a per-client atlas_holds_srgb_bytes flag.

Three philosophies, each grown to fit the apps it met.

Two coherent end-states

Model A — Passthrough (what in-process now is). Treat the swapchain as already display-ready bytes; no conversions; DP gets them verbatim.

• ✅ Simple, consistent, matches how apps here actually behave (they write display-referred bytes into both sRGB and UNORM swapchains).
• ❌ Compose blending in non-linear space → alpha overlays / launcher band / compose-under-bg transparency / MSAA / mips technically wrong (usually tolerable). Can't honor a true-linear app.

Model B — Colorspace-aware (the "proper" model). Decode iff sRGB → compose in linear → encode at the DP boundary (sRGB-typed handoff). DP always gets encoded.

• ✅ Correct linear compositing (real win for the Leia transparency model). Honors both linear and encoded apps per their declared format. One rule for all three paths.
• ❌ Requires apps to declare colorspace honestly — and today they don't: the cube test apps put encoded content in UNORM swapchains, so Model B would over-brighten them. So Model B is an ecosystem change, not just a runtime change.

Proposed systematic design (Model B, if we go there)

One rule for all three paths:

1. Format is source-of-truth for a swapchain's encoding state (needs an app-side contract: sRGB ⟺ encoded, UNORM/float ⟺ linear).
2. Atlas/compose space is linear (UNORM-as-linear, or float16 for HDR/wide-gamut headroom later).
3. DP-handoff is encoded — DP-input texture sRGB-typed (or final write encodes), so the weaver always receives display-referred bytes.

What's missing isn't code — it's a canonical ADR stating the encoding state at every hop + asserting the matched-pair invariant. That's what turns "ad-hoc per app" into "systematic per contract."

Open questions for discussion

1. Do we want Model A (passthrough) or Model B (linear compose)? Model B is "more correct" and fixes blending/transparency quality, but requires an app colorspace audit. Is the blending-correctness win worth it for the Leia transparency / compose-under-bg work?
2. What does the Leia weaver actually want at handoff — confirm encoded-bytes for all DP backends (D3D11/D3D12/GL/VK/Metal), and does any DP path expect linear?
3. Can we get apps to declare colorspace honestly, or do we need a per-app "treat-as-encoded" override for legacy/test apps?
4. HDR / wide-gamut: if that's on any roadmap, a float16 linear compose space changes the calculus toward Model B now.
5. Verification gap: none of our current test apps render true linear into a UNORM swapchain, so the "linear input" path has never been exercised. Should we add a true-linear test app regardless of the model we pick?

Suggested next step (cheap, model-agnostic)

Write the contract down — an ADR "Color management & the encoding-state invariant" defining compose space, DP-handoff space, and the app format contract. Even staying on Model A, documenting "swapchain holds display-referred bytes; runtime passes through; DP presents" stops the next reactive patch.

cc @dfattal — context from the #407/#408 investigation.

🤖 drafted by Claude Code from the sRGB-fix investigation

[dfattal]

Strong +1 on writing the ADR first — but resolve Q2 before choosing A vs B, because the issue's own table implies one of the server paths may have an unverified half-conversion.

The matched-pair invariant is the real deliverable; adopt it now, model-agnostically

The "decode … encode in matched pairs, or passthrough, never half" rule is the fix for the entire bug class — it's path-independent and not in tension with either model. Land that as the ADR's central assertion regardless of A/B, with the encoding-state table having a column per path and a row per hop, so "is this path balanced?" becomes a mechanical check (and ideally a test, see Q5). That alone stops the next reactive patch.

Q2 is the gate, and the table already hints at a problem

The issue treats DP-handoff = encoded as empirically settled — but that evidence came from the in-process path (#407/#408). The two server-side strategies need the same empirical confirmation, because as written they describe different conversion chains landing on the same DP:

• IPC/multi = linearize-on-write → atlas is linear.
• Workspace/shell = track-and-reinterpret → atlas byte-state varies by atlas_holds_srgb_bytes.
• In-process = passthrough → atlas holds encoded bytes.

If the same Leia DP backend is shared across modes, it can't want both linear and encoded at handoff. So either (a) the IPC/workspace paths re-encode at the DP boundary (the issue's "linear was an intermediate, not the handoff" parenthetical assumes this — but it should be located in code, not assumed), or (b) one of them is the same too-dark half-conversion #407 was, just unexercised. Concrete ask: run the #407 eyeball test (known midtone ramp on-panel) in workspace mode and IPC mode, and point at the line where each path re-encodes before process_atlas(). Until that's pinned, "DP wants encoded" is a one-path generalization.

A vs B: I'd target B, because it has a concrete payoff exactly where blending lives

Model A and Model B are identical for the in-process single-app / zero-copy path — there's nothing to blend, so passthrough == linear-compose there. They only diverge where the runtime actually composites overlapping surfaces, i.e. the workspace/shell path — which is also where the Leia transparency / compose-under-bg model lives. Alpha compositing and premultiplied-alpha math in a non-linear space produce visibly wrong edges/halos; that's not "usually tolerable" for overlapping translucent app windows, it's the exact case the transparency work cares about. So B's correctness win isn't theoretical — it's targeted at an active feature, and it costs ~nothing on the trivial path.

B's blocker (Q3) is already half-solved by the app contract

The "apps must declare colorspace honestly" problem is real — the cube apps put encoded bytes in UNORM swapchains. But the app-authoring contract from the #407 investigation (request an sRGB swapchain and store a correctly-encoded image) is precisely the lever: well-behaved apps stop producing UNORM-holding-encoded ambiguity. The remaining liars are the legacy test apps → fix them to sRGB swapchains (cheap) or a transitional per-app treat-as-encoded override. So Q3 is tractable and already in motion.

On the others

• Q4 (HDR/wide-gamut): if it's on the roadmap at all, it forces B + float16 linear compose — that decides A-vs-B by itself. Worth confirming roadmap intent before debating.
• Q5 (verification gap): yes, add a true-linear test app (linear values into a UNORM swapchain) regardless of model — it's the only thing that exercises the path neither model has ever tested, and it's the regression guard for the matched-pair invariant.

Suggested sequencing

1. Write the ADR with the per-hop / per-path encoding table + matched-pair invariant (model-agnostic).
2. Resolve Q2 empirically (workspace/IPC eyeball + locate the re-encode) — this may itself surface a latent bug and will settle "encoded at handoff" for real.
3. Decide A vs B with Q4 (HDR) as a tiebreaker; my lean is B, staged, gated on the app contract + legacy-app fix + the true-linear test app.

— drafted from the #407/#408 + app-authoring-rules context.

🤖 Claude Code

[dfattal]

Q2 (what the DP-handoff space actually is) is now settled by code inspection — and it confirms hypothesis (b): one server path carries the same too-dark half-conversion #407 fixed, just unexercised.

The ask was "point at the line where each server path re-encodes before process_atlas(), or one of them is an unbalanced half-conversion." The answer is the latter, and it's provable from the source:

The re-encode partner exists but is never called

src/xrt/compositor/d3d11_service/d3d11_service_shaders.h:687 defines linear_to_srgb(), and its own comment (lines 684–686) states the intent exactly:

"When sampling from an SRGB SRV, the GPU auto-linearizes the values. We need to re-encode to sRGB before writing to the non-SRGB stereo texture so the weaver receives sRGB-encoded values (matching SR Hydra's behavior)."

It has zero call sites (grep linear_to_srgb\s*\( → only the definition). The matched-pair partner the invariant requires was written, then never wired up.

Corroborating: every convert_srgb value the shaders actually use is decode or non-color — 1.0 = decode-on-sample, 0.0 = passthrough, 2.0 = solid-color, 2.5+ = glow/rim. There is no "encode-on-write" path in use.

The actual chain, and the latent bug

Service/workspace compose (comp_d3d11_service.cpp:6525-6526): when atlas_holds_srgb_bytes == true, it selects atlas_srv_srgb → GPU decodes sRGB→linear on sample → the multi-comp shader writes those linear values at convert_srgb=0 (passthrough) → handed to process_atlas() labeled UNORM. A decode with no matching encode → weaver receives ~2.2×-too-dark values.

It's dead in the current tree only because every workspace/test app writes encoded-into-UNORM swapchains → atlas_holds_srgb_bytes is always false → UNORM SRV → raw passthrough → correct. It arms the first time a real sRGB-swapchain app (Unity/Unreal commonly are) runs under the workspace.

Conclusion for the issue

• DP-handoff space = ENCODED (display-referred). Proven twice now: the fix(compositor-gl): sRGB passthrough for in-process GL swapchains #407/fix(compositors): sRGB passthrough for in-process D3D11/D3D12/VK/Metal swapchains #408 in-process fix direction, and the dead helper's own "so the weaver receives sRGB-encoded values (matching SR Hydra's behavior)" comment. The settled answer to Q2 is "encoded," for real, not a one-path generalization.
• docs/architecture/compositor-pipeline.md:30,35 is wrong — it asserts "DP expects linear input." That's the line that misleads the next reader.
• A-vs-B collapses to a single decision in one path. In-process is identical under both models; the only divergence is the service/workspace branch above — which is exactly where compose-under-bg transparency blends. The immediate bug fix is the A-vs-B fork: passthrough that branch (Model A baseline, delete the dead helper) or keep the decode and wire up linear_to_srgb (Model B's matched pair).

One trap for whoever implements B

linear_to_srgb uses pow(x, 1/2.333) ("SR Hydra's gamma"), but the decode side (sRGB SRV) uses the true sRGB curve. Pairing an sRGB decode with a 2.333-power encode is a half-broken matched pair — a persistent tint, not a clean round-trip. The ADR should name one canonical transfer function used on both sides of every pair.

Next steps

Writing ADR-021 "Color management & the encoding-state invariant" now (matched-pair invariant + per-hop/per-path encoding table + DP-handoff = encoded), correcting the doc, and adding a one-shot guard at the latent branch so it can't be rediscovered cold. Baseline is Model A (coherent passthrough across all three paths today); Model B recorded as the sanctioned future upgrade, scoped to the workspace compose path and gated on the transparency feature.

— code-proof drafted by Claude Code from the #407/#408 investigation.

[dfattal]

Correction to my previous comment — "DP-handoff = encoded" was the wrong framing. It derives a DisplayXR-wide convention from one vendor's weaver, which inverts our dependency direction (ADR-003/007/019: the DP adapts to the runtime, never the reverse). The code-proof in that comment stands — the service sRGB-SRV branch is an unmatched decode, and the Leia DP does consume encoded bytes today — but the conclusion to bake into the runtime should be:

The handoff encoding is declared by the DP, and the runtime supports both

• DisplayXR owns a vendor-neutral compose space + the matched-pair invariant.
• The DP declares its accepted handoff encoding — LINEAR, ENCODED, or EITHER — via the DP vtable. The runtime converts compose→handoff to match, as a matched-pair step (no-op when they already agree). A vendor whose weaver only takes linear, or only encoded, is fully served; the runtime adapts at the boundary.
• "Leia wants encoded" → "the Leia DP declares ENCODED" — one instance of the contract, not its definition.
• No vendor curve in the runtime. The canonical encoded state is standard sRGB. The dead linear_to_srgb() helper bakes Leia's pow(x,1/2.333) into shared shader code — that's a vendor-isolation violation and gets deleted; any panel-specific curve lives inside the DP, after the runtime hands off standard bytes.

This decouples two things I'd wrongly fused: compose-space model (A passthrough vs B linear — an internal correctness choice) and handoff encoding (a per-DP declared contract). The both-direction conversion machinery (encode-at-handoff for an ENCODED DP, decode-at-handoff for a LINEAR DP) is exactly what lets one compose space serve any vendor.

ABI: per ADR-020 the declaration is an append-only struct_size-gated field; absent ⟹ ENCODED, preserving today's de-facto behavior and the Leia DP's current need.

Landed in a PR (docs + guard, for review)

• ADR-021 "Color management & the encoding-state invariant" — rewritten around DP-declared handoff + both-direction support + standard-sRGB-only.
• compositor-pipeline.md — corrected the "DP expects linear input" assertion to the declared-handoff model; documented the latent sRGB-SRV half-conversion.
• One-shot guard at the latent branch (comp_d3d11_service.cpp).
• Inbound anchor links fixed.

Baseline stays Model A (coherent passthrough against an ENCODED-declaring DP today); Model B (linear compose) recorded as the sanctioned future, scoped to the workspace compose path and gated on the transparency feature. The DP-declaration vtable field is specified in the ADR as the next implementation step — not in this PR.

— thanks @dfattal for the vendor-neutrality catch.

[dfattal]

Verified against sr_test + the Leia plugin — the SR weaver accepts EITHER encoding, which makes the contract cheap for Leia.

The weaver exposes setShaderSRGBConversion(bool read, bool write) (sr_test/modules/srDirectX/dxweaver/sr/weaver/dx11weaver.h, plus D3D12/GL equivalents):

• read → decode sRGB→linear before weaving
• write → encode linear→sRGB after weaving

Encoding is an explicit knob, not inferred from the texture format. So:

1. Leia's DP capability is EITHER. The runtime can send its native compose space and never convert at the boundary; the DP sets the knob to match. atlas encoded → (false,false) (today) or (true,true); atlas linear → (false,true) (weave in linear, encode on output).
2. The matched encode partner belongs in the DP, not the runtime. The weaver's write=true is the linear→sRGB encode. This confirms deleting linear_to_srgb() from runtime shaders is correct, not just vendor-hygiene — and means Model B needs no runtime encode shader against Leia.
3. The latent bug is confirmed real today: the plugin's leiasr_d3d11_set_srgb_conversion() wrapper exists but is never called, so the weaver does no conversion. Hand it linear bytes (the sRGB-SRV branch) and it weaves linear → outputs linear → too dark. The fix is either passthrough (Model A) or wire write=true.

Plugin work this implies (displayxr-leia-plugin, separate repo)

• Call setShaderSRGBConversion(read, write) from process_atlas, driven by the runtime's declared atlas encoding (write=true whenever input is linear).
• Expose the setter for the D3D12 and GL wrappers — today only D3D11 has it, though the SR SDK provides all three.
• Declare capability EITHER.

Net effect on the design

The runtime's Model-A-vs-B choice becomes a purely internal correctness decision with zero boundary-conversion cost against an EITHER-capable DP. ADR-021 records: DP capability declaration (LINEAR/ENCODED/EITHER, absent⟹ENCODED for back-compat per ADR-020) + a per-frame runtime encoding declaration replacing the dead hardcoded R8G8B8A8_UNORM process_atlas format arg.

Note on neutrality: the ADR and the architecture docs are written vendor-neutral — the concrete weaver knob and the plug-in wiring gaps above live in docs/vendors/<vendor>/, not in the official record.

Landed in #411 (ADR + doc fixes + one-shot guard). The process_atlas encoding arg, the DP-vtable capability field, and the per-vendor plug-in wiring are specified there as the next implementation steps (not in this docs PR).

— verified against the vendor SDK test sources and plug-in.