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<'a, K>(&'a self, fun: impl FnOnce(&'a 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<'a, K>(&'a self, fun: impl FnOnce(&'a 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 ///
137 /// Some backends allocate structures with this flag from memory meant for
138 /// short-lived resources. Only set it on structures you compact soon after building.
139 const ALLOW_COMPACTION = 1 << 1;
140 /// Optimize for fast ray tracing performance, recommended if the geometry is unlikely
141 /// to change (e.g. in a game: non-interactive scene geometry)
142 const PREFER_FAST_TRACE = 1 << 2;
143 /// Optimize for fast build time, recommended if geometry is likely to change frequently
144 /// (e.g. in a game: player model).
145 const PREFER_FAST_BUILD = 1 << 3;
146 /// Optimize for low memory footprint (both while building and in the output BLAS).
147 const LOW_MEMORY = 1 << 4;
148 /// Use `BlasTriangleGeometry::transform_buffer` when building a BLAS (only allowed in
149 /// BLAS creation)
150 const USE_TRANSFORM = 1 << 5;
151 /// Allow retrieval of the vertices of the triangle hit by a ray.
152 const ALLOW_RAY_HIT_VERTEX_RETURN = 1 << 6;
153 }
154);
155
156bitflags::bitflags!(
157 /// Flags for acceleration structure geometries
158 #[cfg_attr(feature = "serde", derive(Serialize, Deserialize))]
159 #[cfg_attr(feature = "serde", serde(transparent))]
160 #[derive(Clone, Copy, Debug, PartialEq, Eq, Hash)]
161 pub struct AccelerationStructureGeometryFlags: u8 {
162 /// Is OPAQUE (there is no alpha test). This disables any-hit shaders on a ray tracing pipeline
163 /// and automatically commits triangle intersections when using ray queries, meaning it does not
164 /// have to return to user code.
165 const OPAQUE = 1 << 0;
166 /// Without this flag, any primitive (triangle or AABB) may invoke multiple any-hit shaders
167 /// (an implementation could, for example, split primitives if they got too large), if this
168 /// flag in present only one hit on a primitive may invoke an any-hit shader. This is
169 /// recommended if the any-hit shader is expensive, but you cannot use
170 /// [`AccelerationStructureGeometryFlags::OPAQUE`].
171 const NO_DUPLICATE_ANY_HIT_INVOCATION = 1 << 1;
172 }
173);
174
175#[derive(Clone, Copy, Debug, PartialEq, Eq, Hash)]
176/// What a copy between acceleration structures should do
177pub enum AccelerationStructureCopy {
178 /// Directly duplicate an acceleration structure to another
179 Clone,
180 /// Duplicate and compact an acceleration structure
181 Compact,
182}
183
184#[derive(Clone, Copy, Debug, PartialEq, Eq, Hash)]
185/// What type the data of an acceleration structure is
186pub enum AccelerationStructureType {
187 /// The types of the acceleration structure are triangles
188 Triangles,
189 /// The types of the acceleration structure are axis aligned bounding boxes
190 AABBs,
191 /// The types of the acceleration structure are instances
192 Instances,
193}
194
195/// Alignment requirement for transform buffers used in acceleration structure builds
196pub const TRANSFORM_BUFFER_ALIGNMENT: crate::BufferAddress = 16;
197
198/// Alignment requirement for instance buffers used in acceleration structure builds (`build_acceleration_structures_unsafe_tlas`)
199pub const INSTANCE_BUFFER_ALIGNMENT: crate::BufferAddress = 16;