Skip to main content

wgpu_core/
ray_tracing.rs

1// Ray tracing
2// Major missing optimizations (no api surface changes needed):
3// - use custom tracker to track build state
4// - no forced rebuilt (build mode deduction)
5// - lazy instance buffer allocation
6// - maybe share scratch and instance staging buffer allocation
7// - partial instance buffer uploads (api surface already designed with this in mind)
8// - Batch BLAS read-backs (if it shows up in performance).
9// - ([non performance] extract function in build (rust function extraction with guards is a pain))
10
11use 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/// Error encountered while attempting to do a copy on a command encoder.
88#[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    /// A [`Tlas`] has been bound and used by any pass. The [`Blas`]es it
375    /// was built with must be validated to have not been built after the
376    /// [`Tlas`] as backends have undefined behaviour on this (it would
377    /// cause AABBs to be incorrect, etc.)
378    BindTlas(Arc<Tlas>),
379    /// A [`RayTracingPipeline`] has had a `trace_rays` call on it.
380    /// This [`Tlas`] has been put in a bindgroup, and so the validation
381    /// must ensure that the maximum intersection index in the [`Tlas`] is
382    /// less than the length of the intersection group array and that the
383    /// types of the [`Blas`]es are the same as those of the
384    /// [`RayTracingPipeline`].
385    ///
386    /// [`RayTracingPipeline`]: crate::ray_tracing_pipeline::RayTracingPipeline
387    TraceTlas(
388        Arc<Tlas>,
389        Arc<[crate::ray_tracing_pipeline::RayTracingIntersectionType]>,
390    ),
391}
392
393/// Like [`BlasTriangleGeometry`], but with owned data.
394#[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/// [`BlasTriangleGeometry`], without the resources.
461#[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);