Pass InstanceDescriptor by reference and make it clonable (#6849)

Wumpf · web-flow · commit fb210ab36393 · 2025-01-06T15:40:30.000-05:00
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -125,6 +125,18 @@ There are some limitations to keep in mind with this new functionality:
 
 By @ErichDonGubler in [#6456](https://github.com/gfx-rs/wgpu/pull/6456), [#6148](https://github.com/gfx-rs/wgpu/pull/6148), [#6533](https://github.com/gfx-rs/wgpu/pull/6533), [#6353](https://github.com/gfx-rs/wgpu/pull/6353), [#6537](https://github.com/gfx-rs/wgpu/pull/6537).
 
+#### `wgpu::Instance::new` now takes `InstanceDescriptor` by reference
+
+Previously `wgpu::Instance::new` took `InstanceDescriptor` by value (which is overall fairly uncommon in wgpu).
+Furthermore, `InstanceDescriptor` is now cloneable.
+
+```diff
+- let instance = wgpu::Instance::new(instance_desc);
++ let instance = wgpu::Instance::new(&instance_desc);
+```
+
+By @wumpf in [#6849](https://github.com/gfx-rs/wgpu/pull/6849).
+
 #### New Features
 
 ##### Naga
diff --git a/benches/benches/root.rs b/benches/benches/root.rs
@@ -25,7 +25,7 @@ impl DeviceState {
             wgpu::Backends::all()
         };
 
-        let instance = wgpu::Instance::new(wgpu::InstanceDescriptor {
+        let instance = wgpu::Instance::new(&wgpu::InstanceDescriptor {
             backends: wgpu::util::backend_bits_from_env().unwrap_or(base_backend),
             flags: wgpu::InstanceFlags::empty(),
             dx12_shader_compiler: wgpu::util::dx12_shader_compiler_from_env()
diff --git a/deno_webgpu/lib.rs b/deno_webgpu/lib.rs
@@ -388,7 +388,7 @@ pub fn op_webgpu_request_adapter(
     } else {
         state.put(std::sync::Arc::new(wgpu_core::global::Global::new(
             "webgpu",
-            wgpu_types::InstanceDescriptor {
+            &wgpu_types::InstanceDescriptor {
                 backends,
                 flags: wgpu_types::InstanceFlags::from_build_config(),
                 dx12_shader_compiler: wgpu_types::Dx12Compiler::Fxc,
diff --git a/examples/src/framework.rs b/examples/src/framework.rs
@@ -268,7 +268,7 @@ impl ExampleContext {
     async fn init_async<E: Example>(surface: &mut SurfaceWrapper, window: Arc<Window>) -> Self {
         log::info!("Initializing wgpu...");
 
-        let instance = wgpu::Instance::new(wgpu::util::instance_descriptor_from_env());
+        let instance = wgpu::Instance::new(&wgpu::util::instance_descriptor_from_env());
         surface.pre_adapter(&instance, window);
 
         let adapter = get_adapter_with_capabilities_or_from_env(
diff --git a/examples/src/hello_triangle/mod.rs b/examples/src/hello_triangle/mod.rs
@@ -10,7 +10,7 @@ async fn run(event_loop: EventLoop<()>, window: Window) {
     size.width = size.width.max(1);
     size.height = size.height.max(1);
 
-    let instance = wgpu::Instance::new(wgpu::util::instance_descriptor_from_env());
+    let instance = wgpu::Instance::new(&wgpu::util::instance_descriptor_from_env());
 
     let surface = instance.create_surface(&window).unwrap();
     let adapter = instance
diff --git a/examples/src/timestamp_queries/mod.rs b/examples/src/timestamp_queries/mod.rs
@@ -181,7 +181,7 @@ impl Queries {
 async fn run() {
     // Instantiates instance of wgpu
     let backends = wgpu::util::backend_bits_from_env().unwrap_or_default();
-    let instance = wgpu::Instance::new(wgpu::InstanceDescriptor {
+    let instance = wgpu::Instance::new(&wgpu::InstanceDescriptor {
         backends,
         flags: wgpu::InstanceFlags::from_build_config().with_env(),
         dx12_shader_compiler: wgpu::Dx12Compiler::default(),
diff --git a/player/src/bin/play.rs b/player/src/bin/play.rs
@@ -48,7 +48,7 @@ fn main() {
         .build(&event_loop)
         .unwrap();
 
-    let global = wgc::global::Global::new("player", wgt::InstanceDescriptor::default());
+    let global = wgc::global::Global::new("player", &wgt::InstanceDescriptor::default());
     let mut command_buffer_id_manager = wgc::identity::IdentityManager::new();
 
     #[cfg(feature = "winit")]
diff --git a/player/tests/test.rs b/player/tests/test.rs
@@ -201,7 +201,7 @@ impl Corpus {
 
                 let global = wgc::global::Global::new(
                     "test",
-                    wgt::InstanceDescriptor {
+                    &wgt::InstanceDescriptor {
                         backends: backend.into(),
                         flags: wgt::InstanceFlags::debugging(),
                         dx12_shader_compiler: wgt::Dx12Compiler::Fxc,
diff --git a/tests/compile_tests/fail/cpass_lifetime.rs b/tests/compile_tests/fail/cpass_lifetime.rs
@@ -4,7 +4,7 @@
 // See #6145 for more info.
 
 fn main() {
-    let instance = wgpu::Instance::new(Default::default());
+    let instance = wgpu::Instance::default();
     let adapter = pollster::block_on(instance.request_adapter(&Default::default())).unwrap();
     let (device, queue) =
         pollster::block_on(adapter.request_device(&Default::default(), None)).unwrap();
diff --git a/tests/compile_tests/fail/rpass_lifetime.rs b/tests/compile_tests/fail/rpass_lifetime.rs
@@ -4,7 +4,7 @@
 // See #6145 for more info.
 
 fn main() {
-    let instance = wgpu::Instance::new(Default::default());
+    let instance = wgpu::Instance::default();
     let adapter = pollster::block_on(instance.request_adapter(&Default::default())).unwrap();
     let (device, queue) =
         pollster::block_on(adapter.request_device(&Default::default(), None)).unwrap();
diff --git a/tests/src/init.rs b/tests/src/init.rs
@@ -37,7 +37,7 @@ pub fn initialize_instance(backends: wgpu::Backends, force_fxc: bool) -> Instanc
         wgpu::util::dx12_shader_compiler_from_env().unwrap_or(wgpu::Dx12Compiler::StaticDxc)
     };
     let gles_minor_version = wgpu::util::gles_minor_version_from_env().unwrap_or_default();
-    Instance::new(wgpu::InstanceDescriptor {
+    Instance::new(&wgpu::InstanceDescriptor {
         backends,
         flags: wgpu::InstanceFlags::debugging().with_env(),
         dx12_shader_compiler,
diff --git a/tests/tests/multi-instance.rs b/tests/tests/multi-instance.rs
@@ -2,7 +2,7 @@
 
 async fn get() -> wgpu::Adapter {
     let adapter = {
-        let instance = wgpu::Instance::new(wgpu::InstanceDescriptor {
+        let instance = wgpu::Instance::new(&wgpu::InstanceDescriptor {
             backends: wgpu::util::backend_bits_from_env().unwrap_or_default(),
             ..Default::default()
         });
diff --git a/wgpu-core/src/global.rs b/wgpu-core/src/global.rs
@@ -31,7 +31,7 @@ pub struct Global {
 }
 
 impl Global {
-    pub fn new(name: &str, instance_desc: wgt::InstanceDescriptor) -> Self {
+    pub fn new(name: &str, instance_desc: &wgt::InstanceDescriptor) -> Self {
         profiling::scope!("Global::new");
         Self {
             instance: Instance::new(name, instance_desc),
diff --git a/wgpu-core/src/instance.rs b/wgpu-core/src/instance.rs
@@ -63,7 +63,7 @@ pub struct Instance {
 }
 
 impl Instance {
-    pub fn new(name: &str, instance_desc: wgt::InstanceDescriptor) -> Self {
+    pub fn new(name: &str, instance_desc: &wgt::InstanceDescriptor) -> Self {
         fn init<A: HalApi>(
             _: A,
             instance_desc: &wgt::InstanceDescriptor,
@@ -99,13 +99,13 @@ impl Instance {
         let mut instance_per_backend = Vec::new();
 
         #[cfg(vulkan)]
-        init(hal::api::Vulkan, &instance_desc, &mut instance_per_backend);
+        init(hal::api::Vulkan, instance_desc, &mut instance_per_backend);
         #[cfg(metal)]
-        init(hal::api::Metal, &instance_desc, &mut instance_per_backend);
+        init(hal::api::Metal, instance_desc, &mut instance_per_backend);
         #[cfg(dx12)]
-        init(hal::api::Dx12, &instance_desc, &mut instance_per_backend);
+        init(hal::api::Dx12, instance_desc, &mut instance_per_backend);
         #[cfg(gles)]
-        init(hal::api::Gles, &instance_desc, &mut instance_per_backend);
+        init(hal::api::Gles, instance_desc, &mut instance_per_backend);
 
         Self {
             name: name.to_string(),
diff --git a/wgpu-info/src/report.rs b/wgpu-info/src/report.rs
@@ -17,7 +17,7 @@ pub struct GpuReport {
 
 impl GpuReport {
     pub fn generate() -> Self {
-        let instance = wgpu::Instance::new(wgpu::InstanceDescriptor {
+        let instance = wgpu::Instance::new(&wgpu::InstanceDescriptor {
             backends: wgpu::util::backend_bits_from_env().unwrap_or_default(),
             flags: wgpu::InstanceFlags::debugging().with_env(),
             dx12_shader_compiler: wgpu::util::dx12_shader_compiler_from_env()
diff --git a/wgpu-types/src/lib.rs b/wgpu-types/src/lib.rs
@@ -7707,7 +7707,7 @@ pub enum Gles3MinorVersion {
 }
 
 /// Options for creating an instance.
-#[derive(Debug)]
+#[derive(Clone, Debug)]
 pub struct InstanceDescriptor {
     /// Which `Backends` to enable.
     pub backends: Backends,
diff --git a/wgpu/src/api/instance.rs b/wgpu/src/api/instance.rs
@@ -31,7 +31,7 @@ impl Default for Instance {
     /// If no backend feature for the active target platform is enabled,
     /// this method will panic, see [`Instance::enabled_backend_features()`].
     fn default() -> Self {
-        Self::new(InstanceDescriptor::default())
+        Self::new(&InstanceDescriptor::default())
     }
 }
 
@@ -113,7 +113,7 @@ impl Instance {
     /// If no backend feature for the active target platform is enabled,
     /// this method will panic, see [`Instance::enabled_backend_features()`].
     #[allow(unreachable_code)]
-    pub fn new(_instance_desc: InstanceDescriptor) -> Self {
+    pub fn new(_instance_desc: &InstanceDescriptor) -> Self {
         if Self::enabled_backend_features().is_empty() {
             panic!(
                 "No wgpu backend feature that is implemented for the target platform was enabled. \
diff --git a/wgpu/src/backend/webgpu.rs b/wgpu/src/backend/webgpu.rs
@@ -1461,7 +1461,7 @@ impl dispatch::InterfaceTypes for ContextWebGpu {
 }
 
 impl dispatch::InstanceInterface for ContextWebGpu {
-    fn new(_desc: crate::InstanceDescriptor) -> Self
+    fn new(_desc: &crate::InstanceDescriptor) -> Self
     where
         Self: Sized,
     {
diff --git a/wgpu/src/backend/wgpu_core.rs b/wgpu/src/backend/wgpu_core.rs
@@ -767,7 +767,7 @@ impl InterfaceTypes for ContextWgpuCore {
 }
 
 impl dispatch::InstanceInterface for ContextWgpuCore {
-    fn new(desc: wgt::InstanceDescriptor) -> Self
+    fn new(desc: &wgt::InstanceDescriptor) -> Self
     where
         Self: Sized,
     {
diff --git a/wgpu/src/dispatch.rs b/wgpu/src/dispatch.rs
@@ -85,7 +85,7 @@ pub trait InterfaceTypes {
 }
 
 pub trait InstanceInterface: CommonTraits {
-    fn new(desc: crate::InstanceDescriptor) -> Self
+    fn new(desc: &wgt::InstanceDescriptor) -> Self
     where
         Self: Sized;
 
diff --git a/wgpu/src/util/init.rs b/wgpu/src/util/init.rs
@@ -199,8 +199,9 @@ pub async fn is_browser_webgpu_supported() -> bool {
 /// this method will panic, see [`Instance::enabled_backend_features()`].
 #[allow(unused_mut)]
 pub async fn new_instance_with_webgpu_detection(
-    mut instance_desc: wgt::InstanceDescriptor,
+    instance_desc: &wgt::InstanceDescriptor,
 ) -> crate::Instance {
+    let mut instance_desc = instance_desc.clone();
     if instance_desc
         .backends
         .contains(wgt::Backends::BROWSER_WEBGPU)
@@ -209,5 +210,5 @@ pub async fn new_instance_with_webgpu_detection(
         instance_desc.backends.remove(wgt::Backends::BROWSER_WEBGPU);
     }
 
-    crate::Instance::new(instance_desc)
+    crate::Instance::new(&instance_desc)
 }
