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);