feat(display_info): per-screen enumeration, display spaces, session binding (multi-screen M1)

[dfattal]

Part of #69 (M1). Refs #1849 (plan + ADR-047), #1851 (M0, this PR's base). M0 (#1851) is merged; this PR is rebased onto main.

What

Multi-screen milestone M1: an app can now see each display, not only the one XrDisplayInfoDXR describes.

• XR_DXR_display_info v22 (append-only; no existing struct, value or behaviour changes)
  • xrEnumerateDisplaysDXR (two-call) → XrDisplayDXR { displayId, XrDisplayInfoDXR info (by value), desktopRect, nativePixelWidth/Height, desktopScale, XrEyeTrackingModeCapabilitiesDXR eyeTracking, flags (PRIMARY / TRACKED / SYSTEM_DEFAULT), vendorPluginId[64], deviceName[64] }. The SYSTEM_DEFAULT entry comes first and reports exactly what XrSystemProperties does (active-mode view scale included).
  • XrDisplaySpaceCreateInfoDXR + xrCreateDisplaySpaceDXR: a DISPLAY space per display. v22 limit: every display space resolves to the session's single display plane (head pose for runtime-window sessions, head tracking origin for app-window / bridge sessions, the pose XrViewDisplayRawDXR::displayPlanePose reports). Per-display poses come in M3; no shared room frame.
  • XrSessionDisplayBindingDXR on XrSessionCreateInfo. v22 effect: binding to a non-default display makes that display's physical size + nominal viewer the session's display-scoped Kooima inputs. Which DP weaves is unchanged (M2/M3). 0 = runtime decides. Unknown id → XR_ERROR_VALIDATION_FAILURE.
  • Type values 1004999214–216; 217 reserved for XrViewDisplayBindingsDXR (M3). Registry README updated.
• Runtime backing. xrt_screen / xrt_screen_info / xrt_screen_list (xrt/xrt_screen.h); target_screens_build turns each per-monitor registry entry (M0) into a screen. Each screen's info comes from, in order: (1) the system info, if it is the system-default screen; (2) the owning plug-in's new get_display_info_for_monitor slot; (3) EDID-derived defaults: mm → metres, connector mode → pixels, view scale 1, no eye tracking, nominal viewer at the distance that keeps the system panel's vertical FOV. The pure rules live in util/u_screen_info.h.
• Plug-in ABI (no version bump). xrt_plugin_iface::get_display_info_for_monitor(inst, const xrt_display_descriptor*, const xrt_display_physical*, xrt_plugin_display_info*) is appended after stereo_camera_close (ADR-020 append-only, struct_size-gated). XRT_PLUGIN_API_VERSION_CURRENT stays 5. New feature macro: XRT_PLUGIN_IFACE_HAS_DISPLAY_INFO_FOR_MONITOR. sim_display implements it. The Leia plug-in is untouched; its other monitors get the EDID-derived defaults.
  • EDID mm and the device mode go in a new struct passed by pointer, xrt_display_physical, and not in xrt_display_descriptor. probe_displays receives descriptors as an array, so appending a field would change the stride under every shipped plug-in: a silent layout break, even though the old comment said "append with no bump". The descriptor doc now warns about this.
• IPC. A new system_enumerate_displays message carries struct xrt_screen_list and is answered through the new optional xrt_instance::enumerate_displays slot. The native instance and the IPC client instance both implement it. The by-value xrt_system_compositor_info is unchanged. No new message is needed for display spaces: the existing space-overseer IPC covers them.
• Visibility. displayxr-cli info has a :: Displays block (and a displays JSON array) built by the same target_screens_build. cube_handle_vk_linux logs one line per display at startup.
• Docs.
  • XR_DXR_display_info.md: v22 section, revision row, OPEN 1 rewritten as partially resolved.
  • view-configuration-model.md: what a session binding does and does not change.
  • xrt_plugin_iface.md: the new slot.

