Summary
On macOS, Window::rwh_06_window_handle() currently resolves to an NSWindow* pointer, but wgpu/raw-window-handle AppKit path expects an NSView* (AppKitWindowHandle.ns_view).
This mismatch breaks Bevy-style surface creation from raw handles and forces downstream projects to add manual CAMetalLayer attach workarounds.
Current behavior
In the package:
- Window::rwh_06_window_handle() -> window_handle(self.id.into_raw())
- window_handle() -> native_window_handle() -> mbw_window_handle()
- mbw_window_handle() returns window->window (the NSWindow*)
Relevant code paths in the current package tree:
- macos/event_loop.mbt: Window::rwh_06_window_handle
- macos/ffi_native.mbt: window_handle / native_window_handle
- macos/backend.c: mbw_window_handle returns window->window
At the same time, backend stores both pointers:
- window->window (NSWindow*)
- window->content_view (NSView*)
Expected behavior
For AppKit raw handle compatibility, rwh_06_window_handle should expose the NSView* handle (content_view) rather than NSWindow*.
That aligns with wgpu/rwh expectations and with Bevy surface creation flow (RawWindowHandle::AppKit ns_view -> wgpu creates/uses metal layer internally).
Why this matters
Downstream engines attempting Bevy 1:1 alignment cannot use the standard raw-handle surface path on macOS. They must manually attach CAMetalLayer to content view as a workaround, which diverges from upstream architecture and increases platform-specific coupling.
Proposed fix
- Change mbw_window_handle to return window->content_view (or equivalent AppKit ns_view pointer).
- Keep window_display_handle behavior unchanged unless there is a platform-specific reason to adjust it.
- Add or adjust tests around raw handle semantics so this regression is caught automatically.
If there is an intentional reason for returning NSWindow*, please document the contract and provide a separate API for AppKit ns_view handle for rendering backends.
Summary
On macOS, Window::rwh_06_window_handle() currently resolves to an NSWindow* pointer, but wgpu/raw-window-handle AppKit path expects an NSView* (AppKitWindowHandle.ns_view).
This mismatch breaks Bevy-style surface creation from raw handles and forces downstream projects to add manual CAMetalLayer attach workarounds.
Current behavior
In the package:
Relevant code paths in the current package tree:
At the same time, backend stores both pointers:
Expected behavior
For AppKit raw handle compatibility, rwh_06_window_handle should expose the NSView* handle (content_view) rather than NSWindow*.
That aligns with wgpu/rwh expectations and with Bevy surface creation flow (RawWindowHandle::AppKit ns_view -> wgpu creates/uses metal layer internally).
Why this matters
Downstream engines attempting Bevy 1:1 alignment cannot use the standard raw-handle surface path on macOS. They must manually attach CAMetalLayer to content view as a workaround, which diverges from upstream architecture and increases platform-specific coupling.
Proposed fix
If there is an intentional reason for returning NSWindow*, please document the contract and provide a separate API for AppKit ns_view handle for rendering backends.