Skip to main content

wgpu_core/
ray_tracing_pipeline.rs

1use alloc::{boxed::Box, string::String, sync::Arc, vec::Vec};
2use core::{mem::ManuallyDrop, num::NonZeroU64};
3use hal::BufferDescriptor;
4
5use arrayvec::ArrayVec;
6use thiserror::Error;
7use wgt::error::{ErrorType, WebGpuError};
8
9use crate::pipeline::{
10    CreatePipelineError, LateSizedBufferGroup, PipelineCache, ProgrammableStageDescriptor,
11    ShaderModule,
12};
13use crate::{
14    binding_model::{BindGroupLayout, GetBindGroupLayoutError, PipelineLayout},
15    device::Device,
16    resource::{InvalidResourceError, Labeled, ResourceState, TrackingData},
17    resource_log, Label,
18};
19
20#[derive(Clone, Debug, Error)]
21#[non_exhaustive]
22pub enum RayTracingPipelineError {
23    #[error("The number of intersection shaders {0} is greater than 2^24")]
24    TooManyIntersectionGroups(usize),
25    #[error(
26        "The ray recursion depth {0} is greater than the limit Limits::max_ray_recursion_depth {1}"
27    )]
28    TooHighRayRecursionDepth(u32, u32),
29}
30
31impl WebGpuError for RayTracingPipelineError {
32    fn webgpu_error_type(&self) -> ErrorType {
33        match self {
34            Self::TooManyIntersectionGroups(..) | Self::TooHighRayRecursionDepth(..) => {
35                ErrorType::Validation
36            }
37        }
38    }
39}
40
41#[derive(Clone, Debug)]
42#[cfg_attr(feature = "serde", derive(serde::Serialize, serde::Deserialize))]
43pub enum RayTracingIntersectionDescriptor<'a, SM = Arc<ShaderModule>> {
44    Triangle {
45        closest_hit: ProgrammableStageDescriptor<'a, SM>,
46        any_hit: Option<ProgrammableStageDescriptor<'a, SM>>,
47    },
48}
49
50/// Describes a ray tracing pipeline.
51#[derive(Clone, Debug)]
52#[cfg_attr(feature = "serde", derive(serde::Serialize, serde::Deserialize))]
53pub struct RayTracingPipelineDescriptor<
54    'a,
55    PLL = Arc<PipelineLayout>,
56    SM = Arc<ShaderModule>,
57    PLC = Arc<PipelineCache>,
58> {
59    pub label: Label<'a>,
60    /// The layout of bind groups for this pipeline.
61    pub layout: Option<PLL>,
62    /// The ray generation stage descriptor
63    pub ray_generation: ProgrammableStageDescriptor<'a, SM>,
64    /// The miss stage descriptor
65    pub miss: ProgrammableStageDescriptor<'a, SM>,
66    /// All the descriptors for intersection functions
67    pub intersections: Vec<RayTracingIntersectionDescriptor<'a, SM>>,
68    /// The maximum number of nested `traceRay` calls. The ray generation stage is at depth 0.
69    pub max_recursion_depth: u32,
70    /// The pipeline cache to use when creating this pipeline.
71    pub cache: Option<PLC>,
72}
73
74/// The type of intersection of a index into `RayTracingPipelineDescriptor::intersections`
75#[derive(Debug, Copy, Clone, PartialEq, Eq, Hash)]
76pub enum RayTracingIntersectionType {
77    /// The intersection is to be used for triangles.
78    Triangle,
79    /// The intersection is to be used for AABBs.
80    AABB,
81}
82
83/// Metal's shader binding data is opaque, but Vulkan's and DX12's has opaque data
84/// but a non-opaque storage mechanism, so each require separate codepaths.
85/// Therefore, this is a semi-opaque structure because if metal gets ray tracing pipelines,
86/// this will need to turn into an enum so it shouldn't have other code
87/// tangled with it.
88#[derive(Debug)]
89pub struct ShaderBindingData {
90    pub(crate) raw: ManuallyDrop<Box<dyn hal::DynBuffer>>,
91    pub(crate) device: Arc<Device>,
92    pub(crate) num_intersection_groups: u32,
93    pub(crate) miss_offset: wgt::BufferAddress,
94    pub(crate) intersection_offset: wgt::BufferAddress,
95}
96
97impl ShaderBindingData {
98    /// Panics if `num_intersection_groups` is above u32::MAX
99    pub(crate) fn from_raw_pipeline(
100        device: Arc<Device>,
101        pipeline: &dyn hal::DynRayTracingPipeline,
102        num_intersection_groups: usize,
103    ) -> Result<Arc<Self>, CreatePipelineError> {
104        let mut base_data = Vec::new();
105
106        let ray_generation_data = unsafe {
107            device
108                .raw()
109                .get_raytracing_pipeline_group_data(pipeline, 0..1)
110        }
111        .map_err(|e| CreatePipelineError::Device(device.handle_hal_error(e)))?;
112
113        base_data.extend_from_slice(&ray_generation_data);
114
115        let padded_miss_offset = (base_data.len() as wgt::BufferAddress).next_multiple_of(
116            device.alignments.ray_tracing_pipeline_data_offset_alignment as wgt::BufferAddress,
117        );
118
119        base_data.resize(padded_miss_offset as _, 0);
120
121        let miss_data = unsafe {
122            device
123                .raw()
124                .get_raytracing_pipeline_group_data(pipeline, 1..2)
125        }
126        .map_err(|e| CreatePipelineError::Device(device.handle_hal_error(e)))?;
127
128        base_data.extend_from_slice(&miss_data);
129
130        let padded_intersection_offset = (base_data.len() as wgt::BufferAddress).next_multiple_of(
131            device.alignments.ray_tracing_pipeline_data_offset_alignment as wgt::BufferAddress,
132        );
133
134        base_data.resize(padded_intersection_offset as _, 0);
135
136        if num_intersection_groups != 0 {
137            let intersection_data = unsafe {
138                device.raw().get_raytracing_pipeline_group_data(
139                    pipeline,
140                    2..(2 + num_intersection_groups as u32),
141                )
142            }
143            .map_err(|e| CreatePipelineError::Device(device.handle_hal_error(e)))?;
144
145            base_data.extend_from_slice(&intersection_data);
146        }
147
148        // Don't need the exact allocated size as it will be grater than this.
149        let (buffer, _) = unsafe {
150            device.raw().create_buffer(&BufferDescriptor {
151                label: None,
152                size: base_data.len() as _,
153                usage: wgt::BufferUses::RAY_TRACING_PIPELINE_SHADER_DATA
154                    | wgt::BufferUses::COPY_DST,
155                memory_flags: hal::MemoryFlags::PREFER_COHERENT,
156            })
157        }
158        .map_err(|e| CreatePipelineError::Device(device.handle_hal_error(e)))?;
159
160        let sbd = Arc::new(Self {
161            raw: ManuallyDrop::new(buffer),
162            device: device.clone(),
163            num_intersection_groups: u32::try_from(num_intersection_groups).unwrap(),
164            miss_offset: padded_miss_offset,
165            intersection_offset: padded_intersection_offset,
166        });
167
168        // If there is no queue anymore, the ray tracing pipeline can't be accessed, so we don't have to worry about UB from uninitialized values
169        if let Some(queue) = device.get_queue() {
170            let mut staging = crate::resource::StagingBuffer::new(
171                &device,
172                NonZeroU64::new(base_data.len() as _).expect(
173                    "The total number of groups is always greater than zero, \
174                         and `ray_tracing_pipeline_group_data_size` must be too.",
175                ),
176            )?;
177
178            staging.write_exact(&base_data);
179
180            let staging_buf = staging.flush();
181
182            let mut writes = queue.pending_writes.lock();
183            let encoder = writes.activate();
184            unsafe {
185                encoder.transition_buffers(&[
186                    hal::BufferBarrier {
187                        buffer: staging_buf.raw(),
188                        usage: hal::StateTransition {
189                            from: wgt::BufferUses::MAP_WRITE,
190                            to: wgt::BufferUses::COPY_SRC,
191                        },
192                    },
193                    hal::BufferBarrier {
194                        buffer: sbd.raw.as_ref(),
195                        usage: hal::StateTransition {
196                            from: wgt::BufferUses::empty(),
197                            to: wgt::BufferUses::COPY_DST,
198                        },
199                    },
200                ]);
201                encoder.copy_buffer_to_buffer(
202                    staging_buf.raw(),
203                    sbd.raw.as_ref(),
204                    &[hal::BufferCopy {
205                        src_offset: 0,
206                        dst_offset: 0,
207                        size: NonZeroU64::new(base_data.len() as _)
208                            .expect("Already checked size isn't zero."),
209                    }],
210                );
211                encoder.transition_buffers(&[hal::BufferBarrier {
212                    buffer: sbd.raw.as_ref(),
213                    usage: hal::StateTransition {
214                        from: wgt::BufferUses::COPY_DST,
215                        to: wgt::BufferUses::RAY_TRACING_PIPELINE_SHADER_DATA,
216                    },
217                }]);
218            };
219
220            writes.consume(staging_buf);
221            writes.use_shader_binding_data(&sbd);
222        }
223
224        Ok(sbd)
225    }
226}
227
228impl Drop for ShaderBindingData {
229    fn drop(&mut self) {
230        // SAFETY: We are in the Drop impl and we don't use self.raw anymore after this point.
231        let raw = unsafe { ManuallyDrop::take(&mut self.raw) };
232        unsafe {
233            self.device.raw().destroy_buffer(raw);
234        }
235    }
236}
237
238#[derive(Debug)]
239pub(crate) struct RayTracingPipelineState {
240    pub(crate) raw: ManuallyDrop<Box<dyn hal::DynRayTracingPipeline>>,
241    pub(crate) layout: Arc<PipelineLayout>,
242    pub(crate) shader_binding_data: Arc<ShaderBindingData>,
243    pub(crate) _shader_modules: Vec<Arc<ShaderModule>>,
244    pub(crate) intersection_types: Arc<[RayTracingIntersectionType]>,
245}
246
247#[derive(Debug)]
248pub struct RayTracingPipeline {
249    pub(crate) state: ResourceState<RayTracingPipelineState>,
250    pub(crate) device: Arc<Device>,
251    pub(crate) late_sized_buffer_groups: ArrayVec<LateSizedBufferGroup, { hal::MAX_BIND_GROUPS }>,
252    pub(crate) immediate_slots_required: naga::valid::ImmediateSlots,
253    /// The `label` from the descriptor used to create the resource.
254    pub(crate) label: String,
255    pub(crate) tracking_data: TrackingData,
256}
257
258impl Drop for RayTracingPipeline {
259    fn drop(&mut self) {
260        resource_log!("Destroy raw {}", self.error_ident());
261
262        #[cfg(feature = "trace")]
263        {
264            use crate::device::trace;
265            if let Some(t) = self.device.trace.lock().as_mut() {
266                t.add(trace::Action::DropRayTracingPipeline(unsafe {
267                    trace::to_trace(self)
268                }));
269            }
270        }
271
272        let ResourceState::Valid(state) = &mut self.state else {
273            return;
274        };
275
276        // SAFETY: We are in the Drop impl and we don't use self.raw anymore after this point.
277        let raw = unsafe { ManuallyDrop::take(&mut state.raw) };
278        unsafe {
279            self.device.raw().destroy_ray_tracing_pipeline(raw);
280        }
281    }
282}
283
284crate::impl_resource_type!(RayTracingPipeline);
285crate::impl_labeled!(RayTracingPipeline);
286crate::impl_parent_device!(RayTracingPipeline);
287crate::impl_storage_item!(RayTracingPipeline);
288crate::impl_trackable!(RayTracingPipeline);
289
290impl RayTracingPipeline {
291    pub(crate) fn raw(&self) -> Result<&dyn hal::DynRayTracingPipeline, InvalidResourceError> {
292        let ResourceState::Valid(state) = &self.state else {
293            return Err(InvalidResourceError(self.error_ident()));
294        };
295        Ok(state.raw.as_ref())
296    }
297
298    pub(crate) fn invalid(device: Arc<Device>, label: String) -> Arc<Self> {
299        Arc::new(Self {
300            tracking_data: TrackingData::new(device.tracker_indices.ray_tracing_pipelines.clone()),
301            state: ResourceState::Invalid,
302            device,
303            immediate_slots_required: naga::valid::ImmediateSlots::default(),
304            late_sized_buffer_groups: ArrayVec::new(),
305            label,
306        })
307    }
308
309    pub(crate) fn check_valid(&self) -> Result<(), InvalidResourceError> {
310        let ResourceState::Valid(_) = &self.state else {
311            return Err(InvalidResourceError(self.error_ident()));
312        };
313        Ok(())
314    }
315
316    pub(crate) fn layout(&self) -> Result<&Arc<PipelineLayout>, InvalidResourceError> {
317        let ResourceState::Valid(state) = &self.state else {
318            return Err(InvalidResourceError(self.error_ident()));
319        };
320        Ok(&state.layout)
321    }
322
323    pub(crate) fn shader_binding_data(&self) -> Result<&ShaderBindingData, InvalidResourceError> {
324        let ResourceState::Valid(state) = &self.state else {
325            return Err(InvalidResourceError(self.error_ident()));
326        };
327        Ok(&state.shader_binding_data)
328    }
329
330    pub(crate) fn intersection_types(
331        &self,
332    ) -> Result<&Arc<[RayTracingIntersectionType]>, InvalidResourceError> {
333        let ResourceState::Valid(state) = &self.state else {
334            return Err(InvalidResourceError(self.error_ident()));
335        };
336        Ok(&state.intersection_types)
337    }
338
339    pub fn get_bind_group_layout_inner(
340        self: &Arc<Self>,
341        index: u32,
342    ) -> Result<Arc<BindGroupLayout>, GetBindGroupLayoutError> {
343        self.layout()?.get_bind_group_layout(index, self.into())
344    }
345
346    pub fn get_bind_group_layout(
347        self: &Arc<Self>,
348        index: u32,
349    ) -> (Arc<BindGroupLayout>, Option<GetBindGroupLayoutError>) {
350        let (bgl, error) = match self.get_bind_group_layout_inner(index) {
351            Ok(bgl) => (bgl, None),
352            Err(e) => (
353                BindGroupLayout::invalid(&self.device, String::new()),
354                Some(e),
355            ),
356        };
357        #[cfg(feature = "trace")]
358        if let Some(ref mut trace) = *self.device.trace.lock() {
359            use crate::device::trace;
360            use trace::IntoTrace;
361            trace.add(trace::Action::GetRayTracingPipelineBindGroupLayout {
362                id: bgl.to_trace(),
363                pipeline: self.to_trace(),
364                index,
365            });
366        };
367        (bgl, error)
368    }
369}