features/limits refactors

CHANGELOG.md

@@ -86,6 +86,7 @@ Previously, `DeviceExt::create_texture_with_data` only allowed data to be provid
 - Rename of `DispatchIndirect`, `DrawIndexedIndirect`, and `DrawIndirect` types in the `wgpu::util` module to `DispatchIndirectArgs`, `DrawIndexedIndirectArgs`, and `DrawIndirectArgs`. By @cwfitzgerald in [#4723](https://github.com/gfx-rs/wgpu/pull/4723).
 - Make the size parameter of `encoder.clear_buffer` an `Option<u64>` instead of `Option<NonZero<u64>>`. By @nical in [#4737](https://github.com/gfx-rs/wgpu/pull/4737)
 - Reduce the `info` log level noise. By @nical in [#4769](https://github.com/gfx-rs/wgpu/pull/4769), [#4711](https://github.com/gfx-rs/wgpu/pull/4711) and [#4772](https://github.com/gfx-rs/wgpu/pull/4772)
+- Rename `features` & `limits` fields of `DeviceDescriptor` to `required_features` & `required_limits`. By @teoxoy in [#4803](https://github.com/gfx-rs/wgpu/pull/4803)
 
 #### Safe `Surface` creation
 

deno_webgpu/lib.rs

@@ -657,8 +657,8 @@ pub async fn op_webgpu_request_device(
 
     let descriptor = wgpu_types::DeviceDescriptor {
         label: Some(Cow::Owned(label)),
-        features: required_features.into(),
-        limits: required_limits.unwrap_or_default(),
+        required_features: required_features.into(),
+        required_limits: required_limits.unwrap_or_default(),
     };
 
     let (device, _queue, maybe_err) = gfx_select!(adapter => instance.adapter_request_device(

examples/src/framework.rs

@@ -317,8 +317,8 @@ impl ExampleContext {
             .request_device(
                 &wgpu::DeviceDescriptor {
                     label: None,
-                    features: (optional_features & adapter_features) | required_features,
-                    limits: needed_limits,
+                    required_features: (optional_features & adapter_features) | required_features,
+                    required_limits: needed_limits,
                 },
                 trace_dir.ok().as_ref().map(std::path::Path::new),
             )

examples/src/hello_compute/mod.rs

@@ -48,8 +48,8 @@ async fn execute_gpu(numbers: &[u32]) -> Option<Vec<u32>> {
         .request_device(
             &wgpu::DeviceDescriptor {
                 label: None,
-                features: wgpu::Features::empty(),
-                limits: wgpu::Limits::downlevel_defaults(),
+                required_features: wgpu::Features::empty(),
+                required_limits: wgpu::Limits::downlevel_defaults(),
             },
             None,
         )

examples/src/hello_synchronization/mod.rs

@@ -17,8 +17,8 @@ async fn run() {
         .request_device(
             &wgpu::DeviceDescriptor {
                 label: None,
-                features: wgpu::Features::empty(),
-                limits: wgpu::Limits::downlevel_defaults(),
+                required_features: wgpu::Features::empty(),
+                required_limits: wgpu::Limits::downlevel_defaults(),
             },
             None,
         )

examples/src/hello_triangle/mod.rs

@@ -28,9 +28,9 @@ async fn run(event_loop: EventLoop<()>, window: Window) {
         .request_device(
             &wgpu::DeviceDescriptor {
                 label: None,
-                features: wgpu::Features::empty(),
+                required_features: wgpu::Features::empty(),
                 // Make sure we use the texture resolution limits from the adapter, so we can support images the size of the swapchain.
-                limits: wgpu::Limits::downlevel_webgl2_defaults()
+                required_limits: wgpu::Limits::downlevel_webgl2_defaults()
                     .using_resolution(adapter.limits()),
             },
             None,

examples/src/hello_windows/mod.rs

@@ -82,8 +82,8 @@ async fn run(event_loop: EventLoop<()>, viewports: Vec<(Arc<Window>, wgpu::Color
         .request_device(
             &wgpu::DeviceDescriptor {
                 label: None,
-                features: wgpu::Features::empty(),
-                limits: wgpu::Limits::downlevel_defaults(),
+                required_features: wgpu::Features::empty(),
+                required_limits: wgpu::Limits::downlevel_defaults(),
             },
             None,
         )

examples/src/hello_workgroups/mod.rs

@@ -30,8 +30,8 @@ async fn run() {
         .request_device(
             &wgpu::DeviceDescriptor {
                 label: None,
-                features: wgpu::Features::empty(),
-                limits: wgpu::Limits::downlevel_defaults(),
+                required_features: wgpu::Features::empty(),
+                required_limits: wgpu::Limits::downlevel_defaults(),
             },
             None,
         )

examples/src/render_to_texture/mod.rs

@@ -19,8 +19,8 @@ async fn run(_path: Option<String>) {
         .request_device(
             &wgpu::DeviceDescriptor {
                 label: None,
-                features: wgpu::Features::empty(),
-                limits: wgpu::Limits::downlevel_defaults(),
+                required_features: wgpu::Features::empty(),
+                required_limits: wgpu::Limits::downlevel_defaults(),
             },
             None,
         )

examples/src/repeated_compute/mod.rs

@@ -167,8 +167,8 @@ impl WgpuContext {
             .request_device(
                 &wgpu::DeviceDescriptor {
                     label: None,
-                    features: wgpu::Features::empty(),
-                    limits: wgpu::Limits::downlevel_defaults(),
+                    required_features: wgpu::Features::empty(),
+                    required_limits: wgpu::Limits::downlevel_defaults(),
                 },
                 None,
             )

examples/src/storage_texture/mod.rs

@@ -33,8 +33,8 @@ async fn run(_path: Option<String>) {
         .request_device(
             &wgpu::DeviceDescriptor {
                 label: None,
-                features: wgpu::Features::empty(),
-                limits: wgpu::Limits::downlevel_defaults(),
+                required_features: wgpu::Features::empty(),
+                required_limits: wgpu::Limits::downlevel_defaults(),
             },
             None,
         )

examples/src/timestamp_queries/mod.rs

@@ -214,8 +214,8 @@ async fn run() {
         .request_device(
             &wgpu::DeviceDescriptor {
                 label: None,
-                features,
-                limits: wgpu::Limits::downlevel_defaults(),
+                required_features: features,
+                required_limits: wgpu::Limits::downlevel_defaults(),
             },
             None,
         )

examples/src/uniform_values/mod.rs

@@ -113,8 +113,8 @@ impl WgpuContext {
             .request_device(
                 &wgpu::DeviceDescriptor {
                     label: None,
-                    features: wgpu::Features::empty(),
-                    limits: wgpu::Limits::downlevel_defaults(),
+                    required_features: wgpu::Features::empty(),
+                    required_limits: wgpu::Limits::downlevel_defaults(),
                 },
                 None,
             )

player/tests/test.rs

@@ -89,8 +89,8 @@ impl Test<'_> {
             adapter,
             &wgt::DeviceDescriptor {
                 label: None,
-                features: self.features,
-                limits: wgt::Limits::default(),
+                required_features: self.features,
+                required_limits: wgt::Limits::default(),
             },
             None,
             device_id,

tests/src/init.rs

@@ -85,8 +85,8 @@ pub async fn initialize_device(
         .request_device(
             &wgpu::DeviceDescriptor {
                 label: None,
-                features,
-                limits,
+                required_features: features,
+                required_limits: limits,
             },
             None,
         )

tests/tests/device.rs

@@ -79,8 +79,8 @@ async fn request_device_error_message() {
         .request_device(
             &wgpu::DeviceDescriptor {
                 // Force a failure by requesting absurd limits.
-                features: wgpu::Features::all(),
-                limits: wgpu::Limits {
+                required_features: wgpu::Features::all(),
+                required_limits: wgpu::Limits {
                     max_texture_dimension_1d: u32::MAX,
                     max_texture_dimension_2d: u32::MAX,
                     max_texture_dimension_3d: u32::MAX,

wgpu-core/src/device/resource.rs

@@ -192,8 +192,6 @@ impl<A: HalApi> Device<A> {
         raw_device: A::Device,
         raw_queue: &A::Queue,
         adapter: &Arc<Adapter<A>>,
-        alignments: hal::Alignments,
-        downlevel: wgt::DownlevelCapabilities,
         desc: &DeviceDescriptor,
         trace_path: Option<&std::path::Path>,
         instance_flags: wgt::InstanceFlags,
@@ -243,6 +241,9 @@ impl<A: HalApi> Device<A> {
                 }));
         }
 
+        let alignments = adapter.raw.capabilities.alignments.clone();
+        let downlevel = adapter.raw.capabilities.downlevel.clone();
+
         Ok(Self {
             raw: Some(raw_device),
             adapter: adapter.clone(),
@@ -272,8 +273,8 @@ impl<A: HalApi> Device<A> {
                 }
             })),
             alignments,
-            limits: desc.limits.clone(),
-            features: desc.features,
+            limits: desc.required_limits.clone(),
+            features: desc.required_features,
             downlevel,
             instance_flags,
             pending_writes: Mutex::new(Some(pending_writes)),

wgpu-core/src/instance.rs

@@ -309,13 +309,10 @@ impl<A: HalApi> Adapter<A> {
     ) -> Result<(Device<A>, Queue<A>), RequestDeviceError> {
         api_log!("Adapter::create_device");
 
-        let caps = &self.raw.capabilities;
         if let Ok(device) = Device::new(
             hal_device.device,
             &hal_device.queue,
             self,
-            caps.alignments.clone(),
-            caps.downlevel.clone(),
             desc,
             trace_path,
             instance_flags,
@@ -337,9 +334,9 @@ impl<A: HalApi> Adapter<A> {
         trace_path: Option<&std::path::Path>,
     ) -> Result<(Device<A>, Queue<A>), RequestDeviceError> {
         // Verify all features were exposed by the adapter
-        if !self.raw.features.contains(desc.features) {
+        if !self.raw.features.contains(desc.required_features) {
             return Err(RequestDeviceError::UnsupportedFeature(
-                desc.features - self.raw.features,
+                desc.required_features - self.raw.features,
             ));
         }
 
@@ -358,7 +355,7 @@ impl<A: HalApi> Adapter<A> {
 
         // Verify feature preconditions
         if desc
-            .features
+            .required_features
             .contains(wgt::Features::MAPPABLE_PRIMARY_BUFFERS)
             && self.raw.info.device_type == wgt::DeviceType::DiscreteGpu
         {
@@ -372,17 +369,20 @@ impl<A: HalApi> Adapter<A> {
             //TODO
         }
 
-        if let Some(failed) = check_limits(&desc.limits, &caps.limits).pop() {
+        if let Some(failed) = check_limits(&desc.required_limits, &caps.limits).pop() {
             return Err(RequestDeviceError::LimitsExceeded(failed));
         }
 
-        let open = unsafe { self.raw.adapter.open(desc.features, &desc.limits) }.map_err(
-            |err| match err {
-                hal::DeviceError::Lost => RequestDeviceError::DeviceLost,
-                hal::DeviceError::OutOfMemory => RequestDeviceError::OutOfMemory,
-                hal::DeviceError::ResourceCreationFailed => RequestDeviceError::Internal,
-            },
-        )?;
+        let open = unsafe {
+            self.raw
+                .adapter
+                .open(desc.required_features, &desc.required_limits)
+        }
+        .map_err(|err| match err {
+            hal::DeviceError::Lost => RequestDeviceError::DeviceLost,
+            hal::DeviceError::OutOfMemory => RequestDeviceError::OutOfMemory,
+            hal::DeviceError::ResourceCreationFailed => RequestDeviceError::Internal,
+        })?;
 
         self.create_device_and_queue_from_hal(open, desc, instance_flags, trace_path)
     }

wgpu-types/src/lib.rs

@@ -1651,21 +1651,27 @@ pub struct AdapterInfo {
 pub struct DeviceDescriptor<L> {
     /// Debug label for the device.
     pub label: L,
-    /// Features that the device should support. If any feature is not supported by
-    /// the adapter, creating a device will panic.
-    pub features: Features,
-    /// Limits that the device should support. If any limit is "better" than the limit exposed by
-    /// the adapter, creating a device will panic.
-    pub limits: Limits,
+    /// Specifies the features that are required by the device request.
+    /// The request will fail if the adapter cannot provide these features.
+    ///
+    /// Exactly the specified set of features, and no more or less,
+    /// will be allowed in validation of API calls on the resulting device.
+    pub required_features: Features,
+    /// Specifies the limits that are required by the device request.
+    /// The request will fail if the adapter cannot provide these limits.
+    ///
+    /// Exactly the specified limits, and no better or worse,
+    /// will be allowed in validation of API calls on the resulting device.
+    pub required_limits: Limits,
 }
 
 impl<L> DeviceDescriptor<L> {
     /// Takes a closure and maps the label of the device descriptor into another.
     pub fn map_label<K>(&self, fun: impl FnOnce(&L) -> K) -> DeviceDescriptor<K> {
         DeviceDescriptor {
             label: fun(&self.label),
-            features: self.features,
-            limits: self.limits.clone(),
+            required_features: self.required_features,
+            required_limits: self.required_limits.clone(),
         }
     }
 }

wgpu/src/backend/direct.rs

@@ -122,7 +122,7 @@ impl Context {
         let device = Device {
             id: device_id,
             error_sink: error_sink.clone(),
-            features: desc.features,
+            features: desc.required_features,
         };
         let queue = Queue {
             id: queue_id,
@@ -646,7 +646,7 @@ impl crate::Context for Context {
         let device = Device {
             id: device_id,
             error_sink: error_sink.clone(),
-            features: desc.features,
+            features: desc.required_features,
         };
         let queue = Queue {
             id: queue_id,

wgpu/src/backend/web.rs

@@ -1151,7 +1151,7 @@ impl crate::context::Context for Context {
 
         // TODO: Migrate to a web_sys api.
         // See https://github.com/rustwasm/wasm-bindgen/issues/3587
-        let limits_object = map_js_sys_limits(&desc.limits);
+        let limits_object = map_js_sys_limits(&desc.required_limits);
 
         js_sys::Reflect::set(
             &mapped_desc,
@@ -1164,7 +1164,7 @@ impl crate::context::Context for Context {
             .iter()
             .copied()
             .flat_map(|(flag, value)| {
-                if desc.features.contains(flag) {
+                if desc.required_features.contains(flag) {
                     Some(JsValue::from(value))
                 } else {
                     None

wgpu/src/lib.rs

@@ -2383,18 +2383,12 @@ impl Adapter {
         )
     }
 
-    /// List all features that are supported with this adapter.
-    ///
-    /// Features must be explicitly requested in [`Adapter::request_device`] in order
-    /// to use them.
+    /// The features which can be used to create devices on this adapter.
     pub fn features(&self) -> Features {
         DynContext::adapter_features(&*self.context, &self.id, self.data.as_ref())
     }
 
-    /// List the "best" limits that are supported by this adapter.
-    ///
-    /// Limits must be explicitly requested in [`Adapter::request_device`] to set
-    /// the values that you are allowed to use.
+    /// The best limits which can be used to create devices on this adapter.
     pub fn limits(&self) -> Limits {
         DynContext::adapter_limits(&*self.context, &self.id, self.data.as_ref())
     }
@@ -2462,16 +2456,16 @@ impl Device {
         DynContext::device_poll(&*self.context, &self.id, self.data.as_ref(), maintain)
     }
 
-    /// List all features that may be used with this device.
+    /// The features which can be used on this device.
     ///
-    /// Functions may panic if you use unsupported features.
+    /// No additional features can be used, even if the underlying adapter can support them.
     pub fn features(&self) -> Features {
         DynContext::device_features(&*self.context, &self.id, self.data.as_ref())
     }
 
-    /// List all limits that were requested of this device.
+    /// The limits which can be used on this device.
     ///
-    /// If any of these limits are exceeded, functions may panic.
+    /// No better limits can be used, even if the underlying adapter can support them.
     pub fn limits(&self) -> Limits {
         DynContext::device_limits(&*self.context, &self.id, self.data.as_ref())
     }