Skip to content

SolidCraft: an open-source parametric 3D CAD application built in pure Rust. Desktop, web, and automation through MCP.

47.8 KB
Raw Blame
//! This crates provides bindings between [`egui`](https://github.com/emilk/egui) and [wgpu](https://crates.io/crates/wgpu).
//!
//! If you're targeting WebGL you also need to turn on the
//! `webgl` feature of the `wgpu` crate:
//!
//! ```toml
//! # Enable both WebGL and WebGPU backends on web.
//! wgpu = { version = "*", features = ["webgpu", "webgl"] }
//! ```
//!
//! You can control whether WebGL or WebGPU will be picked at runtime by configuring
//! [`WgpuConfiguration::wgpu_setup`].
//! The default is to prefer WebGPU and fall back on WebGL.
//!
//! ## Feature flags
#![doc = document_features::document_features!()]
//!

pub use wgpu;

/// Low-level painting of [`egui`](https://github.com/emilk/egui) on [`wgpu`].
mod renderer;

mod setup;

pub use renderer::*;
pub use setup::{
    EguiDisplayHandle, NativeAdapterSelectorMethod, WgpuSetup, WgpuSetupCreateNew,
    WgpuSetupExisting,
};

/// Helpers for capturing screenshots of the UI.
#[cfg(feature = "capture")]
pub mod capture;

/// Module for painting [`egui`](https://github.com/emilk/egui) with [`wgpu`] on [`winit`].
#[cfg(feature = "winit")]
pub mod winit;

use std::sync::Arc;

use epaint::mutex::RwLock;

