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 host-supplied device cannot run the renderer.
70    #[error("host GPU context is missing: {}", missing.join("; "))]
71    HostRequirements {
72        /// Every unmet requirement, one sentence each, naming the feature,
73        /// limit or format capability.
74        missing: Vec<String>,
75    },
76
77    /// A host-supplied texture cannot be rendered into.
78    #[error("host texture is unusable: {}", problems.join("; "))]
79    HostTarget {
80        /// Every problem found, one sentence each.
81        problems: Vec<String>,
82    },
83
84    /// A GPU operation failed validation or exhausted backend resources.
85    #[error("GPU runtime operation failed: {detail}")]
86    Runtime {
87        /// The first backend diagnostic, retained before secondary failures.
88        detail: String,
89    },
90}
91
92impl GpuError {
93    /// The stable registry code for this condition.
94    #[must_use]
95    pub fn code(&self) -> &'static str {
96        match self {
97            Self::NoAdapter { .. } => "MOLGFX-E0001",
98            Self::SurfaceCreation { .. } => "MOLGFX-E0004",
99            Self::DeviceRequest { .. } => "MOLGFX-E0005",
100            Self::DeviceLost => "MOLGFX-E0002",
101            Self::Surface(_) => "MOLGFX-E0003",
102            Self::Capability { .. } => "MOLGFX-E0010",
103            Self::LimitExceeded { .. } => "MOLGFX-E0011",
104            Self::HostRequirements { .. } => "MOLGFX-E0012",
105            Self::HostTarget { .. } => "MOLGFX-E0013",
106            Self::ShaderCompile { .. } => "MOLGFX-E0060",
107            Self::Runtime { .. } => "MOLGFX-E0061",
108        }
109    }
110}
111
112#[cfg(test)]
113#[path = "error_tests.rs"]
114mod tests;
molgfx_gpu/error.rs

molgfx_gpu/
error.rs
