feat(vk_native): per-screen segment DPs for spanning windows (multi-screen M2)

[dfattal]

What / why

Multi-screen M2 — segments, one vendor (ADR-047 D2). A window whose canvas covers several screens is woven per segment (canvas ∩ screen) by the display processor of that screen, each with its own canvas and present origin, composited into the one presented surface. Stacked on #1852 (M1); do not merge before it.

Target demo on ds1-linux: cube_handle_vk_linux across eDP-1 ↔ DS1 with DXR_PLUGIN_EXCLUSIVE=sim-display is anaglyph on both halves — two sim DPs, two canvases, no 2D band.

The segment model (10 lines)

1. A segment = canvas ∩ screen: window_rect (window px, = the canvas handed to process_atlas), screen_rect (that screen's px), present_origin (window origin relative to that screen; the DP adds the canvas offset, so phase = screen_rect origin).
2. util/comp_segments.{h,c} — backend-agnostic, pure math: the table (via u_multi_display_compute_slices), the 1:1 policy, uncovered canvas, DP lifecycle hysteresis.
3. The primary (system-default) screen's segment keeps the session's DP; it still owns eyes / window metrics / Kooima (one view pair — per-segment views are M3).
4. Every other screen gets a segment DP from its registry plug-in through create_dp_vk_for_screen only (no plain create_dp_vk fallback — a plug-in without the slot gets flat 2D there), windowless, created on the Decouple weave rate from app render rate: re-weave the last atlas at panel rate with fresh eye positions #868 runtime-owned queue, phase via set_present_origin.
5. Lifecycle: create after 2 metric updates, destroy after 30 (~0.5 s); failed creates are not retried while the segment lasts; a table change logs once at INFO.
6. Split frame (vk_native/comp_vk_native_segments.c): clear → crop each woven segment's views out of the atlas (crop before the DP) → process_atlas per segment with canvas = segment (primary first, then left to right) → flat 2D view for unweavable segments + uncovered canvas → target left in PRESENT_SRC_KHR, so everything after the weave is unchanged.
7. Viewport and scissor = segment, set by the DP from the canvas (plan risk 7); a segment DP must not assume it is the first writer.
8. A window entirely on the primary screen never leaves the single-DP process_atlas call (byte-for-byte).
9. Scope: in-process Vulkan, desktop Linux X11/XWayland. Native Wayland stays primary-only (payload follow-up documented in wayland-window-geometry.md §5); also off for zero-copy, self-submitting DPs, pinned sessions (XrSessionDisplayBindingDXR), mixed vendors (M4). Kill switch DXR_SEGMENTS=0.
10. The post-compose atlas capture also writes each segment's DP input as <stem>.seg<i>.png.

ABI (ADR-020 append-only; XRT_PLUGIN_API_VERSION_CURRENT stays 5)

• xrt_plugin_iface::create_dp_vk_for_screen(inst, vk_bundle, cmd_pool, window_handle, target_format, const struct xrt_screen_binding *, out) appended after get_display_info_for_monitor; XRT_PLUGIN_IFACE_HAS_CREATE_DP_FOR_SCREEN + xrt_plugin_iface_has_create_dp_vk_for_screen(). xrt_screen_binding {struct_size, monitor_id, desktop rect, native px, mm, scale, vendor display_id, serial, device_name}, passed by pointer.
• xrt_dp_scanout_caps::flags carved out of reserved[0] (same size/offsets) with XRT_DP_SCANOUT_FLAG_TOLERATES_RESAMPLE; read via the existing get_scanout_caps slot (no new DP vtable slot). Clear = needs 1:1 = what every existing plug-in wrote there.
• Leia plug-in untouched (no slot → its other screens are flat 2D; and mixed-vendor layouts don't segment in M2).

The 1:1 policy

Per segment and per DP capability (comp_segments_decide): no DP → flat 2D; DP needs 1:1 on a resampled screen → flat 2D; 1:1 / unknown / resample-tolerant DP → woven ("unknown never degrades"). The session-level gates (X11 #1831, Wayland #1595 resample reasons b/c) no longer degrade a primary DP that declares the flag. sim_display declares it for every output except INTERLACED. Behaviour change: a sim_display anaglyph session on a fractionally scaled panel now weaves anaglyph instead of presenting 2D; lenticular weaves are unaffected.

sim_display

Per-instance screen state seeded from the binding (EDID mm / native px / desktop origin; the SIM_DISPLAY_* panel is the fallback); process_atlas confines viewport + scissor to the canvas (full-target canvas = pre-M2 pass exactly); a screen-bound DP uses a render-pass variant that starts in COLOR_ATTACHMENT_OPTIMAL and clears only its render area; set_present_origin feeds the interlaced phase; get_scanout_caps implemented. Output mode / view count stay session state (one atlas, one rendering mode, 1/2/3 keys) — segment DPs follow it.

Tests

• tests_comp_segments (new): table math on ds1-linux geometry, seam ownership, canvas sub-rect, uncovered canvas (coverage, gaps, area conservation), the 1:1 policy, lifecycle hysteresis (N/M, one-frame touch, failed create, no-factory, drain).
• tests_dp_weave_scope: flags default + offsets. tests_stereo_camera: iface now ends with create_dp_vk_for_screen.
• ./scripts/build_linux.sh --hybrid --apps green + selftest PASSED; ctest: all pass except the pre-existing tests_rig_composer / tests_oxr_view_space* failures on this box.
• MinGW: this box's toolchain is broken before any of this (Windows.h casing, TIME_UTC in the mcp dep); only comp_segments.c was cross-compiled cleanly by hand.
• Not yet run on hardware — no windowed app was launched (shared DS1). Gate below.

Gate (hub runs; X11/XWayland, sim-display only, dev plug-in dir)

cd .claude/worktrees/m2-segments
rm -f /tmp/displayxr_atlas*.png /tmp/displayxr_atlas_trigger
# 1600x900 at +2656+400 relative to eDP-1 (0,0): 800 px on eDP-1, 800 px on HDMI-1
DXR_PLUGIN_EXCLUSIVE=sim-display SIM_DISPLAY_OUTPUT=anaglyph DXR_CUBE_WINDOW=1600x900+2656+400 \
  ./build/run_cube_handle_vk_linux.sh --platform=x11 > /tmp/m2_gate.log 2>&1 &
APP=$!; sleep 8; touch /tmp/displayxr_atlas_trigger; sleep 3; kill $APP
grep -E "segments:|Atlas capture|X11 1:1 gate|sim_display: segment DP" /tmp/m2_gate.log
ls -la /tmp/displayxr_atlas*.png   # displayxr_atlas.png + .seg0.png (eDP) + .seg1.png (DS1)

Optional drag across the seam (hysteresis + table log): start at DXR_CUBE_WINDOW=1600x900+800+400 with DXR_X11_TEST_DRAG=2400,0,24.

Review fixes (after the gate)

• No plain-factory fallback for a segment DP: has_dp_factory requires create_dp_vk_for_screen; otherwise flat 2D. The per-screen call gets the Decouple weave rate from app render rate: re-weave the last atlas at panel rate with fresh eye positions #868 queue swap.
• No release under a parked fill: the epic: in-process tier parity — panel-rate weave everywhere (VK / D3D12 to match d3d11-hybrid smoothness) #1264 S1 fence-park releases c->mutex; segment DPs/images now go on a retire list (comp_segments_retire, tested) drained only when no fill is parked (c->fill_parked), with a debug assert in the release path. DP input images are per frame class (app / repaint), so the two never write each other's. set_screens defers the rebuild to a weave with no fill parked.
• sim_display single-monitor behaviour, stated explicitly: the unbound DP keeps the pre-M2 interlace phase (canvas_offset_x); only screen-bound segment DPs take set_present_origin. Viewport/scissor confinement to the canvas is kept for every caller on purpose (it is the process_atlas contract and the split path needs it from the unbound primary). It is identical to before whenever canvas == target, and differs only when canvas < target: the window-shrink transient, the shared-texture path, a comp_multi zone canvas (where sim used to stretch the canvas-sized atlas across the whole target). Documented in comp-segments.md.
• Tolerance follows the mode: re-read on a head rendering-mode change (never per frame); the X11 Linux: an X11/XWayland app on a fractionally-scaled 3D panel weaves for the wrong display (panel matched by size), and is resampled anyway #1831 one-shot is re-armed and clears its own degrade when the DP becomes tolerant; segment DPs re-read too.
• Nits: X11 gate waits for the DP create attempt; segment DPs get encoding (DXR_VK_ATLAS_ENCODING) and transparency on change; segment capture honours DXR_ATLAS_CAPTURE_RAW_ALPHA and splits the suffix on the extension's dot; mirrored outputs are de-duplicated (primary wins).
• Known, pre-existing, not addressed: a DP shared by the app frame and a parked fill (the primary today, segment DPs alike) may update its descriptor set while the fill's command buffer still uses it.

Gate result — PASSED on ds1-linux (2026-10-07)

Run by the hub with the exact gate command above (X11/XWayland, DXR_PLUGIN_EXCLUSIVE=sim-display, anaglyph, window 1600x900+2656+400, i.e. 800 px on eDP-1 and 800 px on HDMI-1).

Log lines:

segments: 2 screens, plug-in 'sim-display'
sim_display: segment DP ... for screen 0x886e4475353b22b9 — 3840x2160 px, 0.344 x 0.193 m, desktop origin (3456, 0)
segments: created a segment DP for screen 0x886e4475353b22b9 ('HDMI-1', plug-in 'sim-display') via create_dp_vk_for_screen — tolerates a resample
Atlas capture: segment 0 (screen 0x03fdab50663276e4) DP input 800x450 -> /tmp/displayxr_atlas.seg0.png
Atlas capture: segment 1 (screen 0x886e4475353b22b9) DP input 800x450 -> /tmp/displayxr_atlas.seg1.png

Captures (described; gh cannot attach images from the CLI):

• /tmp/displayxr_atlas.png, 1600x450: the whole-window atlas, two 800x450 view tiles (left and right eye).
• /tmp/displayxr_atlas.seg0.png, 800x450: the eDP-1 segment's DP input, the left 400 px of each view (two 400x450 tiles).
• /tmp/displayxr_atlas.seg1.png, 800x450: the HDMI-1 (DS1) segment's DP input, the right 400 px of each view.

So the window was split into two segments, each with its own sim DP (the secondary built through create_dp_vk_for_screen, describing the DS1's own geometry and desktop origin), and the per-segment atlas crop is correct: each DP received exactly its half of every view.

Part of #69 (M2). Addresses #546 items 2 (several DPs per compositor) and 4 (DP lifecycle with hysteresis) and the re-scoped item 3 (segments instead of an atlas split) for the in-process Vulkan compositor on Linux X11 — not closed: item 1 (real monitor id on the COMP_DP_PRIMARY_MONITOR call sites), the other APIs and Wayland remain. Refs #1849 #1851 #1852.

🤖 Generated with Claude Code