/// SolidCraft: what [`set_startup_hook`] is told before each step of getting the graphics
/// device and the window's surface up, so a crash inside the driver (with no Rust panic) can
/// still say which step it died in. `detail` is empty except for [`STEP_ADAPTER_CHOSEN`].
pub type StartupHook = fn(step: &'static str, detail: &str);

static STARTUP_HOOK: std::sync::OnceLock<StartupHook> = std::sync::OnceLock::new();

/// SolidCraft: the steps [`StartupHook`] is told about, in order.
pub const STEP_INSTANCE: &str = "graphics instance";
pub const STEP_SURFACE: &str = "window surface";
pub const STEP_ADAPTER: &str = "adapter request";
/// The adapter was picked; `detail` names it, its backend and driver.
pub const STEP_ADAPTER_CHOSEN: &str = "adapter chosen";
pub const STEP_DEVICE: &str = "device creation";
pub const STEP_RENDERER: &str = "egui renderer (shader compile)";
pub const STEP_SURFACE_CONFIGURE: &str = "surface configure";
pub const STEP_FIRST_PRESENT: &str = "first frame (present)";

/// SolidCraft: install the startup hook (once; later calls are ignored).
pub fn set_startup_hook(hook: StartupHook) {
    let _ = STARTUP_HOOK.set(hook);
}

pub(crate) fn startup_step(step: &'static str, detail: &str) {
    if let Some(hook) = STARTUP_HOOK.get() {
        hook(step, detail);
    }
}

/// An error produced by egui-wgpu.
#[derive(thiserror::Error, Debug)]
pub enum WgpuError {
    #[error(transparent)]
    RequestAdapterError(#[from] wgpu::RequestAdapterError),

    #[error("Adapter selection failed: {0}")]
    CustomNativeAdapterSelectionError(String),

    #[error("There was no valid format for the surface at all.")]
    NoSurfaceFormatsAvailable,

    #[error(transparent)]
    RequestDeviceError(#[from] wgpu::RequestDeviceError),

    /// SolidCraft: pipeline validation must return to the startup retry.
    #[error("Could not create the egui renderer: {0}")]
    CreateRendererError(wgpu::Error),

    #[error(transparent)]
    CreateSurfaceError(#[from] wgpu::CreateSurfaceError),

    #[cfg(feature = "winit")]
    #[error(transparent)]
    HandleError(#[from] ::winit::raw_window_handle::HandleError),
}

/// Runtime-mutable subset of [`WgpuConfiguration`].
#[derive(Clone, Copy, Debug, PartialEq, Eq, Hash)]
pub struct SurfaceConfig {
    /// Present mode used for the primary surface.
    pub present_mode: wgpu::PresentMode,

    /// Desired maximum number of frames that the presentation engine should queue in advance.
    ///
    /// Use `1` for low-latency, and `2` for high-throughput.
    ///
    /// See [`wgpu::SurfaceConfiguration::desired_maximum_frame_latency`] for details.
    ///
    /// `None` => Let `wgpu` pick a default (currently `2`).
    pub desired_maximum_frame_latency: Option<u32>,
}

impl SurfaceConfig {
    /// Good default for GUIs with very little (or no) extra GPU work.
    pub const LOW_LATENCY: Self = Self {
        present_mode: wgpu::PresentMode::AutoVsync,

        desired_maximum_frame_latency: if cfg!(target_os = "ios") {
            None // The default is good on iOS, while `Some(1)` cuts FPS in half
        } else {
            Some(1)
        },
    };

    /// Good default for GUIs with a lot of extra GPU work,
    /// or that want to prioritize smoothness over latency.
    pub const HIGH_THROUGHPUT: Self = Self {
        present_mode: wgpu::PresentMode::AutoVsync,
        desired_maximum_frame_latency: Some(2), // High-throughput.
    };
}

/// SolidCraft: whether a device was lost (the driver reset it, Windows' TDR among others, #4172).
///
/// A lost device can't be used again. wgpu only learns of the loss when a call into the driver
/// fails: from then on every call on the device fails quietly, and the device's lost callback
/// marks this. But a queue write that is the first call to meet the loss panics inside wgpu
/// (`PendingWrites::activate`), so the painter first probes the device ([`DeviceLost::probe`]):
/// the probe meets the loss instead, and the frame's uploads are skipped.
#[derive(Clone, Debug, Default)]
pub struct DeviceLost {
    lost: Arc<std::sync::atomic::AtomicBool>,
    reason: Arc<std::sync::Mutex<Option<String>>>,
}

impl DeviceLost {
    /// Watch `device`: its lost callback marks the loss. A device has one lost callback, so this
    /// replaces any set before.
    pub fn watch(device: &wgpu::Device) -> Self {
        let lost = Self::default();
        let seen = lost.clone();
        device.set_device_lost_callback(move |reason, message| {
            seen.mark(&format!("{reason:?}: {message}"));
        });
        lost
    }

    /// Mark the device lost, for `reason` (the first reason is kept).
    pub fn mark(&self, reason: &str) {
        if let Ok(mut kept) = self.reason.lock() {
            kept.get_or_insert_with(|| reason.to_owned());
        }
        self.lost.store(true, std::sync::atomic::Ordering::Release);
    }

    /// The device was lost.
    pub fn is_lost(&self) -> bool {
        self.lost.load(std::sync::atomic::Ordering::Acquire)
    }

    /// Why the device was lost, as wgpu said it.
    pub fn reason(&self) -> Option<String> {
        self.reason.lock().ok().and_then(|r| r.clone())
    }

    /// The flag [`DeviceLost::is_lost`] reads, for others drawing on the same device.
    pub fn flag(&self) -> Arc<std::sync::atomic::AtomicBool> {
        self.lost.clone()
    }

    /// Whether the device is lost, asking the driver first, so a loss it reports is marked here
    /// rather than met by the next upload.
    ///
    /// The probe opens a command list, as the upload would: a queue write's first call into the
    /// driver is `begin_encoding`, and on D3D12 that is where a reset device says so. An empty
    /// submission only signals a fence: #6528 met a reset D3D12 device in the upload right after
    /// one. wgpu handles a failed `begin_encoding` in a command encoder's `finish` (it loses the
    /// device, and the lost callback marks it); only its queue writes unwrap it.
    pub fn probe(&self, device: &wgpu::Device, queue: &wgpu::Queue) -> bool {
        if self.is_lost() {
            return true;
        }
        let mut encoder = device.create_command_encoder(&wgpu::CommandEncoderDescriptor {
            label: Some("device lost probe"),
        });
        encoder.insert_debug_marker("device lost probe");
        queue.submit([encoder.finish()]);
        self.is_lost()
    }

    /// Run `draw`, GPU work on this device, and survive a panic it meets once the device is lost:
    /// `None` then. The driver resets a device at any moment, so a reset can land after the
    /// probe and a queue write (or the present) still be the first call to meet it, which panics
    /// inside wgpu (`PendingWrites::activate` unwraps `Lost`, #10240). After such a panic the
    /// probe meets the loss and marks it. Any other panic carries on unwinding.
    pub fn survive<R>(
        &self,
        device: &wgpu::Device,
        queue: &wgpu::Queue,
        draw: impl FnOnce() -> R,
    ) -> Option<R> {
        match std::panic::catch_unwind(std::panic::AssertUnwindSafe(draw)) {
            Ok(drawn) => Some(drawn),
            Err(_) if self.probe(device, queue) => None,
            Err(panic) => std::panic::resume_unwind(panic),
        }
    }
}

/// SolidCraft: a frame acquired from a window's surface, which gives its swapchain image back
/// however the frame ends: presented, dropped unpresented, or dropped while a panic unwinds
/// (#7148).
///
/// wgpu presents or discards a frame only on a valid device. On a lost one both return early, and
/// the surface keeps the frame's image, which holds one of the swapchain's acquire semaphores.
/// Dropping or reconfiguring that surface later (the window closing as the app restarts after the
/// loss) then panics in wgpu-hal: "Trying to destroy a SwapchainAcquireSemaphore that is still in
/// use by a SurfaceTexture". So the frame keeps a second handle to its texture, and once the frame
/// is gone that handle is destroyed ([`FreeSurfaceTexture`]), which takes the image (and its
/// semaphores) back from the surface, lost device or not. After a present or discard that worked,
/// the image is already back and the destroy does nothing.
///
/// The order is the struct's: Rust drops fields in declaration order, so [`Self::frame`] always
/// goes before the texture handle is destroyed, and [`Self::present`] presents before it.
pub struct AcquiredFrame<F, T: FreeSurfaceTexture> {
    /// The frame; dropped (discarded) before the texture is freed.
    pub frame: F,
    texture: FreeOnDrop<T>,
}

impl<F, T: FreeSurfaceTexture> AcquiredFrame<F, T> {
    /// `texture` is a second handle to `frame`'s texture.
    pub fn new(frame: F, texture: T) -> Self {
        Self {
            frame,
            texture: FreeOnDrop(texture),
        }
    }

    /// Present the frame with `present`, then free the texture.
    pub fn present(self, present: impl FnOnce(F)) {
        let Self { frame, texture } = self;
        present(frame);
        drop(texture);
    }
}

/// SolidCraft: what [`AcquiredFrame`] does with its texture handle once the frame is gone.
pub trait FreeSurfaceTexture {
    /// Give the surface's image back, whatever the device's state; nothing once it is back.
    fn free(&self);
}

impl FreeSurfaceTexture for wgpu::Texture {
    /// wgpu-core's destroy of a surface texture takes its image and drops it without checking the
    /// device, and does nothing when a present or discard took it already.
    fn free(&self) {
        self.destroy();
    }
}

/// Frees its texture when dropped, also while a panic unwinds.
struct FreeOnDrop<T: FreeSurfaceTexture>(T);

impl<T: FreeSurfaceTexture> Drop for FreeOnDrop<T> {
    fn drop(&mut self) {
        self.0.free();
    }
}

/// Access to the render state for egui.
#[derive(Clone)]
pub struct RenderState {
    /// Wgpu adapter used for rendering.
    pub adapter: wgpu::Adapter,

    /// All the available adapters.
    ///
    /// This is not available on web.
    /// On web, we always select WebGPU is available, then fall back to WebGL if not.
    #[cfg(not(target_arch = "wasm32"))]
    pub available_adapters: Vec<wgpu::Adapter>,

    /// Wgpu instance used for creating surfaces and adapters.
    pub instance: wgpu::Instance,

    /// Wgpu device used for rendering, created from the adapter.
    pub device: wgpu::Device,

    /// Wgpu queue used for rendering, created from the adapter.
    pub queue: wgpu::Queue,

    /// The target texture format used for presenting to the window.
    pub target_format: wgpu::TextureFormat,

    /// Effective sample count after backend compatibility handling.
    /// Custom paint callbacks must use this, rather than the requested setting.
    pub msaa_samples: u32,

    /// SolidCraft: the MSAA sample counts this device can render the target (and depth) format
    /// with, ascending, always starting with 1.
    pub msaa_supported: Vec<u32>,

    /// Egui renderer responsible for drawing the UI.
    pub renderer: Arc<RwLock<Renderer>>,

    /// SolidCraft: the device was lost; the painter draws nothing more (#4172).
    pub device_lost: DeviceLost,
}

async fn request_adapter(
    instance: &wgpu::Instance,
    power_preference: wgpu::PowerPreference,
    compatible_surface: Option<&wgpu::Surface<'_>>,
    available_adapters: &[wgpu::Adapter],
) -> Result<wgpu::Adapter, WgpuError> {
    profiling::function_scope!();

    let adapter = instance
        .request_adapter(&wgpu::RequestAdapterOptions {
            power_preference,
            compatible_surface,
            // We don't expose this as an option right now since it's fairly rarely useful:
            // * only has an effect on native
            // * fails if there's no software rasterizer available
            // * can achieve the same with `native_adapter_selector`
            force_fallback_adapter: false,
            apply_limit_buckets: false,
        })
        .await
        .inspect_err(|_err| {
            if cfg!(target_arch = "wasm32") {
                // Nothing to add here
            } else if available_adapters.is_empty() {
                if std::env::var("DYLD_LIBRARY_PATH").is_ok() {
                    // DYLD_LIBRARY_PATH can sometimes lead to loading dylibs that cause
                    // us to find zero adapters. Very strange.
                    // I don't want to debug this again.
                    // See https://github.com/rerun-io/rerun/issues/11351 for more
                    log::warn!(
                        "No wgpu adapter found. This could be because DYLD_LIBRARY_PATH causes dylibs to be loaded that interfere with Metal device creation. Try restarting with DYLD_LIBRARY_PATH=''"
                    );
                } else {
                    log::info!("No wgpu adapter found");
                }
            } else if available_adapters.len() == 1 {
                log::info!(
                    "The only available wgpu adapter was not suitable: {}",
                    adapter_info_summary(&available_adapters[0].get_info())
                );
            } else {
                log::info!(
                    "No suitable wgpu adapter found out of the {} available ones: {}",
                    available_adapters.len(),
                    describe_adapters(available_adapters)
                );
            }
        })?;

    if 1 < available_adapters.len() {
        log::info!(
            "There are {} available wgpu adapters: {}",
            available_adapters.len(),
            describe_adapters(available_adapters)
        );
    }

    Ok(adapter)
}

impl RenderState {
    /// Creates a new [`RenderState`], containing everything needed for drawing egui with wgpu.
    ///
    /// # Errors
    /// Wgpu initialization may fail due to incompatible hardware or driver for a given config.
    pub async fn create(
        config: &WgpuConfiguration,
        instance: &wgpu::Instance,
        compatible_surface: Option<&wgpu::Surface<'static>>,
        options: RendererOptions,
    ) -> Result<Self, WgpuError> {
        profiling::scope!("RenderState::create"); // async yield give bad names using `profile_function`

        // This is always an empty list on web.
        #[cfg(not(target_arch = "wasm32"))]
        let available_adapters = {
            let backends = if let WgpuSetup::CreateNew(create_new) = &config.wgpu_setup {
                create_new.instance_descriptor.backends
            } else {
                wgpu::Backends::all()
            };

            startup_step(STEP_ADAPTER, ""); // SolidCraft
            instance.enumerate_adapters(backends).await
        };

        let (instance, adapter, device, queue) = match config.wgpu_setup.clone() {
            WgpuSetup::CreateNew(WgpuSetupCreateNew {
                instance_descriptor: _,
                display_handle: _,
                power_preference,
                native_adapter_selector: _native_adapter_selector,
                device_descriptor,
            }) => {
                let adapter = {
                    #[cfg(target_arch = "wasm32")]
                    {
                        request_adapter(instance, power_preference, compatible_surface, &[]).await
                    }
                    #[cfg(not(target_arch = "wasm32"))]
                    {
                        let selected = _native_adapter_selector
                            .map(|select| select(&available_adapters, compatible_surface))
                            .transpose()
                            .map_err(WgpuError::CustomNativeAdapterSelectionError)?
                            .flatten();
                        if let Some(adapter) = selected {
                            Ok(adapter)
                        } else {
                            request_adapter(
                                instance,
                                power_preference,
                                compatible_surface,
                                &available_adapters,
                            )
                            .await
                        }
                    }
                }?;

                // SolidCraft: name the adapter before the driver is asked for a device.
                let info = adapter.get_info();
                startup_step(
                    STEP_ADAPTER_CHOSEN,
                    &format!(
                        "{:?} {} ({:?}, driver {} {})",
                        info.backend, info.name, info.device_type, info.driver, info.driver_info
                    ),
                );
                startup_step(STEP_DEVICE, "");
                let (device, queue) = {
                    profiling::scope!("request_device");
                    adapter
                        .request_device(&(*device_descriptor)(&adapter))
                        .await?
                };

                (instance.clone(), adapter, device, queue)
            }
            WgpuSetup::Existing(WgpuSetupExisting {
                instance,
                adapter,
                device,
                queue,
            }) => (instance, adapter, device, queue),
        };
        // SolidCraft: a device the driver loses stops the painter, not the app (#4172).
        let device_lost = DeviceLost::watch(&device);

        log_adapter_info(&adapter.get_info());

        let surface_formats = {
            profiling::scope!("get_capabilities");
            compatible_surface.map_or_else(
                || vec![wgpu::TextureFormat::Rgba8Unorm],
                |s| s.get_capabilities(&adapter).formats,
            )
        };
        let target_format = crate::preferred_framebuffer_format(&surface_formats)?;

        // SolidCraft: the OpenGL resolve path can present an entirely black frame with MSAA
        // (notably Mesa/llvmpipe). Decide after selecting the real surface adapter,
        // before creating either pipelines or attachments; no second GPU probe.
        // A sample count the device doesn't support for the target or depth format fails
        // pipeline validation (a panic at start): fall back to the largest supported one.
        let msaa_supported =
            supported_msaa_samples(&adapter, &device, target_format, options.depth_stencil_format);
        let wanted = effective_msaa_samples(adapter.get_info().backend, options.msaa_samples);
        let msaa_samples = clamp_msaa_samples(&msaa_supported, wanted);
        if msaa_samples != wanted {
            log::warn!(
                "MSAA {wanted}x is not supported for {target_format:?} on this device (supported: {msaa_supported:?}); using {msaa_samples}x"
            );
        }
        let options = RendererOptions {
            msaa_samples,
            ..options
        };
        startup_step(STEP_RENDERER, ""); // SolidCraft
        // SolidCraft: capture errors on the real surface/device, including driver shader
        // compilation failures, before wgpu's default uncaptured-error handler can panic.
        // Await every scope (also on WebGPU); an invalid renderer is never handed to eframe.
        let scopes = [
            wgpu::ErrorFilter::OutOfMemory,
            wgpu::ErrorFilter::Internal,
            wgpu::ErrorFilter::Validation,
        ]
        .map(|filter| device.push_error_scope(filter));
        let renderer = Renderer::new(&device, target_format, options);
        let mut failed = None;
        for scope in scopes.into_iter().rev() {
            if let Some(error) = scope.pop().await {
                failed.get_or_insert(error);
            }
        }
        if let Some(error) = failed {
            return Err(WgpuError::CreateRendererError(error));
        }

        // On wasm, depending on feature flags, wgpu objects may or may not implement sync.
        // It doesn't make sense to switch to Rc for that special usecase, so simply disable the lint.
        #[allow(clippy::allow_attributes, clippy::arc_with_non_send_sync)] // For wasm
        Ok(Self {
            instance,
            adapter,
            #[cfg(not(target_arch = "wasm32"))]
            available_adapters,
            device,
            queue,
            target_format,
            msaa_samples: options.msaa_samples,
            msaa_supported,
            renderer: Arc::new(RwLock::new(renderer)),
            device_lost,
        })
    }
}

fn describe_adapters(adapters: &[wgpu::Adapter]) -> String {
    if adapters.is_empty() {
        "(none)".to_owned()
    } else if adapters.len() == 1 {
        adapter_info_summary(&adapters[0].get_info())
    } else {
        adapters
            .iter()
            .map(|a| format!("{{{}}}", adapter_info_summary(&a.get_info())))
            .collect::<Vec<_>>()
            .join(", ")
    }
}

/// Specifies which action should be taken as consequence of a surface error.
pub enum SurfaceErrorAction {
    /// Do nothing and skip the current frame.
    SkipFrame,

    /// Reconfigure the existing surface, then skip the current frame.
    ///
    /// Calls [`wgpu::Surface::configure`] on the current surface object.
    /// Use for [`wgpu::CurrentSurfaceTexture::Outdated`].
    Reconfigure,

    /// Drop the surface, create a new one via [`wgpu::Instance::create_surface`], configure it,
    /// then skip the current frame.
    ///
    /// Use for [`wgpu::CurrentSurfaceTexture::Lost`], where reconfiguring the same surface
    /// object cannot recover.
    RecreateSurface,
}

/// Configuration for using wgpu with eframe or the egui-wgpu winit feature.
#[derive(Clone)]
pub struct WgpuConfiguration {
    /// Runtime-mutable configuration for the surface (present mode, frame latency).
    pub surface: SurfaceConfig,

    /// How to create the wgpu adapter & device
    pub wgpu_setup: WgpuSetup,

    /// Callback for surface status changes.
    ///
    /// Called with the [`wgpu::CurrentSurfaceTexture`] result whenever acquiring a frame
    /// does not return [`wgpu::CurrentSurfaceTexture::Success`]. For
    /// [`wgpu::CurrentSurfaceTexture::Suboptimal`], egui uses the frame as-is and
    /// defers surface reconfiguration to the next frame — the callback is not invoked
    /// in that case either.
    pub on_surface_status:
        Arc<dyn Fn(&wgpu::CurrentSurfaceTexture) -> SurfaceErrorAction + Send + Sync>,
}

// Compile-time check that `WgpuConfiguration` is `Send + Sync`.
// Deliberately not a `#[test]`: tests never run on wasm, but `cargo check` does.
// On wasm this only holds with `fragile-send-sync-non-atomic-wasm` and without threads;
// look at the feature flag for an explanation.
#[cfg(any(
    not(target_arch = "wasm32"),
    all(
        feature = "fragile-send-sync-non-atomic-wasm",
        not(target_feature = "atomics")
    ),
))]
const _: () = {
    const fn assert_send_sync<T: Send + Sync>() {}
    assert_send_sync::<WgpuConfiguration>();
};

impl core::fmt::Debug for WgpuConfiguration {
    fn fmt(&self, f: &mut core::fmt::Formatter<'_>) -> core::fmt::Result {
        let Self {
            surface,
            wgpu_setup,
            on_surface_status: _,
        } = self;
        f.debug_struct("WgpuConfiguration")
            .field("surface", &surface)
            .field("wgpu_setup", &wgpu_setup)
            .finish_non_exhaustive()
    }
}

impl WgpuConfiguration {
    #[inline]
    pub fn with_surface_config(mut self, surface_config: SurfaceConfig) -> Self {
        self.surface = surface_config;
        self
    }
}

impl Default for WgpuConfiguration {
    fn default() -> Self {
        Self {
            surface: SurfaceConfig::HIGH_THROUGHPUT,

            // No display handle available at this point — callers should replace this with
            // `WgpuSetup::from_display_handle(...)` before creating the instance if one is available.
            wgpu_setup: WgpuSetup::without_display_handle(),
            on_surface_status: Arc::new(|status| match status {
                wgpu::CurrentSurfaceTexture::Outdated => {
                    // The compositor changed the surface (resize, scale, output, …). wgpu
                    // requires us to reconfigure before the next acquire. Skipping would mean
                    // we are stuck in `Outdated` forever.
                    log::trace!("Dropped frame with error: {status:?}");
                    SurfaceErrorAction::Reconfigure
                }
                wgpu::CurrentSurfaceTexture::Lost => {
                    // The underlying surface is gone and we need a fresh one from the `wgpu::Instance`.
                    log::debug!("Dropped frame with error: {status:?}");
                    SurfaceErrorAction::RecreateSurface
                }
                wgpu::CurrentSurfaceTexture::Occluded => {
                    // App is hidden (minimized / behind another window). Skip silently.
                    log::trace!("Skipping frame due to occlusion.");
                    SurfaceErrorAction::SkipFrame
                }
                wgpu::CurrentSurfaceTexture::Validation => {
                    // SolidCraft: the acquire's error was captured; most often the surface has
                    // no configuration ("Surface is not configured for presentation", #7007).
                    // Skipping alone would meet the same error on every frame after.
                    log::debug!("Dropped frame with error: {status:?}");
                    SurfaceErrorAction::Reconfigure
                }
                _ => {
                    log::warn!("Dropped frame with error: {status:?}");
                    SurfaceErrorAction::SkipFrame
                }
            }),
        }
    }
}

/// Find the framebuffer format that egui prefers
///
/// # Errors
/// Returns [`WgpuError::NoSurfaceFormatsAvailable`] if the given list of formats is empty.
pub fn preferred_framebuffer_format(
    formats: &[wgpu::TextureFormat],
) -> Result<wgpu::TextureFormat, WgpuError> {
    for &format in formats {
        if matches!(
            format,
            wgpu::TextureFormat::Rgba8Unorm | wgpu::TextureFormat::Bgra8Unorm
        ) {
            return Ok(format);
        }
    }

    formats
        .first()
        .copied()
        .ok_or(WgpuError::NoSurfaceFormatsAvailable)
}

/// Take's epi's depth/stencil bits and returns the corresponding wgpu format.
pub fn depth_format_from_bits(depth_buffer: u8, stencil_buffer: u8) -> Option<wgpu::TextureFormat> {
    match (depth_buffer, stencil_buffer) {
        (0, 8) => Some(wgpu::TextureFormat::Stencil8),
        (16, 0) => Some(wgpu::TextureFormat::Depth16Unorm),
        (24, 0) => Some(wgpu::TextureFormat::Depth24Plus),
        (24, 8) => Some(wgpu::TextureFormat::Depth24PlusStencil8),
        (32, 0) => Some(wgpu::TextureFormat::Depth32Float),
        (32, 8) => Some(wgpu::TextureFormat::Depth32FloatStencil8),
        _ => None,
    }
}

// ---------------------------------------------------------------------------

fn log_adapter_info(info: &wgpu::AdapterInfo) {
    let summary = adapter_info_summary(info);

    let is_test = cfg!(test); // Software rasterizers are expected (and preferred) during testing!

    if info.device_type == wgpu::DeviceType::Cpu && !is_test {
        log::warn!("Software rasterizer detected - loss of performance expected. {summary}");
    } else {
        log::debug!("wgpu adapter: {summary}");
    }
}

/// A human-readable summary about an adapter
pub fn adapter_info_summary(info: &wgpu::AdapterInfo) -> String {
    let wgpu::AdapterInfo {
        name,
        vendor,
        device,
        device_type,
        driver,
        driver_info,
        backend,
        device_pci_bus_id,
        subgroup_min_size,
        subgroup_max_size,
        transient_saves_memory,
        limit_bucket,
    } = &info;

    // Example values:
    // > name: "llvmpipe (LLVM 16.0.6, 256 bits)", device_type: Cpu, backend: Vulkan, driver: "llvmpipe", driver_info: "Mesa 23.1.6-arch1.4 (LLVM 16.0.6)"
    // > name: "Apple M1 Pro", device_type: IntegratedGpu, backend: Metal, driver: "", driver_info: ""
    // > name: "ANGLE (Apple, Apple M1 Pro, OpenGL 4.1)", device_type: IntegratedGpu, backend: Gl, driver: "", driver_info: ""

    use core::fmt::Write as _;

    let mut summary = format!("backend: {backend:?}, device_type: {device_type:?}");

    if !name.is_empty() {
        write!(summary, ", name: {name:?}").ok();
    }
    if !driver.is_empty() {
        write!(summary, ", driver: {driver:?}").ok();
    }
    if !driver_info.is_empty() {
        write!(summary, ", driver_info: {driver_info:?}").ok();
    }
    if *vendor != 0 {
        #[cfg(not(target_arch = "wasm32"))]
        {
            write!(
                summary,
                ", vendor: {} (0x{vendor:04X})",
                parse_vendor_id(*vendor)
            )
            .ok();
        }
        #[cfg(target_arch = "wasm32")]
        {
            write!(summary, ", vendor: 0x{vendor:04X}").ok();
        }
    }
    if *device != 0 {
        write!(summary, ", device: 0x{device:02X}").ok();
    }
    if !device_pci_bus_id.is_empty() {
        write!(summary, ", pci_bus_id: {device_pci_bus_id:?}").ok();
    }
    if *subgroup_min_size != 0 || *subgroup_max_size != 0 {
        write!(
            summary,
            ", subgroup_size: {subgroup_min_size}..={subgroup_max_size}"
        )
        .ok();
    }
    write!(
        summary,
        ", transient_saves_memory: {transient_saves_memory:?}"
    )
    .ok();
    write!(summary, ", limit_bucket: {limit_bucket:?}").ok();

    summary
}

/// Tries to parse the adapter's vendor ID to a human-readable string.
#[cfg(not(target_arch = "wasm32"))]
pub fn parse_vendor_id(vendor_id: u32) -> &'static str {
    match vendor_id {
        wgpu::hal::auxil::db::amd::VENDOR => "AMD",
        wgpu::hal::auxil::db::apple::VENDOR => "Apple",
        wgpu::hal::auxil::db::arm::VENDOR => "ARM",
        wgpu::hal::auxil::db::broadcom::VENDOR => "Broadcom",
        wgpu::hal::auxil::db::imgtec::VENDOR => "Imagination Technologies",
        wgpu::hal::auxil::db::intel::VENDOR => "Intel",
        wgpu::hal::auxil::db::mesa::VENDOR => "Mesa",
        wgpu::hal::auxil::db::nvidia::VENDOR => "NVIDIA",
        wgpu::hal::auxil::db::qualcomm::VENDOR => "Qualcomm",
        _ => "Unknown",
    }
}

/// Selected-adapter policy shared by egui pipelines, attachments and host callbacks.
pub fn effective_msaa_samples(backend: wgpu::Backend, requested: u32) -> u32 {
    if backend == wgpu::Backend::Gl { 1 } else { requested.max(1) }
}

/// SolidCraft: the MSAA sample counts `device` can render `target_format` and
/// `depth_stencil_format` with (ascending, always starting with 1). Without
/// [`wgpu::Features::TEXTURE_ADAPTER_SPECIFIC_FORMAT_FEATURES`] the device allows only the counts
/// WebGPU guarantees for a format (1 and 4), whatever the adapter could do.
pub fn supported_msaa_samples(
    adapter: &wgpu::Adapter,
    device: &wgpu::Device,
    target_format: wgpu::TextureFormat,
    depth_stencil_format: Option<wgpu::TextureFormat>,
) -> Vec<u32> {
    let features = device.features();
    let flags = |format: wgpu::TextureFormat| {
        if features.contains(wgpu::Features::TEXTURE_ADAPTER_SPECIFIC_FORMAT_FEATURES) {
            adapter.get_texture_format_features(format).flags
        } else {
            format.guaranteed_format_features(features).flags
        }
    };
    let target = flags(target_format);
    let depth = depth_stencil_format.map(flags);
    msaa_counts(target, depth)
}

/// The sample counts both the colour target and the depth buffer support. A multisampled colour
/// target must also resolve into the single-sampled surface.
fn msaa_counts(
    target: wgpu::TextureFormatFeatureFlags,
    depth: Option<wgpu::TextureFormatFeatureFlags>,
) -> Vec<u32> {
    let resolves = target.contains(wgpu::TextureFormatFeatureFlags::MULTISAMPLE_RESOLVE);
    [1, 2, 4, 8, 16]
        .into_iter()
        .filter(|&n| {
            n == 1
                || (resolves
                    && target.sample_count_supported(n)
                    && depth.is_none_or(|d| d.sample_count_supported(n)))
        })
        .collect()
}

/// SolidCraft: the largest of the `supported` sample counts that is at most `requested` (1 when
/// none is).
pub fn clamp_msaa_samples(supported: &[u32], requested: u32) -> u32 {
    supported
        .iter()
        .copied()
        .filter(|&n| n <= requested.max(1))
        .max()
        .unwrap_or(1)
}

#[cfg(test)]
mod msaa_tests {
    #[test]
    fn gl_saved_multisampling_is_clamped_and_native_backends_keep_it() {
        for requested in [0, 1, 2, 4, 8] {
            assert_eq!(super::effective_msaa_samples(wgpu::Backend::Gl, requested), 1);
            for backend in [wgpu::Backend::Vulkan, wgpu::Backend::Dx12, wgpu::Backend::Metal, wgpu::Backend::BrowserWebGpu] {
                assert_eq!(super::effective_msaa_samples(backend, requested), requested.max(1));
            }
        }
    }

    #[test]
    fn unsupported_sample_counts_fall_back_to_the_largest_supported_one() {
        use wgpu::TextureFormatFeatureFlags as F;
        // WebGPU's guarantee for Bgra8Unorm without adapter-specific features: 1 and 4 (a
        // saved 8x failed pipeline validation at start).
        let guaranteed = F::MULTISAMPLE_X4 | F::MULTISAMPLE_RESOLVE;
        let supported = super::msaa_counts(guaranteed, Some(F::MULTISAMPLE_X4));
        assert_eq!(supported, [1, 4]);
        assert_eq!(super::clamp_msaa_samples(&supported, 8), 4);
        assert_eq!(super::clamp_msaa_samples(&supported, 2), 1);
        assert_eq!(super::clamp_msaa_samples(&supported, 0), 1);
        // The depth buffer limits it too, and a target that can't resolve can't multisample.
        let adapter = F::MULTISAMPLE_X2 | F::MULTISAMPLE_X4 | F::MULTISAMPLE_X8 | F::MULTISAMPLE_RESOLVE;
        assert_eq!(super::msaa_counts(adapter, None), [1, 2, 4, 8]);
        assert_eq!(super::msaa_counts(adapter, Some(F::MULTISAMPLE_X4)), [1, 4]);
        assert_eq!(super::msaa_counts(F::MULTISAMPLE_X4, None), [1]);
        assert_eq!(super::clamp_msaa_samples(&[], 8), 1);
    }
}

/// SolidCraft: run `f` with `device`'s errors captured, and the first error it caused. Uncaptured,
/// an error goes to the device's handler, which panics by default: a surface the driver can't
/// reconfigure (D3D12 "Failed to wait for GPU to come idle", #1935) crashed the app. Native error
/// scopes resolve at once; on the web the scope still keeps the error from the handler.
pub fn capture_errors<T>(device: &wgpu::Device, f: impl FnOnce() -> T) -> (T, Option<wgpu::Error>) {
    let scopes = [
        wgpu::ErrorFilter::OutOfMemory,
        wgpu::ErrorFilter::Internal,
        wgpu::ErrorFilter::Validation,
    ]
    .map(|filter| device.push_error_scope(filter));
    let value = f();
    let mut failed = None;
    for scope in scopes.into_iter().rev() {
        let mut popped = std::pin::pin!(scope.pop());
        let mut cx = std::task::Context::from_waker(std::task::Waker::noop());
        if let std::task::Poll::Ready(Some(error)) =
            std::future::Future::poll(popped.as_mut(), &mut cx)
        {
            failed.get_or_insert(error);
        }
    }
    (value, failed)
}

/// SolidCraft: why a surface configure ([`configure_captured`]) left the surface without its
/// configuration.
#[derive(Debug)]
pub enum ConfigureError {
    /// The device refused it, with this error (#1935).
    Refused(wgpu::Error),
    /// The device was lost (#7007).
    DeviceLost,
    /// The adapter doesn't support the surface.
    Unsupported,
}

impl std::fmt::Display for ConfigureError {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        match self {
            Self::Refused(error) => error.fmt(f),
            Self::DeviceLost => f.write_str("the graphics device was lost"),
            Self::Unsupported => f.write_str("the surface isn't supported by this adapter"),
        }
    }
}

