feat(cursor): runtime-drawn depth cursor in display-zones frames (#1949)

[dfattal]

Closes #1949.

The runtime-drawn depth cursor (ADR-046 Amendment 2 §B, #1941 Metal / #1946 Vulkan+GL) skipped display-zones frames and reported willDraw = false. With this PR it draws one cursor per frame, in the zone whose zone-scoped locate carried the hint (the zone under the pointer).

Design

• State tracker. The arming locate records the XrDisplayZoneDXR::zoneId it carried. That locate's canvas is the zone rect, so cursorUV, the placement and its unit are zone-relative already. In a zones frame, xrEndFrame maps the placement through the views of the projection layer chained with that zone: its submitted poses and fovs, with the same-space rule unchanged. The result is a zone-normalised map. u_cursor_draw_request gains zone_valid, zone_id and zone_rect, where zone_rect is the rect as submitted (authoritative per ADR-027). The fallback is unchanged in three cases: no zone with that id, a zone-scoped hint in a frame without zones, and a zones frame whose hint was not zone-scoped. In each, nothing is drawn, the next locates report willDraw = false, and a one-time WARN is logged.
• Two pure aux helpers used at every draw site:
  • u_cursor_draw_into_zone() re-expresses the zone-normalised views in the tile exactly as each compositor places the zone's own layer (zone rect × tile / window). It also returns the zone's sub-rect as a clip.
  • u_cursor_draw_canvas_px_h() sizes the sprite against the zone's height.
• Metal, vk_native, GL now accept zone requests and scissor the draw to tile ∩ zone, so the cursor never bleeds into a 2D zone or another 3D zone. A request without a zone is untouched: its clip is the whole tile, as before.
• There is no new XrStructureType and no spec bump, because willDraw already reports the change to the app frame by frame. The spec text and the ADR-046 as-built notes are updated.
• §0 still holds: there is zero cost without a request. Every new line runs only on a frame whose request is already set.
• D3D11/D3D12 are untouched (draft feat(cursor): the runtime draws the depth cursor — D3D11 + D3D12 (ADR-046 Amendment 2 §B) #1944). That PR only has to call the same two helpers at its draw site; see the comment there.

Evidence (this Mac, sim-display, scripted pointer DISPLAYXR_CURSOR_DEPTH_UV, atlas capture)

• Unit tests (tests_aux_cursor_depth): two new cases.
  • An off-centre zone with 4 eyes (N-view) and an off-axis viewer. The remapped zone map equals the map computed with views framed to the whole window (the oracle) for every view, at two disparities. Also checked: the hotspot lands at the zone UV inside the zone, and the canvas height is the zone's.
  • Clip and refusal cases: a zone hanging off the window edge, an empty zone, a zone outside the window, and no target.
  • All pass (24468 assertions). Mutation check: 8/8 mutants killed (axis scales, origin offsets, clip clamp, outside-accept, zone ignored, canvas height).
• cube_zones_metal_macos (Metal, 2 tiles of 1512×823):
  • Pointer at window UV (0.25, 0.60), i.e. zone A at UV (0.500, 0.467): willDraw=TRUE, disparity −0.049. The arrow is on zone A's cube in both tiles at x ≈ 385 and ≈ 370, y ≈ 493 (expected 378, 494). It pops out (crossed disparity). Zone B is clean.
  • Pointer at (0.745, 0.47), in zone B: the arrow is drawn only on zone B's cube, at (1128, 385) and (1123, 387), expected (1126, 387). Zone A is clean.
  • Pointer at (0.5, 0.1), over the Local2D strip: no hint, nothing drawn anywhere.
• cube_zones_vk_macos (vk_native, 2 tiles of 1280×720):
  • Zone A: the arrow is at (328, 432) and (312, 432), expected 320, 432. Zone B is clean.
  • Zone B: the arrow is on zone B's cube only. Zone A is clean.
• Regression without zones: cube_handle_metal_macos, cube_handle_vk_macos and cube_handle_gl_macos (DISPLAYXR_CURSOR_DEPTH=1) all still draw the cursor in front of the cube in both tiles.
• The test apps share test_apps/common/cursor_depth_zones.h, a thin wrapper over dxr::CursorDepth (displayxr-common v2.29.0, the same pin as the cube_handle apps). It picks the topmost 3D zone under the pointer, feeds the pointer in that zone's UV, and chains the hint only on that zone's locate.

Not tested

• GL zones path: there is no _handle GL zones app on macOS, and the cube_zones_texture_* apps were not adopted. The GL change is covered only by the shared aux math, the matching scissor arithmetic and the non-zones GL regression run.
• Real Leia hardware, Windows and Linux. Linux vk_native shares the renderer code, but nothing was run there.
• Overlapping zones (O key) with the pointer in the overlap. The topmost zone is picked by layer order, and the clip is that zone's rect, so the cursor is drawn over the lower zone's content in the overlap. That is correct for alpha-over composition, but it was not captured.
• Live mouse (only the scripted pointer was used), the custom-sprite path in zones, and the depth-layer source (XrCursorDepthSourceDXR) in zones. Zone layers have no depth variant, so that source still reports no content there.

🤖 Generated with Claude Code