wgpu_types/
ray_tracing.rs

1use alloc::vec::Vec;
2
3#[cfg(any(feature = "serde", test))]
4use serde::{Deserialize, Serialize};
5
6#[cfg(doc)]
7use crate::{Features, VertexFormat};
8
9#[derive(Clone, Debug, PartialEq, Eq)]
10#[cfg_attr(feature = "serde", derive(Serialize, Deserialize))]
11/// Descriptor for all size defining attributes of a single triangle geometry inside a bottom level acceleration structure.
12pub struct BlasTriangleGeometrySizeDescriptor {
13    /// Format of a vertex position, must be [`VertexFormat::Float32x3`]
14    /// with just [`Features::EXPERIMENTAL_RAY_QUERY`]
15    /// but [`Features::EXTENDED_ACCELERATION_STRUCTURE_VERTEX_FORMATS`] adds more.
16    pub vertex_format: crate::VertexFormat,
17    /// Number of vertices.
18    pub vertex_count: u32,
19    /// Format of an index. Only needed if an index buffer is used.
20    /// If `index_format` is provided `index_count` is required.
21    pub index_format: Option<crate::IndexFormat>,
22    /// Number of indices. Only needed if an index buffer is used.
23    /// If `index_count` is provided `index_format` is required.
24    pub index_count: Option<u32>,
25    /// Flags for the geometry.
26    pub flags: AccelerationStructureGeometryFlags,
27}
28
29#[derive(Clone, Debug, PartialEq, Eq)]
30#[cfg_attr(feature = "serde", derive(Serialize, Deserialize))]
31/// Descriptor for size-defining attributes of one AABB geometry group in a bottom level acceleration structure.
32///
33/// Each primitive is one axis-aligned bounding box, typically stored as two `vec3<f32>` min/max corners.
34pub struct BlasAABBGeometrySizeDescriptor {
35    /// Number of AABB primitives in this geometry.
36    pub primitive_count: u32,
37    /// Flags for the geometry.
38    pub flags: AccelerationStructureGeometryFlags,
39}
40
41/// Minimum stride for AABB geometry (24 bytes: two `vec3<f32>`).
42pub const AABB_GEOMETRY_MIN_STRIDE: crate::BufferAddress = 24;
43
44#[derive(Clone, Debug)]
45#[cfg_attr(feature = "serde", derive(Serialize, Deserialize))]
46/// Descriptor for all size defining attributes of all geometries inside a bottom level acceleration structure.
47pub enum BlasGeometrySizeDescriptors {
48    /// Triangle geometry version.
49    Triangles {
50        /// Descriptor for each triangle geometry.
51        descriptors: Vec<BlasTriangleGeometrySizeDescriptor>,
52    },
53    /// AABB geometry version.
54    AABBs {
55        /// Descriptor for each AABB geometry.
56        descriptors: Vec<BlasAABBGeometrySizeDescriptor>,
57    },
58}
59
60#[repr(u8)]
61#[derive(Copy, Clone, Debug, PartialEq, Eq, Hash)]
62#[cfg_attr(feature = "serde", derive(Serialize, Deserialize))]
63/// Update mode for acceleration structure builds.
64pub enum AccelerationStructureUpdateMode {
65    /// Always perform a full build.
66    Build,
67    /// If possible, perform an incremental update.
68    ///
69    /// Not advised for major topology changes.
70    /// (Useful for e.g. skinning)
71    PreferUpdate,
72}
73
74#[repr(C)]
75#[derive(Clone, Debug, PartialEq, Eq, Hash)]
76#[cfg_attr(feature = "serde", derive(Serialize, Deserialize))]
77/// Descriptor for creating a bottom level acceleration structure.
78pub struct CreateBlasDescriptor<L> {
79    /// Label for the bottom level acceleration structure.
80    pub label: L,
81    /// Flags for the bottom level acceleration structure.
82    pub flags: AccelerationStructureFlags,
83    /// Update mode for the bottom level acceleration structure.
84    pub update_mode: AccelerationStructureUpdateMode,
85}
86
87impl<L> CreateBlasDescriptor<L> {
88    /// Takes a closure and maps the label of the blas descriptor into another.
89    pub fn map_label<K>(&self, fun: impl FnOnce(&L) -> K) -> CreateBlasDescriptor<K> {
90        CreateBlasDescriptor {
91            label: fun(&self.label),
92            flags: self.flags,
93            update_mode: self.update_mode,
94        }
95    }
96}
97
98#[repr(C)]
99#[derive(Clone, Debug, PartialEq, Eq, Hash)]
100#[cfg_attr(feature = "serde", derive(Serialize, Deserialize))]
101/// Descriptor for creating a top level acceleration structure.
102pub struct CreateTlasDescriptor<L> {
103    /// Label for the top level acceleration structure.
104    pub label: L,
105    /// Number of instances that can be stored in the acceleration structure.
106    pub max_instances: u32,
107    /// Flags for the bottom level acceleration structure.
108    pub flags: AccelerationStructureFlags,
109    /// Update mode for the bottom level acceleration structure.
110    pub update_mode: AccelerationStructureUpdateMode,
111}
112
113impl<L> CreateTlasDescriptor<L> {
114    /// Takes a closure and maps the label of the blas descriptor into another.
115    pub fn map_label<K>(&self, fun: impl FnOnce(&L) -> K) -> CreateTlasDescriptor<K> {
116        CreateTlasDescriptor {
117            label: fun(&self.label),
118            flags: self.flags,
119            update_mode: self.update_mode,
120            max_instances: self.max_instances,
121        }
122    }
123}
124
125bitflags::bitflags!(
126    /// Flags for acceleration structures
127    #[cfg_attr(feature = "serde", derive(Serialize, Deserialize))]
128    #[cfg_attr(feature = "serde", serde(transparent))]
129    #[derive(Clone, Copy, Debug, PartialEq, Eq, Hash)]
130    pub struct AccelerationStructureFlags: u8 {
131        /// Allow for incremental updates (no change in size), currently this is unimplemented
132        /// and will build as normal (this is fine, update vs build should be unnoticeable)
133        const ALLOW_UPDATE = 1 << 0;
134        /// Allow the acceleration structure to be compacted in a copy operation
135        /// (`Blas::prepare_for_compaction`, `CommandEncoder::compact_blas`).
136        const ALLOW_COMPACTION = 1 << 1;
137        /// Optimize for fast ray tracing performance, recommended if the geometry is unlikely
138        /// to change (e.g. in a game: non-interactive scene geometry)
139        const PREFER_FAST_TRACE = 1 << 2;
140        /// Optimize for fast build time, recommended if geometry is likely to change frequently
141        /// (e.g. in a game: player model).
142        const PREFER_FAST_BUILD = 1 << 3;
143        /// Optimize for low memory footprint (both while building and in the output BLAS).
144        const LOW_MEMORY = 1 << 4;
145        /// Use `BlasTriangleGeometry::transform_buffer` when building a BLAS (only allowed in
146        /// BLAS creation)
147        const USE_TRANSFORM = 1 << 5;
148        /// Allow retrieval of the vertices of the triangle hit by a ray.
149        const ALLOW_RAY_HIT_VERTEX_RETURN = 1 << 6;
150    }
151);
152
153bitflags::bitflags!(
154    /// Flags for acceleration structure geometries
155    #[cfg_attr(feature = "serde", derive(Serialize, Deserialize))]
156    #[cfg_attr(feature = "serde", serde(transparent))]
157    #[derive(Clone, Copy, Debug, PartialEq, Eq, Hash)]
158    pub struct AccelerationStructureGeometryFlags: u8 {
159        /// Is OPAQUE (is there no alpha test) recommended as currently in naga there is no
160        /// candidate intersections yet so currently BLASes without this flag will not have hits.
161        /// Not enabling this makes the BLAS unable to be interacted with in WGSL.
162        const OPAQUE = 1 << 0;
163        /// NO_DUPLICATE_ANY_HIT_INVOCATION, not useful unless using hal with wgpu, ray-tracing
164        /// pipelines are not supported in wgpu so any-hit shaders do not exist. For when any-hit
165        /// shaders are implemented (or experienced users who combine this with an underlying library:
166        /// for any primitive (triangle or AABB) multiple any-hit shaders sometimes may be invoked
167        /// (especially in AABBs like a sphere), if this flag in present only one hit on a primitive may
168        /// invoke an any-hit shader.
169        const NO_DUPLICATE_ANY_HIT_INVOCATION = 1 << 1;
170    }
171);
172
173#[derive(Clone, Copy, Debug, PartialEq, Eq, Hash)]
174/// What a copy between acceleration structures should do
175pub enum AccelerationStructureCopy {
176    /// Directly duplicate an acceleration structure to another
177    Clone,
178    /// Duplicate and compact an acceleration structure
179    Compact,
180}
181
182#[derive(Clone, Copy, Debug, PartialEq, Eq, Hash)]
183/// What type the data of an acceleration structure is
184pub enum AccelerationStructureType {
185    /// The types of the acceleration structure are triangles
186    Triangles,
187    /// The types of the acceleration structure are axis aligned bounding boxes
188    AABBs,
189    /// The types of the acceleration structure are instances
190    Instances,
191}
192
193/// Alignment requirement for transform buffers used in acceleration structure builds
194pub const TRANSFORM_BUFFER_ALIGNMENT: crate::BufferAddress = 16;
195
196/// Alignment requirement for instance buffers used in acceleration structure builds (`build_acceleration_structures_unsafe_tlas`)
197pub const INSTANCE_BUFFER_ALIGNMENT: crate::BufferAddress = 16;
wgpu_types/ray_tracing.rs

wgpu_types/
ray_tracing.rs
