From e30e30043672a03d89525ec6ee2c50b5f340bd00 Mon Sep 17 00:00:00 2001 From: Jim Blandy Date: Fri, 29 Mar 2024 17:19:52 -0700 Subject: [PATCH] [hal/vulkan] Document more PhysicalDeviceFeatures-related things. Improve documentation for: - `PhysicalDeviceFeatures::from_extensions_and_requested_features` - `PhysicalDeviceFeatures::to_wgpu` - `Adapter::physical_device_features` --- wgpu-hal/src/vulkan/adapter.rs | 47 +++++++++++++++++++++++++++++++--- 1 file changed, 44 insertions(+), 3 deletions(-) diff --git a/wgpu-hal/src/vulkan/adapter.rs b/wgpu-hal/src/vulkan/adapter.rs index 3c540a9dad..2665463792 100644 --- a/wgpu-hal/src/vulkan/adapter.rs +++ b/wgpu-hal/src/vulkan/adapter.rs @@ -151,9 +151,32 @@ impl PhysicalDeviceFeatures { info } - /// Create a `PhysicalDeviceFeatures` that will be used to create a logical device. + /// Create a `PhysicalDeviceFeatures` that can be used to create a logical + /// device. /// - /// `requested_features` should be the same as what was used to generate `enabled_extensions`. + /// Return a `PhysicalDeviceFeatures` value capturing all the Vulkan + /// features needed for the given [`Features`], [`DownlevelFlags`], and + /// [`PrivateCapabilities`]. You can use the returned value's + /// [`add_to_device_create_builder`] method to configure a + /// [`DeviceCreateInfoBuilder`] to build a logical device providing those + /// features. + /// + /// To ensure that the returned value is able to select all the Vulkan + /// features needed to express `requested_features`, `downlevel_flags`, and + /// `private_caps`: + /// + /// - The given `enabled_extensions` set must include all the extensions + /// selected by [`Adapter::required_device_extensions`] when passed + /// `features`. + /// + /// - The given `device_api_version` must be the Vulkan API version of the + /// physical device we will use to create the logical device. + /// + /// [`Features`]: wgt::Features + /// [`DownlevelFlags`]: wgt::DownlevelFlags + /// [`PrivateCapabilities`]: super::PrivateCapabilities + /// [`DeviceCreateInfoBuilder`]: vk::DeviceCreateInfoBuilder + /// [`Adapter::required_device_extensions`]: super::Adapter::required_device_extensions fn from_extensions_and_requested_features( device_api_version: u32, enabled_extensions: &[&'static CStr], @@ -414,6 +437,11 @@ impl PhysicalDeviceFeatures { } } + /// Compute the wgpu [`Features`] and [`DownlevelFlags`] supported by a physical device. + /// + /// Given `self`, together with the instance and physical device it was + /// built from, and a `caps` also built from those, determine which wgpu + /// features and downlevel flags the device can support. fn to_wgpu( &self, instance: &ash::Instance, @@ -1420,7 +1448,20 @@ impl super::Adapter { supported_extensions } - /// `features` must be the same features used to create `enabled_extensions`. + /// Create a `PhysicalDeviceFeatures` for opening a logical device with + /// `features` from this adapter. + /// + /// The given `enabled_extensions` set must include all the extensions + /// selected by [`required_device_extensions`] when passed `features`. + /// Otherwise, the `PhysicalDeviceFeatures` value may not be able to select + /// all the Vulkan features needed to represent `features` and this + /// adapter's characteristics. + /// + /// Typically, you'd simply call `required_device_extensions`, and then pass + /// its return value and the feature set you gave it directly to this + /// function. But it's fine to add more extensions to the list. + /// + /// [`required_device_extensions`]: Self::required_device_extensions pub fn physical_device_features( &self, enabled_extensions: &[&'static CStr],