wgpu/api/
tlas.rs

Help
1use crate::{api::blas::TlasInstance, dispatch};
2use crate::{BindingResource, Label};
3use alloc::vec::Vec;
4#[cfg(wgpu_core)]
5use core::ops::Deref;
6use core::ops::{Index, IndexMut, Range};
7use wgt::WasmNotSendSync;
8
9/// Descriptor to create top level acceleration structures.
10pub type CreateTlasDescriptor<'a> = wgt::CreateTlasDescriptor<Label<'a>>;
11static_assertions::assert_impl_all!(CreateTlasDescriptor<'_>: Send, Sync);
12
13#[derive(Debug, Clone)]
14/// Top Level Acceleration Structure (TLAS).
15///
16/// A TLAS contains a series of [TLAS instances], which are a reference to
17/// a BLAS and a transformation matrix placing the geometry in the world.
18///
19/// A TLAS also contains an extra set of TLAS instances in a device readable form, you cant interact
20/// directly with these, instead you have to build the TLAS with [TLAS instances].
21///
22/// [TLAS instances]: TlasInstance
23pub struct Tlas {
24    pub(crate) inner: dispatch::DispatchTlas,
25    pub(crate) instances: Vec<Option<TlasInstance>>,
26    pub(crate) lowest_unmodified: u32,
27}
28static_assertions::assert_impl_all!(Tlas: WasmNotSendSync);
29
30crate::cmp::impl_eq_ord_hash_proxy!(Tlas => .inner);
31
32impl Tlas {
33    /// Get the [`wgpu_hal`] acceleration structure from this `Tlas`.
34    ///
35    /// Find the Api struct corresponding to the active backend in [`wgpu_hal::api`],
36    /// and pass that struct to the to the `A` type parameter.
37    ///
38    /// Returns a guard that dereferences to the type of the hal backend
39    /// which implements [`A::AccelerationStructure`].
40    ///
41    /// # Types
42    ///
43    /// The returned type depends on the backend:
44    ///
45    #[doc = crate::hal_type_vulkan!("AccelerationStructure")]
46    #[doc = crate::hal_type_metal!("AccelerationStructure")]
47    #[doc = crate::hal_type_dx12!("AccelerationStructure")]
48    #[doc = crate::hal_type_gles!("AccelerationStructure")]
49    ///
50    /// # Deadlocks
51    ///
52    /// - The returned guard holds a read-lock on a device-local "destruction"
53    ///   lock, which will cause all calls to `destroy` to block until the
54    ///   guard is released.
55    ///
56    /// # Errors
57    ///
58    /// This method will return None if:
59    /// - The acceleration structure is not from the backend specified by `A`.
60    /// - The acceleration structure is from the `webgpu` or `custom` backend.
61    ///
62    /// # Safety
63    ///
64    /// - The returned resource must not be destroyed unless the guard
65    ///   is the last reference to it and it is not in use by the GPU.
66    ///   The guard and handle may be dropped at any time however.
67    /// - All the safety requirements of wgpu-hal must be upheld.
68    ///
69    /// [`A::AccelerationStructure`]: hal::Api::AccelerationStructure
70    #[cfg(wgpu_core)]
71    pub unsafe fn as_hal<A: hal::Api>(
72        &mut self,
73    ) -> Option<impl Deref<Target = A::AccelerationStructure>> {
74        let tlas = self.inner.as_core_opt()?;
75        unsafe { tlas.context.tlas_as_hal::<A>(tlas) }
76    }
77
78    #[cfg(custom)]
79    /// Returns custom implementation of Tlas (if custom backend and is internally T)
80    pub fn as_custom<T: crate::custom::TlasInterface>(&self) -> Option<&T> {
81        self.inner.as_custom()
82    }
83
84    /// Get a reference to all instances.
85    pub fn get(&self) -> &[Option<TlasInstance>] {
86        &self.instances
87    }
88
89    /// Get a mutable slice to a range of instances.
90    /// Returns None if the range is out of bounds.
91    /// All elements from the lowest accessed index up are marked as modified.
92    // this recommendation is not useful yet, but is likely to be when ability to update arrives or possible optimisations for building get implemented.
93    /// For best performance it is recommended to prefer access to low elements and modify higher elements as little as possible.
94    /// This can be done by ordering instances from the most to the least used. It is recommended
95    /// to use [`Self::index_mut`] unless the option if out of bounds is required
96    pub fn get_mut_slice(&mut self, range: Range<usize>) -> Option<&mut [Option<TlasInstance>]> {
97        if range.end > self.instances.len() {
98            return None;
99        }
100        if range.end as u32 > self.lowest_unmodified {
101            self.lowest_unmodified = range.end as u32;
102        }
103        Some(&mut self.instances[range])
104    }
105
106    /// Get a single mutable reference to an instance.
107    /// Returns None if the range is out of bounds.
108    /// All elements from the lowest accessed index up are marked as modified.
109    // this recommendation is not useful yet, but is likely to be when ability to update arrives or possible optimisations for building get implemented.
110    /// For best performance it is recommended to prefer access to low elements and modify higher elements as little as possible.
111    /// This can be done by ordering instances from the most to the least used. It is recommended
112    /// to use [`Self::index_mut`] unless the option if out of bounds is required
113    pub fn get_mut_single(&mut self, index: usize) -> Option<&mut Option<TlasInstance>> {
114        if index >= self.instances.len() {
115            return None;
116        }
117        if index as u32 + 1 > self.lowest_unmodified {
118            self.lowest_unmodified = index as u32 + 1;
119        }
120        Some(&mut self.instances[index])
121    }
122
123    /// Get the binding resource for the underling acceleration structure, to be used when creating a [`BindGroup`]
124    ///
125    /// [`BindGroup`]: super::BindGroup
126    pub fn as_binding(&self) -> BindingResource<'_> {
127        BindingResource::AccelerationStructure(self)
128    }
129}
130
131impl Index<usize> for Tlas {
132    type Output = Option<TlasInstance>;
133
134    fn index(&self, index: usize) -> &Self::Output {
135        self.instances.index(index)
136    }
137}
138
139impl Index<Range<usize>> for Tlas {
140    type Output = [Option<TlasInstance>];
141
142    fn index(&self, index: Range<usize>) -> &Self::Output {
143        self.instances.index(index)
144    }
145}
146
147impl IndexMut<usize> for Tlas {
148    fn index_mut(&mut self, index: usize) -> &mut Self::Output {
149        let idx = self.instances.index_mut(index);
150        if index as u32 + 1 > self.lowest_unmodified {
151            self.lowest_unmodified = index as u32 + 1;
152        }
153        idx
154    }
155}
156
157impl IndexMut<Range<usize>> for Tlas {
158    fn index_mut(&mut self, index: Range<usize>) -> &mut Self::Output {
159        let idx = self.instances.index_mut(index.clone());
160        if index.end > self.lowest_unmodified as usize {
161            self.lowest_unmodified = index.end as u32;
162        }
163        idx
164    }
165}
wgpu/api/tlas.rs

wgpu/api/
tlas.rs