/// SolidCraft: run a surface configure on `device` under [`capture_errors`], and say whether the
/// surface has its configuration. A configure that meets a lost device reports nothing: wgpu
/// passes device-loss errors to no error scope and no handler, only to the lost callback. On
/// D3D12 a driver reset is found that way, when the configure waits for the present queue, after
/// wgpu has dropped the surface's old configuration. Taken as configured, the surface's next
/// acquire failed with "Surface is not configured for presentation", and the device's default
/// error handler panicked (#7007). `lost` is the device's [`DeviceLost`], marked by then.
pub fn configure_captured(
    device: &wgpu::Device,
    lost: &DeviceLost,
    configure: impl FnOnce(),
) -> Result<(), ConfigureError> {
    let ((), failed) = capture_errors(device, configure);
    if let Some(error) = failed {
        return Err(ConfigureError::Refused(error));
    }
    if lost.is_lost() {
        return Err(ConfigureError::DeviceLost);
    }
    Ok(())
}

/// SolidCraft: refused configures in a row after which the surface is recreated (#1935).
pub const SURFACE_RECREATE_AFTER: u32 = 3;

/// SolidCraft: a surface's streak of refused configures (#1935) and when the next try is due.
/// A refusal waits 16 ms, doubling with each refusal in a row up to 1 s, and every
/// [`SURFACE_RECREATE_AFTER`] refusals the surface is recreated before the next try. Until the
/// try is due, no configure or recreate happens however often the window repaints, so a device
/// that keeps refusing costs a try a second instead of one a frame. A configure the device takes
/// ends the streak, a recreate still pending included. The clock is passed in, for tests.
#[derive(Clone, Copy, Debug, Default, PartialEq, Eq)]
pub struct ConfigureRetry {
    failures: u32,
    due: Option<web_time::Instant>,
    /// The streak asked for a recreate that hasn't happened yet.
    recreate: bool,
}

