feat(vk dp, weave/linux): set_overlay_2d VK slot — 2D under the lens on Vulkan

[dfattal]

What

Vulkan twin of the D3D11 set_overlay_2d / set_overlay_2d_filter_strength slots (#1814 / #1822, ADR-027 Amendment), and the desktop-Linux weave engine as its first producer. Needed by DisplayXR/displayxr-leia-plugin's Linux port of "2D under the lens" (SR SDK srWeaverSetComposeInputsVulkan).

Interface (xrt_display_processor_vk.h)

• Appended after set_transparency_active (ADR-020, no ABI major; asserts + size bumped 15 → 17):
  • bool set_overlay_2d(xdp, VkImageView, VkFormat_XDP, w, h, enum xrt_atlas_encoding, bool layer_unchanged)
  • void set_overlay_2d_filter_strength(xdp, float) (negative = DP default)
• Macros XRT_DP_VK_HAS_OVERLAY_2D, XRT_DP_VK_HAS_OVERLAY_2D_FILTER_STRENGTH; helpers xrt_display_processor_vk_supports_overlay_2d / _set_overlay_2d / _set_overlay_2d_filter_strength.
• Contract = the D3D11 one (stateless per frame, target-sized, premultiplied, ENCODED, RGBA8/BGRA8; true = DP composites inside the next process_atlas, false/absent = runtime blends post-weave), plus: layer in SHADER_READ_ONLY_OPTIMAL, owned by process_atlas' queue family, alive until that command buffer completes. The PRESENT_SRC_KHR target contract is unchanged.

Producer (comp_multi_weave_linux.c)

• When the frame weaves, the v4 overlay is exactly output-sized and the DP has the slot: acquire + transition the overlay before the self-submitting split, call strength, then set_overlay_2d with the submit's v14 overlay_unchanged.
• DP took it: the full-window post-weave blend is skipped. Off-panel bands and flat regions are painted over the weave afterwards (clear + flat copy), so the overlay is redrawn over those rects only and 2D stays readable across the seam as before.
• DP declined: exactly the old path (the overlay may already be acquired; the release is shared).
• One WARN on each change of verdict: weave: 2D overlay (WxH) composited by the display processor INSIDE the weave / blended post-weave by the runtime.
• IPC: overlay_unchanged / overlay_filter_strength (already on the wire) are forwarded on both Linux submit paths via comp_multi_weave_linux_set_overlay_hints (per submit, like v13 mono).

Docs: ADR-027 Amendment + XR_DXR_weave v14/v15 notes.

Not done

• The macOS / Android Vulkan weave engines and the in-process vk_native Local2D-over path don't call the slot yet (same shape when needed).
• v6 N-view submits: the overlay is window-sized but the output is one content view, so the size check keeps them on the runtime blend.

Testing

• ./scripts/build_linux.sh --hybrid --apps green; clang-format clean; scripts/tests/test_downstream_pin_bump.py OK.
• weave_present_vk_linux --headless 90 against a private-XDG displayxr-service with DXR_PLUGIN_EXCLUSIVE=sim-display (no slot): PASS (incl. "HUD overlay composited over the weave"); the log shows the runtime-blend verdict.
• DP path: the plug-in side builds against this branch (leia-plugin PR). The on-panel check (DS1) is pending with David.
• The features downstream-pin gate should pick up the new XRT_DP_VK_HAS_* macros for leia's Linux track on the next release.

🤖 Generated with Claude Code