Deploying to master from @ gfx-rs/wgpu@fbe005f 🚀

Author: nical

doc/search-index.js

@@ -401,7 +401,8 @@
 <a href="#400" id="400">400</a>
 <a href="#401" id="401">401</a>
 <a href="#402" id="402">402</a>
-<a href="#403" id="403">403</a></pre></div><pre class="rust"><code><span class="attr">#[cfg(native)]
+<a href="#403" id="403">403</a>
+<a href="#404" id="404">404</a></pre></div><pre class="rust"><code><span class="attr">#[cfg(native)]
 </span><span class="kw">use </span>alloc::vec::Vec;
 <span class="kw">use </span>core::future::Future;
 
@@ -639,13 +640,14 @@
     ///
     /// Some options are "soft", so treated as non-mandatory. Others are "hard".
     ///
-    /// If no adapters are found that suffice all the "hard" options, `None` is returned.
+    /// If no adapters are found that satisfy all the "hard" options, an error is returned.
     ///
-    /// A `compatible_surface` is required when targeting WebGL2.
+    /// When targeting WebGL2, a [`compatible_surface`](RequestAdapterOptions::compatible_surface)
+    /// must be specified; using `RequestAdapterOptions::default()` will not succeed.
     </span><span class="kw">pub fn </span>request_adapter(
         <span class="kw-2">&amp;</span><span class="self">self</span>,
         options: <span class="kw-2">&amp;</span>RequestAdapterOptions&lt;<span class="lifetime">'_</span>, <span class="lifetime">'_</span>&gt;,
-    ) -&gt; <span class="kw">impl </span>Future&lt;Output = <span class="prelude-ty">Option</span>&lt;Adapter&gt;&gt; + WasmNotSend {
+    ) -&gt; <span class="kw">impl </span>Future&lt;Output = <span class="prelude-ty">Result</span>&lt;Adapter, RequestAdapterError&gt;&gt; + WasmNotSend {
         <span class="kw">let </span>future = <span class="self">self</span>.inner.request_adapter(options);
         <span class="kw">async move </span>{ future.<span class="kw">await</span>.map(|adapter| Adapter { inner: adapter }) }
     }

doc/search.desc/wgpu/wgpu-desc-0-.js

@@ -4474,7 +4474,7 @@
             <span class="kw">let </span>generic: dispatch::DispatchAdapter = core.into();
             generic
         });
-        Box::pin(ready(adapter.ok()))
+        Box::pin(ready(adapter))
     }
 
     <span class="kw">fn </span>poll_all_devices(<span class="kw-2">&amp;</span><span class="self">self</span>, force_wait: bool) -&gt; bool {

doc/search.desc/wgpu/wgpu-desc-1-.js

@@ -852,7 +852,7 @@
 }
 
 <span class="comment">// Various return futures in the API.