/// SolidCraft: what follows a refused configure ([`ConfigureRetry::refused`]).
#[derive(Clone, Copy, Debug, PartialEq, Eq)]
pub struct RetryPlan {
    /// Refusals in a row, this one included.
    pub failures: u32,
    /// The first refusal of the streak: the one worth a warning.
    pub first: bool,
    /// How long until the next try.
    pub delay: std::time::Duration,
    /// This refusal asked for the surface to be recreated before the next try.
    pub recreate: bool,
}

impl ConfigureRetry {
    /// Refusals in a row so far.
    pub fn failures(&self) -> u32 {
        self.failures
    }

    /// How long until the next try is due at `now`; `None` when a configure may go ahead (no
    /// refusal pending, or its delay has passed).
    pub fn wait(&self, now: web_time::Instant) -> Option<std::time::Duration> {
        self.due
            .and_then(|due| due.checked_duration_since(now))
            .filter(|left| !left.is_zero())
    }

    /// Whether a configure (or recreate) may go ahead at `now`.
    pub fn is_due(&self, now: web_time::Instant) -> bool {
        self.wait(now).is_none()
    }

    /// Whether the streak asked for a recreate that hasn't happened yet.
    pub fn recreate_pending(&self) -> bool {
        self.recreate
    }

    /// Whether the surface should be recreated at `now`: a recreate is pending and its try is due.
    pub fn recreate_due(&self, now: web_time::Instant) -> bool {
        self.recreate && self.is_due(now)
    }

