Add Layer::into_raw

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.

src/lib.rs

@@ -35,8 +35,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.
 //! ```
@@ -168,7 +169,6 @@ impl Layer {
     /// # Example
     ///
     /// ```no_run
-    /// use objc2::rc::Retained;
     /// use objc2_quartz_core::CAMetalLayer;
     /// use raw_window_metal::Layer;
     ///
@@ -177,7 +177,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.
     /// ```
@@ -187,6 +187,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()
+    }
+
     /// Whether `raw-window-metal` created a new [`CAMetalLayer`] for you.
     #[inline]
     pub fn pre_existing(&self) -> bool {