configurable wgpu backend (#2207)

* introduce new wgpu configuration option to allow configuring wgpu renderer

* use new options with wgpu web painter

* use on_surface_error callback

* changelog update

* cleanup

* changelog and comment fixes

crates/egui-wgpu/src/lib.rs

@@ -20,8 +20,7 @@ pub mod winit;
 use egui::mutex::RwLock;
 use std::sync::Arc;
 
-/// Access to the render state for egui, which can be useful in combination with
-/// [`egui::PaintCallback`]s for custom rendering using WGPU.
+/// Access to the render state for egui.
 #[derive(Clone)]
 pub struct RenderState {
     pub device: Arc<wgpu::Device>,
@@ -30,6 +29,60 @@ pub struct RenderState {
     pub renderer: Arc<RwLock<Renderer>>,
 }
 
+/// Specifies which action should be taken as consequence of a [`wgpu::SurfaceError`]
+pub enum SurfaceErrorAction {
+    /// Do nothing and skip the current frame.
+    SkipFrame,
+
+    /// Instructs egui to recreate the surface, then skip the current frame.
+    RecreateSurface,
+}
+
+/// Configuration for using wgpu with eframe or the egui-wgpu winit feature.
+#[derive(Clone)]
+pub struct WgpuConfiguration {
+    /// Configuration passed on device request.
+    pub device_descriptor: wgpu::DeviceDescriptor<'static>,
+
+    /// Backends that should be supported (wgpu will pick one of these)
+    pub backends: wgpu::Backends,
+
+    /// Present mode used for the primary surface.
+    pub present_mode: wgpu::PresentMode,
+
+    /// Power preference for the adapter.
+    pub power_preference: wgpu::PowerPreference,
+
+    /// Callback for surface errors.
+    pub on_surface_error: Arc<dyn Fn(wgpu::SurfaceError) -> SurfaceErrorAction>,
+}
+
+impl Default for WgpuConfiguration {
+    fn default() -> Self {
+        Self {
+            device_descriptor: wgpu::DeviceDescriptor {
+                label: Some("egui wgpu device"),
+                features: wgpu::Features::default(),
+                limits: wgpu::Limits::default(),
+            },
+            backends: wgpu::Backends::PRIMARY | wgpu::Backends::GL,
+            present_mode: wgpu::PresentMode::AutoVsync,
+            power_preference: wgpu::PowerPreference::HighPerformance,
+
+            on_surface_error: Arc::new(|err| {
+                if err == wgpu::SurfaceError::Outdated {
+                    // This error occurs when the app is minimized on Windows.
+                    // Silently return here to prevent spamming the console with:
+                    // "The underlying surface has changed, and therefore the swap chain must be updated"
+                } else {
+                    tracing::warn!("Dropped frame with error: {err}");
+                }
+                SurfaceErrorAction::SkipFrame
+            }),
+        }
+    }
+}
+
 /// Find the framebuffer format that egui prefers
 pub fn preferred_framebuffer_format(formats: &[wgpu::TextureFormat]) -> wgpu::TextureFormat {
     for &format in formats {