molgfx_gpu/
error.rs

1//! Typed GPU errors with stable registry codes.
2//!
3//! A lost device or surface is a recoverable state the caller handles as a
4//! value; nothing in the engine panics on a condition a caller could hit.
5
6use crate::surface::SurfaceError;
7use thiserror::Error;
8
9/// Everything that can go wrong opening or driving a device.
10#[derive(Debug, Error)]
11#[non_exhaustive]
12pub enum GpuError {
13    /// No adapter satisfied the device request.
14    #[error("no compatible GPU adapter found: {detail}")]
15    NoAdapter {
16        /// Backend selection diagnostics supplied by the active HAL.
17        detail: String,
18    },
19
20    /// A window or canvas could not be converted into a presentation surface.
21    #[error("GPU presentation surface creation failed: {detail}")]
22    SurfaceCreation {
23        /// Backend-reported creation failure.
24        detail: String,
25    },
26
27    /// An adapter was found but opening its logical device failed.
28    #[error("GPU device request failed: {detail}")]
29    DeviceRequest {
30        /// Backend-reported device negotiation failure.
31        detail: String,
32    },
33
34    /// The device was lost; recreate and retry.
35    #[error("device lost")]
36    DeviceLost,
37
38    /// The presentation surface is unavailable; reconfigure and skip the
39    /// frame.
40    #[error("surface unavailable")]
41    Surface(#[from] SurfaceError),
42
43    /// A requested capability is unavailable and no fallback applies.
44    #[error("capability {name:?} unavailable")]
45    Capability {
46        /// The capability that was required.
47        name: &'static str,
48    },
49
50    /// A requested resource exceeds a reported portable device limit.
51    #[error("resource {resource:?} exceeds device limit {limit}")]
52    LimitExceeded {
53        /// Resource class that exceeded the limit.
54        resource: &'static str,
55        /// Reported device ceiling.
56        limit: u64,
57    },
58
59    /// A shader failed to compile on this backend.
60    #[error("shader compilation failed in {label:?}: {detail}")]
61    ShaderCompile {
62        /// Which shader module.
63        label: String,
64        /// Backend-reported detail, including stage and location where
65        /// available.
66        detail: String,
67    },
68
69    /// A GPU operation failed validation or exhausted backend resources.
70    #[error("GPU runtime operation failed: {detail}")]
71    Runtime {
72        /// The first backend diagnostic, retained before secondary failures.
73        detail: String,
74    },
75}
76
77impl GpuError {
78    /// The stable registry code for this condition.
79    #[must_use]
80    pub fn code(&self) -> &'static str {
81        match self {
82            Self::NoAdapter { .. } => "MOLGFX-E0001",
83            Self::SurfaceCreation { .. } => "MOLGFX-E0004",
84            Self::DeviceRequest { .. } => "MOLGFX-E0005",
85            Self::DeviceLost => "MOLGFX-E0002",
86            Self::Surface(_) => "MOLGFX-E0003",
87            Self::Capability { .. } => "MOLGFX-E0010",
88            Self::LimitExceeded { .. } => "MOLGFX-E0011",
89            Self::ShaderCompile { .. } => "MOLGFX-E0060",
90            Self::Runtime { .. } => "MOLGFX-E0061",
91        }
92    }
93}
94
95#[cfg(test)]
96#[path = "error_tests.rs"]
97mod tests;
molgfx_gpu/error.rs

molgfx_gpu/
error.rs
