Rework module layout for less redundancy and cleaner isolation

All core and extension raw type definitions and constants are exported directly under ash::vk, which is now flat. This includes e.g. extension name constants, which are named in the upstream style, less VK_. Extensions modules are exported under ash::{khr, ext, ...}, and include high-level wrappers, *Fn tables, and NAME and SPEC_VERSION reexports. Core *Fn structs are exported directly under ash.

Changelog.md

@@ -76,6 +76,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - extensions/ext/ray_tracing_pipeline: Pass indirect SBT regions as single item reference (#829)
 - Replaced `c_char` array setters with `CStr` setters (#831)
 - `push_next()` functions now allow unsized `p_next` argument (#855)
+- Flattened `ash::extensions` into `ash`, flattened `ash::vk::*` extension modules into `ash::vk`, and moved `*Fn` function pointer table structs from `ash::vk` into `ash` or the associated extension module (#894)
 
 ### Removed
 

ash-examples/src/lib.rs

@@ -11,11 +11,11 @@ use std::{
     borrow::Cow, cell::RefCell, default::Default, error::Error, ffi, ops::Drop, os::raw::c_char,
 };
 
-use ash::extensions::{
+use ash::{
     ext::debug_utils,
     khr::{surface, swapchain},
+    vk, Device, Entry, Instance,
 };
-use ash::{vk, Device, Entry, Instance};
 use winit::{
     event::{ElementState, Event, KeyEvent, WindowEvent},
     event_loop::{ControlFlow, EventLoop},
@@ -230,9 +230,9 @@ impl ExampleBase {
 
             #[cfg(any(target_os = "macos", target_os = "ios"))]
             {
-                extension_names.push(vk::khr::portability_enumeration::NAME.as_ptr());
+                extension_names.push(ash::khr::portability_enumeration::NAME.as_ptr());
                 // Enabling this extension is a requirement when using `VK_KHR_portability_subset`
-                extension_names.push(vk::khr::get_physical_device_properties2::NAME.as_ptr());
+                extension_names.push(ash::khr::get_physical_device_properties2::NAME.as_ptr());
             }
 
             let appinfo = vk::ApplicationInfo::default()
@@ -316,7 +316,7 @@ impl ExampleBase {
             let device_extension_names_raw = [
                 swapchain::NAME.as_ptr(),
                 #[cfg(any(target_os = "macos", target_os = "ios"))]
-                vk::khr::portability_subset::NAME.as_ptr(),
+                ash::khr::portability_subset::NAME.as_ptr(),
             ];
             let features = vk::PhysicalDeviceFeatures {
                 shader_clip_distance: 1,

ash-window/examples/winit.rs

@@ -35,7 +35,7 @@ fn main() -> Result<(), Box<dyn Error>> {
             .build(&event_loop)?;
 
         // Load the surface extensions
-        let surface_fn = ash::extensions::khr::surface::Instance::new(&entry, &instance);
+        let surface_fn = ash::khr::surface::Instance::new(&entry, &instance);
         let mut surface = None;
 
         let _ = event_loop.run(move |event, elwp| match event {

ash-window/src/lib.rs

@@ -3,12 +3,8 @@
 use std::os::raw::c_char;
 
 use ash::{
-    extensions::{
-        ext::metal_surface,
-        khr::{
-            android_surface, surface, wayland_surface, win32_surface, xcb_surface, xlib_surface,
-        },
-    },
+    ext::metal_surface,
+    khr::{android_surface, surface, wayland_surface, win32_surface, xcb_surface, xlib_surface},
     prelude::*,
     vk, Entry, Instance,
 };

ash/src/device.rs

@@ -12,14 +12,14 @@ use core::ptr;
 pub struct Device {
     pub(crate) handle: vk::Device,
 
-    pub(crate) device_fn_1_0: vk::DeviceFnV1_0,
-    pub(crate) device_fn_1_1: vk::DeviceFnV1_1,
-    pub(crate) device_fn_1_2: vk::DeviceFnV1_2,
-    pub(crate) device_fn_1_3: vk::DeviceFnV1_3,
+    pub(crate) device_fn_1_0: crate::DeviceFnV1_0,
+    pub(crate) device_fn_1_1: crate::DeviceFnV1_1,
+    pub(crate) device_fn_1_2: crate::DeviceFnV1_2,
+    pub(crate) device_fn_1_3: crate::DeviceFnV1_3,
 }
 
 impl Device {
-    pub unsafe fn load(instance_fn: &vk::InstanceFnV1_0, device: vk::Device) -> Self {
+    pub unsafe fn load(instance_fn: &crate::InstanceFnV1_0, device: vk::Device) -> Self {
         Self::load_with(
             |name| mem::transmute((instance_fn.get_device_proc_addr)(device, name.as_ptr())),
             device,
@@ -32,20 +32,20 @@ impl Device {
     ) -> Self {
         Self::from_parts_1_3(
             device,
-            vk::DeviceFnV1_0::load(&mut load_fn),
-            vk::DeviceFnV1_1::load(&mut load_fn),
-            vk::DeviceFnV1_2::load(&mut load_fn),
-            vk::DeviceFnV1_3::load(&mut load_fn),
+            crate::DeviceFnV1_0::load(&mut load_fn),
+            crate::DeviceFnV1_1::load(&mut load_fn),
+            crate::DeviceFnV1_2::load(&mut load_fn),
+            crate::DeviceFnV1_3::load(&mut load_fn),
         )
     }
 
     #[inline]
     pub fn from_parts_1_3(
         handle: vk::Device,
-        device_fn_1_0: vk::DeviceFnV1_0,
-        device_fn_1_1: vk::DeviceFnV1_1,
-        device_fn_1_2: vk::DeviceFnV1_2,
-        device_fn_1_3: vk::DeviceFnV1_3,
+        device_fn_1_0: crate::DeviceFnV1_0,
+        device_fn_1_1: crate::DeviceFnV1_1,
+        device_fn_1_2: crate::DeviceFnV1_2,
+        device_fn_1_3: crate::DeviceFnV1_3,
     ) -> Self {
         Self {
             handle,
@@ -66,7 +66,7 @@ impl Device {
 /// Vulkan core 1.3
 impl Device {
     #[inline]
-    pub fn fp_v1_3(&self) -> &vk::DeviceFnV1_3 {
+    pub fn fp_v1_3(&self) -> &crate::DeviceFnV1_3 {
         &self.device_fn_1_3
     }
 
@@ -556,7 +556,7 @@ impl Device {
 /// Vulkan core 1.2
 impl Device {
     #[inline]
-    pub fn fp_v1_2(&self) -> &vk::DeviceFnV1_2 {
+    pub fn fp_v1_2(&self) -> &crate::DeviceFnV1_2 {
         &self.device_fn_1_2
     }
 
@@ -736,7 +736,7 @@ impl Device {
 /// Vulkan core 1.1
 impl Device {
     #[inline]
-    pub fn fp_v1_1(&self) -> &vk::DeviceFnV1_1 {
+    pub fn fp_v1_1(&self) -> &crate::DeviceFnV1_1 {
         &self.device_fn_1_1
     }
 
@@ -982,7 +982,7 @@ impl Device {
 /// Vulkan core 1.0
 impl Device {
     #[inline]
-    pub fn fp_v1_0(&self) -> &vk::DeviceFnV1_0 {
+    pub fn fp_v1_0(&self) -> &crate::DeviceFnV1_0 {
         &self.device_fn_1_0
     }
 

ash/src/entry.rs

@@ -1,4 +1,6 @@
 use crate::instance::Instance;
+#[cfg(doc)]
+use crate::khr;
 use crate::prelude::*;
 use crate::vk;
 use crate::RawPtr;
@@ -14,9 +16,9 @@ use libloading::Library;
 /// Holds the Vulkan functions independent of a particular instance
 #[derive(Clone)]
 pub struct Entry {
-    static_fn: vk::StaticFn,
-    entry_fn_1_0: vk::EntryFnV1_0,
-    entry_fn_1_1: vk::EntryFnV1_1,
+    static_fn: crate::StaticFn,
+    entry_fn_1_0: crate::EntryFnV1_0,
+    entry_fn_1_1: crate::EntryFnV1_1,
     #[cfg(feature = "loaded")]
     _lib_guard: Option<alloc::sync::Arc<Library>>,
 }
@@ -111,7 +113,7 @@ impl Entry {
         // Sound because we're linking to Vulkan, which provides a vkGetInstanceProcAddr that has
         // defined behavior in this use.
         unsafe {
-            Self::from_static_fn(vk::StaticFn {
+            Self::from_static_fn(crate::StaticFn {
                 get_instance_proc_addr: vkGetInstanceProcAddr,
             })
         }
@@ -133,7 +135,7 @@ impl Entry {
             .map_err(LoadingError::LibraryLoadFailure)
             .map(alloc::sync::Arc::new)?;
 
-        let static_fn = vk::StaticFn::load_checked(|name| {
+        let static_fn = crate::StaticFn::load_checked(|name| {
             lib.get(name.to_bytes_with_nul())
                 .map(|symbol| *symbol)
                 .unwrap_or(ptr::null_mut())
@@ -145,13 +147,13 @@ impl Entry {
         })
     }
 
-    /// Load entry points based on an already-loaded [`vk::StaticFn`]
+    /// Load entry points based on an already-loaded [`crate::StaticFn`]
     ///
     /// # Safety
     ///
     /// `static_fn` must contain valid function pointers that comply with the semantics specified
     /// by Vulkan 1.0, which must remain valid for at least the lifetime of the returned [`Entry`].
-    pub unsafe fn from_static_fn(static_fn: vk::StaticFn) -> Self {
+    pub unsafe fn from_static_fn(static_fn: crate::StaticFn) -> Self {
         let load_fn = move |name: &ffi::CStr| {
             mem::transmute((static_fn.get_instance_proc_addr)(
                 vk::Instance::null(),
@@ -161,16 +163,16 @@ impl Entry {
 
         Self::from_parts_1_1(
             static_fn,
-            vk::EntryFnV1_0::load(load_fn),
-            vk::EntryFnV1_1::load(load_fn),
+            crate::EntryFnV1_0::load(load_fn),
+            crate::EntryFnV1_1::load(load_fn),
         )
     }
 
     #[inline]
     pub fn from_parts_1_1(
-        static_fn: vk::StaticFn,
-        entry_fn_1_0: vk::EntryFnV1_0,
-        entry_fn_1_1: vk::EntryFnV1_1,
+        static_fn: crate::StaticFn,
+        entry_fn_1_0: crate::EntryFnV1_0,
+        entry_fn_1_1: crate::EntryFnV1_1,
     ) -> Self {
         Self {
             static_fn,
@@ -182,12 +184,12 @@ impl Entry {
     }
 
     #[inline]
-    pub fn fp_v1_0(&self) -> &vk::EntryFnV1_0 {
+    pub fn fp_v1_0(&self) -> &crate::EntryFnV1_0 {
         &self.entry_fn_1_0
     }
 
     #[inline]
-    pub fn static_fn(&self) -> &vk::StaticFn {
+    pub fn static_fn(&self) -> &crate::StaticFn {
         &self.static_fn
     }
 
@@ -235,8 +237,8 @@ impl Entry {
     /// # Safety
     ///
     /// The resulting [`Instance`] and any function-pointer objects (e.g. [`Device`][crate::Device]
-    /// and [extensions][crate::extensions]) loaded from it may not be used after this [`Entry`]
-    /// object is dropped, unless it was crated using [`Entry::linked()`] or
+    /// and extensions like [`khr::swapchain::Device`]) loaded from it may not be used after
+    /// this [`Entry`] object is dropped, unless it was crated using [`Entry::linked()`] or
     /// [`Entry::from_parts_1_1()`].
     ///
     /// [`Instance`] does _not_ implement [drop][drop()] semantics and can only be destroyed via
@@ -294,7 +296,7 @@ impl Entry {
 /// Vulkan core 1.1
 impl Entry {
     #[inline]
-    pub fn fp_v1_1(&self) -> &vk::EntryFnV1_1 {
+    pub fn fp_v1_1(&self) -> &crate::EntryFnV1_1 {
         &self.entry_fn_1_1
     }
 
@@ -319,7 +321,7 @@ impl Default for Entry {
     }
 }
 
-impl vk::StaticFn {
+impl crate::StaticFn {
     pub fn load_checked<F>(mut _f: F) -> Result<Self, MissingEntryPoint>
     where
         F: FnMut(&ffi::CStr) -> *const ffi::c_void,

ash/src/extensions/amd/buffer_marker.rs

@@ -1,22 +1,8 @@
 //! <https://registry.khronos.org/vulkan/specs/1.3-extensions/man/html/VK_AMD_buffer_marker.html>
 
 use crate::vk;
-use core::mem;
-pub use vk::amd::buffer_marker::NAME;
-
-#[derive(Clone)]
-pub struct Device {
-    fp: vk::amd::buffer_marker::DeviceFn,
-}
-
-impl Device {
-    pub fn new(instance: &crate::Instance, device: &crate::Device) -> Self {
-        let fp = vk::amd::buffer_marker::DeviceFn::load(|name| unsafe {
-            mem::transmute(instance.get_device_proc_addr(device.handle(), name.as_ptr()))
-        });
-        Self { fp }
-    }
 
+impl crate::amd::buffer_marker::Device {
     /// <https://registry.khronos.org/vulkan/specs/1.3-extensions/man/html/vkCmdWriteBufferMarkerAMD.html>
     #[inline]
     pub unsafe fn cmd_write_buffer_marker(
@@ -35,9 +21,4 @@ impl Device {
             marker,
         )
     }
-
-    #[inline]
-    pub fn fp(&self) -> &vk::amd::buffer_marker::DeviceFn {
-        &self.fp
-    }
 }

ash/src/extensions/amd/shader_info.rs

@@ -4,23 +4,8 @@ use crate::prelude::*;
 use crate::vk;
 use alloc::vec::Vec;
 use core::mem;
-pub use vk::amd::shader_info::NAME;
-
-#[derive(Clone)]
-pub struct Device {
-    handle: vk::Device,
-    fp: vk::amd::shader_info::DeviceFn,
-}
-
-impl Device {
-    pub fn new(instance: &crate::Instance, device: &crate::Device) -> Self {
-        let handle = device.handle();
-        let fp = vk::amd::shader_info::DeviceFn::load(|name| unsafe {
-            mem::transmute(instance.get_device_proc_addr(handle, name.as_ptr()))
-        });
-        Self { handle, fp }
-    }
 
+impl crate::amd::shader_info::Device {
     /// <https://registry.khronos.org/vulkan/specs/1.3-extensions/man/html/vkGetShaderInfoAMD.html>
     #[inline]
     pub unsafe fn get_shader_info(
@@ -64,16 +49,6 @@ impl Device {
             x => unimplemented!("ShaderInfoTypeAMD {}", x.0),
         }
     }
-
-    #[inline]
-    pub fn fp(&self) -> &vk::amd::shader_info::DeviceFn {
-        &self.fp
-    }
-
-    #[inline]
-    pub fn device(&self) -> vk::Device {
-        self.handle
-    }
 }
 
 #[derive(Clone)]

ash/src/extensions/amdx/shader_enqueue.rs

@@ -5,23 +5,8 @@ use crate::vk;
 use crate::RawPtr;
 use alloc::vec::Vec;
 use core::mem;
-pub use vk::amdx::shader_enqueue::NAME;
-
-#[derive(Clone)]
-pub struct Device {
-    handle: vk::Device,
-    fp: vk::amdx::shader_enqueue::DeviceFn,
-}
-
-impl Device {
-    pub fn new(instance: &crate::Instance, device: &crate::Device) -> Self {
-        let handle = device.handle();
-        let fp = vk::amdx::shader_enqueue::DeviceFn::load(|name| unsafe {
-            mem::transmute(instance.get_device_proc_addr(handle, name.as_ptr()))
-        });
-        Self { handle, fp }
-    }
 
+impl crate::amdx::shader_enqueue::Device {
     /// <https://registry.khronos.org/vulkan/specs/1.3-extensions/man/html/vkCreateExecutionGraphPipelinesAMDX.html>
     #[inline]
     pub unsafe fn create_execution_graph_pipelines(
@@ -116,14 +101,4 @@ impl Device {
     ) {
         (self.fp.cmd_dispatch_graph_indirect_count_amdx)(command_buffer, scratch, count_info)
     }
-
-    #[inline]
-    pub fn fp(&self) -> &vk::amdx::shader_enqueue::DeviceFn {
-        &self.fp
-    }
-
-    #[inline]
-    pub fn device(&self) -> vk::Device {
-        self.handle
-    }
 }