Separate Out Backend Options into Individual Structs

CHANGELOG.md

@@ -75,6 +75,74 @@ let desc: ShaderModuleDescriptor = include_wgsl!(...)
 
 By @cwfitzgerald and @rudderbucky in [#6662](https://github.com/gfx-rs/wgpu/pull/6662).
 
+#### `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).
+
+#### Environment Variable Handling Overhaul
+
+Previously how various bits of code handled reading settings from environment variables was inconsistent and unideomatic.
+We have unified it to `Type::from_env()` for all types.
+
+```diff
+- wgpu::util::backend_bits_from_env()
++ wgpu::Backends::from_env()
+
+- wgpu::util::power_preference_from_env()
++ wgpu::PowerPreference::from_env()
+
+- wgpu::util::dx12_shader_compiler_from_env()
++ wgpu::Dx12Compiler::from_env()
+
+- wgpu::util::gles_minor_version_from_env()
++ wgpu::Gles3MinorVersion::from_env()
+
+- wgpu::util::instance_descriptor_from_env()
++ wgpu::InstanceDescriptor::from_env()
+
+- wgpu::util::parse_backends_from_comma_list(&str)
++ wgpu::Backends::from_comma_list(&str)
+```
+
+By @cwfitzgerald in [#6895](https://github.com/gfx-rs/wgpu/pull/6895)
+
+#### Backend-specific instance options are now in separate structs
+
+In order to better facilitate growing more interesting backend options, we have put them into individual structs. This allows users to more easily understand what options can be defaulted and which they care about. All of these new structs implement `from_env()` and delegate to their respective `from_env()` methods.
+
+```diff
+- let instance = wgpu::Instance::new(&wgpu::InstanceDescriptor {
+-     backends: wgpu::Backends::all(),
+-     flags: wgpu::InstanceFlags::default(),
+-     dx12_shader_compiler: wgpu::Dx12Compiler::Dxc,
+-     gles_minor_version: wgpu::Gles3MinorVersion::Automatic,
+- });
++ let instance = wgpu::Instance::new(&wgpu::InstanceDescriptor {
++     backends: wgpu::Backends::all(),
++     flags: wgpu::InstanceFlags::default(),
++     backend_options: wgpu::BackendOptions {
++         dx12: wgpu::Dx12BackendOptions {
++             shader_compiler: wgpu::Dx12ShaderCompiler::Dxc,
++         },
++         gl: wgpu::GlBackendOptions {
++             gles_minor_version: wgpu::Gles3MinorVersion::Automatic,
++         },
++     },
++ });
+```
+
+If you do not need any of these options, or only need one backend's info use the `default()` impl to fill out the remaining feelds.
+
+By @cwfitzgerald in [#6895](https://github.com/gfx-rs/wgpu/pull/6895)
+
 #### The `diagnostic(…);` directive is now supported in WGSL
 
 Naga now parses `diagnostic(…);` directives according to the WGSL spec. This allows users to control certain lints, similar to Rust's `allow`, `warn`, and `deny` attributes. For example, in standard WGSL (but, notably, not Naga yet—see <https://github.com/gfx-rs/wgpu/issues/4369>) this snippet would emit a uniformity error:
@@ -125,18 +193,6 @@ 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

benches/benches/root.rs

@@ -26,11 +26,8 @@ impl DeviceState {
         };
 
         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()
-                .unwrap_or(wgpu::Dx12Compiler::Fxc),
-            gles_minor_version: wgpu::Gles3MinorVersion::Automatic,
+            backends: wgpu::Backends::from_env().unwrap_or(base_backend),
+            ..wgpu::InstanceDescriptor::from_env()
         });
 
         let adapter = block_on(wgpu::util::initialize_adapter_from_env_or_default(

deno_webgpu/lib.rs

@@ -381,7 +381,7 @@ pub fn op_webgpu_request_adapter(
 
     let backends = std::env::var("DENO_WEBGPU_BACKEND").map_or_else(
         |_| wgpu_types::Backends::all(),
-        |s| wgpu_core::instance::parse_backends_from_comma_list(&s),
+        |s| wgpu_types::Backends::from_comma_list(&s),
     );
     let instance = if let Some(instance) = state.try_borrow::<Instance>() {
         instance
@@ -391,8 +391,14 @@ pub fn op_webgpu_request_adapter(
             &wgpu_types::InstanceDescriptor {
                 backends,
                 flags: wgpu_types::InstanceFlags::from_build_config(),
-                dx12_shader_compiler: wgpu_types::Dx12Compiler::Fxc,
-                gles_minor_version: wgpu_types::Gles3MinorVersion::default(),
+                backend_options: wgpu_types::BackendOptions {
+                    dx12: wgpu_types::Dx12BackendOptions {
+                        shader_compiler: wgpu_types::Dx12Compiler::Fxc,
+                    },
+                    gl: wgpu_types::GlBackendOptions {
+                        gles_minor_version: wgpu_types::Gles3MinorVersion::default(),
+                    },
+                },
             },
         )));
         state.borrow::<Instance>()

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::InstanceDescriptor::from_env());
         surface.pre_adapter(&instance, window);
 
         let adapter = get_adapter_with_capabilities_or_from_env(

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::InstanceDescriptor::from_env());
 
     let surface = instance.create_surface(&window).unwrap();
     let adapter = instance

examples/src/timestamp_queries/mod.rs

@@ -180,13 +180,7 @@ impl Queries {
 #[cfg_attr(test, allow(unused))]
 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 {
-        backends,
-        flags: wgpu::InstanceFlags::from_build_config().with_env(),
-        dx12_shader_compiler: wgpu::Dx12Compiler::default(),
-        gles_minor_version: wgpu::Gles3MinorVersion::default(),
-    });
+    let instance = wgpu::Instance::new(&wgpu::InstanceDescriptor::from_env());
 
     // `request_adapter` instantiates the general connection to the GPU
     let adapter = instance

player/tests/test.rs

@@ -199,15 +199,7 @@ impl Corpus {
             for test_path in &corpus.tests {
                 println!("\t\tTest '{test_path:?}'");
 
-                let global = wgc::global::Global::new(
-                    "test",
-                    &wgt::InstanceDescriptor {
-                        backends: backend.into(),
-                        flags: wgt::InstanceFlags::debugging(),
-                        dx12_shader_compiler: wgt::Dx12Compiler::Fxc,
-                        gles_minor_version: wgt::Gles3MinorVersion::default(),
-                    },
-                );
+                let global = wgc::global::Global::new("test", &wgt::InstanceDescriptor::from_env());
                 let adapter = match global.request_adapter(
                     &wgc::instance::RequestAdapterOptions {
                         power_preference: wgt::PowerPreference::None,

tests/src/init.rs

@@ -34,14 +34,18 @@ pub fn initialize_instance(backends: wgpu::Backends, force_fxc: bool) -> Instanc
     let dx12_shader_compiler = if force_fxc {
         wgpu::Dx12Compiler::Fxc
     } else {
-        wgpu::util::dx12_shader_compiler_from_env().unwrap_or(wgpu::Dx12Compiler::StaticDxc)
+        wgpu::Dx12Compiler::from_env().unwrap_or(wgpu::Dx12Compiler::StaticDxc)
     };
-    let gles_minor_version = wgpu::util::gles_minor_version_from_env().unwrap_or_default();
+    let gles_minor_version = wgpu::Gles3MinorVersion::from_env().unwrap_or_default();
     Instance::new(&wgpu::InstanceDescriptor {
         backends,
         flags: wgpu::InstanceFlags::debugging().with_env(),
-        dx12_shader_compiler,
-        gles_minor_version,
+        backend_options: wgpu::BackendOptions {
+            dx12: wgpu::Dx12BackendOptions {
+                shader_compiler: dx12_shader_compiler,
+            },
+            gl: wgpu::GlBackendOptions { gles_minor_version },
+        },
     })
 }
 

tests/src/native.rs

@@ -90,7 +90,7 @@ pub fn main() -> MainResult {
         GpuReport::from_json(config_text).context("Could not parse .gpuconfig JSON")?;
 
     // Filter out the adapters that are not part of WGPU_BACKEND.
-    let wgpu_backends = wgpu::util::backend_bits_from_env().unwrap_or(wgpu::Backends::all());
+    let wgpu_backends = wgpu::Backends::from_env().unwrap_or_default();
     report
         .devices
         .retain(|report| wgpu_backends.contains(wgpu::Backends::from(report.info.backend)));

wgpu-core/src/instance.rs

@@ -73,8 +73,12 @@ impl Instance {
                 let hal_desc = hal::InstanceDescriptor {
                     name: "wgpu",
                     flags: instance_desc.flags,
-                    dx12_shader_compiler: instance_desc.dx12_shader_compiler.clone(),
-                    gles_minor_version: instance_desc.gles_minor_version,
+                    dx12_shader_compiler: instance_desc
+                        .backend_options
+                        .dx12
+                        .shader_compiler
+                        .clone(),
+                    gles_minor_version: instance_desc.backend_options.gl.gles_minor_version,
                 };
 
                 use hal::Instance as _;
@@ -969,38 +973,3 @@ impl Global {
         Ok((device_id, queue_id))
     }
 }
-
-/// Generates a set of backends from a comma separated list of case-insensitive backend names.
-///
-/// Whitespace is stripped, so both 'gl, dx12' and 'gl,dx12' are valid.
-///
-/// Always returns WEBGPU on wasm over webgpu.
-///
-/// Names:
-/// - vulkan = "vulkan" or "vk"
-/// - dx12   = "dx12" or "d3d12"
-/// - metal  = "metal" or "mtl"
-/// - gles   = "opengl" or "gles" or "gl"
-/// - webgpu = "webgpu"
-pub fn parse_backends_from_comma_list(string: &str) -> Backends {
-    let mut backends = Backends::empty();
-    for backend in string.to_lowercase().split(',') {
-        backends |= match backend.trim() {
-            "vulkan" | "vk" => Backends::VULKAN,
-            "dx12" | "d3d12" => Backends::DX12,
-            "metal" | "mtl" => Backends::METAL,
-            "opengl" | "gles" | "gl" => Backends::GL,
-            "webgpu" => Backends::BROWSER_WEBGPU,
-            b => {
-                log::warn!("unknown backend string '{}'", b);
-                continue;
-            }
-        }
-    }
-
-    if backends.is_empty() {
-        log::warn!("no valid backend strings found!");
-    }
-
-    backends
-}

wgpu-info/src/report.rs

@@ -17,12 +17,10 @@ pub struct GpuReport {
 
 impl GpuReport {
     pub fn generate() -> Self {
-        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()
-                .unwrap_or(wgpu::Dx12Compiler::StaticDxc),
-            gles_minor_version: wgpu::util::gles_minor_version_from_env().unwrap_or_default(),
+        let instance = wgpu::Instance::new(&{
+            let mut desc = wgpu::InstanceDescriptor::from_env();
+            desc.flags = wgpu::InstanceFlags::debugging().with_env();
+            desc
         });
         let adapters = instance.enumerate_adapters(wgpu::Backends::all());
 

wgpu-types/Cargo.toml

@@ -39,6 +39,7 @@ unexpected_cfgs = { level = "warn", check-cfg = ['cfg(web_sys_unstable_apis)'] }
 
 [dependencies]
 bitflags = { workspace = true, features = ["serde"] }
+log.workspace = true
 serde = { workspace = true, features = ["derive"], optional = true }
 
 [target.'cfg(target_arch = "wasm32")'.dependencies]