1use alloc::{boxed::Box, sync::Arc, vec::Vec};
12
13#[cfg(feature = "serde")]
14use macro_rules_attribute::apply;
15use thiserror::Error;
16use wgt::{
17 error::{ErrorType, WebGpuError},
18 AccelerationStructureGeometryFlags, BufferAddress, IndexFormat, VertexFormat,
19};
20
21#[cfg(feature = "serde")]
22use crate::command::serde_object_reference_struct;
23use crate::{
24 command::{ArcReferences, EncoderStateError, ReferenceType},
25 device::{DeviceError, MissingFeatures},
26 resource::{
27 self, Blas, BlasCompactCallback, BlasPrepareCompactResult, DestroyedResourceError,
28 InvalidResourceError, MissingBufferUsageError, ResourceErrorIdent, Tlas,
29 },
30};
31
32#[derive(Clone, Debug, Error)]
33pub enum CreateBlasError {
34 #[error(transparent)]
35 Device(#[from] DeviceError),
36 #[error(transparent)]
37 MissingFeatures(#[from] MissingFeatures),
38 #[error(
39 "Only one of 'index_count' and 'index_format' was provided (either provide both or none)"
40 )]
41 MissingIndexData,
42 #[error("Provided format was not within allowed formats. Provided format: {0:?}. Allowed formats: {1:?}")]
43 InvalidVertexFormat(VertexFormat, Vec<VertexFormat>),
44 #[error("Limit `max_blas_geometry_count` is {0}, but the BLAS had {1} geometries")]
45 TooManyGeometries(u32, u32),
46 #[error(
47 "Limit `max_blas_primitive_count` is {0}, but the BLAS had a maximum of {1} primitives"
48 )]
49 TooManyPrimitives(u32, u32),
50}
51
52impl WebGpuError for CreateBlasError {
53 fn webgpu_error_type(&self) -> ErrorType {
54 match self {
55 Self::Device(e) => e.webgpu_error_type(),
56 Self::MissingFeatures(e) => e.webgpu_error_type(),
57 Self::MissingIndexData
58 | Self::InvalidVertexFormat(..)
59 | Self::TooManyGeometries(..)
60 | Self::TooManyPrimitives(..) => ErrorType::Validation,
61 }
62 }
63}
64
65#[derive(Clone, Debug, Error)]
66pub enum CreateTlasError {
67 #[error(transparent)]
68 Device(#[from] DeviceError),
69 #[error(transparent)]
70 MissingFeatures(#[from] MissingFeatures),
71 #[error("Flag {0:?} is not allowed on a TLAS")]
72 DisallowedFlag(wgt::AccelerationStructureFlags),
73 #[error("Limit `max_tlas_instance_count` is {0}, but the TLAS had a maximum of {1} instances")]
74 TooManyInstances(u32, u32),
75}
76
77impl WebGpuError for CreateTlasError {
78 fn webgpu_error_type(&self) -> ErrorType {
79 match self {
80 Self::Device(e) => e.webgpu_error_type(),
81 Self::MissingFeatures(e) => e.webgpu_error_type(),
82 Self::DisallowedFlag(..) | Self::TooManyInstances(..) => ErrorType::Validation,
83 }
84 }
85}
86
87#[derive(Clone, Debug, Error)]
89pub enum BuildAccelerationStructureError {
90 #[error(transparent)]
91 EncoderState(#[from] EncoderStateError),
92
93 #[error(transparent)]
94 Device(#[from] DeviceError),
95
96 #[error(transparent)]
97 InvalidResource(#[from] InvalidResourceError),
98
99 #[error(transparent)]
100 DestroyedResource(#[from] DestroyedResourceError),
101
102 #[error(transparent)]
103 MissingBufferUsage(#[from] MissingBufferUsageError),
104
105 #[error(transparent)]
106 MissingFeatures(#[from] MissingFeatures),
107
108 #[error(
109 "Data range of {region_size} B starting at offset {offset} would overrun the size {buffer_size} of buffer {buffer_ident:?}"
110 )]
111 InsufficientBufferSize {
112 buffer_ident: ResourceErrorIdent,
113 offset: BufferAddress,
114 region_size: BufferAddress,
115 buffer_size: BufferAddress,
116 },
117
118 #[error(
119 "Offset {offset}, computed as {count} times {stride} B, exceeds the maximum addressable offset 2^32 - 1 within buffer {buffer_ident:?}"
120 )]
121 OffsetLimitedTo4GB {
122 buffer_ident: ResourceErrorIdent,
123 offset: BufferAddress,
124 count: BufferAddress,
125 stride: BufferAddress,
126 },
127
128 #[error("Buffer {0:?} associated offset doesn't align with the index type")]
129 UnalignedIndexBufferOffset(ResourceErrorIdent),
130
131 #[error("Buffer {0:?} associated offset is unaligned")]
132 UnalignedTransformBufferOffset(ResourceErrorIdent),
133
134 #[error("Buffer {0:?} associated index count not divisible by 3 (count: {1}")]
135 InvalidIndexCount(ResourceErrorIdent, u32),
136
137 #[error("Buffer {0:?} associated data contains None")]
138 MissingAssociatedData(ResourceErrorIdent),
139
140 #[error(
141 "Blas {0:?} build sizes to may be greater than the descriptor at build time specified"
142 )]
143 IncompatibleBlasBuildSizes(ResourceErrorIdent),
144
145 #[error("Blas {0:?} flags are different, creation flags: {1:?}, provided: {2:?}")]
146 IncompatibleBlasFlags(
147 ResourceErrorIdent,
148 AccelerationStructureGeometryFlags,
149 AccelerationStructureGeometryFlags,
150 ),
151
152 #[error("Blas {0:?} build vertex count is greater than creation count (needs to be less than or equal to), creation: {1:?}, build: {2:?}")]
153 IncompatibleBlasVertexCount(ResourceErrorIdent, u32, u32),
154
155 #[error("Blas {0:?} vertex formats are different, creation format: {1:?}, provided: {2:?}")]
156 DifferentBlasVertexFormats(ResourceErrorIdent, VertexFormat, VertexFormat),
157
158 #[error("Blas {0:?} stride was required to be at least {1} but stride given was {2}")]
159 VertexStrideTooSmall(ResourceErrorIdent, u64, u64),
160
161 #[error("Blas {0:?} stride was required to be a multiple of {1} but stride given was {2}")]
162 VertexStrideUnaligned(ResourceErrorIdent, u64, u64),
163
164 #[error("Blas {0:?} index count was provided at creation or building, but not the other")]
165 BlasIndexCountProvidedMismatch(ResourceErrorIdent),
166
167 #[error("Blas {0:?} build index count is greater than creation count (needs to be less than or equal to), creation: {1:?}, build: {2:?}")]
168 IncompatibleBlasIndexCount(ResourceErrorIdent, u32, u32),
169
170 #[error("Blas {0:?} index formats are different, creation format: {1:?}, provided: {2:?}")]
171 DifferentBlasIndexFormats(ResourceErrorIdent, Option<IndexFormat>, Option<IndexFormat>),
172
173 #[error("Blas {0:?} is compacted and so cannot be built")]
174 CompactedBlas(ResourceErrorIdent),
175
176 #[error("Blas {0:?} build sizes require index buffer but none was provided")]
177 MissingIndexBuffer(ResourceErrorIdent),
178
179 #[error("Tlas {0:?} instance {1} contains an invalid custom data (more than 24bits)")]
180 TlasInvalidCustomData(ResourceErrorIdent, usize),
181
182 #[error(
183 "Tlas {0:?} has {1} active instances but only {2} are allowed as specified by the descriptor at creation"
184 )]
185 TlasInstanceCountExceeded(ResourceErrorIdent, u32, u32),
186
187 #[error("Blas {0:?} has flag USE_TRANSFORM but the transform buffer is missing")]
188 TransformMissing(ResourceErrorIdent),
189
190 #[error("Blas {0:?} is missing the flag USE_TRANSFORM but the transform buffer is set")]
191 UseTransformMissing(ResourceErrorIdent),
192 #[error(
193 "Tlas {0:?} dependent {1:?} is missing AccelerationStructureFlags::ALLOW_RAY_HIT_VERTEX_RETURN"
194 )]
195 TlasDependentMissingVertexReturn(ResourceErrorIdent, ResourceErrorIdent),
196
197 #[error("Blas {0:?} geometry kind at creation does not match build (triangles vs AABBs)")]
198 BlasGeometryKindMismatch(ResourceErrorIdent),
199
200 #[error(
201 "Blas {0:?} build AABB primitive count is greater than creation count (creation: {1}, build: {2})"
202 )]
203 IncompatibleBlasAabbPrimitiveCount(ResourceErrorIdent, u32, u32),
204
205 #[error("Blas {0:?} AABB primitive offset must be a multiple of 8")]
206 UnalignedAabbPrimitiveOffset(ResourceErrorIdent),
207
208 #[error("Blas {0:?} AABB stride is invalid (must be >= {1} and a multiple of 8)")]
209 InvalidAabbStride(ResourceErrorIdent, BufferAddress),
210 #[error(
211 "Tlas {0:?} instance {1} contains an intersection index {2} which is greater than 2^24 - 1"
212 )]
213 TlasInvalidIntersectionIndex(ResourceErrorIdent, usize, u32),
214}
215
216impl WebGpuError for BuildAccelerationStructureError {
217 fn webgpu_error_type(&self) -> ErrorType {
218 match self {
219 Self::EncoderState(e) => e.webgpu_error_type(),
220 Self::Device(e) => e.webgpu_error_type(),
221 Self::InvalidResource(e) => e.webgpu_error_type(),
222 Self::DestroyedResource(e) => e.webgpu_error_type(),
223 Self::MissingBufferUsage(e) => e.webgpu_error_type(),
224 Self::MissingFeatures(e) => e.webgpu_error_type(),
225 Self::InsufficientBufferSize { .. }
226 | Self::OffsetLimitedTo4GB { .. }
227 | Self::UnalignedIndexBufferOffset(..)
228 | Self::UnalignedTransformBufferOffset(..)
229 | Self::InvalidIndexCount(..)
230 | Self::MissingAssociatedData(..)
231 | Self::IncompatibleBlasBuildSizes(..)
232 | Self::IncompatibleBlasFlags(..)
233 | Self::IncompatibleBlasVertexCount(..)
234 | Self::DifferentBlasVertexFormats(..)
235 | Self::VertexStrideTooSmall(..)
236 | Self::VertexStrideUnaligned(..)
237 | Self::BlasIndexCountProvidedMismatch(..)
238 | Self::IncompatibleBlasIndexCount(..)
239 | Self::DifferentBlasIndexFormats(..)
240 | Self::CompactedBlas(..)
241 | Self::MissingIndexBuffer(..)
242 | Self::TlasInvalidCustomData(..)
243 | Self::TlasInstanceCountExceeded(..)
244 | Self::TransformMissing(..)
245 | Self::UseTransformMissing(..)
246 | Self::TlasDependentMissingVertexReturn(..)
247 | Self::TlasInvalidIntersectionIndex(..)
248 | Self::BlasGeometryKindMismatch(..)
249 | Self::IncompatibleBlasAabbPrimitiveCount(..)
250 | Self::UnalignedAabbPrimitiveOffset(..)
251 | Self::InvalidAabbStride(..) => ErrorType::Validation,
252 }
253 }
254}
255
256#[derive(Clone, Debug, Error)]
257pub enum ValidateAsActionsError {
258 #[error(transparent)]
259 DestroyedResource(#[from] DestroyedResourceError),
260
261 #[error("Tlas {0:?} is used before it is built")]
262 UsedUnbuiltTlas(ResourceErrorIdent),
263
264 #[error("Blas {0:?} is used before it is built (in Tlas {1:?})")]
265 UsedUnbuiltBlas(ResourceErrorIdent, ResourceErrorIdent),
266
267 #[error("Blas {0:?} is newer than the containing Tlas {1:?}")]
268 BlasNewerThenTlas(ResourceErrorIdent, ResourceErrorIdent),
269
270 #[error("Tlas {0:?} has an intersection index {1:?} out of bounds of the length of the intersection array {2:?}")]
271 TlasIntersectionInvalid(ResourceErrorIdent, u32, u32),
272
273 #[error("An instance of Tlas {0:?} requires an intersection type of {1:?} for index {2}, but got {3:?}")]
274 TlasInstancesIntersectionIndicesDiffer(
275 ResourceErrorIdent,
276 crate::ray_tracing_pipeline::RayTracingIntersectionType,
277 u32,
278 Option<crate::ray_tracing_pipeline::RayTracingIntersectionType>,
279 ),
280}
281
282impl WebGpuError for ValidateAsActionsError {
283 fn webgpu_error_type(&self) -> ErrorType {
284 match self {
285 Self::DestroyedResource(e) => e.webgpu_error_type(),
286 Self::UsedUnbuiltTlas(..)
287 | Self::UsedUnbuiltBlas(..)
288 | Self::BlasNewerThenTlas(..)
289 | Self::TlasIntersectionInvalid(..)
290 | Self::TlasInstancesIntersectionIndicesDiffer(..) => ErrorType::Validation,
291 }
292 }
293}
294
295#[derive(Debug)]
296pub struct BlasTriangleGeometry<'a, Buffer = Arc<resource::Buffer>> {
297 pub size: &'a wgt::BlasTriangleGeometrySizeDescriptor,
298 pub vertex_buffer: Buffer,
299 pub index_buffer: Option<Buffer>,
300 pub transform_buffer: Option<Buffer>,
301 pub first_vertex: u32,
302 pub vertex_stride: BufferAddress,
303 pub first_index: Option<u32>,
304 pub transform_buffer_offset: Option<BufferAddress>,
305}
306
307#[derive(Debug)]
308pub struct BlasAabbGeometry<'a, Buffer = Arc<resource::Buffer>> {
309 pub size: &'a wgt::BlasAABBGeometrySizeDescriptor,
310 pub stride: BufferAddress,
311 pub aabb_buffer: Buffer,
312 pub primitive_offset: u32,
313}
314
315pub enum BlasGeometries<'a, Buffer = Arc<resource::Buffer>> {
316 TriangleGeometries(Box<dyn Iterator<Item = BlasTriangleGeometry<'a, Buffer>> + 'a>),
317 AabbGeometries(Box<dyn Iterator<Item = BlasAabbGeometry<'a, Buffer>> + 'a>),
318}
319
320pub struct BlasBuildEntry<'a, Blas = Arc<resource::Blas>, Buffer = Arc<resource::Buffer>> {
321 pub blas: Blas,
322 pub geometries: BlasGeometries<'a, Buffer>,
323}
324
325#[derive(Debug, Clone)]
326#[cfg_attr(feature = "serde", derive(serde::Serialize, serde::Deserialize))]
327pub struct TlasBuildEntry<Tlas = Arc<resource::Tlas>, Buffer = Arc<resource::Buffer>> {
328 pub tlas: Tlas,
329 pub instance_buffer: Buffer,
330 pub instance_count: u32,
331}
332
333#[derive(Debug)]
334pub struct TlasInstance<'a, Blas = Arc<resource::Blas>> {
335 pub blas: Blas,
336 pub transform: &'a [f32; 12],
337 pub custom_data: u32,
338 pub mask: u8,
339 pub intersection_index: u32,
340}
341
342pub struct TlasPackage<'a, Tlas = Arc<resource::Tlas>, Blas = Arc<resource::Blas>> {
343 pub tlas: Tlas,
344 pub instances: Box<dyn Iterator<Item = Option<TlasInstance<'a, Blas>>> + 'a>,
345 pub lowest_unmodified: u32,
346}
347
348#[derive(Debug, Clone)]
349pub(crate) struct TlasBuild {
350 pub tlas: Arc<Tlas>,
351 pub dependencies: Vec<Arc<Blas>>,
352 pub max_intersection_idx: Option<u32>,
353 pub required_intersection_types: Vec<resource::TlasIntersectionType>,
354}
355
356#[derive(Debug, Clone, Default)]
357pub(crate) struct AsBuild {
358 pub blas_s_built: Vec<Arc<Blas>>,
359 pub tlas_s_built: Vec<TlasBuild>,
360}
361
362impl AsBuild {
363 pub(crate) fn with_capacity(blas: usize, tlas: usize) -> Self {
364 Self {
365 blas_s_built: Vec::with_capacity(blas),
366 tlas_s_built: Vec::with_capacity(tlas),
367 }
368 }
369}
370
371#[derive(Debug, Clone)]
372pub(crate) enum AsAction {
373 Build(AsBuild),
374 BindTlas(Arc<Tlas>),
379 TraceTlas(
388 Arc<Tlas>,
389 Arc<[crate::ray_tracing_pipeline::RayTracingIntersectionType]>,
390 ),
391}
392
393#[derive(Debug, Clone)]
395#[cfg_attr(feature = "serde", apply(serde_object_reference_struct))]
396pub struct OwnedBlasTriangleGeometry<R: ReferenceType> {
397 pub size: wgt::BlasTriangleGeometrySizeDescriptor,
398 pub vertex_buffer: R::Buffer,
399 pub index_buffer: Option<R::Buffer>,
400 pub transform_buffer: Option<R::Buffer>,
401 pub first_vertex: u32,
402 pub vertex_stride: BufferAddress,
403 pub first_index: Option<u32>,
404 pub transform_buffer_offset: Option<BufferAddress>,
405}
406
407pub type ArcBlasTriangleGeometry = OwnedBlasTriangleGeometry<ArcReferences>;
408
409#[derive(Debug, Clone)]
410#[cfg_attr(feature = "serde", apply(serde_object_reference_struct))]
411pub struct OwnedBlasAabbGeometry<R: ReferenceType> {
412 pub size: wgt::BlasAABBGeometrySizeDescriptor,
413 pub stride: BufferAddress,
414 pub aabb_buffer: R::Buffer,
415 pub primitive_offset: u32,
416}
417
418pub type ArcBlasAabbGeometry = OwnedBlasAabbGeometry<ArcReferences>;
419
420#[derive(Debug, Clone)]
421#[cfg_attr(feature = "serde", apply(serde_object_reference_struct))]
422pub enum OwnedBlasGeometries<R: ReferenceType> {
423 TriangleGeometries(Vec<OwnedBlasTriangleGeometry<R>>),
424 AabbGeometries(Vec<OwnedBlasAabbGeometry<R>>),
425}
426
427pub type ArcBlasGeometries = OwnedBlasGeometries<ArcReferences>;
428
429#[derive(Debug, Clone)]
430#[cfg_attr(feature = "serde", apply(serde_object_reference_struct))]
431pub struct OwnedBlasBuildEntry<R: ReferenceType> {
432 pub blas: R::Blas,
433 pub geometries: OwnedBlasGeometries<R>,
434}
435
436pub type ArcBlasBuildEntry = OwnedBlasBuildEntry<ArcReferences>;
437
438#[derive(Debug, Clone)]
439#[cfg_attr(feature = "serde", apply(serde_object_reference_struct))]
440pub struct OwnedTlasInstance<R: ReferenceType> {
441 pub blas: R::Blas,
442 pub transform: [f32; 12],
443 pub custom_data: u32,
444 pub mask: u8,
445 pub intersection_index: u32,
446}
447
448pub type ArcTlasInstance = OwnedTlasInstance<ArcReferences>;
449
450#[derive(Debug, Clone)]
451#[cfg_attr(feature = "serde", apply(serde_object_reference_struct))]
452pub struct OwnedTlasPackage<R: ReferenceType> {
453 pub tlas: R::Tlas,
454 pub instances: Vec<Option<OwnedTlasInstance<R>>>,
455 pub lowest_unmodified: u32,
456}
457
458pub type ArcTlasPackage = OwnedTlasPackage<ArcReferences>;
459
460#[derive(Debug, Clone)]
462pub struct BlasTriangleGeometryInfo {
463 pub size: wgt::BlasTriangleGeometrySizeDescriptor,
464 pub first_vertex: u32,
465 pub vertex_stride: BufferAddress,
466 pub first_index: Option<u32>,
467 pub transform_buffer_offset: Option<BufferAddress>,
468}
469
470#[derive(Clone, Debug, Error)]
471pub enum BlasPrepareCompactError {
472 #[error(transparent)]
473 Device(#[from] DeviceError),
474 #[error(transparent)]
475 InvalidResource(#[from] InvalidResourceError),
476 #[error("Compaction is already being prepared")]
477 CompactionPreparingAlready,
478 #[error("Cannot compact an already compacted BLAS")]
479 DoubleCompaction,
480 #[error("BLAS is not yet built")]
481 NotBuilt,
482 #[error("BLAS does not support compaction (is AccelerationStructureFlags::ALLOW_COMPACTION missing?)")]
483 CompactionUnsupported,
484}
485
486impl WebGpuError for BlasPrepareCompactError {
487 fn webgpu_error_type(&self) -> ErrorType {
488 match self {
489 Self::Device(e) => e.webgpu_error_type(),
490 Self::InvalidResource(e) => e.webgpu_error_type(),
491 Self::CompactionPreparingAlready
492 | Self::DoubleCompaction
493 | Self::NotBuilt
494 | Self::CompactionUnsupported => ErrorType::Validation,
495 }
496 }
497}
498
499#[derive(Clone, Debug, Error)]
500pub enum CompactBlasError {
501 #[error(transparent)]
502 Encoder(#[from] EncoderStateError),
503
504 #[error(transparent)]
505 Device(#[from] DeviceError),
506
507 #[error(transparent)]
508 InvalidResource(#[from] InvalidResourceError),
509
510 #[error(transparent)]
511 DestroyedResource(#[from] DestroyedResourceError),
512
513 #[error(transparent)]
514 MissingFeatures(#[from] MissingFeatures),
515
516 #[error("BLAS was not prepared for compaction")]
517 BlasNotReady,
518}
519
520impl WebGpuError for CompactBlasError {
521 fn webgpu_error_type(&self) -> ErrorType {
522 match self {
523 Self::Encoder(e) => e.webgpu_error_type(),
524 Self::Device(e) => e.webgpu_error_type(),
525 Self::InvalidResource(e) => e.webgpu_error_type(),
526 Self::DestroyedResource(e) => e.webgpu_error_type(),
527 Self::MissingFeatures(e) => e.webgpu_error_type(),
528 Self::BlasNotReady => ErrorType::Validation,
529 }
530 }
531}
532
533pub type BlasCompactReadyPendingClosure = (Option<BlasCompactCallback>, BlasPrepareCompactResult);