    /// The surface was recreated: no recreate is pending. The streak and its deadline stay.
    pub fn recreated(&mut self) {
        self.recreate = false;
    }

    /// The device refused a configure at `now`: the streak grows and the next try waits.
    pub fn refused(&mut self, now: web_time::Instant) -> RetryPlan {
        self.failures = self.failures.saturating_add(1);
        let doublings = self.failures.saturating_sub(1).min(6);
        let delay = std::time::Duration::from_millis((16u64 << doublings).min(1000));
        // A deadline past the clock's range can't happen in practice; it would make the try due.
        self.due = now.checked_add(delay);
        let recreate = self.failures % SURFACE_RECREATE_AFTER == 0;
        self.recreate |= recreate;
        RetryPlan {
            failures: self.failures,
            first: self.failures == 1,
            delay,
            recreate,
        }
    }

    /// The device took a configure: the streak ends, and a pending recreate with it. Returns how
    /// many refusals it had.
    pub fn took(&mut self) -> u32 {
        std::mem::take(self).failures
    }

    /// Runs `configure` at `now` unless a refused one's retry isn't due yet, and keeps the
    /// streak. The surface's configures all go through here, so an early repaint (input, an
    /// animation) can't bring a retry forward.
    pub fn attempt<E>(
        &mut self,
        now: web_time::Instant,
        configure: impl FnOnce() -> Result<(), E>,
    ) -> Attempt<E> {
        if let Some(left) = self.wait(now) {
            return Attempt::Waiting(left);
        }
        match configure() {
            Ok(()) => Attempt::Took(self.took()),
            Err(error) => Attempt::Refused(self.refused(now), error),
        }
    }
}

