Crate raw_window_metal

source ·
Available on Apple only.
Expand description

§Interop between Metal and raw-window-handle

Helpers for constructing a CAMetalLayer from a handle given by raw-window-handle. See the Layer type for the full API.

§Example

Create a layer from a window that implements HasWindowHandle.

use objc2::rc::Retained;
use objc2_quartz_core::CAMetalLayer;
use raw_window_handle::{RawWindowHandle, HasWindowHandle};
use raw_window_metal::Layer;

let layer = match window.window_handle().expect("handle available").as_raw() {
    // SAFETY: The handle is a valid `NSView` because it came from `WindowHandle<'_>`.
    RawWindowHandle::AppKit(handle) => unsafe { Layer::from_ns_view(handle.ns_view) },
    // SAFETY: The handle is a valid `UIView` because it came from `WindowHandle<'_>`.
    RawWindowHandle::UiKit(handle) => unsafe { Layer::from_ui_view(handle.ui_view) },
    _ => panic!("unsupported handle"),
};
let layer: *mut CAMetalLayer = layer.into_raw().as_ptr().cast();
// SAFETY: The pointer is a valid `CAMetalLayer`, and because we consumed `Layer` with
// `into_raw`, the pointer has +1 retain count.
let layer = unsafe { Retained::from_raw(layer).unwrap() };

// Use `CAMetalLayer` here.

§Semantics

As the user of this crate, you are likely creating a library yourself, and need to interface with a layer provided by a windowing library like Winit or SDL.

In that sense, when the user hands your library a view or a layer via. raw-window-handle, they likely expect you to render into it. You should freely do that, but you should refrain from doing things like resizing the layer by changing its bounds, changing its contentsGravity, opacity, and similar such properties; semantically, these are things that are “outside” of your library’s control, and interferes with the platforms normal handling of such things (i.e. the user creating a MTKView, and placing it inside a NSStackView. In such cases, you should not change the bounds of the view, as that will be done automatically at a “higher” level).

Properties specific to CAMetalLayer like drawableSize, colorspace and so on probably are fine to change, because these are properties that the user expects your library to change when they’ve given it to you (and they won’t be changed by e.g. the layer being inside a stack view).

§Reasoning behind creating a sublayer

If a view does not have a CAMetalLayer as the root layer (as is the default for most views), then we’re in a bit of a tricky position! We cannot use the existing layer with Metal, so we must do something else. There are a few options:

  1. Panic, and require the user to pass a view with a CAMetalLayer layer.

    While this would “work”, it doesn’t solve the problem, and instead passes the ball onwards to the user and ecosystem to figure it out.

  2. Override the existing layer with a newly created layer.

    If we overlook that this does not work in UIKit since UIView’s layer is readonly, and that as such we will need to do something different there anyhow, this is actually a fairly good solution, and was what the original implementation did.

    It has some problems though, due to:

    a. Consumers of raw-window-metal like Wgpu and Ash in their API design choosing not to register a callback with -[CALayerDelegate displayLayer:], but instead leaves it up to the user to figure out when to redraw. That is, they rely on other libraries’ callbacks telling them when to render.

    (If you were to make an API only for Metal, you would probably make the user provide a render closure that’d be called in the right situations).

    b. Overwriting the layer on NSView makes the view “layer-hosting”, see wantsLayer, which disables drawing functionality on the view like drawRect:/updateLayer.

    These two in combination makes it basically impossible for crates like Winit to provide a robust rendering callback that integrates with the system’s built-in mechanisms for redrawing, exactly because overwriting the layer would be disabling those mechanisms!

  3. Create a sublayer.

    CALayer has the concept of “sublayers”, which we can use instead of overriding the layer.

    This is also the recommended solution on UIKit, so it’s nice that we can use the same implementation regardless of operating system.

    It might, however, perform ever so slightly worse than overriding the layer directly.

  4. Create a new MTKView (or a custom view), and add it as a subview.

    Similar to creating a sublayer (see above), but also provides a bunch of event handling that we don’t need.

Option 3 seems like the most robust solution, so this is what this crate does.

Now we have another problem though: The bounds and contentsScale of sublayers are not automatically updated from the super layer.

We could again choose to let that be up to the user of our crate, but that would be very cumbersome. Instead, this crate registers the necessary observers to make the sublayer track the size and scale factor of its super layer automatically. This makes it extra important that you do not modify common CALayer properties of the layer that raw-window-metal creates, since they may just end up being overwritten (see also “Semantics” above).

Structs§