Deploying to master from @ gfx-rs/wgpu@59f56e0 🚀

Author: Wumpf

doc/search-index.js

@@ -390,6 +390,11 @@
 <a href="#389" id="389">389</a>
 <a href="#390" id="390">390</a>
 <a href="#391" id="391">391</a>
+<a href="#392" id="392">392</a>
+<a href="#393" id="393">393</a>
+<a href="#394" id="394">394</a>
+<a href="#395" id="395">395</a>
+<a href="#396" id="396">396</a>
 </pre></div><pre class="rust"><code><span class="kw">use </span>parking_lot::Mutex;
 
 <span class="kw">use crate</span>::<span class="kw-2">*</span>;
@@ -485,10 +490,15 @@
     ///   during instantiation, and which [DX12 shader compiler][Dx12Compiler] wgpu will use.
     ///
     ///   [`Backends::BROWSER_WEBGPU`] takes a special role:
-    ///   If it is set and WebGPU support is detected, this instance will *only* be able to create
-    ///   WebGPU adapters. If you instead want to force use of WebGL, either
-    ///   disable the `webgpu` compile-time feature or don't add the [`Backends::BROWSER_WEBGPU`]
-    ///   flag to the the `instance_desc`'s `backends` field.
+    ///   If it is set and a [`navigator.gpu`](https://developer.mozilla.org/en-US/docs/Web/API/Navigator/gpu)
+    ///   object is present, this instance will *only* be able to create WebGPU adapters.
+    ///
+    ///   ⚠️ On some browsers this check is insufficient to determine whether WebGPU is supported,
+    ///   as the browser may define the `navigator.gpu` object, but be unable to create any WebGPU adapters.
+    ///   For targeting _both_ WebGPU &amp; WebGL is recommended to use [`crate::util::new_instance_with_webgpu_detection`].
+    ///
+    ///   If you instead want to force use of WebGL, either disable the `webgpu` compile-time feature
+    ///   or don't add the [`Backends::BROWSER_WEBGPU`] flag to the the `instance_desc`'s `backends` field.
     ///   If it is set and WebGPU support is *not* detected, the instance will use wgpu-core
     ///   to create adapters. Meaning that if the `webgl` feature is enabled, it is able to create
     ///   a WebGL adapter.

doc/src/wgpu/api/instance.rs.html

@@ -136,6 +136,64 @@
 <a href="#135" id="135">135</a>
 <a href="#136" id="136">136</a>
 <a href="#137" id="137">137</a>
+<a href="#138" id="138">138</a>
+<a href="#139" id="139">139</a>
+<a href="#140" id="140">140</a>
+<a href="#141" id="141">141</a>
+<a href="#142" id="142">142</a>
+<a href="#143" id="143">143</a>
+<a href="#144" id="144">144</a>
+<a href="#145" id="145">145</a>
+<a href="#146" id="146">146</a>
+<a href="#147" id="147">147</a>
+<a href="#148" id="148">148</a>
+<a href="#149" id="149">149</a>
+<a href="#150" id="150">150</a>
+<a href="#151" id="151">151</a>
+<a href="#152" id="152">152</a>
+<a href="#153" id="153">153</a>
+<a href="#154" id="154">154</a>
+<a href="#155" id="155">155</a>
+<a href="#156" id="156">156</a>
+<a href="#157" id="157">157</a>
+<a href="#158" id="158">158</a>
+<a href="#159" id="159">159</a>
+<a href="#160" id="160">160</a>
+<a href="#161" id="161">161</a>
+<a href="#162" id="162">162</a>
+<a href="#163" id="163">163</a>
+<a href="#164" id="164">164</a>
+<a href="#165" id="165">165</a>
+<a href="#166" id="166">166</a>
+<a href="#167" id="167">167</a>
+<a href="#168" id="168">168</a>
+<a href="#169" id="169">169</a>
+<a href="#170" id="170">170</a>
+<a href="#171" id="171">171</a>
+<a href="#172" id="172">172</a>
+<a href="#173" id="173">173</a>
+<a href="#174" id="174">174</a>
+<a href="#175" id="175">175</a>
+<a href="#176" id="176">176</a>
+<a href="#177" id="177">177</a>
+<a href="#178" id="178">178</a>
+<a href="#179" id="179">179</a>
+<a href="#180" id="180">180</a>
+<a href="#181" id="181">181</a>
+<a href="#182" id="182">182</a>
+<a href="#183" id="183">183</a>
+<a href="#184" id="184">184</a>
+<a href="#185" id="185">185</a>
+<a href="#186" id="186">186</a>
+<a href="#187" id="187">187</a>
+<a href="#188" id="188">188</a>
+<a href="#189" id="189">189</a>
+<a href="#190" id="190">190</a>
+<a href="#191" id="191">191</a>
+<a href="#192" id="192">192</a>
+<a href="#193" id="193">193</a>
+<a href="#194" id="194">194</a>
+<a href="#195" id="195">195</a>
 </pre></div><pre class="rust"><code><span class="kw">use </span>wgt::{Backends, PowerPreference, RequestAdapterOptions};
 
 <span class="kw">use crate</span>::{Adapter, Instance, Surface};
