feat(display_info): per-segment views and view display bindings (multi-screen M3)

[dfattal]

What / why

Multi-screen M3: per-segment views (ADR-047 decision D3). A window that spans two screens is already woven per segment by M2, but every segment wove a crop of ONE view pair, so the off-primary half had the wrong perspective. Now, under PRIMARY_MULTIVIEW_DXR, each segment gets its own views: located from that screen's eyes, with that segment (relative to its own screen, in its own metres) as the Kooima canvas, and routed to that segment's DP.

Also closes the M4 runtime gap: M2's one-vendor rule is lifted. A segment DP is created from its screen's registry entry (owning iface/instance + ABI-checked VK factory), whichever plug-in won that screen; one INFO line when a mixed-vendor table is built. Every segment DP follows the session's 2D/3D mode (request_display_mode) and gets set_present_origin per frame. DXR_SEGMENTS=0 remains the kill switch.

The view-count contract

• PRIMARY_MULTIVIEW_DXR reports device max × view-set capacity (capped at XRT_MAX_VIEWS = 8). Capacity = min(XRT_MAX_SEGMENTS (2), DP-registry screens with a VK DP factory), computed once in oxr_system_fill_in, and 1 wherever no compositor can segment a window (every platform but desktop Linux, any service session). So a single-screen box, Windows, macOS and Android keep exactly the pre-M3 count (no change for existing multiview apps or the CTS); ds1-linux gets device max × 2. Per-view recommended sizes stay the worst-case envelope.
• A window on one screen locates byte-for-byte as before (active views first), the longer tail aliased onto view 0. Swapchain/atlas sizing unchanged (tiles are per active view of a set).
• Two segments: views [0,n) left segment, [n,2n) right (n = active mode count; mode is session-wide). activeViewCount = Σ. New XrViewDisplayBindingsDXR (1004999217, chained on XrViewState, two-call) names display / segment rect / view range. XR_DXR_display_info stays v22 (append).
• The View config: PRIMARY_STEREO session should suppress or deny view_count>2 rendering modes (follow-up to #1486 option B) #1499 mode floor asks one segment's share (oxr_segment_views_per_segment_capacity) — same verdict as pre-M3.
• PRIMARY_STEREO stays exactly 2.

The legacy-stereo rule

A PRIMARY_STEREO (or MONO) session never splits its views: its 2 views are framed from the segment holding most of the window (that screen's eyes, the whole window relative to it — identical to today's path when the majority is the primary screen), and the compositor crops them per segment as shipped in M2.

Routing / atlas choice

One atlas, per-segment tile ranges, as a mosaic: atlas layout unchanged (cols × rows tiles of canvas × scale), but local view j of segment k is drawn at segment k's rect inside tile j (blit + compose paths). The rect comes from comp_segments_tile_rect — the exact mapping M2's crop reads with — so cropping each segment out of every tile yields that segment's own views and the M2 split path runs unchanged. Routed frames never zero-copy. The routing travels oxr → compositor at xrEndFrame (what the app's last locate handed out).

Keeps one view set (M2 crop): STEREO/MONO, camera-rig and zone-scoped locates, >2 segments, unknown screen size. IPC/service: in-process only; the service never segments, so service sessions see one view set and 0 bindings (documented).

Tests

• New tests_oxr_segment_views (view-count contract, per-segment capacity, majority selection, seam-continuous placement across different pitches, segment window metrics, two screens of different size/nominal viewer → two different frusta, checked analytically through the shared Kooima core, stereo whole-window framing, binding ranges, tail alias).
• tests_comp_segments: shared tile-rect mapping (seam column shared).
• tests_oxr_view_space*: MULTIVIEW count updated to the new contract; remaining failures are the pre-existing ones (identical set on the M2 base: :953 centroid, device_max > 2, mode-floor cases), plus pre-existing tests_rig_composer.
• ./scripts/build_linux.sh --hybrid --apps + selftest green; check_displayxr_app.py test_apps/cube_handle_vk_linux clean; gen_extensions_index.py --check, check_doc_paths.py green.
• cube_handle_vk_linux now begins MULTIVIEW (DXR_STEREO_FIXED_APP=1 keeps stereo), renders every active view, chains XrViewActivityStateDXR + XrViewDisplayBindingsDXR, renders each display's views into its segment of each tile, logs bindings once per change.

Gate (hub runs it — nothing was put on the panel)

DXR_PLUGIN_EXCLUSIVE=sim-display SIM_DISPLAY_OUTPUT=anaglyph XRT_LOG=info \
  DXR_CUBE_WINDOW=1600x900+2656+400 ./build/run_cube_handle_vk_linux.sh --platform=x11
# once it renders:
touch "${TMPDIR:-/tmp}/displayxr_atlas_trigger"
# -> ${TMPDIR:-/tmp}/displayxr_atlas.png, displayxr_atlas.seg0.png, displayxr_atlas.seg1.png

Expect: app log Views: activeViewCount=4; display 0x… views 0..1 segment 0,0 …; display 0x… views 2..3 segment …,0 …; runtime INFO per-segment views: 2 segment(s) and segments: per-segment views routed — 2 segment(s) x 2 view(s). Each seg<i>.png holds that segment's OWN two views from its own frustum (the cube continues across the seam, with each half's perspective from its own screen's nominal viewer), not a crop of a shared pair.

