Skip to main content

wgpu/api/
ray_tracing_pass.rs

1use wgt::DynamicOffset;
2
3use crate::{api::SharedDeferredCommandBufferActions, *};
4
5/// In-progress recording of a ray tracing pass.
6///
7/// It can be created with [`CommandEncoder::begin_ray_tracing_pass`].
8#[derive(Debug)]
9pub struct RayTracingPass<'encoder> {
10    pub(crate) inner: dispatch::DispatchRayTracingPass,
11
12    /// Shared with CommandEncoder to enqueue deferred actions from within a pass.
13    pub(crate) actions: SharedDeferredCommandBufferActions,
14
15    /// This lifetime is used to protect the [`CommandEncoder`] from being used
16    /// while the pass is alive. This needs to be PhantomDrop to prevent the lifetime
17    /// from being shortened.
18    pub(crate) _encoder_guard: crate::api::PhantomDrop<&'encoder ()>,
19}
20
21#[cfg(send_sync)]
22static_assertions::assert_impl_all!(RayTracingPass<'_>: Send, Sync);
23
24crate::cmp::impl_eq_ord_hash_proxy!(RayTracingPass<'_> => .inner);
25
26impl RayTracingPass<'_> {
27    /// Drops the lifetime relationship to the parent command encoder, making usage of
28    /// the encoder while this pass is recorded a run-time error instead.
29    ///
30    /// Attention: As long as the ray tracing pass has not been ended, any mutating operation on the parent
31    /// command encoder will cause a run-time error and invalidate it!
32    /// By default, the lifetime constraint prevents this, but it can be useful
33    /// to handle this at run time, such as when storing the pass and encoder in the same
34    /// data structure.
35    ///
36    /// This operation has no effect on pass recording.
37    /// It's a safe operation, since [`CommandEncoder`] is in a locked state as long as the pass is active
38    /// regardless of the lifetime constraint or its absence.
39    pub fn forget_lifetime(self) -> RayTracingPass<'static> {
40        RayTracingPass {
41            inner: self.inner,
42            actions: self.actions,
43            _encoder_guard: crate::api::PhantomDrop::default(),
44        }
45    }
46
47    /// Sets the active ray tracing pipeline.
48    pub fn set_pipeline(&mut self, pipeline: &RayTracingPipeline) {
49        self.inner.set_pipeline(&pipeline.inner);
50    }
51
52    /// Sets the active bind group for a given bind group index. The bind group layout
53    /// in the active pipeline when the `trace_rays()` function is called must match the layout of this bind group.
54    ///
55    /// If the bind group have dynamic offsets, provide them in the binding order.
56    /// These offsets have to be aligned to [`Limits::min_uniform_buffer_offset_alignment`]
57    /// or [`Limits::min_storage_buffer_offset_alignment`] appropriately.
58    pub fn set_bind_group<'a, BG>(&mut self, index: u32, bind_group: BG, offsets: &[DynamicOffset])
59    where
60        Option<&'a BindGroup>: From<BG>,
61    {
62        let bg: Option<&BindGroup> = bind_group.into();
63        let bg = bg.map(|bg| &bg.inner);
64        self.inner.set_bind_group(index, bg, offsets);
65    }
66
67    /// Inserts debug marker.
68    pub fn insert_debug_marker(&mut self, label: &str) {
69        self.inner.insert_debug_marker(label);
70    }
71
72    /// Start record commands and group it into debug marker group.
73    pub fn push_debug_group(&mut self, label: &str) {
74        self.inner.push_debug_group(label);
75    }
76
77    /// Stops command recording and creates debug group.
78    pub fn pop_debug_group(&mut self) {
79        self.inner.pop_debug_group();
80    }
81
82    /// Dispatches rays in the current ray tracing pipeline.
83    pub fn trace_rays(&mut self, x: u32, y: u32, z: u32) {
84        self.inner.trace_rays(x, y, z);
85    }
86}
87
88/// [`Features::IMMEDIATES`] must be enabled on the device in order to call these functions.
89impl RayTracingPass<'_> {
90    /// Set immediate data for subsequent [RayTracingPass::trace_rays] calls.
91    ///
92    /// Write the bytes in `data` at offset `offset` within immediate data
93    /// storage.  Both `offset` and the length of `data` must be
94    /// multiples of [`crate::IMMEDIATE_DATA_ALIGNMENT`], which is always 4.
95    ///
96    /// For example, if `offset` is `4` and `data` is eight bytes long, this
97    /// call will write `data` to bytes `4..12` of immediate data storage.
98    pub fn set_immediates(&mut self, offset: u32, data: &[u8]) {
99        self.inner.set_immediates(offset, data);
100    }
101}
102
103/// Describes the attachments of a ray tracing pass.
104///
105/// For use with [`CommandEncoder::begin_ray_tracing_pass`].
106#[derive(Clone, Default, Debug)]
107pub struct RayTracingPassDescriptor<'a> {
108    /// Debug label of the ray tracing pass. This will show up in graphics debuggers for easy identification.
109    pub label: Label<'a>,
110}
111#[cfg(send_sync)]
112static_assertions::assert_impl_all!(RayTracingPassDescriptor<'_>: Send, Sync);