cotis-wgpu 0.1.0-alpha

//! Initialization and presentation errors for the wgpu backend.
//!
//! Errors from [`WgpuBackendError`] fall into two categories:
//!
//! - **Startup failures** returned by [`crate::renderer::CotisWgpuRenderer::new`] and
//!   [`crate::renderer::CotisWgpuRenderer::new_with_config`] — no adapter, surface creation,
//!   event loop, or device request failures.
//! - **Per-frame surface errors** returned internally during swapchain acquisition; these are
//!   typically logged and the frame is skipped rather than propagated to application code.

use std::error::Error;
use std::fmt::{Display, Formatter};

/// Errors that can occur while initializing or presenting through wgpu.
///
/// # Examples
///
/// ```
/// use cotis_wgpu::WgpuBackendError;
///
/// assert_eq!(
///     WgpuBackendError::NoAdapter.to_string(),
///     "no compatible wgpu adapter found"
/// );
/// assert_eq!(
///     WgpuBackendError::Init("window closed".into()).to_string(),
///     "failed to initialize renderer: window closed"
/// );
/// ```
#[derive(Debug)]
pub enum WgpuBackendError {
    /// No compatible GPU adapter was found during GPU device initialization.
    ///
    /// Occurs when wgpu cannot enumerate a suitable adapter for the current platform.
    NoAdapter,
    /// Failed to create the window surface from the winit window handle.
    ///
    /// Returned by [`crate::surface::SurfaceState::new`] when `create_surface_unsafe` fails.
    CreateSurface(String),
    /// Failed to initialize the winit event loop or create the window.
    ///
    /// Also returned when the window is closed before bootstrap completes.
    Init(String),
    /// Failed to request a logical device and queue from the adapter.
    ///
    /// Occurs when wgpu `request_device` fails during startup.
    RequestDevice(String),
    /// The swapchain surface reported an error while acquiring or presenting a frame.
    ///
    /// [`crate::surface::SurfaceState::acquire_frame`] retries once on
    /// [`wgpu::SurfaceError::Lost`] or [`wgpu::SurfaceError::Outdated`] after reconfiguring.
    Surface(wgpu::SurfaceError),
}

impl Display for WgpuBackendError {
    fn fmt(&self, f: &mut Formatter<'_>) -> std::fmt::Result {
        match self {
            Self::NoAdapter => write!(f, "no compatible wgpu adapter found"),
            Self::CreateSurface(message) => write!(f, "failed to create surface: {message}"),
            Self::Init(message) => write!(f, "failed to initialize renderer: {message}"),
            Self::RequestDevice(message) => write!(f, "failed to request device: {message}"),
            Self::Surface(error) => write!(f, "surface error: {error}"),
        }
    }
}

impl Error for WgpuBackendError {}