macOS: Fix one-second delay when switching a wgpu app to the foreground

[emilk]

Connections

• Closes Mac/Metal: After alt-tab, get_current_texture locks for exactly one second #8309
• Related to surface.get_current_texture blocks for the duration of fullscreen animation on macOS #5613

Description

• Fix 1-second hang when switching to a wgpu application that was in the background on macOS
• ⚠️ get_current_texture can now return SurfaceError::Occluded (only on Mac currently)
• Change return type of fn acquire_texture to return timeouts as an error variant

On macOS, when a window is occluded (minimized, behind other windows, or on another virtual desktop), CAMetalLayer.nextDrawable() can block for up to 1 second. This happens because presented drawables get stuck waiting for vsync that isn't happening while the window is hidden.

When switching back to a wgpu application that was in the background, users experience a noticeable 1-second delay before the application becomes responsive.

This PR adds a fix: in the top of aquire_texture we first check if the window is occluded. If it is, we return a new SurfaceError::Occluded error right away, avoiding the 1 second delay.

This then requires users to actually handle this new error by attempting again later.

Thanks to Claude and @Wumpf for helping me with this PR!

Testing
I ran cargo r -p wgpu-example-02-hello-window, switching the app to be behind and then in front of another opaque window.

• cargo run --bin wgpu-examples cube
• cargo run --bin wgpu-examples hello_triangle
• cargo run --bin wgpu-examples uniform_values
• cargo r -p wgpu-example-02-hello-window

Squash or Rebase?
Squash

Checklist

• Run cargo fmt.
• Run taplo format.
• Run cargo clippy --tests. If applicable, add:
  • --target wasm32-unknown-unknown
• Run cargo xtask test to run tests.
• If this contains user-facing changes, add a CHANGELOG.md entry.

[emilk]

I hear from @Wumpf (on other channels) that we should return a new error code instead of returning None (indicating timeout).

My plan is to change acquire_texture from returning a Result<Option<Surface>, SurfaceError> to returning Result<Surface, SurfaceError>, and add Timeout as an error variant in SurfaceError instead (mirroring SurfaceStatus). After that, add Occluded as an error variant both to SurfaceError and to SurfaceStatus.

[Wumpf]

looks good to me, except for the wrong comment I found. Much cleaner than before!

[Wumpf]

nice. Going to land that and further investigate correct reaction to inclusion events as part of #9089
Which I want to review soonish; I'll then put some effort into learning about how to correctly process occluded events on winit and will transfer those learnings to eframe as well if it can be mitigated there

[emilk]

It actually looks like I accidentally counteracted the same problem in this PR:

• Only run App::ui if the application is visible emilk/egui#7950

On egui main now (without the fix in this wgpu PR), I get zero delay when moving the window to the front EXCEPT if I do so very quickly (switch back and forth within a single second).