Decouple hardware 2D/3D from content tile-count across all native compositors (D3D11/D3D12/GL/Metal/VK-native)

[dfattal]

Background

The Android single-app OOP path was fixed in #541 to decouple two independent concerns that were fused into one hardware_display_3d flag:

• Hardware — the panel's lenticular weave state (2D flat ↔ 3D), a display-processor operation driven by xrRequestDisplayRenderingModeEXT → request_display_mode, gated on what display_info advertises.
• Content — how the app draws: 1 high-res tile (2D) vs N lower-res tiles (3D), packed into the atlas the runtime hands to the DP.

While doing that I audited the other compositors. All five native compositors still conflate the two — a single hardware_display_3d flag drives both the DP weave and clamps the content tile-count:

d3d11:  compute_effective_views(): if (!hardware_display_3d && views>1) views = 1     // comp_d3d11_renderer.cpp:1290
d3d12:  view_count = hardware_display_3d ? 2 : 1                                       // comp_d3d12_renderer.cpp:1426,1672
vk_nat: view_count = hardware_display_3d ? layer->data.view_count : 1                  // comp_vk_native_renderer.c:373
gl:     effective_views = hardware_display_3d ? (tile_columns * tile_rows) : 1         // comp_gl_compositor.cpp:2725,2878
metal:  mode_views = hardware_display_3d ? (tile_columns * tile_rows) : 1              // comp_metal_compositor.m:3024,3217

This is harmless today because in-process (handle apps) the flag is set reliably by request_display_mode, and the D3D11 service is driven by the workspace controller via workspace_request_display_mode (which crosses IPC) — and each renderer knows its own tile layout. It only broke on Android OOP, where the request was a no-op over IPC (so the flag was inferred from content and latched) and tile_columns was the stale server mode. #541 fixed Android by making the hardware flag reliable (new compositor_request_display_mode IPC) and taking content purely from the submission.

Why this matters (not just consistency)

Developers need to switch hardware and content independently to author their own transitions. The hardware_3d ? N : 1 clamp removes that control: the hardware flag dictates the tile count, so the app can't, say, hold its 3D content while the panel goes flat, or run a custom cross-fade across the switch.

