diff --git a/CHANGELOG.md b/CHANGELOG.md index 653e2e8..cf08b2b 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,6 +1,6 @@ # Unreleased - Bump Rust Edition from 2018 to 2021. -- Make `Layer`'s implementation details private; it is now a struct with `as_ptr` and `is_existing` accessor methods. +- Make `Layer`'s implementation details private; it is now a struct with `as_ptr`, `into_raw` and `is_existing` accessor methods. - Add support for tvOS, watchOS and visionOS. - Use `objc2` internally. - Move `Layer` constructors to the type itself. diff --git a/src/lib.rs b/src/lib.rs index 66c059b..3f08cdf 100644 --- a/src/lib.rs +++ b/src/lib.rs @@ -36,8 +36,9 @@ //! RawWindowHandle::UiKit(handle) => unsafe { Layer::from_ui_view(handle.ui_view) }, //! _ => panic!("unsupported handle"), //! }; -//! let layer: *mut CAMetalLayer = layer.as_ptr().cast(); -//! let layer = unsafe { Retained::retain(layer).unwrap() }; +//! let layer: *mut CAMetalLayer = layer.into_raw().cast(); +//! // SAFETY: The pointer is a valid `CAMetalLayer` with +1 retain count. +//! let layer = unsafe { Retained::from_raw(layer).unwrap() }; //! //! // Use `CAMetalLayer` here. //! ``` @@ -205,7 +206,6 @@ impl Layer { /// # Example /// /// ```no_run - /// use objc2::rc::Retained; /// use objc2_quartz_core::CAMetalLayer; /// use raw_window_metal::Layer; /// @@ -214,7 +214,7 @@ impl Layer { /// /// let layer: *mut CAMetalLayer = layer.as_ptr().cast(); /// // SAFETY: The pointer is a valid `CAMetalLayer`. - /// let layer = unsafe { Retained::retain(layer).unwrap() }; + /// let layer: &CAMetalLayer = unsafe { &*layer }; /// /// // Use the `CAMetalLayer` here. /// ``` @@ -224,6 +224,36 @@ impl Layer { ptr as *mut _ } + /// 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`. + /// + /// ```no_run + /// use objc2::rc::Retained; + /// use objc2_quartz_core::CAMetalLayer; + /// use raw_window_metal::Layer; + /// + /// let layer: Layer; + /// # layer = unimplemented!(); + /// + /// let layer: *mut CAMetalLayer = layer.into_raw().cast(); + /// // SAFETY: The pointer is a valid `CAMetalLayer` with +1 retain count. + /// let layer = unsafe { Retained::from_raw(layer).unwrap() }; + /// + /// // Use the `CAMetalLayer` here. + /// ``` + #[inline] + pub fn into_raw(self) -> *mut c_void { + Retained::into_raw(self.layer).cast() + } + /// 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