Skip to main content

sgl_3d/scene/
error.rs

1//! Why a `Scene` operation refused its input. A refused operation changes
2//! nothing.
3use crate::baked_specular_probe::ProbeError;
4
5/// A `Scene` operation's refusal.
6#[derive(Debug)]
7pub enum SceneError {
8    /// The material was removed, or another scene issued its identity.
9    UnknownMaterial,
10    /// The model was removed, or another scene issued its identity.
11    UnknownModel,
12    /// The instance was removed, or another scene issued its identity.
13    UnknownInstance,
14    /// The light was removed, or another scene issued its identity.
15    UnknownLight,
16    /// The environment was removed, or another scene issued its identity.
17    UnknownEnvironment,
18    /// The decal was removed, or another scene issued its identity.
19    UnknownDecal,
20    /// The decal image was removed, or another scene issued its identity.
21    UnknownDecalImage,
22    /// A model's mesh uses the material.
23    MaterialInUse,
24    /// An instance uses the model, or it is a level of detail of a mesh.
25    ModelInUse,
26    /// A decal uses the decal image, or a light projects it as its cookie.
27    DecalImageInUse,
28    /// A material names an image index beyond the images added with it.
29    MissingImage,
30    /// An asset's mesh names a material index beyond the asset's materials.
31    MissingMaterial,
32    /// The model has no mesh at that index.
33    MissingMesh,
34    /// An image has no texels.
35    EmptyImage,
36    /// An ETC2/ASTC image needs decoded level 0 for material ray sampling
37    /// or the CPU decal atlas, but supplied none.
38    MissingDecodedImage,
39    /// A prepared model's ray-data capability differs from this scene's.
40    RayDataMismatch,
41    /// A compressed image's sides are not multiples of its block size or
42    /// exceed 16384, or it holds no level, more than a full chain, or a level
43    /// of the wrong size; an ETC2/ASTC decoded companion must match level 0,
44    /// whereas BC7 must not carry a companion.
45    InvalidCompressedImage,
46    /// A compressed image that materials sample as both sRGB colour and
47    /// linear data needs `DownlevelFlags::VIEW_FORMATS`, which wgpu's GL
48    /// backend lacks.
49    CompressedImageViews,
50    /// A mesh index names no vertex of its mesh.
51    IndexOutOfRange,
52    /// A vertex position, UV or lightmap UV is not finite, a mesh's UVs span
53    /// more than `f32` holds, or a vertex normal is zero or not finite.
54    NonFiniteGeometry,
55    /// A mesh's vertices name more than 65,536 distinct lightmap chart
56    /// bounds (`Vertex::lightmap_bounds`). `mesh` is its index among the
57    /// model's meshes, an asset's mesh index through `Scene::add_asset`.
58    TooManyLightmapCharts { mesh: usize },
59    /// A pose is not finite or not invertible.
60    InvalidPose,
61    /// A material's metallic, roughness, clearcoat, clearcoat roughness or
62    /// base alpha is outside 0..=1, or a channel of its base colour or
63    /// emission or its environment scale is negative or not finite.
64    /// Also returned for a non-finite normal, coat-normal or bump scale.
65    InvalidMaterialFactors,
66    /// Anisotropy strength is outside 0..=1 or its rotation is not finite.
67    InvalidAnisotropy,
68    /// An anisotropic material's mesh lacks authored tangent frames.
69    MissingAnisotropyTangents,
70    /// A masked material's alpha cutoff is not finite and nonnegative.
71    InvalidAlphaCutoff,
72    /// A material's IOR is below 1 or NaN, its specular strength outside
73    /// 0..=1, or a channel of its specular colour not finite and
74    /// nonnegative.
75    InvalidReflectance,
76    /// A material's occlusion strength is outside 0..=1.
77    InvalidOcclusion,
78    /// A material's iridescence is outside 0..=1, its film's IOR below 1 or
79    /// not finite, or a film thickness negative or not finite.
80    InvalidIridescence,
81    /// A material's transmission is outside 0..=1 or set on an unlit
82    /// material, its thickness or dispersion is negative or not finite, its
83    /// attenuation distance is not positive, or an attenuation colour
84    /// channel is outside 0..=1.
85    InvalidTransmission,
86    /// A material's sheen colour or sheen roughness is outside 0..=1.
87    InvalidSheen,
88    /// A material's diffuse transmission is outside 0..=1, or its colour is
89    /// negative or not finite.
90    InvalidDiffuseTransmission,
91    /// A material's normal layers have a velocity, scale or strength that is
92    /// not finite, a scale that is not positive or a speed beyond 2^24
93    /// repeats of the map per hour, or the material has no normal map that
94    /// repeats on both axes for them to scroll.
95    InvalidNormalLayers,
96    /// A level of detail's error is not finite and nonnegative.
97    InvalidLod,
98    /// A mesh is given more alternatives than `lod::MAX_MESH_LODS`.
99    TooManyLods,
100    /// A mesh holds more than 65,536 sections of 128 triangles (8,388,608
101    /// triangles), the most a GPU-built draw list culls a mesh by.
102    TooManySections,
103    /// A level of detail names a mesh of the model it details, which draws
104    /// all its meshes.
105    LodInSameModel,
106    /// An ambient cube was given to a static instance, which takes baked
107    /// diffuse light from lightmap charts and the irradiance atlas.
108    StaticInstance,
109    /// A light's position, colour, intensity, range or specular scale is
110    /// not finite, or not positive where it must be, its shadow opacity is
111    /// outside 0..=1, a spot's direction is zero or its angles are not
112    /// `0 <= inner <= outer < π/2`, or it has a cookie but is not a spot of
113    /// a positive outer angle, or the cookie's `up` has no finite part
114    /// across the spot's direction.
115    InvalidLight,
116    /// A decal's position, rotation or size is not finite, its size not
117    /// positive, or its colour, mix or fades outside their ranges.
118    InvalidDecal,
119    /// A PMREM atlas's texels do not match its dimensions.
120    InvalidEnvironmentMap,
121    /// A lightmap's texels do not match its size, or its UV scale/offset is
122    /// not finite.
123    InvalidLightmap,
124    /// Directionality neither is empty nor matches its chart with finite
125    /// [0, 1] lobes, or it holds a lobe that rounds to the reserved all-zero
126    /// RGBA8 lobe.
127    InvalidDirectionality,
128    /// An irradiance atlas's layers do not match its size (for a compressed
129    /// atlas, nonzero multiples of 4).
130    InvalidIrradianceAtlas,
131    /// Irradiance outside the finite nonnegative RGBA16F range, or a
132    /// compressed atlas's scale that is not finite and nonnegative.
133    InvalidIrradiance,
134    /// The device lacks the image format’s BC, ETC2 or ASTC compression feature.
135    CompressionUnsupported,
136    /// Heat geometry is not a triangle list of at most
137    /// `heat_distortion::MAX_VERTICES` vertices.
138    HeatVertexCount,
139    /// A heat vertex's position is not finite, its displacement not within
140    /// `heat_distortion::MAX_DISPLACEMENT_PIXELS` or its weight not in 0..=1.
141    InvalidHeatVertex,
142    /// A fog volume's centre, rotation or size is not finite, its rotation is
143    /// zero, its size not positive, or its density, albedo or edge fade
144    /// negative or not finite.
145    InvalidFogVolume,
146    /// A mesh's influences or morph targets do not match its vertices, a
147    /// vertex's weights are not finite and nonnegative with a finite positive sum,
148    /// a displacement is not finite, a joint or morph weight index is above
149    /// 65535, or the mesh has more than 256 morph targets.
150    InvalidDeformation,
151    /// The instance's model does not deform, or its joint matrices or morph
152    /// weights are fewer than its model takes, or not finite.
153    DeformationMismatch,
154    /// A deforming model's instances move and keep their model, and it
155    /// takes no part in levels of detail.
156    DeformingModel,
157    /// A render origin (`Scene::move_origin`) is not finite.
158    InvalidOrigin,
159    /// A dynamic GI volume's origin or spacing is not finite, its spacing
160    /// not positive, or it has fewer than two probes along an axis.
161    InvalidDynamicGiVolume,
162    /// An irradiance volume's origin or cell size is not finite, its cell
163    /// size not positive, or it has no cell along an axis.
164    InvalidIrradianceVolume,
165    /// A prepared irradiance region's corner is not finite, it has no cell
166    /// along an axis, its values are not one per cell, or a value's light is
167    /// not finite, nonnegative and within RGBA16F range or its sky
168    /// visibility not within 0..=1.
169    InvalidIrradianceRegion,
170    /// No irradiance volume is installed, or an irradiance region's corner
171    /// is off its lattice or the region not wholly within it.
172    IrradianceRegionOutside,
173    /// The shader was removed, or another scene issued its identity; or a
174    /// material names such a shader.
175    UnknownShader,
176    /// A material names the shader.
177    ShaderInUse,
178    /// `Scene::set_shader_parameters` was given `given` bytes for a
179    /// material whose shader's `ShaderParams` takes `expected`, 0 for a
180    /// material without a shader.
181    ShaderParameters { expected: u32, given: u32 },
182    /// `Scene::add_shader` refused the module.
183    Shader(crate::shader::ShaderError),
184    /// A material's shader's displacement bound is not finite and
185    /// nonnegative.
186    InvalidDisplacementBound,
187    /// Mesh `mesh`'s shader data is neither empty nor one entry per vertex,
188    /// or no data was given for it (`PreparedModel::with_shader_data`).
189    ShaderDataLength { mesh: usize },
190    /// The content would exceed a limit of the device.
191    DeviceLimit,
192    /// The specular probe collection was refused.
193    Probe(ProbeError),
194}
195
196impl std::fmt::Display for SceneError {
197    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
198        f.write_str(match self {
199            Self::UnknownMaterial => "the material is not in this scene",
200            Self::UnknownModel => "the model is not in this scene",
201            Self::UnknownInstance => "the instance is not in this scene",
202            Self::UnknownLight => "the light is not in this scene",
203            Self::UnknownEnvironment => "the environment is not in this scene",
204            Self::UnknownDecal => "the decal is not in this scene",
205            Self::UnknownDecalImage => "the decal image is not in this scene",
206            Self::MaterialInUse => "a model's mesh uses the material",
207            Self::ModelInUse => "an instance uses the model, or it is a level of detail",
208            Self::DecalImageInUse => "a decal or a light's cookie uses the decal image",
209            Self::MissingImage => "a material names an image that was not added with it",
210            Self::MissingMaterial => "a mesh names a material the asset does not have",
211            Self::MissingMesh => "the model has no mesh at that index",
212            Self::EmptyImage => "an image has no texels",
213            Self::MissingDecodedImage => "ETC2/ASTC material rays and decals need a matching decoded level 0 companion",
214            Self::RayDataMismatch => "the prepared model and scene must use the same ray-data capability",
215            Self::CompressedImageViews => {
216                "a compressed image sampled as both colour and data needs DownlevelFlags::VIEW_FORMATS"
217            }
218            Self::InvalidCompressedImage => {
219                "a compressed image needs sides that are multiples of its block size, at most 16384, and one to a full chain of levels, each of its size; any ETC2/ASTC decoded companion must match level 0, BC7 needs none"
220            }
221            Self::IndexOutOfRange => "a mesh index names no vertex",
222            Self::NonFiniteGeometry => {
223                "vertex positions, UVs and lightmap UVs must be finite, a mesh's UVs span a finite extent, and normals finite and not zero"
224            }
225            Self::TooManyLightmapCharts { mesh } => {
226                return write!(
227                    f,
228                    "mesh {mesh}'s vertices may name at most 65536 distinct lightmap chart bounds"
229                );
230            }
231            Self::InvalidPose => "a pose must be finite and invertible",
232            Self::InvalidMaterialFactors => {
233                "metallic, roughness, clearcoat, clearcoat roughness and base alpha must be in 0..1, base colour, emission and environment scale finite and nonnegative, and normal, coat-normal and bump scales finite"
234            }
235            Self::InvalidAnisotropy => {
236                "anisotropy strength must be finite in 0..1 and rotation finite"
237            }
238            Self::MissingAnisotropyTangents => {
239                "anisotropy requires authored nonzero tangent frames on every mesh using this material"
240            }
241            Self::InvalidAlphaCutoff => "an alpha cutoff must be finite and nonnegative",
242            Self::InvalidReflectance => {
243                "IOR must be at least 1 (infinity allowed), specular in 0..1 and specular colour finite and nonnegative"
244            }
245            Self::InvalidOcclusion => "occlusion strength must be in 0..1",
246            Self::InvalidIridescence => {
247                "iridescence must be in 0..1, its film IOR finite and at least 1 and its thicknesses finite and nonnegative"
248            }
249            Self::InvalidTransmission => {
250                "transmission must be in 0..1 on a lit material, thickness and dispersion finite and nonnegative, attenuation distance positive and attenuation colour in 0..1"
251            }
252            Self::InvalidSheen => "sheen colour and sheen roughness must be in 0..1",
253            Self::InvalidDiffuseTransmission => {
254                "diffuse transmission must be in 0..1 and its colour finite and nonnegative"
255            }
256            Self::InvalidNormalLayers => {
257                "normal layers need finite velocities and strengths, positive finite scales, at most 2^24 repeats per hour and a normal map that repeats on both axes"
258            }
259            Self::InvalidLod => "LOD error must be finite and nonnegative",
260            Self::TooManyLods => "a mesh takes at most 8 levels of detail",
261            Self::TooManySections => "a mesh holds at most 65,536 sections of 128 triangles",
262            Self::LodInSameModel => "a level of detail must be a mesh of another model",
263            Self::StaticInstance => {
264                "a static instance takes baked light from charts, not an ambient cube"
265            }
266            Self::InvalidLight => {
267                "a light needs a finite position, nonnegative colour, intensity and specular scale, a shadow opacity in 0..=1, a positive range, a spot a nonzero direction with 0 <= inner <= outer < pi/2, and a cookie a spot of positive outer angle and an up not parallel to its direction"
268            }
269            Self::InvalidDecal => {
270                "a decal needs a finite pose, a positive size, and colour, mix and fades in range"
271            }
272            Self::InvalidEnvironmentMap => {
273                "PMREM atlas dimensions do not match its RGBA16F data"
274            }
275            Self::InvalidLightmap => "static lightmap dimensions do not match its texels or its UV scale/offset is not finite",
276            Self::InvalidDirectionality => {
277                "directionality must be empty or match the chart with finite [0,1] lobes; a lobe that rounds to all-zero RGBA8 is reserved"
278            }
279            Self::InvalidIrradianceAtlas => {
280                "irradiance atlas layers do not match its size; compressed sizes are nonzero multiples of 4"
281            }
282            Self::InvalidIrradiance => {
283                "irradiance and its scale must be finite, nonnegative and within RGBA16F range"
284            }
285            Self::CompressionUnsupported => {
286                "compressed content needs its matching BC, ETC2 or ASTC device feature"
287            }
288            Self::HeatVertexCount => {
289                "heat geometry must be a triangle list of at most 6144 vertices"
290            }
291            Self::InvalidHeatVertex => {
292                "heat vertices require finite positions, displacement within +/-32 pixels and weight in 0..=1"
293            }
294            Self::InvalidFogVolume => {
295                "fog volumes require a finite centre and rotation, a positive size and finite nonnegative density, albedo and edge fade"
296            }
297            Self::InvalidDeformation => {
298                "influences and morph targets must match their mesh's vertices, with finite nonnegative weights of finite positive sum, finite displacements, indices of at most 65535 and at most 256 morph targets a mesh"
299            }
300            Self::DeformationMismatch => {
301                "a deformation needs a deforming instance and at least as many finite joint matrices and morph weights as its model takes"
302            }
303            Self::DeformingModel => {
304                "a deforming model's instances move and keep their model, and it takes no part in levels of detail"
305            }
306            Self::InvalidOrigin => "a render origin must be finite",
307            Self::InvalidDynamicGiVolume => {
308                "a dynamic GI volume needs a finite origin, a finite positive spacing and at least two probes along each axis"
309            }
310            Self::InvalidIrradianceVolume => {
311                "an irradiance volume needs a finite origin, a finite positive cell size and at least one cell along each axis"
312            }
313            Self::InvalidIrradianceRegion => {
314                "an irradiance region needs a finite corner, at least one cell along each axis and one valid cell value per cell: finite nonnegative light within RGBA16F range and sky visibility in 0..=1"
315            }
316            Self::IrradianceRegionOutside => {
317                "an irradiance region must lie on the installed irradiance volume's lattice and wholly within it"
318            }
319            Self::UnknownShader => "the shader is not in this scene",
320            Self::ShaderInUse => "a material names the shader",
321            Self::ShaderParameters { expected, given } => {
322                return write!(
323                    f,
324                    "the material's shader parameters take {expected} bytes, not {given}"
325                );
326            }
327            Self::Shader(error) => return error.fmt(f),
328            Self::InvalidDisplacementBound => {
329                "a shader's displacement bound must be finite and nonnegative"
330            }
331            Self::ShaderDataLength { mesh } => {
332                return write!(
333                    f,
334                    "mesh {mesh}'s shader data must be empty or one entry per vertex"
335                );
336            }
337            Self::DeviceLimit => "the content exceeds a limit of the device",
338            Self::Probe(error) => return error.fmt(f),
339        })
340    }
341}
342
343impl std::error::Error for SceneError {
344    fn source(&self) -> Option<&(dyn std::error::Error + 'static)> {
345        match self {
346            Self::Probe(error) => Some(error),
347            Self::Shader(error) => Some(error),
348            _ => None,
349        }
350    }
351}
352
353impl From<crate::shader::ShaderError> for SceneError {
354    fn from(error: crate::shader::ShaderError) -> Self {
355        Self::Shader(error)
356    }
357}
358
359impl From<ProbeError> for SceneError {
360    fn from(error: ProbeError) -> Self {
361        Self::Probe(error)
362    }
363}