This is most important in MANUAL eye-tracking mode (#522): there, the app owns the tracking-loss lifecycle. On an XrEventDataEyeTrackingStateChangedEXT loss event the app should be free to craft its own response — e.g. drop the panel to 2D (flat, comfortable) immediately while it independently transitions its content (fade the parallax to zero over a few frames, then collapse to a single tile), or vice-versa. With hardware and content fused, none of that is expressible — the moment the app changes one, the runtime forces the other.

Proposed work

Apply the #541 model uniformly to D3D11, D3D12, GL, Metal, and VK-native:

1. Drive the DP's mode_3d (weave) from the hardware request (request_display_mode), recorded as a dedicated weave-state — not re-derived from the submitted view count.
2. Build the atlas tile-count/layout from the submission (view count + per-view imageRects), not from the hardware flag.
3. Remove the hardware_3d ? N : 1 clamp; let the DP weave (hardware-3D) or show the tiles flat (hardware-2D) regardless of how many tiles arrive — so a hardware/content mismatch during a custom transition renders predictably instead of being clamped away.

Reference implementation: comp_multi_system.c render path in #541 (hardware from multi_compositor_request_display_mode, content from layer->data.view_count, mono-blit removed, single atlas→DP path).

Notes / risk

• Not a bug fix — these paths work today (reliable flag + known tiles). This is an architectural-consistency + developer-flexibility refactor, and future-proofs any OOP variant of these APIs against what Android hit.
• Medium-sized, low-risk; do per-API with on-device 2D/3D + switch + a custom-transition test (hold 3D content while requesting hardware-2D, and the MANUAL loss-of-tracking case).
• Pairs with the timing follow-up from fix(#533): decouple hardware 2D/3D from content; unify the 2D/3D render path #541 (a 1-frame hardware-leads-content transient on switch — lead/lag the hardware request to hide it), which the same independence makes possible to author.

Refs: #538, #541, DisplayXR/displayxr-leia-plugin#90 (MANUAL/MANAGED eye tracking).

[dfattal]

Implementation kickoff — branch, parallel split, and prompts

Work happens on shared branch feat/decouple-compositors-542 (off main). Two boxes run in parallel on disjoint files (no conflicts; git pull --rebase before pushing); one PR to main when all five compositors are done.

• Windows + Leia SR box: D3D11, D3D12, GL, VK-native — real-panel validation.
• macOS box: Metal only — compile + sim_display (no lenticular panel; real-weave confidence comes from the identical D3D/VK pattern).

The pattern (apply per compositor — in-process, NO IPC needed)

The hardware request already reaches the DP in-process via *_compositor_request_display_mode, so unlike the Android #541 fix this is render-path-only:

1. Drive the DP's mode_3d (weave) from the hardware request state, not re-derived from the submitted view count.
2. Build the atlas tile count/layout from the submission (view_count + per-view subImage.imageRect), not from the hardware flag.
3. Delete the hardware_3d ? N : 1 clamp. The DP weaves (hardware-3D) or shows tiles flat (hardware-2D) regardless of tile count, so a hardware/content mismatch during a custom transition renders predictably instead of being clamped away.

Reference: PR #541 render path (comp_multi_system.c, commit 2ac7bbbdf).

Clamp sites (from the audit)

d3d11:  compute_effective_views() — comp_d3d11_renderer.cpp:1279-1293
d3d12:  comp_d3d12_renderer.cpp:1426, 1672
gl:     comp_gl_compositor.cpp:2725, 2878
vk_nat: comp_vk_native_renderer.c:373 + comp_vk_native_compositor.c:1247-1257
metal:  comp_metal_compositor.m:3082, 3262, 3318-3322

---

Windows-box prompt (D3D11 / D3D12 / GL / VK-native)

You're implementing DisplayXR/displayxr-runtime#542 on a Windows + Leia SR machine. Branch feat/decouple-compositors-542
(off main, pushed). A macOS box owns Metal on the SAME branch in parallel — you own D3D11,
D3D12, GL, VK-native; leave src/xrt/compositor/metal/ alone. pull --rebase before pushing.

ASK: decouple the panel HARDWARE 2D/3D weave-state from the rendered CONTENT (tile count) so
they switch INDEPENDENTLY — for app-authored transitions, especially MANUAL eye-tracking (#522)
on loss-of-tracking (flatten the panel while the app fades its own content's parallax).

PATTERN (render-path only; in-process the hardware request already reaches the DP via
*_compositor_request_display_mode, so NO IPC work):
 1. Drive the DP's mode_3d from the hardware request state, not the submitted view count.
 2. Build the atlas from the submission (view_count + per-view imageRect), not the hardware flag.
 3. DELETE the `hardware_3d ? N : 1` clamp (sites above). DP weaves (hw-3D) or shows tiles flat
    (hw-2D) regardless of tile count.
Reference: PR DisplayXR/displayxr-runtime#541 render path (comp_multi_system.c, 2ac7bbbdf).

FIRST STEP: scripts\build_windows.bat all ; _package\run_cube_handle_d3d11_win.bat ; confirm a
clean 2D<->3D switch on the Leia panel = baseline. Do D3D11 first (real hw + cleanest clamp),
prove on the panel, then D3D12, GL, VK-native.
BUILD: scripts\build_windows.bat build (runtime) / test-apps. Copy binaries to
C:\Program Files\DisplayXR\Runtime. Logs: %LOCALAPPDATA%\DisplayXR\.
VALIDATE on the real panel: clean 2D<->3D; and the NEW capability — request hardware-2D while
still submitting 2 tiles (renders flat, not garbage) and hardware-3D while submitting 1 tile
(shows the single tile, no overflow/crash); the MANUAL-loss case if drivable.
DON'T: touch IPC (proto.json/ipc_*) — not needed in-process; touch metal/; regress the normal
case (request+submit matching mode → byte-identical output).
WRAP: commit per compositor referencing DisplayXR/displayxr-runtime#542, push to feat/decouple-compositors-542. One PR to
main when all four + Metal are done. Don't tag/release.

macOS-box prompt (Metal)

You're implementing the Metal leg of DisplayXR/displayxr-runtime#542 on macOS. Worktree .claude/worktrees/metal-542 is on
branch feat/decouple-compositors-542 (shared; a Windows box owns D3D11/D3D12/GL/VK-native in
parallel — you own ONLY src/xrt/compositor/metal/). pull --rebase before pushing.

ASK + PATTERN: identical to the Windows prompt above (decouple hardware weave-state from content
tile count; mode_3d from the request state; atlas from the submission; DELETE the clamp). NO IPC
needed (comp_metal_compositor_request_display_mode already reaches the DP in-process).
Reference: PR DisplayXR/displayxr-runtime#541 (comp_multi_system.c, 2ac7bbbdf).

CLAMP SITES: comp_metal_compositor.m:3082, 3262 (window-space variant), 3318-3322 (tile origins/sizes).
BUILD: ./scripts/build_macos.sh ; _package/DisplayXR-macOS/run_cube_handle_metal.sh (+ texture).
VALIDATE (sim_display only — NO lenticular panel on Mac): compiles; 2D/3D logic yields the right
atlas tile count; hardware/content can diverge without crash/garbage. Pixel check: metal compositor
polls /tmp/dxr_atlas_trigger → /tmp/dxr_atlas.png (CLAUDE.md "macOS test-app pixels"). Real-weave
confidence comes from the D3D11/VK validation on the Windows box.
DON'T: touch IPC or non-metal compositors; regress the normal case.
WRAP: commit referencing DisplayXR/displayxr-runtime#542, push to feat/decouple-compositors-542. Don't tag/release.

---

Docs / ADR checklist (do once both legs are validated — fold into the #542 PR or an immediate follow-up)

• New ADR — "Hardware 2D/3D panel state is decoupled from rendered content": the principle (two independent signals), the rationale (app-authored transitions + the MANUAL loss-of-tracking case), and the per-compositor implementation.
• docs/specs/vendor/eye-tracking-modes.md — in MANUAL, state the app may transition hardware (panel) and content (tiles) independently on a tracking-loss event.
• 2D/3D rendering-mode spec + docs/architecture/compositor-pipeline.md / multiview-tiling — make explicit that content (atlas, from the submission) and hardware (DP mode_3d, from request_display_mode) are independent signals.
• Cross-link fix(#533): decouple hardware 2D/3D from content; unify the 2D/3D render path #541 (Android reference), fix(#533): 2D mono view ~2x zoom (oxr halves the collapsed eye distance) #538, Eye-tracking modes (Android Leia): advertise MANAGED+MANUAL; default MANAGED (CNSDK-managed); MANUAL disables CNSDK management displayxr-leia-plugin#90 (MANUAL/MANAGED).