feat(XR_DXR_cursor_depth): v3 anchor modes - HYBRID default + 0.005 margin (ADR-046)

[dfattal]

Why

Feedback from a tester on a real head-tracked panel, about the ADR-046 depth-aware cursor:

1. The sprite sits on the cyclopean ray through the pointer's canvas point. Its image on the glass therefore ignores head motion: it has disparity but no motion parallax. Everything around it parallaxes, so the cursor reads as "at the glass". A world-fixed cursor reads correctly, but sits ~1–2 mm off the click point.
2. The default margin, 0.03 eye baselines, floats the cursor ~1–2 cm off the content. 0.003–0.005 rests on it.

What

u_cursor_depth: u_cursor_depth_place_anchored() with three anchor modes. E is the cyclopean eye, S the canvas point under the pointer, f the display normal, e = dot(S−E, f) and t = 1/(1−d).

• SCREEN: C = E + t·(S−E). This is the v1/v2 placement.
• WORLD: C = S − f·(1−t)·e.
• HYBRID (new default): while the pointer moves (|Δu| or |Δv| > 1e-4, first step, or a filter re-prime), use the SCREEN position and store that locate's line of sight {E₀, S₀, D₀ = e}. While it is still, C = E₀ + s·(S₀ − E₀) with s = 1 − (1−t)·e/D₀: the point on the anchor-time line at the current depth in front of the glass. Continuous on the stop frame (s = t); world-fixed under lateral head motion (parallax like content); a depth change slides C along the anchor-time line, so it stays on the click point. Same rule as web SDK inline3d 1.37.1.
• Height and orientation are unchanged in every mode. Hit testing is unchanged.
• u_cursor_depth_filter_will_prime() exposes the filter's snap condition, so the session re-anchors on exactly those steps.
• The default margin goes from 0.03 to 0.005.

XR_DXR_cursor_depth spec v3: a new optional input struct, XrCursorDepthOptionsDXR (1004999323), chained on XrCursorDepthHintDXR::next. It carries anchorMode (HYBRID=0 / SCREEN=1 / WORLD=2) and margin (≤0 or non-finite means the default). No existing struct grows. The registry row in openxr_includes/openxr/README.md is updated (324–329 still held).

• Without the struct, an app gets HYBRID and the 0.005 margin. This deliberately changes the default behaviour from v2, at the tester's request. Apps that want the old placement chain SCREEN with margin = 0.03. This is called out in the spec's version history and in ADR-046 §7.
• The anchor state sits next to the filter in oxr_session and is dropped whenever the filter re-primes.
• The zero-cost rule (§0) still holds: the options struct is looked up only behind the hint.

Docs: ADR-046 gets a new §7 (the conflict, the modes, and why HYBRID beats both pure modes, with evidence), a rewritten head-motion consequence bullet, and the new margin row. The spec gets §2.4, an updated runtime-behaviour section and usage snippet, and a v3 history row.

Reference app: cube_handle_metal_macos reads DISPLAYXR_CURSOR_DEPTH_ANCHOR=hybrid|screen|world. When the variable is unset, the app doesn't chain the struct, so the runtime default applies.

Evidence

Unit tests (tests_aux_cursor_depth): 23 cases and 388 assertions, all passing. The new tests pin:

• HYBRID, off-axis viewer, content appears / changes depth under a still pointer (anchored at d = 0): at every depth C projects from E₀ onto S₀ (the click point) and has the requested disparity; WORLD does not stay on the click point; a later lateral head move keeps C fixed.
• HYBRID, pointer still, head moving laterally: C is unchanged in locate space, so its image on the glass moves (SCREEN's doesn't); head toward the glass: C slides along the anchor line.
• HYBRID, pointer moving: equals SCREEN, and the anchor stores the locate's line of sight.
• Continuity on the stop frame, sub-epsilon UV noise counting as still, and a depth change under a still pointer equalling SCREEN for an unmoved head.
• WORLD: C = S − f·(1−t)·e; disparity round-trips on- and off-axis; WORLD equals SCREEN on-axis.
• Default margin 0.005; will_prime matches every case where the filter snaps.

The old "head motion does not move the cursor on the glass" test is now explicitly the SCREEN-mode property.

Mutation testing: 14 of 15 mutants caught: drop the D₀ ratio (s = t), E for E₀, current e for D₀, flipped lift sign in s, the earlier normal-lift (foot) rule, WORLD sign, HYBRID→SCREEN, WORLD→SCREEN, ignoring the re-prime, always "moved", lift = t·e, margin 0.03, exact-compare move test, will_prime ignoring a stale gap. S for S₀ survives: for a still pointer on a display-fixed canvas, S equals S₀, so it is an equivalent mutant.

Headless captures: macOS, sim_display SBS, cube_handle_metal_macos, DISPLAYXR_CURSOR_DEPTH_UV=0.5,0.5. Atlas 1512×1646, two tiles stacked. Disparity = cursor x in the right tile minus the left tile; the cube's nearest edge under the cursor is about −15 px. The scripted pointer never moves, so HYBRID anchors at d = 0 on frame 1 and the cursor then rises to the cube with the pointer still. sim_display's viewer is 0.10 m above the canvas centre.

anchor	target d	cursor disparity	cursor y in tile (pointer at 411)
unset (HYBRID)	−0.040	−16.6 px	411
hybrid	−0.040	−16.6 px	411
screen	−0.040	−16.6 px	411
world	−0.040	−16.6 px	438
foot-anchored HYBRID (first push)	−0.040	−16.6 px	438
before (0.03 margin, SCREEN)	−0.066	−23.4 px	—

HYBRID now stays on the click point like SCREEN; the first push's foot-anchored rule drifted 27 px, as WORLD does. In every capture the midpoint of the two cursor images is at u = 0.4995.

Not tested

• Not tested on a head-tracked panel. sim_display has no tracking, so the parallax behaviour is pinned only by the unit tests.
• No interactive mouse run, so HYBRID's re-anchoring on real pointer motion wasn't observed in an app.
• Not tested over IPC/service or on non-Metal compositors. The placement code is shared state-tracker code, so it should behave the same there.
• The depth-layer source (DISPLAYXR_CURSOR_DEPTH_SOURCE=layer) was not re-run with the new modes. It needs a -DXRT_FEATURE_OPENXR_LAYER_DEPTH=ON build.
• The web SDK's parallel implementation was not cross-checked numerically against these tests.

🤖 Generated with Claude Code