From 70e3f4d66ad0979df9ec090df2122b3760d47492 Mon Sep 17 00:00:00 2001
From: Mads Marquart <mads@marquart.dk>
Date: Mon, 9 Sep 2024 13:25:01 +0200
Subject: [PATCH] Add Layer::into_raw (#22)

---
 CHANGELOG.md |  2 +-
 src/lib.rs   | 38 ++++++++++++++++++++++++++++++++++----
 2 files changed, 35 insertions(+), 5 deletions(-)

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