/// SolidCraft: what came of [`ConfigureRetry::attempt`].
#[derive(Debug)]
pub enum Attempt<E> {
    /// Not tried: the retry after a refusal is due in this long.
    Waiting(std::time::Duration),
    /// The configure was taken, after this many refusals in a row (0 when none).
    Took(u32),
    /// The configure was refused with this error; the plan says what follows.
    Refused(RetryPlan, E),
}

/// SolidCraft: the present mode a viewport's surface is configured with. The main window keeps
/// `configured`. Another window (the agent chat popped out into its own window) is an immediate
/// viewport: eframe draws and presents it inside the main window's frame, one surface after the
/// other. With vsync on both, every frame waited for the display twice, and on a compositor that
/// sends no frame callbacks to a window it isn't showing (Wayland: on another workspace, scrolled
/// away, covered) the main window stalled behind the other one's present. So another window
/// presents without waiting where its surface can (Mailbox, which doesn't tear, before
/// Immediate); the main window's vsync still paces both. A `configured` mode without vsync is
/// kept everywhere.
pub fn viewport_present_mode(
    root: bool,
    configured: wgpu::PresentMode,
    supported: &[wgpu::PresentMode],
) -> wgpu::PresentMode {
    use wgpu::PresentMode;
    let waits = matches!(
        configured,
        PresentMode::AutoVsync | PresentMode::Fifo | PresentMode::FifoRelaxed
    );
    if root || !waits {
        return configured;
    }
    [PresentMode::Mailbox, PresentMode::Immediate]
        .into_iter()
        .find(|mode| supported.contains(mode))
        .unwrap_or(configured)
}

