Port cube_texture_metal_macos to real-view + shared-surface mode and implement 2D surround

[dfattal]

Summary

The macOS texture sample (test_apps/cube_texture_metal_macos/main.mm) diverges from the Windows texture apps in two ways, so "a _texture app passes a real window handle + a shared surface, and may fill the 2D surround" is currently not true on macOS. Surfaced during the app-authoring-rules research (see docs/guides/displayxr-app-rules.md §12).

Divergence 1 — uses the offscreen/IOSurface mode, not real-view + shared-surface

The Windows texture apps pass the real window handle and a shared texture:

• test_apps/cube_texture_d3d11_win/xr_session.cpp:193-194 (real HWND + shared HANDLE)
• test_apps/cube_texture_d3d12_win/xr_session.cpp:198-199

cube_texture_metal_macos instead passes viewHandle = NULL + sharedIOSurface (main.mm:1540-1541) — i.e. the offscreen mode, not the "real NSView + shared IOSurface" texture mode. It sets the canvas rect (main.mm:1798) and blits the canvas sub-rect of the IOSurface to its own CAMetalLayer (BlitIOSurfaceToDrawable, main.mm:1075-1109), but the binding model differs from Windows.

Divergence 2 — no 2D surround

The Cocoa header (XR_EXT_cocoa_window_binding.h:179) and spec (docs/specs/extensions/XR_EXT_cocoa_window_binding.md §xrSetSharedTextureSurround2DEXT, spec v6) define xrSetSharedTextureSurround2DEXT, but the macOS sample does not call it — there is no 2D surround on macOS, while D3D11 (xrSetSharedTextureSurround2DEXT) and D3D12 (…Surround2DFenceEXT) both implement it.

Proposed work

1. Migrate cube_texture_metal_macos to pass the real NSView/CAMetalLayer handle + shared IOSurface, matching the Windows texture-app binding model (or document the platform split deliberately if the offscreen path is the intended macOS contract).
2. Implement xrSetSharedTextureSurround2DEXT in the sample: allocate the surround at worst-case-atlas size (per ADR-010), write window-aligned 2D content into the top-left client-area region, register it.
3. Verify the Metal compositor's surround strip-blit path handles the IOSurface case (parity with comp_d3d11_compositor.cpp d3d11_blit_surround_strips).
4. Reconcile the Cocoa surround spec size language with the corrected XR_EXT_win32_window_binding.md §3.6 (worst-case allocation, window-aligned 1:1 content).

Acceptance

• macOS _texture story matches Windows (real handle + shared surface; functional 2D surround), or the intended macOS difference is documented in the spec + docs/guides/displayxr-app-rules.md.

Filed from app-authoring-rules research; relates to the §12 discrepancies in docs/guides/displayxr-app-rules.md.