Breaking: Change type of create_surface() functions to expose canvas errors.

Part of fixing #3017.

Author: kpreid

CHANGELOG.md

@@ -40,6 +40,10 @@ Bottom level categories:
 
 ## Unreleased
 
+### Major changes
+
+- `Instance::create_surface()` now returns `Result<Surface, CreateSurfaceError>` instead of `Surface`. This allows an error to be returned instead of panicking if the given window is a HTML canvas and obtaining a WebGPU or WebGL 2 context fails. (No other platforms currently report any errors through this path.) By @kpreid in [#3052](https://github.com/gfx-rs/wgpu/pull/3052/)
+
 ### Changes
 
 #### General

wgpu-core/src/instance.rs

@@ -529,45 +529,53 @@ impl<G: GlobalIdentityHandlerFactory> Global<G> {
         &self,
         canvas: &web_sys::HtmlCanvasElement,
         id_in: Input<G, SurfaceId>,
-    ) -> SurfaceId {
+    ) -> Result<SurfaceId, hal::InstanceError> {
         profiling::scope!("Instance::create_surface_webgl_canvas");
 
         let surface = Surface {
             presentation: None,
-            gl: self.instance.gl.as_ref().map(|inst| HalSurface {
-                raw: {
-                    inst.create_surface_from_canvas(canvas)
-                        .expect("Create surface from canvas")
-                },
-            }),
+            gl: self
+                .instance
+                .gl
+                .as_ref()
+                .map(|inst| {
+                    Ok(HalSurface {
+                        raw: inst.create_surface_from_canvas(canvas)?,
+                    })
+                })
+                .transpose()?,
         };
 
         let mut token = Token::root();
         let id = self.surfaces.prepare(id_in).assign(surface, &mut token);
-        id.0
+        Ok(id.0)
     }
 
     #[cfg(all(target_arch = "wasm32", not(target_os = "emscripten")))]
     pub fn create_surface_webgl_offscreen_canvas(
         &self,
         canvas: &web_sys::OffscreenCanvas,
         id_in: Input<G, SurfaceId>,
-    ) -> SurfaceId {
+    ) -> Result<SurfaceId, hal::InstanceError> {
         profiling::scope!("Instance::create_surface_webgl_offscreen_canvas");
 
         let surface = Surface {
             presentation: None,
-            gl: self.instance.gl.as_ref().map(|inst| HalSurface {
-                raw: {
-                    inst.create_surface_from_offscreen_canvas(canvas)
-                        .expect("Create surface from offscreen canvas")
-                },
-            }),
+            gl: self
+                .instance
+                .gl
+                .as_ref()
+                .map(|inst| {
+                    Ok(HalSurface {
+                        raw: inst.create_surface_from_offscreen_canvas(canvas)?,
+                    })
+                })
+                .transpose()?,
         };
 
         let mut token = Token::root();
         let id = self.surfaces.prepare(id_in).assign(surface, &mut token);
-        id.0
+        Ok(id.0)
     }
 
     #[cfg(dx12)]

wgpu/Cargo.toml

@@ -100,7 +100,7 @@ optional = true
 [dependencies.wgt]
 workspace = true
 
-[target.'cfg(any(not(target_arch = "wasm32"), target_os = "emscripten"))'.dependencies.hal]
+[dependencies.hal]
 workspace = true
 
 [dependencies]

wgpu/examples/framework.rs

@@ -164,7 +164,7 @@ async fn setup<E: Example>(title: &str) -> Setup {
         let size = window.inner_size();
 
         #[cfg(not(target_arch = "wasm32"))]
-        let surface = instance.create_surface(&window);
+        let surface = instance.create_surface(&window).unwrap();
         #[cfg(target_arch = "wasm32")]
         let surface = {
             if let Some(offscreen_canvas_setup) = &offscreen_canvas_setup {
@@ -174,7 +174,8 @@ async fn setup<E: Example>(title: &str) -> Setup {
             } else {
                 instance.create_surface(&window)
             }
-        };
+        }
+        .unwrap();
 
         (size, surface)
     };

wgpu/examples/hello-triangle/main.rs

@@ -8,7 +8,7 @@ use winit::{
 async fn run(event_loop: EventLoop<()>, window: Window) {
     let size = window.inner_size();
     let instance = wgpu::Instance::new(wgpu::Backends::all());
-    let surface = unsafe { instance.create_surface(&window) };
+    let surface = unsafe { instance.create_surface(&window) }.unwrap();
     let adapter = instance
         .request_adapter(&wgpu::RequestAdapterOptions {
             power_preference: wgpu::PowerPreference::default(),

wgpu/examples/hello-windows/main.rs

@@ -20,7 +20,7 @@ struct Viewport {
 
 impl ViewportDesc {
     fn new(window: Window, background: wgpu::Color, instance: &wgpu::Instance) -> Self {
-        let surface = unsafe { instance.create_surface(&window) };
+        let surface = unsafe { instance.create_surface(&window) }.unwrap();
         Self {
             window,
             background,

wgpu/src/backend/direct.rs

@@ -220,24 +220,30 @@ impl Context {
     pub fn instance_create_surface_from_canvas(
         self: &Arc<Self>,
         canvas: &web_sys::HtmlCanvasElement,
-    ) -> Surface {
-        let id = self.0.create_surface_webgl_canvas(canvas, ());
-        Surface {
+    ) -> Result<Surface, crate::CreateSurfaceError> {
+        let id = self
+            .0
+            .create_surface_webgl_canvas(canvas, ())
+            .map_err(|hal::InstanceError| crate::CreateSurfaceError {})?;
+        Ok(Surface {
             id,
             configured_device: Mutex::default(),
-        }
+        })
     }
 
     #[cfg(all(target_arch = "wasm32", feature = "webgl", not(feature = "emscripten")))]
     pub fn instance_create_surface_from_offscreen_canvas(
         self: &Arc<Self>,
         canvas: &web_sys::OffscreenCanvas,
-    ) -> Surface {
-        let id = self.0.create_surface_webgl_offscreen_canvas(canvas, ());
-        Surface {
+    ) -> Result<Surface, crate::CreateSurfaceError> {
+        let id = self
+            .0
+            .create_surface_webgl_offscreen_canvas(canvas, ())
+            .map_err(|hal::InstanceError| crate::CreateSurfaceError {})?;
+        Ok(Surface {
             id,
             configured_device: Mutex::default(),
-        }
+        })
     }
 
     #[cfg(target_os = "windows")]
@@ -944,13 +950,13 @@ impl crate::Context for Context {
         &self,
         display_handle: raw_window_handle::RawDisplayHandle,
         window_handle: raw_window_handle::RawWindowHandle,
-    ) -> Self::SurfaceId {
-        Surface {
+    ) -> Result<Self::SurfaceId, crate::CreateSurfaceError> {
+        Ok(Surface {
             id: self
                 .0
                 .instance_create_surface(display_handle, window_handle, ()),
             configured_device: Mutex::new(None),
-        }
+        })
     }
 
     fn instance_request_adapter(

wgpu/src/backend/web.rs

@@ -1026,17 +1026,15 @@ impl Context {
     pub fn instance_create_surface_from_canvas(
         &self,
         canvas: &web_sys::HtmlCanvasElement,
-    ) -> <Self as crate::Context>::SurfaceId {
+    ) -> Result<<Self as crate::Context>::SurfaceId, crate::CreateSurfaceError> {
         self.create_surface_from_context(canvas.get_context("webgpu"))
-            .unwrap()
     }
 
     pub fn instance_create_surface_from_offscreen_canvas(
         &self,
         canvas: &web_sys::OffscreenCanvas,
-    ) -> <Self as crate::Context>::SurfaceId {
+    ) -> Result<<Self as crate::Context>::SurfaceId, crate::CreateSurfaceError> {
         self.create_surface_from_context(canvas.get_context("webgpu"))
-            .unwrap()
     }
 
     /// Common portion of public `instance_create_surface_from_*` functions.
@@ -1046,7 +1044,7 @@ impl Context {
     fn create_surface_from_context(
         &self,
         context_result: Result<Option<js_sys::Object>, wasm_bindgen::JsValue>,
-    ) -> Result<<Self as crate::Context>::SurfaceId, ()> {
+    ) -> Result<<Self as crate::Context>::SurfaceId, crate::CreateSurfaceError> {
         let context: js_sys::Object = match context_result {
             Ok(Some(context)) => context,
             Ok(None) => {
@@ -1056,7 +1054,7 @@ impl Context {
                 // “not supported” could include “insufficient GPU resources” or “the GPU process
                 // previously crashed”. So, we must return it as an `Err` since it could occur
                 // for circumstances outside the application author's control.
-                return Err(());
+                return Err(crate::CreateSurfaceError {});
             }
             Err(js_error) => {
                 // <https://html.spec.whatwg.org/multipage/canvas.html#dom-canvas-getcontext>
@@ -1171,7 +1169,7 @@ impl crate::Context for Context {
         &self,
         _display_handle: raw_window_handle::RawDisplayHandle,
         window_handle: raw_window_handle::RawWindowHandle,
-    ) -> Self::SurfaceId {
+    ) -> Result<Self::SurfaceId, crate::CreateSurfaceError> {
         let canvas_attribute = match window_handle {
             raw_window_handle::RawWindowHandle::Web(web_handle) => web_handle.id,
             _ => panic!("expected valid handle for canvas"),

wgpu/src/lib.rs

@@ -204,7 +204,7 @@ trait Context: Debug + Send + Sized + Sync {
         &self,
         display_handle: raw_window_handle::RawDisplayHandle,
         window_handle: raw_window_handle::RawWindowHandle,
-    ) -> Self::SurfaceId;
+    ) -> Result<Self::SurfaceId, crate::CreateSurfaceError>;
     fn instance_request_adapter(
         &self,
         options: &RequestAdapterOptions<'_>,
@@ -1826,23 +1826,34 @@ impl Instance {
     ///
     /// # Safety
     ///
-    /// - Raw Window Handle must be a valid object to create a surface upon and
-    ///   must remain valid for the lifetime of the returned surface.
-    /// - If not called on the main thread, metal backend will panic.
+    /// - `raw_window_handle` must be a valid object to create a surface upon.
+    /// - `raw_window_handle` must remain valid until after the returned [`Surface`] is
+    ///   dropped.
+    ///
+    /// # Errors
+    ///
+    /// - On WebGL 2: Will return an error if the browser does not support WebGL 2,
+    ///   or declines to provide GPU access (such as due to a resource shortage).
+    ///
+    /// # Panics
+    ///
+    /// - On macOS/Metal: will panic if not called on the main thread.
+    /// - On web: will panic if the `raw_window_handle` does not properly refer to a
+    ///   canvas element.
     pub unsafe fn create_surface<
         W: raw_window_handle::HasRawWindowHandle + raw_window_handle::HasRawDisplayHandle,
     >(
         &self,
         window: &W,
-    ) -> Surface {
-        Surface {
+    ) -> Result<Surface, CreateSurfaceError> {
+        Ok(Surface {
             context: Arc::clone(&self.context),
             id: Context::instance_create_surface(
                 &*self.context,
                 raw_window_handle::HasRawDisplayHandle::raw_display_handle(window),
                 raw_window_handle::HasRawWindowHandle::raw_window_handle(window),
-            ),
-        }
+            )?,
+        })
     }
 
     /// Creates a surface from `CoreAnimationLayer`.
@@ -1872,29 +1883,42 @@ impl Instance {
     ///
     /// The `canvas` argument must be a valid `<canvas>` element to
     /// create a surface upon.
+    ///
+    /// # Errors
+    ///
+    /// - On WebGL 2: Will return an error if the browser does not support WebGL 2,
+    ///   or declines to provide GPU access (such as due to a resource shortage).
     #[cfg(all(target_arch = "wasm32", not(feature = "emscripten")))]
-    pub fn create_surface_from_canvas(&self, canvas: &web_sys::HtmlCanvasElement) -> Surface {
-        Surface {
+    pub fn create_surface_from_canvas(
+        &self,
+        canvas: &web_sys::HtmlCanvasElement,
+    ) -> Result<Surface, CreateSurfaceError> {
+        Ok(Surface {
             context: Arc::clone(&self.context),
-            id: self.context.instance_create_surface_from_canvas(canvas),
-        }
+            id: self.context.instance_create_surface_from_canvas(canvas)?,
+        })
     }
 
     /// Creates a surface from a `web_sys::OffscreenCanvas`.
     ///
     /// The `canvas` argument must be a valid `OffscreenCanvas` object
     /// to create a surface upon.
+    ///
+    /// # Errors
+    ///
+    /// - On WebGL 2: Will return an error if the browser does not support WebGL 2,
+    ///   or declines to provide GPU access (such as due to a resource shortage).
     #[cfg(all(target_arch = "wasm32", not(feature = "emscripten")))]
     pub fn create_surface_from_offscreen_canvas(
         &self,
         canvas: &web_sys::OffscreenCanvas,
-    ) -> Surface {
-        Surface {
+    ) -> Result<Surface, CreateSurfaceError> {
+        Ok(Surface {
             context: Arc::clone(&self.context),
             id: self
                 .context
-                .instance_create_surface_from_offscreen_canvas(canvas),
-        }
+                .instance_create_surface_from_offscreen_canvas(canvas)?,
+        })
     }
 
     /// Polls all devices.
@@ -2363,6 +2387,22 @@ impl Display for RequestDeviceError {
 
 impl error::Error for RequestDeviceError {}
 
+/// [`Instance::create_surface()`] or a related function failed.
+#[derive(Clone, PartialEq, Eq, Debug)]
+#[non_exhaustive]
+pub struct CreateSurfaceError {
+    // TODO: Report diagnostic clues
+}
+static_assertions::assert_impl_all!(CreateSurfaceError: Send, Sync);
+
+impl Display for CreateSurfaceError {
+    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        write!(f, "Creating a surface failed")
+    }
+}
+
+impl error::Error for CreateSurfaceError {}
+
 /// Error occurred when trying to async map a buffer.
 #[derive(Clone, PartialEq, Eq, Debug)]
 pub struct BufferAsyncError;