wgpu/util/
init.rs

1use crate::{Adapter, Instance, RequestAdapterOptions, Surface};
2
3#[cfg(doc)]
4use crate::Backends;
5
6/// Initialize the adapter obeying the `WGPU_ADAPTER_NAME` environment variable.
7#[cfg(wgpu_core)]
8#[cfg_attr(not(std), expect(unused_variables, unreachable_code))]
9pub fn initialize_adapter_from_env(
10    instance: &Instance,
11    compatible_surface: Option<&Surface<'_>>,
12) -> Result<Adapter, wgt::RequestAdapterError> {
13    let desired_adapter_name: alloc::string::String = {
14        cfg_if::cfg_if! {
15            if #[cfg(std)] {
16                std::env::var("WGPU_ADAPTER_NAME")
17                    .as_deref()
18                    .map(str::to_lowercase)
19                    .map_err(|_| wgt::RequestAdapterError::EnvNotSet)?
20            } else {
21                return Err(wgt::RequestAdapterError::EnvNotSet)
22            }
23        }
24    };
25
26    let adapters = instance.enumerate_adapters(crate::Backends::all());
27
28    let mut chosen_adapter = None;
29    for adapter in adapters {
30        let info = adapter.get_info();
31
32        if let Some(surface) = compatible_surface {
33            if !adapter.is_surface_supported(surface) {
34                continue;
35            }
36        }
37
38        if info.name.to_lowercase().contains(&desired_adapter_name) {
39            chosen_adapter = Some(adapter);
40            break;
41        }
42    }
43
44    Ok(chosen_adapter.expect("WGPU_ADAPTER_NAME set but no matching adapter found!"))
45}
46
47/// Initialize the adapter obeying the `WGPU_ADAPTER_NAME` environment variable.
48#[cfg(not(wgpu_core))]
49pub fn initialize_adapter_from_env(
50    _instance: &Instance,
51    _compatible_surface: Option<&Surface<'_>>,
52) -> Result<Adapter, wgt::RequestAdapterError> {
53    Err(wgt::RequestAdapterError::EnvNotSet)
54}
55
56/// Initialize the adapter obeying the `WGPU_ADAPTER_NAME` environment variable and if it doesn't exist fall back on a default adapter.
57pub async fn initialize_adapter_from_env_or_default(
58    instance: &Instance,
59    compatible_surface: Option<&Surface<'_>>,
60) -> Result<Adapter, wgt::RequestAdapterError> {
61    match initialize_adapter_from_env(instance, compatible_surface) {
62        Ok(a) => Ok(a),
63        Err(_) => {
64            instance
65                .request_adapter(&RequestAdapterOptions {
66                    power_preference: crate::PowerPreference::from_env().unwrap_or_default(),
67                    force_fallback_adapter: false,
68                    compatible_surface,
69                })
70                .await
71        }
72    }
73}
74
75/// Determines whether the [`Backends::BROWSER_WEBGPU`] backend is supported.
76///
77/// The result can only be true if this is called from the main thread or a dedicated worker.
78/// For convenience, this is also supported on non-wasm targets, always returning false there.
79pub async fn is_browser_webgpu_supported() -> bool {
80    #[cfg(webgpu)]
81    {
82        // In theory it should be enough to check for the presence of the `gpu` property...
83        let gpu = crate::backend::get_browser_gpu_property();
84        let Ok(Some(gpu)) = gpu else {
85            return false;
86        };
87
88        // ...but in practice, we also have to try to create an adapter, since as of writing
89        // Chrome on Linux has the `gpu` property but doesn't support WebGPU.
90        let adapter_promise = gpu.request_adapter();
91        wasm_bindgen_futures::JsFuture::from(adapter_promise)
92            .await
93            .is_ok_and(|adapter| !adapter.is_undefined() && !adapter.is_null())
94    }
95    #[cfg(not(webgpu))]
96    {
97        false
98    }
99}
100
101/// Create an new instance of wgpu, but disabling [`Backends::BROWSER_WEBGPU`] if no WebGPU support was detected.
102///
103/// If the instance descriptor enables [`Backends::BROWSER_WEBGPU`],
104/// this checks via [`is_browser_webgpu_supported`] for WebGPU support before forwarding
105/// the descriptor with or without [`Backends::BROWSER_WEBGPU`] respecitively to [`Instance::new`].
106///
107/// You should prefer this method over [`Instance::new`] if you want to target WebGPU and automatically
108/// fall back to WebGL if WebGPU is not available.
109/// This is because WebGPU support has to be decided upon instance creation and [`Instance::new`]
110/// (being a `sync` function) can't establish WebGPU support (details see [`is_browser_webgpu_supported`]).
111///
112/// # Panics
113///
114/// If no backend feature for the active target platform is enabled,
115/// this method will panic, see [`Instance::enabled_backend_features()`].
116pub async fn new_instance_with_webgpu_detection(
117    instance_desc: &wgt::InstanceDescriptor,
118) -> crate::Instance {
119    let mut instance_desc = instance_desc.clone();
120    if instance_desc
121        .backends
122        .contains(wgt::Backends::BROWSER_WEBGPU)
123        && !is_browser_webgpu_supported().await
124    {
125        instance_desc.backends.remove(wgt::Backends::BROWSER_WEBGPU);
126    }
127
128    crate::Instance::new(&instance_desc)
129}
wgpu/util/init.rs

wgpu/util/
init.rs
