[dfattal]

Extends ADR-046 Amendment 2 §B (the runtime draws the depth cursor) from Metal (#1941) to the in-process vk_native and GL compositors. XR_DXR_cursor_depth stays at spec v6 — no new structs, no new XrStructureType, no version bump. This implements the existing v5 XrCursorDepthDrawInfoDXR / XrCursorDepthDrawStateDXR.

What changed

• One default look for all three backends. The Metal compositor's OS-cursor mirror moved to compositor/util/comp_cursor_look.{h,c} + comp_cursor_look_macos.m, a small library that Metal, vk_native and GL all link. It uses the mirrored [NSCursor currentCursor] on the main thread, otherwise the last snapshot, otherwise the procedural arrow from u_cursor_draw_arrow_rgba(). DXR_CURSOR_DEFAULT_LOOK=arrow still forces the arrow. Metal now uses the shared module, and its behaviour is unchanged (re-measured below). OS-cursor mirroring works on macOS only. Linux (XFixesGetCursorImage) and Windows draw the arrow, and that is noted in the ADR as future work.
• vk_native:
  • The request is consumed by the next commit and resolved there into tile corners for each view.
  • A cursor frame never zero-copies and always goes through the renderer's compose pass. The cursor is the pass's last draw, using the pass's own pipelines through the QUAD vertex path with an affine MVP. It is scissored to each tile, with depth testing off.
  • The pass draws into the private _SRGB target and publishes to the atlas with a raw copy, so the sprite blends in linear light and the atlas stays ENCODED (no double encode).
  • The sprite is sampled through the single compose_source_view(), the same source-view choice every layer uses. tests_comp_color_policy holds that choice to one code line.
  • Ordering differs from Metal: window-space layers are stamped later, at weave time, so on vk_native the cursor ends up under window-space HUD layers. This is documented in the ADR.
• GL:
  • Drawn after the window-space layers and before the DP, into whatever the atlas pass is painting.
  • The source is bound with gl_bind_layer_source().
  • A cursor frame counts as a sub-rect layer in gl_frame_takes_fast_path().
  • Small lazy program; blend, scissor and viewport state are restored afterwards.
  • GL sprites are sampled bottom-up. The spec now says so explicitly.
• State tracker: additive arms only for is_vk_native_compositor / is_gl_native_compositor in oxr_session_cursor_draw_supported / _hand_request. oxr_session_frame_end.c is untouched.
• Apps: cube_handle_vk_macos and cube_handle_gl_macos now adopt the cursor through dxr::CursorDepth (displayxr-common v2.29.0, the same way as test_apps(cube_handle_metal_macos): adopt the depth cursor through dxr::CursorDepth (needs displayxr-common tag) #1943). Supported env vars: DISPLAYXR_CURSOR_DEPTH_DRAW=runtime|app, DISPLAYXR_CURSOR_DEPTH_SPRITE=custom, DISPLAYXR_CURSOR_DEPTH_UV, DISPLAYXR_CURSOR_DEPTH=0 (on the GL cube the cursor is opt-in with DISPLAYXR_CURSOR_DEPTH=1, see GL compositor repaint thread vs AppKit cursor hide: ~1/5 crash in Apple's GL driver (cube_handle_gl_macos) #1947). The GL cube had no cursor-depth code before; it now has the cube ray test and an app-mode crosshair.
• Docs:
  • ADR-046 has a new "§B as built on Vulkan and GL" section.
  • The spec's backends note is updated, plus the note about the GL sprite's row order.
  • The DXR_CURSOR_DEFAULT_LOOK census row is updated.

Evidence (this Mac, sim-display Cropped SBS, cursorUV 0.5,0.5 over the cube)

backend	atlas	look	disparity (tile1 − tile0)	colour
vk_native	1280×1440	arrow	−22.0 px (−18…−22 as the cube turns)	fill (255,255,255), outline (5,5,8)
vk_native	1280×1440	mirrored OS cursor	−20.8 px	—
vk_native	1280×1440	custom ring, 1 cm	−21.7 px	ring (0,220,255) = authored bytes
GL	1512×1646	arrow	−24.1 px	(255,255,255) / (5,5,8)
GL	1512×1646	mirrored OS cursor	−20.0…−24.0 px	—
GL	1512×1646	custom ring	−23.4 px	(0,220,255)
Metal (after the refactor)	1512×1646	mirrored OS cursor	−24.0 px	—

• At UV 0.1,0.1 (no content): nothing is drawn on either backend.
• With DISPLAYXR_CURSOR_DEPTH_DRAW=app: the app's amber crosshair only, and no runtime pixels.
• With DISPLAYXR_CURSOR_DEPTH=0: nothing.
• Both captures are taken after the cursor pass. The vk_native capture is the POST_COMPOSE atlas, $TMPDIR/displayxr_atlas_trigger. The GL capture comes from /tmp/dxr_atlas_trigger, written after the cursor and the compose publish.
• tests_aux_cursor_depth and tests_comp_color_policy pass. ctest is 105/108; the 3 failures are not caused by this change:
  • tests_service_client_class: path comparison on a case-insensitive filesystem.
  • tests_oxr_view_space_mode_pinned: CI already excludes this suite.
  • tests_stereo_camera_manager: a load flake that passes on rerun.
• check_displayxr_app.py reports nothing new. The vk app's INV-5.9 (enable1) and the missing manifest warnings were already there.

Known issue found (not caused by the runtime draw)

cube_handle_gl_macos crashes in about 1 of 5 launches once the depth cursor is active. The crash is inside Apple's GL driver, either on the #868 repaint thread (gl_repaint_thread → glBlitFramebuffer) or in the app's own draw.

It follows the app's [NSCursor hide], not the runtime draw:

configuration	crashes
app-draw mode	yes
runtime draw with the OS cursor left visible	0/10
DXR_WEAVE_REPAINT=0	0/8
extension off	0/20
cursor at UV 0.1,0.1, so the depth cursor is never active (no hide)	0/10

So this looks like a latent race between the GL repaint thread and AppKit, which surfaces now that the GL cube hides the OS cursor. It is tracked as #1947. Until that is fixed, the GL cube's depth cursor is opt-in (DISPLAYXR_CURSOR_DEPTH=1); the Metal and Vulkan cubes stay default-on. vk_native showed no crashes in about 30 launches.

Also found in passing: #1948. On the Vulkan-app-on-Metal fallback, a custom sprite is handed to the Metal compositor as the client swapchain and cast to the native Metal type (#1941; found by reading the code, not reproduced).

Standalone pins: the displayxr-common FetchContent pin of cube_handle_metal/vk/gl_macos is now v2.29.0, the same as the aggregate pin. Each app was configured and built standalone and builds.

Not tested

• The GL linear compose-target path. Apple's GL 4.1 has no glCopyImageSubData, so every macOS GL frame composes in encoded space. The Windows GL path is untested.
• vk_native on Linux, Windows and Android (in-process), including the arrow fallback there.
• Layered (arraySize > 1) sprites: vk handles them through the array pipeline, but that path was not run. GL skips them with a one-time WARN.
• Multi-screen routed frames. vk and GL skip the cursor on these.
• The legacy colour hatch (DXR_COLOR_LEGACY_UNORM_ENCODED=1).
• A real Leia panel.

🤖 Generated with Claude Code