-</span><span class="macro">trait_alias!</span>(RequestAdapterFuture: Future&lt;Output = <span class="prelude-ty">Option</span>&lt;DispatchAdapter&gt;&gt; + WasmNotSend + <span class="lifetime">'static</span>);
+</span><span class="macro">trait_alias!</span>(RequestAdapterFuture: Future&lt;Output = <span class="prelude-ty">Result</span>&lt;DispatchAdapter, wgt::RequestAdapterError&gt;&gt; + WasmNotSend + <span class="lifetime">'static</span>);
 <span class="macro">trait_alias!</span>(RequestDeviceFuture: Future&lt;Output = <span class="prelude-ty">Result</span>&lt;(DispatchDevice, DispatchQueue), <span class="kw">crate</span>::RequestDeviceError&gt;&gt; + WasmNotSend + <span class="lifetime">'static</span>);
 <span class="macro">trait_alias!</span>(PopErrorScopeFuture: Future&lt;Output = <span class="prelude-ty">Option</span>&lt;<span class="kw">crate</span>::Error&gt;&gt; + WasmNotSend + <span class="lifetime">'static</span>);
 <span class="macro">trait_alias!</span>(ShaderCompilationInfoFuture: Future&lt;Output = <span class="kw">crate</span>::CompilationInfo&gt; + WasmNotSend + <span class="lifetime">'static</span>);

doc/search.desc/wgpu_core/wgpu_core-desc-0-.js

@@ -206,13 +206,13 @@
     InstanceFlags, InternalCounters, Limits, MemoryHints, MultisampleState, NoopBackendOptions,
     Origin2d, Origin3d, PipelineStatisticsTypes, PollError, PollStatus, PolygonMode,
     PowerPreference, PredefinedColorSpace, PresentMode, PresentationTimestamp, PrimitiveState,
-    PrimitiveTopology, PushConstantRange, QueryType, RenderBundleDepthStencil, SamplerBindingType,
-    SamplerBorderColor, ShaderLocation, ShaderModel, ShaderRuntimeChecks, ShaderStages,
-    StencilFaceState, StencilOperation, StencilState, StorageTextureAccess, SurfaceCapabilities,
-    SurfaceStatus, TexelCopyBufferLayout, TextureAspect, TextureDimension, TextureFormat,
-    TextureFormatFeatureFlags, TextureFormatFeatures, TextureSampleType, TextureTransition,
-    TextureUsages, TextureUses, TextureViewDimension, Trace, VertexAttribute, VertexFormat,
-    VertexStepMode, WasmNotSend, WasmNotSendSync, WasmNotSync, COPY_BUFFER_ALIGNMENT,
+    PrimitiveTopology, PushConstantRange, QueryType, RenderBundleDepthStencil, RequestAdapterError,
+    SamplerBindingType, SamplerBorderColor, ShaderLocation, ShaderModel, ShaderRuntimeChecks,
+    ShaderStages, StencilFaceState, StencilOperation, StencilState, StorageTextureAccess,
+    SurfaceCapabilities, SurfaceStatus, TexelCopyBufferLayout, TextureAspect, TextureDimension,
+    TextureFormat, TextureFormatFeatureFlags, TextureFormatFeatures, TextureSampleType,
+    TextureTransition, TextureUsages, TextureUses, TextureViewDimension, Trace, VertexAttribute,
+    VertexFormat, VertexStepMode, WasmNotSend, WasmNotSendSync, WasmNotSync, COPY_BUFFER_ALIGNMENT,
     COPY_BYTES_PER_ROW_ALIGNMENT, MAP_ALIGNMENT, PUSH_CONSTANT_ALIGNMENT,
     QUERY_RESOLVE_BUFFER_ALIGNMENT, QUERY_SET_MAX_QUERIES, QUERY_SIZE, VERTEX_STRIDE_ALIGNMENT,
 };

doc/search.desc/wgpu_types/wgpu_types-desc-0-.js

@@ -128,11 +128,11 @@
 </span><span class="kw">pub fn </span>initialize_adapter_from_env(
     instance: <span class="kw-2">&amp;</span>Instance,
     compatible_surface: <span class="prelude-ty">Option</span>&lt;<span class="kw-2">&amp;</span>Surface&lt;<span class="lifetime">'_</span>&gt;&gt;,
-) -&gt; <span class="prelude-ty">Option</span>&lt;Adapter&gt; {
+) -&gt; <span class="prelude-ty">Result</span>&lt;Adapter, wgt::RequestAdapterError&gt; {
     <span class="kw">let </span>desired_adapter_name = std::env::var(<span class="string">"WGPU_ADAPTER_NAME"</span>)
         .as_deref()
         .map(str::to_lowercase)
-        .ok()<span class="question-mark">?</span>;
+        .map_err(|<span class="kw">_</span>| wgt::RequestAdapterError::EnvNotSet)<span class="question-mark">?</span>;
 
     <span class="kw">let </span>adapters = instance.enumerate_adapters(<span class="kw">crate</span>::Backends::all());
 
@@ -152,26 +152,26 @@
         }
     }
 
-    <span class="prelude-val">Some</span>(chosen_adapter.expect(<span class="string">"WGPU_ADAPTER_NAME set but no matching adapter found!"</span>))
+    <span class="prelude-val">Ok</span>(chosen_adapter.expect(<span class="string">"WGPU_ADAPTER_NAME set but no matching adapter found!"</span>))
 }
 
 <span class="doccomment">/// Initialize the adapter obeying the `WGPU_ADAPTER_NAME` environment variable.
 </span><span class="attr">#[cfg(not(native))]
 </span><span class="kw">pub fn </span>initialize_adapter_from_env(
     _instance: <span class="kw-2">&amp;</span>Instance,
     _compatible_surface: <span class="prelude-ty">Option</span>&lt;<span class="kw-2">&amp;</span>Surface&lt;<span class="lifetime">'_</span>&gt;&gt;,
-) -&gt; <span class="prelude-ty">Option</span>&lt;Adapter&gt; {
-    <span class="prelude-val">None
-</span>}
+) -&gt; <span class="prelude-ty">Result</span>&lt;Adapter, wgt::RequestAdapterError&gt; {
+    <span class="prelude-val">Err</span>(wgt::RequestAdapterError::EnvNotSet)
+}
 
 <span class="doccomment">/// Initialize the adapter obeying the `WGPU_ADAPTER_NAME` environment variable and if it doesn't exist fall back on a default adapter.
 </span><span class="kw">pub async fn </span>initialize_adapter_from_env_or_default(
     instance: <span class="kw-2">&amp;</span>Instance,
     compatible_surface: <span class="prelude-ty">Option</span>&lt;<span class="kw-2">&amp;</span>Surface&lt;<span class="lifetime">'_</span>&gt;&gt;,
-) -&gt; <span class="prelude-ty">Option</span>&lt;Adapter&gt; {
+) -&gt; <span class="prelude-ty">Result</span>&lt;Adapter, wgt::RequestAdapterError&gt; {
     <span class="kw">match </span>initialize_adapter_from_env(instance, compatible_surface) {
-        <span class="prelude-val">Some</span>(a) =&gt; <span class="prelude-val">Some</span>(a),
-        <span class="prelude-val">None </span>=&gt; {
+        <span class="prelude-val">Ok</span>(a) =&gt; <span class="prelude-val">Ok</span>(a),
+        <span class="prelude-val">Err</span>(<span class="kw">_</span>) =&gt; {
             instance
                 .request_adapter(<span class="kw-2">&amp;</span>RequestAdapterOptions {
                     power_preference: <span class="kw">crate</span>::PowerPreference::from_env().unwrap_or_default(),