@@ -273,4 +331,62 @@
         },
     )
 }
+
+<span class="doccomment">/// Determines whether the [`Backends::BROWSER_WEBGPU`] backend is supported.
+///
+/// The result can only be true if this is called from the main thread or a dedicated worker.
+/// For convenience, this is also supported on non-wasm targets, always returning false there.
+</span><span class="kw">pub async fn </span>is_browser_webgpu_supported() -&gt; bool {
+    <span class="attr">#[cfg(webgpu)]
+    </span>{
+        <span class="comment">// In theory it should be enough to check for the presence of the `gpu` property...
+        </span><span class="kw">let </span>gpu = <span class="kw">crate</span>::backend::get_browser_gpu_property();
+        <span class="kw">let </span><span class="prelude-val">Ok</span>(<span class="prelude-val">Some</span>(gpu)) = gpu <span class="kw">else </span>{
+            <span class="kw">return </span><span class="bool-val">false</span>;
+        };
+
+        <span class="comment">// ...but in practice, we also have to try to create an adapter, since as of writing
+        // Chrome on Linux has the `gpu` property but doesn't support WebGPU.
+        </span><span class="kw">let </span>adapter_promise = gpu.request_adapter();
+        wasm_bindgen_futures::JsFuture::from(adapter_promise)
+            .<span class="kw">await
+            </span>.map_or(<span class="bool-val">false</span>, |adapter| {
+                !adapter.is_undefined() &amp;&amp; !adapter.is_null()
+            })
+    }
+    <span class="attr">#[cfg(not(webgpu))]
+    </span>{
+        <span class="bool-val">false
+    </span>}
+}
+
+<span class="doccomment">/// Create an new instance of wgpu, but disabling [`Backends::BROWSER_WEBGPU`] if no WebGPU support was detected.
+///
+/// If the instance descriptor enables [`Backends::BROWSER_WEBGPU`],
+/// this checks via [`is_browser_webgpu_supported`] for WebGPU support before forwarding
+/// the descriptor with or without [`Backends::BROWSER_WEBGPU`] respecitively to [`Instance::new`].
+///
+/// You should prefer this method over [`Instance::new`] if you want to target WebGPU and automatically
+/// fall back to WebGL if WebGPU is not available.
+/// This is because WebGPU support has to be decided upon instance creation and [`Instance::new`]
+/// (being a `sync` function) can't establish WebGPU support (details see [`is_browser_webgpu_supported`]).
+///
+/// # Panics
+///
+/// If no backend feature for the active target platform is enabled,
+/// this method will panic, see [`Instance::enabled_backend_features()`].
+</span><span class="attr">#[allow(unused_mut)]
+</span><span class="kw">pub async fn </span>new_instance_with_webgpu_detection(
+    <span class="kw-2">mut </span>instance_desc: wgt::InstanceDescriptor,
+) -&gt; <span class="kw">crate</span>::Instance {
+    <span class="kw">if </span>instance_desc
+        .backends
+        .contains(wgt::Backends::BROWSER_WEBGPU)
+        &amp;&amp; !is_browser_webgpu_supported().<span class="kw">await
+    </span>{
+        instance_desc.backends.remove(wgt::Backends::BROWSER_WEBGPU);
+    }
+
+    <span class="kw">crate</span>::Instance::new(instance_desc)
+}
 </code></pre></div></section></main></body></html>