From d22104709f9efc1fd631ecdf727cf89d964d8790 Mon Sep 17 00:00:00 2001
From: Rua <ruawhitepaw@gmail.com>
Date: Sun, 1 Oct 2023 23:10:18 +0200
Subject: [PATCH] Document `SurfaceApi` better (#2340)

* Document `SurfaceApi` better

* Add TryFrom<RawWindowHandle> for SurfaceApi

* Rename Qnx > QnxScreen to match the `from_qnx_screen` constructor
---
 vulkano/src/swapchain/surface.rs | 83 +++++++++++++++++++++++++++++---
 1 file changed, 77 insertions(+), 6 deletions(-)

diff --git a/vulkano/src/swapchain/surface.rs b/vulkano/src/swapchain/surface.rs
index d66bcf9987..06e0a30867 100644
--- a/vulkano/src/swapchain/surface.rs
+++ b/vulkano/src/swapchain/surface.rs
@@ -130,7 +130,10 @@ impl Surface {
             (RawWindowHandle::Xlib(window), RawDisplayHandle::Xlib(display)) => {
                 Self::from_xlib(instance, display.display, window.window, None)
             }
-            _ => unimplemented!(),
+            _ => unimplemented!(
+                "the window was created with a windowing API that is not supported \
+                by Vulkan/Vulkano"
+            ),
         }
     }
 
@@ -139,7 +142,7 @@ impl Surface {
     /// # Safety
     ///
     /// - `handle` must be a valid Vulkan object handle created from `instance`.
-    /// - `handle` must have been created from `api`.
+    /// - `handle` must have been created using the function specified by `api`.
     /// - The window object that `handle` was created from must outlive the created `Surface`.
     ///   The `object` parameter can be used to ensure this.
     pub unsafe fn from_handle(
@@ -998,7 +1001,7 @@ impl Surface {
         Ok(Arc::new(Self::from_handle(
             instance,
             handle,
-            SurfaceApi::Qnx,
+            SurfaceApi::QnxScreen,
             object,
         )))
     }
@@ -1676,29 +1679,97 @@ impl DisplaySurfaceCreateInfo {
     }
 }
 
-/// The windowing API that was used to construct a surface.
+/// The windowing API function that was used to construct a surface.
 #[derive(Clone, Copy, Debug, PartialEq, Eq, Hash)]
 #[non_exhaustive]
 pub enum SurfaceApi {
+    /// The surface was constructed using [`Surface::headless`] or the
+    /// `vkCreateHeadlessSurfaceEXT` Vulkan API function.
     Headless,
+
+    /// The surface was constructed using [`Surface::from_display_plane`] or the
+    /// `vkCreateDisplayPlaneSurfaceKHR` Vulkan API function.
     DisplayPlane,
 
-    // Alphabetical order
+    /*
+        Alphabetical order
+    */
+    /// The surface was constructed using [`Surface::from_android`] or the
+    /// `vkCreateAndroidSurfaceKHR` Vulkan API function.
     Android,
+
+    /// The surface was constructed using [`Surface::from_directfb`] or the
+    /// `vkCreateDirectFBSurfaceEXT` Vulkan API function.
     DirectFB,
+
+    /// The surface was constructed using [`Surface::from_fuchsia_image_pipe`] or the
+    /// `vkCreateImagePipeSurfaceFUCHSIA` Vulkan API function.
     FuchsiaImagePipe,
+
+    /// The surface was constructed using [`Surface::from_ggp_stream_descriptor`] or the
+    /// `vkCreateStreamDescriptorSurfaceGGP` Vulkan API function.
     GgpStreamDescriptor,
+
+    /// The surface was constructed using [`Surface::from_ios`] or the
+    /// `vkCreateIOSSurfaceMVK` Vulkan API function.
     Ios,
+
+    /// The surface was constructed using [`Surface::from_mac_os`] or the
+    /// `vkCreateMacOSSurfaceMVK` Vulkan API function.
     MacOs,
+
+    /// The surface was constructed using [`Surface::from_metal`] or the
+    /// `vkCreateMetalSurfaceEXT` Vulkan API function.
     Metal,
-    Qnx,
+
+    /// The surface was constructed using [`Surface::from_qnx_screen`] or the
+    /// `vkCreateScreenSurfaceQNX` Vulkan API function.
+    QnxScreen,
+
+    /// The surface was constructed using [`Surface::from_vi`] or the
+    /// `vkCreateViSurfaceNN` Vulkan API function.
     Vi,
+
+    /// The surface was constructed using [`Surface::from_wayland`] or the
+    /// `vkCreateWaylandSurfaceKHR` Vulkan API function.
     Wayland,
+
+    /// The surface was constructed using [`Surface::from_win32`] or the
+    /// `vkCreateWin32SurfaceKHR` Vulkan API function.
     Win32,
+
+    /// The surface was constructed using [`Surface::from_xcb`] or the
+    /// `vkCreateXcbSurfaceKHR` Vulkan API function.
     Xcb,
+
+    /// The surface was constructed using [`Surface::from_xlib`] or the
+    /// `vkCreateXlibSurfaceKHR` Vulkan API function.
     Xlib,
 }
 
+impl TryFrom<RawWindowHandle> for SurfaceApi {
+    type Error = ();
+
+    fn try_from(handle: RawWindowHandle) -> Result<Self, Self::Error> {
+        match handle {
+            RawWindowHandle::UiKit(_) => Ok(SurfaceApi::Ios),
+            RawWindowHandle::AppKit(_) => Ok(SurfaceApi::MacOs),
+            RawWindowHandle::Orbital(_) => Err(()),
+            RawWindowHandle::Xlib(_) => Ok(SurfaceApi::Xlib),
+            RawWindowHandle::Xcb(_) => Ok(SurfaceApi::Xcb),
+            RawWindowHandle::Wayland(_) => Ok(SurfaceApi::Wayland),
+            RawWindowHandle::Drm(_) => Err(()),
+            RawWindowHandle::Gbm(_) => Err(()),
+            RawWindowHandle::Win32(_) => Ok(SurfaceApi::Win32),
+            RawWindowHandle::WinRt(_) => Err(()),
+            RawWindowHandle::Web(_) => Err(()),
+            RawWindowHandle::AndroidNdk(_) => Ok(SurfaceApi::Android),
+            RawWindowHandle::Haiku(_) => Err(()),
+            _ => Err(()),
+        }
+    }
+}
+
 vulkan_enum! {
     #[non_exhaustive]