displayxr-cli info on ds1-linux (eDP-1 + Acer DS1 on HDMI-1, installed leia-sr active)

 :: Displays (XR_DXR_display_info v22 — what xrEnumerateDisplaysDXR reports)
    [0] 0xcb5af163f67dd93c 'HDMI-1' plug-in='leia-sr' SYSTEM_DEFAULT TRACKED
        desktop 3840x2160 @ (3456,0)  native 3840x2160  scale 2.00  edid 344x193 mm
        info[system]: 0.3440 x 0.1930 m  3840x2160 px  nominal=(0.000, 0.000, 0.600) m  view scale 0.500 x 0.500  eye tracking MANAGED (default MANAGED)
    [1] 0x50cab5190604ffb9 'eDP-1' plug-in='sim-display' PRIMARY
        desktop 3456x2160 @ (0,0)  native 2880x1800  scale 1.67  edid 300x190 mm
        info[derived]: 0.3000 x 0.1900 m  2880x1800 px  nominal=(0.000, 0.000, 0.590) m  view scale 1.000 x 1.000  eye tracking none

With DXR_PLUGIN_EXCLUSIVE=sim-display and the dev sim-display, HDMI-1 reports info[plugin-monitor] (the new sim slot: EDID 344x193 mm, 3840x2160).

Headless end-to-end, in-process: a probe that only calls xrCreateInstance and xrGetSystem (no session, no window), then xrEnumerateDisplaysDXR. It returned the same two displays:

• the HDMI-1 flags are SYSTEM_DEFAULT|TRACKED, and its info matches XrSystemProperties;
• capacity=1 returns XR_ERROR_SIZE_INSUFFICIENT;
• xrCreateDisplaySpaceDXR resolves through xrGetInstanceProcAddr.

Tests

• New tests_target_screens (6 cases: default pick, fallback, slot vs derived, empty registry, id stability).
• New tests_aux_screen_info: 8 cases covering the three source rules, a slot that declines, a plug-in whose struct_size predates the slot (never called), unknown mm, no system info, and xrt_screen_list_find.
• tests_stereo_camera: the slot-order pin now expects the new slot to end the iface.
• ./scripts/build_linux.sh (headless) + selftest: PASSED. --hybrid --apps + selftest: PASSED.
• ctest: everything passes except tests_rig_composer and tests_oxr_view_space* (4 variants). Those already fail on this box on main.
• scripts/check_displayxr_app.py test_apps/cube_handle_vk_linux is clean. gen_extensions_index.py --check, check_doc_paths.py and gen_adr_index.py --check pass.

Review fixes (follow-up commits)

• 1d42570f3: the registry is published under g_display_info_mutex. The refresh callback now holds that mutex across the display-info refresh, the registry rebuild and the desktop-rect fill, and the registry is resolved into a local first. Lock order stays g_display_info_mutex → g_refresh_mutex.
• defcf2ff5: the default screen is the monitor whose rect contains the resolved panel origin, so a screen can no longer carry one monitor's id with another monitor's rect.
• 2e0631580: new tests_target_screens covers target_screens_build and the default-screen pick.
• f1c474f03: where the connector is known, displayId hashes EDID identity + connector and no longer the desktop position, so it survives a monitor rearrangement. Windows ids are unchanged (still position-based) and the docs say so. Also adds the spec's missing v21 row.

The ids in the CLI output above predate the rebase onto main. M0's review fixes made the connector key card-prefixed (card1-HDMI-A-1), and the id hash now includes that prefix, so the ids changed again. eDP-1 is now 0x9e6f2f2a48d37339. HDMI-1's new id could not be read: the DS1 was disconnected at the time of the rebase.

Not verified

• IPC at runtime. The message, handler and client compile in the hybrid build. I did not start a dev service on the shared DS1 box.
• The DISPLAY space pose and the session binding's Kooima effect. Both need a session, which means a windowed app, and that is not allowed on this box.
• Windows. A MinGW syntax check of target_screens.c is clean when given a Windows.h shim. This box's mingw toolchain fails on pre-existing headers (Windows.h case, timespec_get), so it does not cover the rest; Windows CI does.

🤖 Generated with Claude Code