/// SolidCraft: the surface size for a window of `width` x `height` pixels on a device whose
/// textures are at most `max_side` on a side, and the scale it is drawn at. A window that fits is
/// unchanged (scale 1); a larger one shrinks uniformly, keeping its aspect ratio, so the image
/// the compositor stretches back over the window is not distorted. Never zero on a side.
pub fn clamp_surface_extent(width: u32, height: u32, max_side: u32) -> (u32, u32, f32) {
    let max_side = max_side.max(1);
    let (width, height) = (width.max(1), height.max(1));
    let longest = width.max(height);
    if longest <= max_side {
        return (width, height, 1.0);
    }
    let scale = f64::from(max_side) / f64::from(longest);
    let fit = |side: u32| -> u32 {
        let scaled = (f64::from(side) * scale).floor() as u32;
        scaled.clamp(1, max_side)
    };
    let scale_f32 = scale as f32;
    (fit(width), fit(height), scale_f32)
}

#[cfg(test)]
mod device_lost_tests {
    /// A loss is marked once, with the first reason, and every clone (and the shared flag) sees it.
    #[test]
    fn a_marked_loss_is_seen_by_every_clone() {
        let lost = super::DeviceLost::default();
        let painter = lost.clone();
        let flag = lost.flag();
        assert!(!painter.is_lost() && lost.reason().is_none());
        lost.mark("Unknown: Device lost");
        lost.mark("Destroyed: ");
        assert!(painter.is_lost());
        assert!(flag.load(std::sync::atomic::Ordering::Acquire));
        assert_eq!(painter.reason().as_deref(), Some("Unknown: Device lost"));
    }

