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}