feat(lift): honour the runtime's viewpoint policy (rect-relative, baseline, y/z, per-stream knobs)

[dfattal]

Part of DisplayXR/displayxr-runtime#1858, addresses #316 (P1).

Plug-in half of Phase 1 of the lift camera design (window-aware lookaround). The runtime now owns the viewpoint policy (rebase to the lifted rect, ipd/parallax factors, axis mask, clamp, recentering ease — runtime ADR-048); the plug-in only translates units.

Depends on DisplayXR/displayxr-runtime#1864 for the new fields (XRT_DP_LIFT_HAS_VIEWPOINT_POLICY, branch feat/lift-viewpoint-policy), but works without it: against runtime headers that lack the macro the new code compiles out, and against a runtime binary that passes a short xrt_dp_lift_params::struct_size the behaviour is byte-for-byte today's (x only, 63 mm unit, ±3 clamp).

What changes

• New pure mapping module src/drv_leia/leia_lift_viewpoint.{h,c} (platform-neutral C, no NeurD/SR/D3D):
  • Legacy: x_n = clamp(G·x/0.063, ±3), y_n = z_n = 0 (old runtime, or eyes from the DP's own tracker).
  • Policy: unit = the nominal 63 mm (NeurD's ±0.5 default pair), so the runtime's ipd factor shows through: x_n = G·x/0.063; y_n = Gy·G·y/0.063 when axis_mode ≥ XY; z_n = Gz·(z − z_ref)/z_ref (clamped ±1) when axis_mode == XYZ; x/y clamp ±G·(max_offset_m + baseline_m/2)/0.063 when the runtime clamped (baseline 0 → 63 mm), else ±3. baseline_m is used only for that clamp margin and the log.
• DP (leia_display_processor_d3d11.cpp): reads the appended fields with LEIA_LIFT_COVERS (gated on the last field, viewpoint_frame), #ifdef XRT_DP_LIFT_HAS_VIEWPOINT_POLICY; z_ref = the panel's nominal viewing distance from the cached SR geometry (leiasr_geometry_get), i.e. the same value the runtime receives via get_display_info and pins z to; unknown → 0.5 m (the runtime's default). static_assert that the axis values match the runtime's.
• Per-stream knobs: ViewGain, new YGain (default 1.0) and ZGain (default 0.5, signed), plus ConvGain/DepthGain/Dilate/Scale are re-read (env > HKLM > default) and snapshotted at each stream create, so a registry change applies to the next stream without a service restart. Process-level knobs (enable, backend, versions, video model) unchanged. Stream-create WARN lists the snapshot.
• Logging: one WARN per stream per contract change (viewpoints = runtime policy (frame rect, axis X, baseline …) / legacy mapping (…)); one process-wide WARN the first time vertical look-around is honoured (vertical parallax used to cause jumps).
• Docs (docs/lift-neurd.md): viewpoint mapping rewritten (fixes the stale "y_n = clamp(G·y/0.063)" claim), z assumption documented, knob table gains YGain/ZGain/DepthGain/Dilate/VideoModel, knob lifetimes, Verifying modes=0x3 (was 0x7; NVIEW is never offered).
• Host test src/drv_leia/tests/test_lift_viewpoint.c, built + run by the Linux CI lane (same pattern as test_display_claims_win).

Decisions worth a reviewer's eye

• Nominal unit, not baseline_m: the runtime already applied ipdFactor to the eyes; dividing by the post-factor baseline would cancel it (every pair → ±0.5). A 32 mm pair maps to ±0.254·G.
• Clamp margin: the runtime clamps the eyes' midpoint; each eye is baseline_m/2 off it, so the per-eye limit adds that half-pair (otherwise the pair collapses at the edge). A runtime clamp wider than ±3 is honoured.
• z mapping is fractional distance change (not baseline units) and uncalibrated; conservative default gain 0.5, sign flippable.

Verified

• Plug-in DLL builds against the runtime branch headers (policy path compiled in) and against runtime origin/main (policy compiled out).
• test_lift_viewpoint passes (MSVC /W4 /WX locally; Linux CI runs it).

Owed (hardware, panel + NeurD)

• Old runtime + this plug-in: lift SBS on the panel looks and logs as before (viewpoints = legacy mapping (… runtime predates the viewpoint policy)).
• Policy runtime, default axis X: lookaround is now relative to the window/rect centre; log viewpoints = runtime policy (frame rect, axis X, baseline ~6x mm …).
• Axis XY: vertical lookaround with no jumps; honouring VERTICAL look-around logged once; tune YGain if needed.
• Axis XYZ: lean in/out — sanity-check NeurD z sign/magnitude; tune ZGain.

🤖 Generated with Claude Code