    /// A window's surface as wgpu-core treats the image of an acquired frame: a present or a
    /// discard gives it back only on a valid device, a destroy of the texture always (#7148).
    #[derive(Default)]
    struct Surface {
        lost: std::cell::Cell<bool>,
        image_held: std::cell::Cell<bool>,
        calls: std::cell::RefCell<Vec<&'static str>>,
    }

    impl Surface {
        fn call(&self, name: &'static str, gives_back: bool) {
            self.calls.borrow_mut().push(name);
            if gives_back {
                self.image_held.set(false);
            }
        }
    }

    /// A frame of [`Surface`]: discarded when dropped unpresented.
    struct Frame<'s> {
        surface: &'s Surface,
        presented: bool,
    }

    impl Drop for Frame<'_> {
        fn drop(&mut self) {
            if !self.presented {
                self.surface.call("discard", !self.surface.lost.get());
            }
        }
    }

    struct Texture<'s>(&'s Surface);

    impl super::FreeSurfaceTexture for Texture<'_> {
        fn free(&self) {
            self.0.call("free", true);
        }
    }

    #[derive(Clone, Copy, Debug)]
    enum End {
        Present,
        Drop,
        Panic,
    }

    /// Acquire a frame from `surface` and end it as `end`.
    fn run_frame(surface: &Surface, end: End) {
        surface.image_held.set(true);
        let frame = super::AcquiredFrame::new(
            Frame {
                surface,
                presented: false,
            },
            Texture(surface),
        );
        match end {
            End::Present => frame.present(|mut frame| {
                frame.presented = true;
                surface.call("present", !surface.lost.get());
            }),
            End::Drop => drop(frame),
            End::Panic => {
                let unwound = std::panic::catch_unwind(std::panic::AssertUnwindSafe(move || {
                    let _frame = frame;
                    panic!("a paint callback panics while the frame is held");
                }));
                assert!(unwound.is_err());
            }
        }
    }

    /// However a frame ends, on a valid or a lost device, the surface has its image back by the
    /// time the frame is gone, so dropping or reconfiguring the surface can't meet a semaphore
    /// still in use (#7148). The texture is freed only after the present or discard: freed first,
    /// a valid device's present or discard would find it destroyed.
    #[test]
    fn a_frame_gives_its_image_back_however_it_ends_even_on_a_lost_device() {
        for lost in [false, true] {
            for end in [End::Present, End::Drop, End::Panic] {
                let surface = Surface::default();
                surface.lost.set(lost);
                run_frame(&surface, end);
                let first = if matches!(end, End::Present) {
                    "present"
                } else {
                    "discard"
                };
                assert_eq!(
                    *surface.calls.borrow(),
                    [first, "free"],
                    "lost {lost}, {end:?}"
                );
                assert!(!surface.image_held.get(), "lost {lost}, {end:?}");
            }
        }
    }
}