Make HasDisplayHandle optional in WindowHandle (#8782)

MarijnS95 · web-flow · commit 35db26b2c687 · 2026-03-10T11:36:12.000-04:00
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -141,6 +141,7 @@ depth_stencil: Some(wgpu::DepthStencilState::stencil(
 - Added `TextureFormat::channels` method to get some information about which color channels are covered by the texture format. By @TornaxO7 in [#9167](https://github.com/gfx-rs/wgpu/pull/9167)
 - BREAKING: Add `V6_8` variant to `DxcShaderModel` and `naga::back::hlsl::ShaderModel`. By @inner-daemons in [#8882](https://github.com/gfx-rs/wgpu/pull/8882) and @ErichDonGubler in [#9083](https://github.com/gfx-rs/wgpu/pull/9083).
 - BREAKING: Add `V6_9` variant to `DxcShaderModel` and `naga::back::hlsl::ShaderModel`. By @ErichDonGubler in [#????](https://github.com/gfx-rs/wgpu/pull/????).
+- `DisplayHandle` is now optional in surface creation if it was passed to `InstanceDescriptor::display`. By @MarijnS95 in [#8782](https://github.com/gfx-rs/wgpu/pull/8782)
 
 #### naga
 
diff --git a/Cargo.lock b/Cargo.lock
diff --git a/benches/benches/wgpu-benchmark/main.rs b/benches/benches/wgpu-benchmark/main.rs
@@ -29,7 +29,7 @@ impl DeviceState {
 
         let instance = wgpu::Instance::new(wgpu::InstanceDescriptor {
             backends: wgpu::Backends::from_env().unwrap_or(base_backend),
-            ..wgpu::InstanceDescriptor::from_env_or_default()
+            ..wgpu::InstanceDescriptor::new_without_display_handle_from_env()
         });
 
         let adapter = block_on(wgpu::util::initialize_adapter_from_env_or_default(
diff --git a/deno_webgpu/byow.rs b/deno_webgpu/byow.rs
@@ -276,7 +276,7 @@ impl<'a> FromV8<'a> for UnsafeWindowSurfaceOptions {
 
 type RawHandles = (
   raw_window_handle::RawWindowHandle,
-  raw_window_handle::RawDisplayHandle,
+  Option<raw_window_handle::RawDisplayHandle>,
 );
 
 #[cfg(target_os = "macos")]
@@ -298,7 +298,7 @@ fn raw_window(
   let display_handle = raw_window_handle::RawDisplayHandle::AppKit(
     raw_window_handle::AppKitDisplayHandle::new(),
   );
-  Ok((win_handle, display_handle))
+  Ok((win_handle, Some(display_handle)))
 }
 
 #[cfg(target_os = "windows")]
@@ -324,7 +324,7 @@ fn raw_window(
 
   let display_handle =
     raw_window_handle::RawDisplayHandle::Windows(WindowsDisplayHandle::new());
-  Ok((win_handle, display_handle))
+  Ok((win_handle, Some(display_handle)))
 }
 
 #[cfg(any(
@@ -366,7 +366,7 @@ fn raw_window(
     return Err(ByowError::InvalidSystem);
   }
 
-  Ok((win_handle, display_handle))
+  Ok((win_handle, Some(display_handle)))
 }
 
 #[cfg(not(any(
diff --git a/examples/features/src/framework.rs b/examples/features/src/framework.rs
@@ -260,8 +260,8 @@ impl ExampleContext {
     async fn init_async<E: Example>(surface: &mut SurfaceWrapper, window: Arc<Window>) -> Self {
         log::info!("Initializing wgpu...");
 
-        let instance_descriptor = wgpu::InstanceDescriptor::from_env_or_default()
-            .with_display_handle(Box::new(
+        let instance_descriptor =
+            wgpu::InstanceDescriptor::new_with_display_handle_from_env(Box::new(
                 // TODO: Use event_loop.owned_display_handle() with winit 0.30
                 window.clone(),
             ));
diff --git a/examples/features/src/hello_triangle/mod.rs b/examples/features/src/hello_triangle/mod.rs
@@ -12,11 +12,10 @@ async fn run(event_loop: EventLoop<()>, window: Window) {
     size.width = size.width.max(1);
     size.height = size.height.max(1);
 
-    let instance = wgpu::Instance::new(
-        wgpu::InstanceDescriptor::from_env_or_default()
-            // TODO: Use event_loop.owned_display_handle() with winit 0.30
-            .with_display_handle(Box::new(window.clone())),
-    );
+    let instance = wgpu::Instance::new(wgpu::InstanceDescriptor::new_with_display_handle_from_env(
+        // TODO: Use event_loop.owned_display_handle() with winit 0.30
+        Box::new(window.clone()),
+    ));
 
     let surface = instance.create_surface(&window).unwrap();
     let adapter = instance
diff --git a/examples/features/src/timestamp_queries/mod.rs b/examples/features/src/timestamp_queries/mod.rs
@@ -193,7 +193,8 @@ impl Queries {
 
 async fn run() {
     // Instantiates instance of wgpu
-    let instance = wgpu::Instance::new(wgpu::InstanceDescriptor::from_env_or_default());
+    let instance =
+        wgpu::Instance::new(wgpu::InstanceDescriptor::new_without_display_handle_from_env());
 
     // `request_adapter` instantiates the general connection to the GPU
     let adapter = instance
diff --git a/examples/standalone/01_hello_compute/src/main.rs b/examples/standalone/01_hello_compute/src/main.rs
@@ -38,7 +38,7 @@ fn main() {
     // We first initialize an wgpu `Instance`, which contains any "global" state wgpu needs.
     //
     // This is what loads the vulkan/dx12/metal/opengl libraries.
-    let instance = wgpu::Instance::new(wgpu::InstanceDescriptor::default());
+    let instance = wgpu::Instance::new(wgpu::InstanceDescriptor::new_without_display_handle());
 
     // We then create an `Adapter` which represents a physical gpu in the system. It allows
     // us to query information about it and create a `Device` from it.
diff --git a/examples/standalone/02_hello_window/src/main.rs b/examples/standalone/02_hello_window/src/main.rs
@@ -18,9 +18,9 @@ struct State {
 
 impl State {
     async fn new(display: OwnedDisplayHandle, window: Arc<Window>) -> State {
-        let instance = wgpu::Instance::new(
-            wgpu::InstanceDescriptor::default().with_display_handle(Box::new(display)),
-        );
+        let instance = wgpu::Instance::new(wgpu::InstanceDescriptor::new_with_display_handle(
+            Box::new(display),
+        ));
         let adapter = instance
             .request_adapter(&wgpu::RequestAdapterOptions::default())
             .await
diff --git a/player/src/bin/play.rs b/player/src/bin/play.rs
@@ -17,7 +17,7 @@ fn main() {
     };
 
     #[cfg(feature = "winit")]
-    use raw_window_handle::{HasDisplayHandle, HasWindowHandle};
+    use raw_window_handle::HasWindowHandle;
     #[cfg(feature = "winit")]
     use winit::{
         event::KeyEvent,
@@ -71,21 +71,16 @@ fn main() {
             .unwrap(),
     );
 
-    let instance_desc = wgt::InstanceDescriptor::from_env_or_default();
+    let instance_desc = wgt::InstanceDescriptor::new_without_display_handle_from_env();
     #[cfg(feature = "winit")]
     // TODO: Use event_loop.owned_display_handle() with winit 0.30
     let instance_desc = instance_desc.with_display_handle(Box::new(window.clone()));
     let instance_flags = instance_desc.flags;
     let instance = wgc::instance::Instance::new("player", instance_desc, None);
 
     #[cfg(feature = "winit")]
-    let surface = unsafe {
-        instance.create_surface(
-            window.display_handle().unwrap().into(),
-            window.window_handle().unwrap().into(),
-        )
-    }
-    .unwrap();
+    let surface =
+        unsafe { instance.create_surface(None, window.window_handle().unwrap().into()) }.unwrap();
     #[cfg(feature = "winit")]
     let mut configured_surface_id = None;
 
diff --git a/player/tests/player/main.rs b/player/tests/player/main.rs
@@ -181,7 +181,7 @@ impl Corpus {
             for test_path in &corpus.tests {
                 println!("\t\tTest '{test_path:?}'");
 
-                let instance_desc = wgt::InstanceDescriptor::from_env_or_default();
+                let instance_desc = wgt::InstanceDescriptor::new_without_display_handle_from_env();
                 let instance_flags = instance_desc.flags;
                 let instance = wgc::instance::Instance::new("test", instance_desc, None);
                 let adapter = match instance.request_adapter(
diff --git a/tests/Cargo.toml b/tests/Cargo.toml
@@ -67,6 +67,7 @@ log.workspace = true
 png.workspace = true
 pollster.workspace = true
 profiling.workspace = true
+raw-window-handle.workspace = true
 serde.workspace = true
 serde_json.workspace = true
 
diff --git a/tests/src/init.rs b/tests/src/init.rs
@@ -76,7 +76,18 @@ pub fn initialize_instance(backends: wgpu::Backends, params: &TestParameters) ->
                 enable: !cfg!(target_arch = "wasm32"),
             },
         },
+        #[cfg(not(all(
+            target_arch = "wasm32",
+            any(target_os = "emscripten", feature = "webgl")
+        )))]
         display: None,
+        // Wasm requires a canvas surface below, and create_surface() requires
+        // the `display` to be set even if it's "empty" on Web:
+        #[cfg(all(
+            target_arch = "wasm32",
+            any(target_os = "emscripten", feature = "webgl")
+        ))]
+        display: Some(Box::new(WebDisplayHandle)),
     })
 }
 
@@ -214,3 +225,24 @@ impl SurfaceGuard {
             != web_sys::WebGl2RenderingContext::NO_ERROR
     }
 }
+
+/// [`raw_window_handle::HasDisplayHandle`] implementation for Web that's [`Send`]+[`Sync`]
+/// because it doesn't own any pointers
+#[cfg(all(
+    target_arch = "wasm32",
+    any(target_os = "emscripten", feature = "webgl")
+))]
+#[derive(Debug)]
+struct WebDisplayHandle;
+
+#[cfg(all(
+    target_arch = "wasm32",
+    any(target_os = "emscripten", feature = "webgl")
+))]
+impl raw_window_handle::HasDisplayHandle for WebDisplayHandle {
+    fn display_handle(
+        &self,
+    ) -> Result<raw_window_handle::DisplayHandle<'_>, raw_window_handle::HandleError> {
+        Ok(raw_window_handle::DisplayHandle::web())
+    }
+}
diff --git a/tests/tests/wgpu-validation/api/experimental.rs b/tests/tests/wgpu-validation/api/experimental.rs
@@ -5,7 +5,7 @@ fn noop_adapter() -> wgpu::Adapter {
             noop: wgpu::NoopBackendOptions { enable: true },
             ..Default::default()
         },
-        ..Default::default()
+        ..wgpu::InstanceDescriptor::new_without_display_handle()
     });
 
     pollster::block_on(instance.request_adapter(&wgpu::RequestAdapterOptions::default()))
diff --git a/tests/tests/wgpu-validation/api/instance.rs b/tests/tests/wgpu-validation/api/instance.rs
@@ -5,7 +5,7 @@ mod multi_instance {
         let adapter = {
             let instance = wgpu::Instance::new(wgpu::InstanceDescriptor {
                 backends: wgpu::Backends::from_env().unwrap_or_default(),
-                ..Default::default()
+                ..wgpu::InstanceDescriptor::new_without_display_handle()
             });
             instance
                 .request_adapter(&wgpu::RequestAdapterOptions::default())
diff --git a/tests/tests/wgpu-validation/noop.rs b/tests/tests/wgpu-validation/noop.rs
@@ -7,7 +7,7 @@ use std::sync::Arc;
 fn device_is_not_available_by_default() {
     let instance = wgpu::Instance::new(wgpu::InstanceDescriptor {
         backends: wgpu::Backends::NOOP,
-        ..Default::default()
+        ..wgpu::InstanceDescriptor::new_without_display_handle()
     });
 
     pollster::block_on(instance.request_adapter(&wgpu::RequestAdapterOptions::default()))
@@ -22,7 +22,7 @@ fn device_is_available_when_requested() {
             noop: wgpu::NoopBackendOptions { enable: true },
             ..Default::default()
         },
-        ..Default::default()
+        ..wgpu::InstanceDescriptor::new_without_display_handle()
     });
 
     pollster::block_on(instance.request_adapter(&wgpu::RequestAdapterOptions::default()))
diff --git a/tests/tests/wgpu_trace.rs b/tests/tests/wgpu_trace.rs
@@ -23,7 +23,7 @@ fn trace_test(test_type: TestType) {
                 noop: wgt::NoopBackendOptions { enable: true },
                 ..Default::default()
             },
-            ..Default::default()
+            ..wgt::instance::InstanceDescriptor::new_without_display_handle()
         },
         None,
     );
diff --git a/wgpu-core/src/instance.rs b/wgpu-core/src/instance.rs
@@ -227,26 +227,33 @@ impl Instance {
     ///
     /// # Safety
     ///
-    /// - `display_handle` must be a valid object to create a surface upon.
+    /// - `display_handle` must be a valid object to create a surface upon,
+    ///   falls back to the instance display handle otherwise.
     /// - `window_handle` must remain valid as long as the returned
     ///   [`SurfaceId`] is being used.
     pub unsafe fn create_surface(
         &self,
-        display_handle: raw_window_handle::RawDisplayHandle,
+        display_handle: Option<raw_window_handle::RawDisplayHandle>,
         window_handle: raw_window_handle::RawWindowHandle,
     ) -> Result<Surface, CreateSurfaceError> {
         profiling::scope!("Instance::create_surface");
 
-        if let Some(instance_display_handle) = &self.display {
-            if instance_display_handle
-                .display_handle()
+        let instance_display_handle = self.display.as_ref().map(|d| {
+            d.display_handle()
                 .expect("Implementation did not provide a DisplayHandle")
                 .as_raw()
-                != display_handle
-            {
-                return Err(CreateSurfaceError::MismatchingDisplayHandle);
+        });
+        let display_handle = match (instance_display_handle, display_handle) {
+            (Some(a), Some(b)) => {
+                if a != b {
+                    return Err(CreateSurfaceError::MismatchingDisplayHandle);
+                }
+                a
             }
-        }
+            (Some(hnd), None) => hnd,
+            (None, Some(hnd)) => hnd,
+            (None, None) => return Err(CreateSurfaceError::MissingDisplayHandle),
+        };
 
         let mut errors = HashMap::default();
         let mut surface_per_backend = HashMap::default();
@@ -936,6 +943,13 @@ pub enum CreateSurfaceError {
     FailedToCreateSurfaceForAnyBackend(HashMap<Backend, hal::InstanceError>),
     #[error("The display handle used to create this Instance does not match the one used to create a surface on it")]
     MismatchingDisplayHandle,
+    #[error(
+        "No `DisplayHandle` is available to create this surface with.  When creating a surface with `create_surface()` \
+        you must specify a display handle in `InstanceDescriptor::display`.  \
+        Rarely, if you need to create surfaces from different `DisplayHandle`s (ex. different Wayland or X11 connections), \
+        you must use `create_surface_unsafe()`."
+    )]
+    MissingDisplayHandle,
 }
 
 impl Global {
@@ -953,12 +967,13 @@ impl Global {
     ///
     /// # Safety
     ///
-    /// - `display_handle` must be a valid object to create a surface upon.
+    /// - `display_handle` must be a valid object to create a surface upon,
+    ///   falls back to the instance display handle otherwise.
     /// - `window_handle` must remain valid as long as the returned
     ///   [`SurfaceId`] is being used.
     pub unsafe fn instance_create_surface(
         &self,
-        display_handle: raw_window_handle::RawDisplayHandle,
+        display_handle: Option<raw_window_handle::RawDisplayHandle>,
         window_handle: raw_window_handle::RawWindowHandle,
         id_in: Option<SurfaceId>,
     ) -> Result<SurfaceId, CreateSurfaceError> {
diff --git a/wgpu-hal/src/dx12/instance.rs b/wgpu-hal/src/dx12/instance.rs
@@ -147,9 +147,13 @@ impl crate::Instance for super::Instance {
 
     unsafe fn create_surface(
         &self,
-        _display_handle: raw_window_handle::RawDisplayHandle,
+        display_handle: raw_window_handle::RawDisplayHandle,
         window_handle: raw_window_handle::RawWindowHandle,
     ) -> Result<super::Surface, crate::InstanceError> {
+        assert!(matches!(
+            display_handle,
+            raw_window_handle::RawDisplayHandle::Windows(_)
+        ));
         match window_handle {
             raw_window_handle::RawWindowHandle::Win32(handle) => {
                 // https://github.com/rust-windowing/raw-window-handle/issues/171
diff --git a/wgpu-hal/src/gles/wgl.rs b/wgpu-hal/src/gles/wgl.rs
@@ -563,12 +563,12 @@ impl crate::Instance for Instance {
         })
     }
 
-    #[cfg_attr(target_os = "macos", allow(unused, unused_mut, unreachable_code))]
     unsafe fn create_surface(
         &self,
-        _display_handle: RawDisplayHandle,
+        display_handle: RawDisplayHandle,
         window_handle: RawWindowHandle,
     ) -> Result<Surface, crate::InstanceError> {
+        assert!(matches!(display_handle, RawDisplayHandle::Windows(_)));
         let window = if let RawWindowHandle::Win32(handle) = window_handle {
             handle
         } else {
diff --git a/wgpu-hal/src/metal/mod.rs b/wgpu-hal/src/metal/mod.rs
@@ -151,16 +151,18 @@ impl crate::Instance for Instance {
 
     unsafe fn create_surface(
         &self,
-        _display_handle: raw_window_handle::RawDisplayHandle,
+        display_handle: raw_window_handle::RawDisplayHandle,
         window_handle: raw_window_handle::RawWindowHandle,
     ) -> Result<Surface, crate::InstanceError> {
-        let layer = match window_handle {
-            raw_window_handle::RawWindowHandle::AppKit(handle) => unsafe {
-                raw_window_metal::Layer::from_ns_view(handle.ns_view)
-            },
-            raw_window_handle::RawWindowHandle::UiKit(handle) => unsafe {
-                raw_window_metal::Layer::from_ui_view(handle.ui_view)
-            },
+        let layer = match (display_handle, window_handle) {
+            (
+                raw_window_handle::RawDisplayHandle::AppKit(_),
+                raw_window_handle::RawWindowHandle::AppKit(handle),
+            ) => unsafe { raw_window_metal::Layer::from_ns_view(handle.ns_view) },
+            (
+                raw_window_handle::RawDisplayHandle::UiKit(_),
+                raw_window_handle::RawWindowHandle::UiKit(handle),
+            ) => unsafe { raw_window_metal::Layer::from_ui_view(handle.ui_view) },
             _ => {
                 return Err(crate::InstanceError::new(format!(
                     "window handle {window_handle:?} is not a Metal-compatible handle"
diff --git a/wgpu-info/src/report.rs b/wgpu-info/src/report.rs
@@ -20,7 +20,7 @@ pub struct GpuReport {
 impl GpuReport {
     pub fn generate() -> Self {
         let instance = wgpu::Instance::new({
-            let mut desc = wgpu::InstanceDescriptor::default();
+            let mut desc = wgpu::InstanceDescriptor::new_without_display_handle();
             desc.backend_options.dx12.shader_compiler = Dx12Compiler::StaticDxc;
             desc.flags = wgpu::InstanceFlags::debugging();
             desc.with_env()
diff --git a/wgpu-types/src/instance.rs b/wgpu-types/src/instance.rs
diff --git a/wgpu/src/api/device.rs b/wgpu/src/api/device.rs
diff --git a/wgpu/src/api/instance.rs b/wgpu/src/api/instance.rs
diff --git a/wgpu/src/api/surface.rs b/wgpu/src/api/surface.rs