Per-screen plug-in pin — DXR_SCREEN_PLUGIN (M4, #793 phase 3)

DXR_SCREEN_PLUGIN=<match>=<plugin-id>[,…] (<match> = RandR output HDMI-1, DRM connector HDMI-A-1, or monitor id hex) pins one monitor to a plug-in. For that monitor only it outranks PreferredPlugin (#791) and the active-plug-in rule (#1521) as long as the pinned plug-in claims it; all other monitors resolve as before. The winner rule is now one pure function (target_screen_pick: pin > preferred > active > confidence) in target_screen_pin.{h,c}, unit-tested with the parser (tests_target_screen_pin). One INFO per applied pin; WARN for no claim / no DP factory / unknown monitor / malformed entry. Documented in docs/specs/runtime/plugin-discovery.md §3.4.

M4 gate mode B: XRT_PREFERRED_PLUGIN_ID=sim-display DXR_SCREEN_PLUGIN=HDMI-1=leia-sr + the M3 gate command.

Gate result — PASSED on ds1-linux

Run by the hub with the command above (sim-display exclusive, anaglyph, X11, window 1600x900+2656+400, straddling eDP-1 / HDMI-1). Log:

[INFO] Views: activeViewCount=4; display 0x03fdab50663276e4 views 0..1 segment 0,0 800x900; display 0x886e4475353b22b9 views 2..3 segment 800,0 800x900
per-segment views: 2 segment(s): [0] display 0x03fd… views 0..1 canvas 0,0 800x900; [1] display 0x886e… views 2..3 canvas 800,0 800x900
segments: per-segment views routed — 2 segment(s) x 2 view(s), tile 800x450; [0] views 0.. at 0,0 400x450; [1] views 2.. at 400,0 400x450
created a segment DP for screen 0x886e… ('HDMI-1', plug-in 'sim-display') via create_dp_vk_for_screen — tolerates a resample
Atlas capture: segment 0 … DP input 800x450
Atlas capture: segment 1 … DP input 800x450

Captures: seg0.png = segment 0's own two views (400x450 each), the cube cut at its right edge; seg1.png = segment 1's own two views, the cube continuing from its left edge — each from its own frustum, not a crop of one shared pair.

Follow-up from the run: the pre-existing VIEW_DIMS WARN claimed the 400x450 per-view submission was "upscaled"; under the mosaic it now reports the segment count instead.

M4 gate result — PASSED on ds1-linux (mixed vendor, both modes)

Run by the hub on ds1-linux (eDP-1 laptop panel + Acer DS1 on HDMI-1), with a Debug dev Leia plug-in matching the runtime build (vk_bundle ABI, #1243).

Mode A — leia-sr active: mixed-vendor screen table built; the eDP segment DP created from sim-display via create_dp_vk_for_screen; the DS1 woven by the Leia main DP; activeViewCount=4, per-segment views routed, seg0/seg1 captures written.

Mode B — XRT_PREFERRED_PLUGIN_ID=sim-display DXR_SCREEN_PLUGIN=HDMI-1=leia-sr:

plugin loader: monitor 0x886e… ('HDMI-1'/'HDMI-A-1') → 'leia-sr' by DXR_SCREEN_PLUGIN (confidence=100; outranks PreferredPlugin and the active plug-in for this monitor)
segments: mixed-vendor screen table — primary 'sim-display', other screens by 'leia-sr'
segments: created a segment DP for screen 0x886e… ('HDMI-1', plug-in 'leia-sr') via create_dp_vk_for_screen — needs 1:1 pixels

Leia windowless weaver created, lens enabled, activeViewCount=4, per-segment views routed, seg0/seg1 captures written.

Human-verified — mode A eyeball on 9c119262e (David at the DS1): PASSED. "M4 fix works, I see anaglyph now laptop side and woven 3D DS1 side." The first eyeball (on 6554af85b) showed the laptop half flat: the sim segment DP reported one eye (sim's process-wide view count is only set by the sim head device, absent with leia-sr active), fixed in 9c119262e. Log lines from the passing run:

Segment 0x03fdab50663276e4 eyes from its DP (2, tracking=0): [0]=(-0.3520,0.1000,0.6000) [1]=(-0.2920,0.1000,0.6000) (reference frame)
Window-relative Kooima [segment 0x03fdab50663276e4]: screen=0.0694x0.0792m, eye_offset=(-0.2067,…)
Window-relative Kooima [segment 0x886e4475353b22b9]: screen=0.0717x0.0804m, eye_offset=(-0.1362,…)
Segment 0x886e… eyes from its DP (2, tracking=1): [0]=(-0.2266,-0.0002,0.5174) [1]=(-0.1799,0.0142,0.5039)

Each segment uses its own pitch (eDP 0.300 m / 3456 px, DS1 0.344 m / 3840 px) and its own eyes (sim's nominal pair on the eDP, the DS1's live tracked eyes). Capture: the eDP segment's two views now differ (mean |v0 − v1| ≈ 1.3 per channel, 0.0 before the fix).

Part of #69 (M3). Refs #1849 #1853.

🤖 Generated with Claude Code