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

wgpu_types/
ray_tracing.rs
