Emit destroy_surfaces() consistently on all platforms

Surface creation and destruction events exist "specifically" for Android
which has diverging lifetimes for its `Surface` structure compared to
other platforms; specifically Vulkan `VkSurfaceKHR` or `EGLSurface`
objects need to be destroyed and recreated.

Commit 6cdb317 ("Consistently deliver a Resumed event on all
platforms") made sure to consistently call `can_create_surfaces()`
(`Event::Resumed` back then) on all platforms directly after
startup so that users don't have to have platform-specific surface
creation behaviour in two disjoint places, but we forgot about
`destroy_surfaces()` (back then `Event::Suspended`) leading to
applications still having to handle this destruction in two different
places.

Solve that by calling the callback on all those platforms, directly
before returning `PumpStatus::Exit` from `fn single_iteration()`.

Author: MarijnS95

winit-appkit/src/event_loop.rs

@@ -315,6 +315,7 @@ impl EventLoop {
 
                 if self.app_state.exiting() {
                     self.app_state.internal_exit();
+                    app.destroy_surfaces(&self.window_target);
                     PumpStatus::Exit(0)
                 } else {
                     PumpStatus::Continue

winit-core/src/application/mod.rs

@@ -72,8 +72,9 @@ pub trait ApplicationHandler {
     /// applications to create a render surface until that point.
     ///
     /// For consistency, all platforms call this method even if they don't themselves have a formal
-    /// surface destroy/create lifecycle. For systems without a surface destroy/create lifecycle the
-    /// [`can_create_surfaces()`] event is always emitted after the [`StartCause::Init`] event.
+    /// surface create/destroy lifecycle. For systems without a surface create/destrory lifecycle
+    /// the [`can_create_surfaces()`] event is always emitted after the [`StartCause::Init`]
+    /// event.
     ///
     /// Applications should be able to gracefully handle back-to-back [`can_create_surfaces()`] and
     /// [`destroy_surfaces()`] calls.
@@ -275,6 +276,21 @@ pub trait ApplicationHandler {
     ///
     /// See [`can_create_surfaces()`] for more details.
     ///
+    /// ## Portability
+    ///
+    /// It's recommended that applications should only destroy their render surfaces after the
+    /// [`destroy_surfaces()`] method is called. Some systems (specifically Android) won't allow
+    /// applications to use the render surface after that point.
+    ///
+    /// For consistency, all platforms call this method even if they don't themselves have a formal
+    /// surface create/destroy lifecycle. For systems without a surface create/destroy lifecycle the
+    /// [`destroy_surfaces()`] event is always emitted before [`PumpStatus::Exit`] is returned.
+    ///
+    /// Applications should be able to gracefully handle back-to-back [`can_create_surfaces()`] and
+    /// [`destroy_surfaces()`] calls.
+    ///
+    /// [`PumpStatus::Exit`]: crate::event_loop::pump_events::PumpStatus::Exit
+    ///
     /// ## Platform-specific
     ///
     /// ### Android
@@ -298,10 +314,6 @@ pub trait ApplicationHandler {
     /// [`VkSurfaceKHR`]: https://www.khronos.org/registry/vulkan/specs/1.3-extensions/man/html/VkSurfaceKHR.html
     /// [`wgpu::Surface`]: https://docs.rs/wgpu/latest/wgpu/struct.Surface.html
     ///
-    /// ### Others
-    ///
-    /// - **iOS / macOS / Orbital / Wayland / Web / Windows / X11:** Unsupported.
-    ///
     /// [`can_create_surfaces()`]: Self::can_create_surfaces()
     /// [`destroy_surfaces()`]: Self::destroy_surfaces()
     fn destroy_surfaces(&mut self, event_loop: &dyn ActiveEventLoop) {

winit-wayland/src/event_loop/mod.rs

@@ -218,6 +218,8 @@ impl EventLoop {
         if let Some(code) = self.exit_code() {
             self.loop_running = false;
 
+            app.destroy_surfaces(&self.active_event_loop);
+
             PumpStatus::Exit(code)
         } else {
             // NOTE: spawn a wake-up thread, thus if we have code reading the wayland connection

winit-win32/src/event_loop.rs

@@ -303,6 +303,9 @@ impl EventLoop {
             // Immediately reset the internal state for the loop to allow
             // the loop to be run more than once.
             self.runner.reset_runner();
+
+            app.destroy_surfaces(ActiveEventLoop::from_ref(&self.runner));
+
             PumpStatus::Exit(code)
         } else {
             self.runner.prepare_wait();

winit-x11/src/event_loop.rs

@@ -479,6 +479,8 @@ impl EventLoop {
         if let Some(code) = self.exit_code() {
             self.loop_running = false;
 
+            app.destroy_surfaces(&self.event_processor.target);
+
             PumpStatus::Exit(code)
         } else {
             PumpStatus::Continue

winit/src/changelog/v0.31.md

@@ -1,3 +1,9 @@
+## Unreleased
+
+### Changed
+
+- `destroy_surfaces()` is now emitted on all platforms for behaviour-parity.
+
 ## 0.31.0-beta.2
 
 ### Added
@@ -86,8 +92,8 @@
 - `ApplicationHandler::can_create|destroy_surfaces()` was split off from
   `ApplicationHandler::resumed/suspended()`.
 
-  `ApplicationHandler::can_create_surfaces()` should, for portability reasons
-  to Android, be the only place to create render surfaces.
+  `ApplicationHandler::can_create_surfaces()` and `ApplicationHandler::destroy_surfaces()` should,
+  for portability reasons to Android, be the only place to create and destroy render surfaces respectively.
 
   `ApplicationHandler::resumed/suspended()` are now only emitted by iOS, Web
   and Android, and now signify actually resuming/suspending the application.

winit/src/event_loop.rs

@@ -165,6 +165,8 @@ impl EventLoop {
     ///     start_cause = event_loop.wait_if_necessary();
     /// }
     ///
+    /// app.destroy_surfaces(event_loop);
+    ///
     /// // Finished running, drop application state.
     /// drop(app);
     /// ```