dear_imgui_rs/texture/
error.rs

1use thiserror::Error;
2
3use super::{ManagedTextureId, TextureRegion, TextureStatus};
4use crate::ContextId;
5
6/// Validation failure while creating or mutating CPU-side texture data.
7#[derive(Clone, Copy, Debug, Eq, Error, PartialEq)]
8#[non_exhaustive]
9pub enum TextureDataError {
10    /// Width or height was zero.
11    #[error("texture dimensions must be positive (got {width}x{height})")]
12    InvalidDimensions {
13        /// Requested texture width.
14        width: u32,
15        /// Requested texture height.
16        height: u32,
17    },
18
19    /// Width does not fit Dear ImGui's signed native dimension field.
20    #[error("texture width {0} exceeds Dear ImGui's signed dimension range")]
21    WidthOutOfRange(u32),
22
23    /// Height does not fit Dear ImGui's signed native dimension field.
24    #[error("texture height {0} exceeds Dear ImGui's signed dimension range")]
25    HeightOutOfRange(u32),
26
27    /// The native allocation size overflowed or exceeded its signed size limit.
28    #[error(
29        "texture byte size is not representable: {width}x{height} pixels at {bytes_per_pixel} bytes per pixel"
30    )]
31    ByteSizeOutOfRange {
32        /// Texture width.
33        width: u32,
34        /// Texture height.
35        height: u32,
36        /// Bytes per pixel.
37        bytes_per_pixel: usize,
38    },
39
40    /// Native metadata is not a valid texture layout.
41    #[error(
42        "texture metadata is invalid: width={width}, height={height}, bytes_per_pixel={bytes_per_pixel}"
43    )]
44    InvalidLayout {
45        /// Native width.
46        width: i32,
47        /// Native height.
48        height: i32,
49        /// Native bytes per pixel.
50        bytes_per_pixel: i32,
51    },
52
53    /// The supplied payload does not exactly match the requested byte contract.
54    #[error("texture payload length mismatch: expected {expected} bytes, got {actual}")]
55    ByteLengthMismatch {
56        /// Required payload length.
57        expected: usize,
58        /// Supplied payload length.
59        actual: usize,
60    },
61
62    /// Pixel mutation is unavailable in the `WantDestroy` or `Destroyed` lifecycle state.
63    #[error("texture cannot be mutated while its status is {0:?}")]
64    InvalidStatus(TextureStatus),
65
66    /// A live texture does not have CPU-side pixel storage.
67    #[error("texture status {0:?} has no CPU pixel storage")]
68    MissingPixelStorage(TextureStatus),
69
70    /// The full texture cannot be represented by Dear ImGui's 16-bit update rectangle.
71    #[error("full texture update {width}x{height} cannot be represented by TextureRect")]
72    FullUpdateRectOutOfRange {
73        /// Texture width.
74        width: u32,
75        /// Texture height.
76        height: u32,
77    },
78
79    /// A subresource region has a zero width or height.
80    #[error("texture update region dimensions must be positive (got {width}x{height})")]
81    InvalidRegionDimensions {
82        /// Requested region width.
83        width: u32,
84        /// Requested region height.
85        height: u32,
86    },
87
88    /// A subresource rectangle exceeds the texture bounds.
89    #[error("texture update region {region:?} exceeds texture bounds {width}x{height}")]
90    UpdateRegionOutOfBounds {
91        /// Requested region.
92        region: TextureRegion,
93        /// Texture width.
94        width: u32,
95        /// Texture height.
96        height: u32,
97    },
98
99    /// A live update region cannot be represented by Dear ImGui's native update queue.
100    #[error("texture update region cannot be represented by the native update queue: {0:?}")]
101    UpdateRegionNotRepresentable(TextureRegion),
102
103    /// The supplied row pitch cannot hold one tightly packed source row.
104    #[error("texture row pitch {actual} is smaller than the required {minimum} bytes")]
105    RowPitchTooSmall {
106        /// Minimum tightly packed row size.
107        minimum: usize,
108        /// Supplied row pitch.
109        actual: usize,
110    },
111
112    /// Computing the strided payload size overflowed.
113    #[error(
114        "texture subresource payload size overflowed for row pitch {row_pitch} and height {height}"
115    )]
116    PayloadSizeOutOfRange {
117        /// Supplied row pitch.
118        row_pitch: usize,
119        /// Rectangle height.
120        height: u32,
121    },
122}
123
124/// Failure to access or retire a Context-owned managed texture.
125#[derive(Clone, Copy, Debug, Eq, Error, PartialEq)]
126#[non_exhaustive]
127pub enum ManagedTextureError {
128    /// The handle belongs to another Context.
129    #[error("managed texture belongs to Context {actual:?}, not Context {expected:?}")]
130    ForeignContext {
131        /// Context used for the attempted operation.
132        expected: ContextId,
133        /// Context encoded in the handle.
134        actual: ContextId,
135    },
136
137    /// The handle does not identify a slot allocated by this Context.
138    #[error("managed texture handle has an unknown slot: {0:?}")]
139    UnknownSlot(ManagedTextureId),
140
141    /// The slot has been reused for a newer texture generation.
142    #[error("managed texture handle has a stale generation: {0:?}")]
143    StaleGeneration(ManagedTextureId),
144
145    /// Removal has started and new drawing or mutation is no longer accepted.
146    #[error("managed texture is retiring: {0:?}")]
147    Retiring(ManagedTextureId),
148
149    /// Removal was already requested and is waiting for renderer retirement.
150    #[error("managed texture removal was already requested: {0:?}")]
151    AlreadyRetiring(ManagedTextureId),
152
153    /// The texture was already fully removed.
154    #[error("managed texture was already removed: {0:?}")]
155    AlreadyRemoved(ManagedTextureId),
156
157    /// An atlas-backed texture was used with a Context that does not own that atlas.
158    #[error("font-atlas texture belongs to a different Context atlas")]
159    ForeignFontAtlas,
160
161    /// One feedback batch addressed the same texture more than once.
162    #[error("managed texture feedback contains a duplicate handle: {0:?}")]
163    DuplicateFeedback(ManagedTextureId),
164
165    /// Renderer feedback may acknowledge only an uploaded or destroyed texture.
166    #[error("managed texture feedback for {id:?} used invalid status {status:?}")]
167    InvalidFeedbackStatus {
168        /// Texture addressed by the feedback.
169        id: ManagedTextureId,
170        /// Status rejected before native mutation.
171        status: TextureStatus,
172    },
173}
174
175/// Failure to access or mutate a Context-owned texture.
176#[derive(Clone, Copy, Debug, Eq, Error, PartialEq)]
177#[non_exhaustive]
178pub enum ManagedTextureMutationError {
179    /// The managed handle could not be accessed.
180    #[error(transparent)]
181    Access(#[from] ManagedTextureError),
182
183    /// The requested pixel mutation was invalid.
184    #[error(transparent)]
185    Data(#[from] TextureDataError),
186}
dear_imgui_rs/texture/error.rs

dear_imgui_rs/texture/
error.rs
