Struct raw_window_metal::Layer

source ·

pub struct Layer { /* private fields */ }

Available on Apple only.

Expand description

A wrapper around CAMetalLayer.

Implementations§

source §

impl Layer

source

pub fn as_ptr(&self) -> NonNull<c_void>

Get a pointer to the underlying CAMetalLayer.

The pointer is valid for at least as long as the Layer is valid, but can be extended by retaining it.

You should usually not change general CALayer properties like bounds, contentsScale and so on of this layer, but instead modify the layer that it was created from.

You can safely modify CAMetalLayer properties like drawableSize to match your needs, though beware that if it does not match the actual size of the layer, the contents will be scaled.

§Example

use objc2_quartz_core::CAMetalLayer;
use raw_window_metal::Layer;

let layer: Layer;

// SAFETY: The pointer is a valid `CAMetalLayer`.
let layer: &CAMetalLayer = unsafe { layer.as_ptr().cast().as_ref() };

// Use the `CAMetalLayer` here.

source

pub fn into_raw(self) -> NonNull<c_void>

Consume the layer, and return a pointer with +1 retain count to the underlying CAMetalLayer.

After calling this function, the caller is responsible for releasing the pointer, otherwise the layer will be leaked.

§Example

Convert a layer to a Retained CAMetalLayer.

use objc2::rc::Retained;
use objc2_quartz_core::CAMetalLayer;
use raw_window_metal::Layer;

let layer: Layer;

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 the `CAMetalLayer` here.

source

pub fn pre_existing(&self) -> bool

If raw-window-metal created a new CAMetalLayer for you, this returns false.

This may be useful if you want to override some part of raw-window-metal’s behaviour, and need to do so based on whether it ended up creating a layer or not.

You should try to avoid this, and instead:

Modify CALayer properties on the layer that you created this from.
Modify CAMetalLayer properties on the layer returned from as_ptr.

source

pub unsafe fn from_ca_layer(layer_ptr: NonNull<c_void>) -> Self

Get or create a new CAMetalLayer from the given CALayer.

If the given layer is a CAMetalLayer, this will simply return that layer. If not, a new CAMetalLayer is created and inserted as a sublayer, and then configured such that it will have the same bounds and scale factor as the given layer.

§Safety

The given layer pointer must be a valid instance of CALayer.

§Examples

Create a new layer from a CAMetalLayer.

use std::ptr::NonNull;
use objc2_quartz_core::CAMetalLayer;
use raw_window_metal::Layer;

let layer = unsafe { CAMetalLayer::new() };
let ptr: NonNull<CAMetalLayer> = NonNull::from(&*layer);

let layer = unsafe { Layer::from_ca_layer(ptr.cast()) };
assert!(layer.pre_existing());

Create a CAMetalLayer sublayer in a CALayer.

use std::ptr::NonNull;
use objc2_quartz_core::CALayer;
use raw_window_metal::Layer;

let layer = CALayer::new();
let ptr: NonNull<CALayer> = NonNull::from(&*layer);

let layer = unsafe { Layer::from_ca_layer(ptr.cast()) };
assert!(!layer.pre_existing());

source

pub unsafe fn from_ns_view(ns_view_ptr: NonNull<c_void>) -> Self

Get or create a new CAMetalLayer from the given NSView.

If the given view is not layer-backed, it will be made so.

If the given view has a CAMetalLayer as the root layer (which can happen for example if the view has overwritten -[NSView layerClass] or the view is MTKView) this will simply return that layer. If not, a new CAMetalLayer is created and inserted as a sublayer into the view’s layer, and then configured such that it will have the same bounds and scale factor as the given view.

§Panics

Panics if called from a thread that is not the main thread.

§Safety

The given view pointer must be a valid instance of NSView.

§Example

Construct a layer from an AppKitWindowHandle.

use raw_window_handle::AppKitWindowHandle;
use raw_window_metal::Layer;

let handle: AppKitWindowHandle;
let layer = unsafe { Layer::from_ns_view(handle.ns_view) };

source

pub unsafe fn from_ui_view(ui_view_ptr: NonNull<c_void>) -> Self

Get or create a new CAMetalLayer from the given UIView.

If the given view has a CAMetalLayer as the root layer (which can happen for example if the view has overwritten -[UIView layerClass] or the view is MTKView) this will simply return that layer. If not, a new CAMetalLayer is created and inserted as a sublayer into the view’s layer, and then configured such that it will have the same bounds and scale factor as the given view.

§Panics

Panics if called from a thread that is not the main thread.

§Safety

The given view pointer must be a valid instance of UIView.

§Example

Construct a layer from a UiKitWindowHandle.

use raw_window_handle::UiKitWindowHandle;
use raw_window_metal::Layer;

let handle: UiKitWindowHandle;
let layer = unsafe { Layer::from_ui_view(handle.ui_view) };