Make request_adapter() report which backends were tried.

This will help users determine whether the problem is:

* a backend is not statically enabled
* a backend is not dynamically enabled
* no drivers or physical adapters are present for that backend
  (further distinction would be useful here)
* no adapters met the required criteria

There are deficiencies in the reporting of WebGPU vs. WebGL support.
Those would best be fixed by also fixing the mutual exclusion of those
backends.

Author: kpreid

CHANGELOG.md

@@ -198,6 +198,7 @@ By @wumpf in [#7144](https://github.com/gfx-rs/wgpu/pull/7144)
 
 #### General
 
+- `wgpu::Instance::request_adapter()` now returns `Result` instead of `Option`; the error provides information about why no suitable adapter was returned. By @kpreid in [#7330](https://github.com/gfx-rs/wgpu/pull/7330).
 - Support BLAS compaction in wgpu-hal. By @Vecvec in [#7101](https://github.com/gfx-rs/wgpu/pull/7101).
 - Avoid using default features in many dependencies, etc. By Brody in [#7031](https://github.com/gfx-rs/wgpu/pull/7031)
 - Use `hashbrown` to simplify no-std support. By Brody in [#6938](https://github.com/gfx-rs/wgpu/pull/6938) & [#6925](https://github.com/gfx-rs/wgpu/pull/6925).

examples/standalone/03_custom_backend/src/custom.rs

@@ -43,7 +43,7 @@ impl InstanceInterface for CustomInstance {
         &self,
         _options: &wgpu::RequestAdapterOptions<'_, '_>,
     ) -> std::pin::Pin<Box<dyn RequestAdapterFuture>> {
-        Box::pin(std::future::ready(Some(DispatchAdapter::custom(
+        Box::pin(std::future::ready(Ok(DispatchAdapter::custom(
             CustomAdapter(self.0.clone()),
         ))))
     }

tests/validation-tests/api/instance.rs

@@ -0,0 +1,80 @@
+mod request_adapter_error {
+    fn id(backends: wgpu::Backends) -> wgpu::InstanceDescriptor {
+        wgpu::InstanceDescriptor {
+            backends,
+            flags: wgpu::InstanceFlags::default(),
+            backend_options: wgpu::BackendOptions::default(),
+        }
+    }
+
+    fn adapter_error(desc: &wgpu::InstanceDescriptor) -> String {
+        let instance = wgpu::Instance::new(desc);
+        pollster::block_on(instance.request_adapter(&wgpu::RequestAdapterOptions {
+            power_preference: wgpu::PowerPreference::default(),
+            force_fallback_adapter: false,
+            compatible_surface: None,
+        }))
+        .unwrap_err()
+        .to_string()
+    }
+
+    #[test]
+    fn no_backends_requested() {
+        assert_eq!(
+            adapter_error(&id(wgpu::Backends::empty())),
+            "No suitable graphics adapter found; \
+            noop not requested, \
+            vulkan not requested, \
+            metal not requested, \
+            dx12 not requested, \
+            gl not requested, \
+            webgpu not requested"
+        );
+    }
+
+    /// This test nominally tests the noop backend, but it also exercises the logic for other backends
+    /// that fail to return any adapter.
+    #[test]
+    fn noop_not_enabled() {
+        assert_eq!(
+            adapter_error(&id(wgpu::Backends::NOOP)),
+            "No suitable graphics adapter found; \
+            noop not explicitly enabled, \
+            vulkan not requested, \
+            metal not requested, \
+            dx12 not requested, \
+            gl not requested, \
+            webgpu not requested"
+        );
+    }
+
+    #[test]
+    fn no_compiled_support() {
+        // Whichever platform we are on, try asking for a backend that definitely will be
+        // cfged out regardless of feature flags. (Not that these tests run on wasm at all yet.)
+
+        #[cfg(target_family = "wasm")]
+        assert_eq!(
+            adapter_error(&id(wgpu::Backends::METAL)),
+            "No suitable graphics adapter found; \
+            noop not requested, \
+            vulkan not requested, \
+            metal support not compiled in, \
+            dx12 not requested, \
+            gl not requested, \
+            webgpu not requested"
+        );
+
+        #[cfg(not(target_family = "wasm"))]
+        assert_eq!(
+            adapter_error(&id(wgpu::Backends::BROWSER_WEBGPU)),
+            "No suitable graphics adapter found; \
+            noop not requested, \
+            vulkan not requested, \
+            metal not requested, \
+            dx12 not requested, \
+            gl not requested, \
+            webgpu support not compiled in"
+        );
+    }
+}

tests/validation-tests/api/mod.rs

@@ -1,4 +1,5 @@
 mod binding_arrays;
 mod buffer;
 mod buffer_slice;
+mod instance;
 mod texture;

tests/validation-tests/noop.rs

@@ -10,11 +10,8 @@ fn device_is_not_available_by_default() {
         ..Default::default()
     });
 
-    assert_eq!(
-        pollster::block_on(instance.request_adapter(&wgpu::RequestAdapterOptions::default())),
-        None,
-        "noop backend adapter present when it should not be"
-    );
+    pollster::block_on(instance.request_adapter(&wgpu::RequestAdapterOptions::default()))
+        .expect_err("noop backend adapter present when it should not be");
 }
 
 #[test]

wgpu-core/src/global.rs

@@ -1,5 +1,5 @@
-use alloc::{borrow::ToOwned as _, boxed::Box, sync::Arc};
-use core::{fmt, iter};
+use alloc::{borrow::ToOwned as _, sync::Arc};
+use core::fmt;
 
 use crate::{
     hal_api::HalApi,
@@ -47,13 +47,8 @@ impl Global {
     pub unsafe fn from_hal_instance<A: HalApi>(name: &str, hal_instance: A::Instance) -> Self {
         profiling::scope!("Global::new");
 
-        let dyn_instance: Box<dyn hal::DynInstance> = Box::new(hal_instance);
         Self {
-            instance: Instance {
-                name: name.to_owned(),
-                instance_per_backend: iter::once((A::VARIANT, dyn_instance)).collect(),
-                ..Default::default()
-            },
+            instance: Instance::from_hal_instance::<A>(name.to_owned(), hal_instance),
             surfaces: Registry::new(),
             hub: Hub::new(),
         }