Skip to main content

wgpu_core/
pipeline.rs

1use alloc::string::ToString as _;
2use alloc::{
3    borrow::{Cow, ToOwned},
4    boxed::Box,
5    string::String,
6    sync::Arc,
7    vec::Vec,
8};
9use core::{marker::PhantomData, mem::ManuallyDrop, num::NonZeroU32};
10
11use arrayvec::ArrayVec;
12use naga::error::ShaderError;
13use thiserror::Error;
14use wgt::error::{ErrorType, WebGpuError};
15
16pub use crate::pipeline_cache::PipelineCacheValidationError;
17use crate::ray_tracing_pipeline::RayTracingPipelineError;
18use crate::{
19    api_log,
20    binding_model::{
21        BindGroupLayout, CreateBindGroupLayoutError, CreatePipelineLayoutError,
22        GetBindGroupLayoutError, PipelineLayout,
23    },
24    command::ColorAttachmentError,
25    device::{
26        AttachmentData, Device, DeviceError, MissingDownlevelFlags, MissingFeatures,
27        RenderPassContext,
28    },
29    pipeline_cache,
30    resource::{InvalidResourceError, Labeled, ResourceState, TrackingData},
31    resource_log, validation, FastHashSet, Label, LabelHelpers as _,
32};
33
34/// Information about buffer bindings, which
35/// is validated against the shader (and pipeline)
36/// at draw time as opposed to initialization time.
37#[derive(Debug, Default)]
38pub(crate) struct LateSizedBufferGroup {
39    // The order has to match `BindGroup::late_buffer_binding_sizes`.
40    pub(crate) shader_sizes: Vec<wgt::BufferAddress>,
41}
42
43#[allow(clippy::large_enum_variant)]
44pub enum ShaderModuleSource<'a> {
45    #[cfg(feature = "wgsl")]
46    Wgsl(Cow<'a, str>),
47    #[cfg(feature = "glsl")]
48    Glsl(Cow<'a, str>, naga::front::glsl::Options),
49    #[cfg(feature = "spirv")]
50    SpirV(Cow<'a, [u32]>, naga::front::spv::Options),
51    Naga(Cow<'static, naga::Module>),
52    /// Dummy variant because `Naga` doesn't have a lifetime and without enough active features it
53    /// could be the last one active.
54    #[doc(hidden)]
55    Dummy(PhantomData<&'a ()>),
56}
57
58#[derive(Clone, Debug)]
59#[cfg_attr(feature = "serde", derive(serde::Serialize, serde::Deserialize))]
60pub struct ShaderModuleDescriptor<'a> {
61    pub label: Label<'a>,
62    #[cfg_attr(feature = "serde", serde(default))]
63    pub runtime_checks: wgt::ShaderRuntimeChecks,
64}
65
66pub type ShaderModuleDescriptorPassthrough<'a> =
67    wgt::CreateShaderModuleDescriptorPassthrough<'a, Label<'a>>;
68
69#[derive(Debug)]
70pub struct PassthroughInterface {
71    pub entry_point_names: FastHashSet<String>,
72}
73
74// Most shaders will use a standard interface which is very large.
75// Passthrough shaders have a much smaller interface. No reason to
76// box the standard interface though.
77#[expect(clippy::large_enum_variant)]
78#[derive(Debug)]
79pub enum ShaderModuleState {
80    /// A Naga module, from which we generate a `wgpu_hal` shader module
81    /// for each pipeline stage that uses it.
82    NagaModule {
83        shader: hal::NagaShader,
84        runtime_checks: wgt::ShaderRuntimeChecks,
85    },
86    Passthrough {
87        raw: Box<dyn hal::DynShaderModule>,
88        interface: PassthroughInterface,
89    },
90}
91
92#[derive(Debug)]
93pub struct ShaderModule {
94    pub(crate) state: ResourceState<ShaderModuleState>,
95    pub(crate) device: Arc<Device>,
96    /// The `label` from the descriptor used to create the resource.
97    pub(crate) label: String,
98    pub(crate) compilation_info: wgt::CompilationInfo,
99}
100
101impl Drop for ShaderModule {
102    #[allow(trivial_casts)]
103    fn drop(&mut self) {
104        profiling::scope!("ShaderModule::drop");
105        api_log!("ShaderModule::drop {:?}", self as *const _);
106        resource_log!("Destroy raw {}", self.error_ident());
107        #[cfg(feature = "trace")]
108        if let Some(t) = self.device.trace.lock().as_mut() {
109            use crate::device::trace::{to_trace, Action};
110
111            t.add(Action::DropShaderModule(unsafe { to_trace(self) }));
112        }
113        let ResourceState::Valid(state) =
114            core::mem::replace(&mut self.state, ResourceState::Invalid)
115        else {
116            return;
117        };
118        match state {
119            ShaderModuleState::NagaModule { .. } => {}
120            ShaderModuleState::Passthrough { raw, .. } => unsafe {
121                self.device.raw().destroy_shader_module(raw);
122            },
123        }
124    }
125}
126
127crate::impl_resource_type!(ShaderModule);
128crate::impl_labeled!(ShaderModule);
129crate::impl_parent_device!(ShaderModule);
130crate::impl_storage_item!(ShaderModule);
131
132impl ShaderModule {
133    pub(crate) fn state(&self) -> Result<&ShaderModuleState, InvalidResourceError> {
134        let ResourceState::Valid(state) = &self.state else {
135            return Err(InvalidResourceError(self.error_ident()));
136        };
137        Ok(state)
138    }
139
140    pub(crate) fn invalid(
141        device: Arc<Device>,
142        label: String,
143        compilation_info: wgt::CompilationInfo,
144    ) -> Arc<Self> {
145        Arc::new(Self {
146            state: ResourceState::Invalid,
147            device,
148            label,
149            compilation_info,
150        })
151    }
152
153    pub fn compilation_info(&self) -> &wgt::CompilationInfo {
154        &self.compilation_info
155    }
156
157    /// Select an entry point name, given an optional name and a shader stage.
158    ///
159    /// This function resolves an `Option<&str>`
160    /// [`ProgrammableStageDescriptor::entry_point`][ep] value to the name of an
161    /// entry point in `self`.
162    ///
163    /// If `entry_point` is given, verify that `self` has an entry point by that
164    /// name for `stage`, and then return the name as an owned `String`.
165    ///
166    /// If `entry_point` is `None`, verify that `self` has exactly one entry
167    /// point for `stage`, and return its name.
168    ///
169    /// Passthrough modules do not record entry points' stages, so for those,
170    /// `stage` is ignored.
171    ///
172    /// [ep]: crate::pipeline::ProgrammableStageDescriptor::entry_point
173    pub(crate) fn finalize_entry_point_name(
174        &self,
175        stage: naga::ShaderStage,
176        entry_point: Option<&str>,
177    ) -> Result<String, validation::StageError> {
178        let state = self.state()?;
179        match state {
180            ShaderModuleState::NagaModule { ref shader, .. } => {
181                finalize_naga_entry_point_name(&shader.module, stage, entry_point)
182            }
183            ShaderModuleState::Passthrough { ref interface, .. } => {
184                finalize_passthrough_entry_point_name(interface, entry_point)
185            }
186        }
187    }
188}
189
190fn finalize_naga_entry_point_name(
191    module: &naga::Module,
192    stage: naga::ShaderStage,
193    entry_point: Option<&str>,
194) -> Result<String, validation::StageError> {
195    let mut candidates = module.entry_points.iter().filter(|ep| ep.stage == stage);
196    if let Some(name) = entry_point {
197        return match candidates.find(|ep| ep.name == name) {
198            Some(ep) => Ok(ep.name.clone()),
199            None => Err(validation::StageError::NoEntryPointWithNameForStage {
200                stage,
201                name: name.to_owned(),
202            }),
203        };
204    }
205
206    let Some(first) = candidates.next() else {
207        return Err(validation::StageError::NoEntryPointForStage(stage));
208    };
209    if candidates.next().is_some() {
210        return Err(validation::StageError::AmbiguousEntryPointForStage(stage));
211    }
212    Ok(first.name.clone())
213}
214
215fn finalize_passthrough_entry_point_name(
216    interface: &PassthroughInterface,
217    entry_point: Option<&str>,
218) -> Result<String, validation::StageError> {
219    if let Some(ep) = entry_point {
220        return if interface.entry_point_names.contains(ep) {
221            Ok(ep.to_owned())
222        } else {
223            Err(validation::StageError::NoEntryPointWithName(ep.to_owned()))
224        };
225    }
226
227    match interface.entry_point_names.len() {
228        0 => Err(validation::StageError::NoEntryPoints),
229        1 => Ok(interface
230            .entry_point_names
231            .iter()
232            .next()
233            .unwrap()
234            .to_owned()),
235        _ => Err(validation::StageError::AmbiguousEntryPoint),
236    }
237}
238
239//Note: `Clone` would require `WithSpan: Clone`.
240#[derive(Clone, Debug, Error)]
241#[non_exhaustive]
242pub enum CreateShaderModuleError {
243    // These variants deliberately don't forward to `ShaderError`'s `Display`,
244    // which would include the shader source text and detailed compiler messages:
245    // per the WebGPU specification <https://gpuweb.github.io/gpuweb/#dom-gpudevice-createshadermodule>,
246    // the message of the validation error raised by `createShaderModule` should not include those details,
247    // since they are accessible via `getCompilationInfo()`.
248    #[cfg(feature = "wgsl")]
249    #[error("Shader '{label}' parsing error. Concrete error is available via `get_compilation_info`", label = _0.label.as_deref().unwrap_or_default())]
250    Parsing(ShaderError<naga::front::wgsl::ParseError>),
251
252    #[cfg(feature = "glsl")]
253    #[error("Shader '{label}' parsing error. Concrete error is available via `get_compilation_info`", label = _0.label.as_deref().unwrap_or_default())]
254    ParsingGlsl(ShaderError<naga::front::glsl::ParseErrors>),
255
256    #[cfg(feature = "spirv")]
257    #[error("Shader '{label}' parsing error. Concrete error is available via `get_compilation_info`", label = _0.label.as_deref().unwrap_or_default())]
258    ParsingSpirV(ShaderError<naga::front::spv::Error>),
259
260    #[error("Failed to generate the backend-specific code")]
261    Generation,
262
263    #[error(transparent)]
264    Device(#[from] DeviceError),
265
266    #[error("Shader '{label}' validation error. Concrete error is available via `get_compilation_info`", label = _0.label.as_deref().unwrap_or_default())]
267    Validation(ShaderError<naga::WithSpan<naga::valid::ValidationError>>),
268
269    #[error(transparent)]
270    MissingFeatures(#[from] MissingFeatures),
271
272    #[error(
273        "Shader global {bind:?} uses a group index {group} that exceeds the max_bind_groups limit of {limit}."
274    )]
275    InvalidGroupIndex {
276        bind: naga::ResourceBinding,
277        group: u32,
278        limit: u32,
279    },
280
281    #[error("Generic shader passthrough does not contain any code compatible with this backend.")]
282    NotCompiledForBackend,
283
284    #[error(
285        "Generic passthrough shaders which use GLSL or DXIL must contain exactly one entry point."
286    )]
287    IncorrectPassthroughEntryPointCount,
288}
289
290impl WebGpuError for CreateShaderModuleError {
291    fn webgpu_error_type(&self) -> ErrorType {
292        match self {
293            Self::Device(e) => e.webgpu_error_type(),
294            Self::MissingFeatures(e) => e.webgpu_error_type(),
295
296            Self::Generation => ErrorType::Internal,
297
298            Self::Validation(..)
299            | Self::InvalidGroupIndex { .. }
300            | Self::IncorrectPassthroughEntryPointCount
301            | Self::NotCompiledForBackend => ErrorType::Validation,
302            #[cfg(feature = "wgsl")]
303            Self::Parsing(..) => ErrorType::Validation,
304            #[cfg(feature = "glsl")]
305            Self::ParsingGlsl(..) => ErrorType::Validation,
306            #[cfg(feature = "spirv")]
307            Self::ParsingSpirV(..) => ErrorType::Validation,
308        }
309    }
310}
311
312#[cfg(feature = "wgsl")]
313pub(crate) fn wgsl_to_compilation_info(
314    value: &ShaderError<naga::front::wgsl::ParseError>,
315) -> wgt::CompilationInfo {
316    use alloc::{string::ToString, vec};
317    wgt::CompilationInfo {
318        messages: vec![wgt::CompilationMessage {
319            message: value.to_string(),
320            message_type: wgt::CompilationMessageType::Error,
321            location: value
322                .inner
323                .location(&value.source)
324                .as_ref()
325                .map(naga_to_source_location),
326        }],
327    }
328}
329#[cfg(feature = "glsl")]
330pub(crate) fn glsl_to_compilation_info(
331    value: &ShaderError<naga::front::glsl::ParseErrors>,
332) -> wgt::CompilationInfo {
333    use alloc::string::ToString;
334    let messages = value
335        .inner
336        .errors
337        .iter()
338        .map(|err| wgt::CompilationMessage {
339            message: err.to_string(),
340            message_type: wgt::CompilationMessageType::Error,
341            location: err
342                .location(&value.source)
343                .as_ref()
344                .map(naga_to_source_location),
345        })
346        .collect();
347    wgt::CompilationInfo { messages }
348}
349
350#[cfg(feature = "spirv")]
351pub(crate) fn spirv_to_compilation_info(
352    value: &ShaderError<naga::front::spv::Error>,
353) -> wgt::CompilationInfo {
354    use alloc::{string::ToString, vec};
355    wgt::CompilationInfo {
356        messages: vec![wgt::CompilationMessage {
357            message: value.to_string(),
358            message_type: wgt::CompilationMessageType::Error,
359            location: None,
360        }],
361    }
362}
363
364pub(crate) fn naga_to_compilation_info(
365    value: &ShaderError<naga::WithSpan<naga::valid::ValidationError>>,
366) -> wgt::CompilationInfo {
367    use alloc::{string::ToString, vec};
368    wgt::CompilationInfo {
369        messages: vec![wgt::CompilationMessage {
370            message: value.to_string(),
371            message_type: wgt::CompilationMessageType::Error,
372            location: value
373                .inner
374                .location(&value.source)
375                .as_ref()
376                .map(naga_to_source_location),
377        }],
378    }
379}
380
381fn naga_to_source_location(value: &naga::SourceLocation) -> wgt::SourceLocation {
382    wgt::SourceLocation {
383        length: value.length,
384        offset: value.offset,
385        line_number: value.line_number,
386        line_position: value.line_position,
387    }
388}
389
390pub(crate) fn shader_module_error_into_compilation_info(
391    value: &CreateShaderModuleError,
392) -> wgt::CompilationInfo {
393    match value {
394        #[cfg(feature = "wgsl")]
395        CreateShaderModuleError::Parsing(v) => wgsl_to_compilation_info(v),
396        #[cfg(feature = "glsl")]
397        CreateShaderModuleError::ParsingGlsl(v) => glsl_to_compilation_info(v),
398        #[cfg(feature = "spirv")]
399        CreateShaderModuleError::ParsingSpirV(v) => spirv_to_compilation_info(v),
400        CreateShaderModuleError::Validation(v) => naga_to_compilation_info(v),
401        // Device errors are reported through the error sink, and are not compilation errors.
402        // Same goes for native shader module generation errors.
403        CreateShaderModuleError::Device(_) | CreateShaderModuleError::Generation => {
404            wgt::CompilationInfo {
405                messages: Vec::new(),
406            }
407        }
408        // Everything else is an error message without location information.
409        _ => wgt::CompilationInfo {
410            messages: alloc::vec![wgt::CompilationMessage {
411                message: value.to_string(),
412                message_type: wgt::CompilationMessageType::Error,
413                location: None,
414            }],
415        },
416    }
417}
418
419/// Describes a programmable pipeline stage.
420#[derive(Clone, Debug)]
421#[cfg_attr(feature = "serde", derive(serde::Serialize, serde::Deserialize))]
422/// cbindgen:ignore
423pub struct ProgrammableStageDescriptor<'a, SM = Arc<ShaderModule>> {
424    /// The compiled shader module for this stage.
425    pub module: SM,
426
427    /// The name of the entry point in `module` that this stage should use.
428    ///
429    /// - If this is `Some(name)`, `module` must contain an entry point with the
430    ///   given name.
431    ///
432    /// - If this is `None`, `module` must have only one entry point for this
433    ///   stage; we use that one.
434    pub entry_point: Option<Cow<'a, str>>,
435
436    /// Values for pipeline-overridable constants in `module` that this stage
437    /// should use.
438    ///
439    /// If an `@id` attribute was specified on the declaration,
440    /// the key must be the pipeline constant ID as a decimal ASCII number; if not,
441    /// the key must be the constant's identifier name.
442    ///
443    /// The value may represent any of WGSL's concrete scalar types.
444    pub constants: naga::back::PipelineConstants,
445
446    /// Whether variables in the workgroup address space will be initialized
447    /// with zero values for this stage.
448    ///
449    /// The WebGPU spec requires variables in the workgroup address space to be
450    /// zeroed. However, initialization does impose some overhead, and
451    /// non-browser applications may not need it.
452    pub zero_initialize_workgroup_memory: bool,
453}
454
455#[derive(Clone, Debug, Error)]
456#[non_exhaustive]
457pub enum CreatePipelineError {
458    #[error(transparent)]
459    Device(#[from] DeviceError),
460    #[error("Unable to derive an implicit layout")]
461    Implicit(#[from] ImplicitLayoutError),
462    #[error("Error matching {stage:?} shader requirements against the pipeline")]
463    Stage {
464        stage: wgt::ShaderStages,
465        #[source]
466        error: validation::StageError,
467    },
468    #[error("Internal error in {stage:?} shader: {message}")]
469    Internal {
470        stage: wgt::ShaderStages,
471        message: String,
472    },
473    #[error("Pipeline constant error in {stage:?} shader: {message}")]
474    PipelineConstants {
475        stage: wgt::ShaderStages,
476        message: String,
477    },
478    #[error(transparent)]
479    MissingFeatures(#[from] MissingFeatures),
480    #[error(transparent)]
481    MissingDownlevelFlags(#[from] MissingDownlevelFlags),
482    #[error(transparent)]
483    InvalidResource(#[from] InvalidResourceError),
484    #[error(transparent)]
485    Render(#[from] RenderError),
486    #[error(transparent)]
487    RayTracing(#[from] RayTracingPipelineError),
488}
489
490impl From<ColorAttachmentError> for CreatePipelineError {
491    fn from(error: ColorAttachmentError) -> Self {
492        Self::Render(error.into())
493    }
494}
495
496impl From<DepthStencilStateError> for CreatePipelineError {
497    fn from(error: DepthStencilStateError) -> Self {
498        Self::Render(error.into())
499    }
500}
501
502impl CreatePipelineError {
503    /// Convert a [`hal::PipelineError`] to a [`CreatePipelineError`], without noting device loss.
504    ///
505    /// If you have a [`Device`] handy, prefer to call
506    /// [`Device::handle_hal_pipeline_error`] instead, since that checks for
507    /// device loss errors and sets the device's lost flag accordingly.
508    ///
509    /// This is deliberately not a `From` impl, so that `?` cannot silently skip
510    /// device-loss handling.
511    pub(crate) fn from_hal_without_device_loss(error: hal::PipelineError) -> Self {
512        match error {
513            hal::PipelineError::Device(error) => {
514                CreatePipelineError::Device(DeviceError::from_hal(error))
515            }
516            hal::PipelineError::Linkage(stage, message) => {
517                CreatePipelineError::Internal { stage, message }
518            }
519            hal::PipelineError::EntryPoint(stage) => CreatePipelineError::Internal {
520                stage: hal::auxil::map_naga_stage(stage),
521                message: crate::device::ENTRYPOINT_FAILURE_ERROR.to_string(),
522            },
523            hal::PipelineError::PipelineConstants(stage, message) => {
524                CreatePipelineError::PipelineConstants { stage, message }
525            }
526        }
527    }
528}
529
530/// Number of implicit bind groups derived at pipeline creation.
531pub type ImplicitBindGroupCount = u8;
532
533#[derive(Clone, Debug, Error)]
534#[non_exhaustive]
535pub enum ImplicitLayoutError {
536    #[error(transparent)]
537    BindGroup(#[from] CreateBindGroupLayoutError),
538    #[error(transparent)]
539    Pipeline(#[from] CreatePipelineLayoutError),
540    #[error("Unable to create implicit pipeline layout from passthrough shader stage: {0:?}")]
541    Passthrough(wgt::ShaderStages),
542}
543
544impl WebGpuError for ImplicitLayoutError {
545    fn webgpu_error_type(&self) -> ErrorType {
546        match self {
547            Self::BindGroup(e) => e.webgpu_error_type(),
548            Self::Pipeline(e) => e.webgpu_error_type(),
549            Self::Passthrough(_) => ErrorType::Validation,
550        }
551    }
552}
553
554/// Describes a compute pipeline.
555#[derive(Clone, Debug)]
556#[cfg_attr(feature = "serde", derive(serde::Serialize, serde::Deserialize))]
557/// cbindgen:ignore
558pub struct ComputePipelineDescriptor<
559    'a,
560    PLL = Arc<PipelineLayout>,
561    SM = Arc<ShaderModule>,
562    PLC = Arc<PipelineCache>,
563> {
564    pub label: Label<'a>,
565    /// The layout of bind groups for this pipeline.
566    pub layout: Option<PLL>,
567    /// The compiled compute stage and its entry point.
568    pub stage: ProgrammableStageDescriptor<'a, SM>,
569    /// The pipeline cache to use when creating this pipeline.
570    pub cache: Option<PLC>,
571}
572
573impl WebGpuError for CreatePipelineError {
574    fn webgpu_error_type(&self) -> ErrorType {
575        match self {
576            Self::Device(e) => e.webgpu_error_type(),
577            Self::InvalidResource(e) => e.webgpu_error_type(),
578            Self::MissingFeatures(e) => e.webgpu_error_type(),
579            Self::MissingDownlevelFlags(e) => e.webgpu_error_type(),
580            Self::Implicit(e) => e.webgpu_error_type(),
581            Self::Stage { error: e, .. } => e.webgpu_error_type(),
582            Self::Internal { .. } => ErrorType::Internal,
583            Self::PipelineConstants { .. } => ErrorType::Validation,
584            Self::Render(e) => e.webgpu_error_type(),
585            Self::RayTracing(e) => e.webgpu_error_type(),
586        }
587    }
588}
589
590#[derive(Debug)]
591pub struct ComputePipelineState {
592    pub(crate) raw: ManuallyDrop<Box<dyn hal::DynComputePipeline>>,
593    pub(crate) layout: Arc<PipelineLayout>,
594    pub(crate) _shader_module: Arc<ShaderModule>,
595}
596
597#[derive(Debug)]
598pub struct ComputePipeline {
599    pub(crate) state: ResourceState<ComputePipelineState>,
600    pub(crate) device: Arc<Device>,
601    pub(crate) late_sized_buffer_groups: ArrayVec<LateSizedBufferGroup, { hal::MAX_BIND_GROUPS }>,
602    pub(crate) immediate_slots_required: naga::valid::ImmediateSlots,
603    /// The `label` from the descriptor used to create the resource.
604    pub(crate) label: String,
605    pub(crate) tracking_data: TrackingData,
606}
607
608impl Drop for ComputePipeline {
609    #[allow(trivial_casts)]
610    fn drop(&mut self) {
611        profiling::scope!("ComputePipeline::drop");
612        api_log!("ComputePipeline::drop {:?}", self as *const _);
613        resource_log!("Destroy raw {}", self.error_ident());
614        #[cfg(feature = "trace")]
615        {
616            use crate::device::trace;
617            if let Some(t) = self.device.trace.lock().as_mut() {
618                t.add(trace::Action::DropComputePipeline(unsafe {
619                    trace::to_trace(self)
620                }));
621            }
622        }
623        let ResourceState::Valid(state) = &mut self.state else {
624            return;
625        };
626        // SAFETY: We are in the Drop impl and we don't use self.raw anymore after this point.
627        let raw = unsafe { ManuallyDrop::take(&mut state.raw) };
628        unsafe {
629            self.device.raw().destroy_compute_pipeline(raw);
630        }
631    }
632}
633
634crate::impl_resource_type!(ComputePipeline);
635crate::impl_labeled!(ComputePipeline);
636crate::impl_parent_device!(ComputePipeline);
637crate::impl_storage_item!(ComputePipeline);
638crate::impl_trackable!(ComputePipeline);
639
640impl ComputePipeline {
641    pub(crate) fn raw(&self) -> Result<&dyn hal::DynComputePipeline, InvalidResourceError> {
642        let ResourceState::Valid(state) = &self.state else {
643            return Err(InvalidResourceError(self.error_ident()));
644        };
645        Ok(state.raw.as_ref())
646    }
647
648    pub(crate) fn layout(&self) -> Result<&Arc<PipelineLayout>, InvalidResourceError> {
649        let ResourceState::Valid(state) = &self.state else {
650            return Err(InvalidResourceError(self.error_ident()));
651        };
652        Ok(&state.layout)
653    }
654
655    pub(crate) fn check_valid(&self) -> Result<(), InvalidResourceError> {
656        let ResourceState::Valid(_) = &self.state else {
657            return Err(InvalidResourceError(self.error_ident()));
658        };
659        Ok(())
660    }
661
662    pub(crate) fn invalid(device: Arc<Device>, label: String) -> Arc<Self> {
663        Arc::new(Self {
664            tracking_data: TrackingData::new(device.tracker_indices.compute_pipelines.clone()),
665            state: ResourceState::Invalid,
666            device,
667            late_sized_buffer_groups: ArrayVec::new(),
668            immediate_slots_required: naga::valid::ImmediateSlots::default(),
669            label,
670        })
671    }
672
673    pub fn get_bind_group_layout_inner(
674        self: &Arc<Self>,
675        index: u32,
676    ) -> Result<Arc<BindGroupLayout>, GetBindGroupLayoutError> {
677        self.layout()?.get_bind_group_layout(index, self.into())
678    }
679
680    pub fn get_bind_group_layout(self: &Arc<Self>, index: u32) -> Arc<BindGroupLayout> {
681        let bgl = self
682            .get_bind_group_layout_inner(index)
683            .unwrap_or_else(|err| {
684                self.device
685                    .handle_error_nolabel(err, "ComputePipeline::get_bind_group_layout");
686                BindGroupLayout::invalid(&self.device, String::new())
687            });
688        #[cfg(feature = "trace")]
689        if let Some(ref mut trace) = *self.device.trace.lock() {
690            use crate::device::trace;
691            use trace::IntoTrace;
692            trace.add(trace::Action::GetComputePipelineBindGroupLayout {
693                id: bgl.to_trace(),
694                pipeline: self.to_trace(),
695                index,
696            });
697        };
698        bgl
699    }
700}
701
702#[derive(Clone, Debug, Error)]
703#[non_exhaustive]
704pub enum CreatePipelineCacheError {
705    #[error(transparent)]
706    Device(#[from] DeviceError),
707    #[error("Pipeline cache validation failed")]
708    Validation(#[from] PipelineCacheValidationError),
709    #[error(transparent)]
710    MissingFeatures(#[from] MissingFeatures),
711}
712
713impl WebGpuError for CreatePipelineCacheError {
714    fn webgpu_error_type(&self) -> ErrorType {
715        match self {
716            Self::Device(e) => e.webgpu_error_type(),
717            Self::Validation(e) => e.webgpu_error_type(),
718            Self::MissingFeatures(e) => e.webgpu_error_type(),
719        }
720    }
721}
722
723#[derive(Debug)]
724pub struct PipelineCache {
725    pub(crate) raw: ResourceState<Box<dyn hal::DynPipelineCache>>,
726    pub(crate) device: Arc<Device>,
727    /// The `label` from the descriptor used to create the resource.
728    pub(crate) label: String,
729}
730
731impl Drop for PipelineCache {
732    #[allow(trivial_casts)]
733    fn drop(&mut self) {
734        profiling::scope!("PipelineCache::drop");
735        api_log!("PipelineCache::drop {:?}", self as *const _);
736        #[cfg(feature = "trace")]
737        if let Some(t) = self.device.trace.lock().as_mut() {
738            use crate::device::trace::{to_trace, Action};
739            t.add(Action::DropPipelineCache(unsafe { to_trace(self) }));
740        }
741        resource_log!("Destroy raw {}", self.error_ident());
742        if let ResourceState::Valid(raw) = core::mem::replace(&mut self.raw, ResourceState::Invalid)
743        {
744            unsafe {
745                self.device.raw().destroy_pipeline_cache(raw);
746            }
747        }
748    }
749}
750
751crate::impl_resource_type!(PipelineCache);
752crate::impl_labeled!(PipelineCache);
753crate::impl_parent_device!(PipelineCache);
754crate::impl_storage_item!(PipelineCache);
755
756impl PipelineCache {
757    pub(crate) fn raw(&self) -> Result<&dyn hal::DynPipelineCache, InvalidResourceError> {
758        self.raw
759            .as_ref()
760            .valid()
761            .map(|raw| raw.as_ref())
762            .ok_or_else(|| InvalidResourceError(self.error_ident()))
763    }
764
765    pub(crate) fn check_is_valid(&self) -> Result<(), InvalidResourceError> {
766        self.raw().map(|_| ())
767    }
768
769    pub(crate) fn invalid(device: Arc<Device>, desc: &PipelineCacheDescriptor) -> Arc<Self> {
770        Arc::new(Self {
771            raw: ResourceState::Invalid,
772            device,
773            label: desc.label.to_string(),
774        })
775    }
776
777    pub fn get_data(self: &Arc<Self>) -> Option<Vec<u8>> {
778        api_log!("PipelineCache::get_data");
779
780        let ResourceState::Valid(raw) = &self.raw else {
781            return None;
782        };
783
784        if !self.device.is_valid() {
785            return None;
786        }
787        let mut vec = unsafe { self.device.raw().pipeline_cache_get_data(raw.as_ref()) }?;
788        let validation_key = self.device.raw().pipeline_cache_validation_key()?;
789
790        let mut header_contents = [0; pipeline_cache::HEADER_LENGTH];
791        pipeline_cache::add_cache_header(
792            &mut header_contents,
793            &vec,
794            &self.device.adapter.raw.info,
795            validation_key,
796        );
797
798        let deleted = vec.splice(..0, header_contents).collect::<Vec<_>>();
799        debug_assert!(deleted.is_empty());
800
801        Some(vec)
802    }
803}
804
805/// Describes how the vertex buffer is interpreted.
806#[derive(Clone, Debug)]
807#[cfg_attr(feature = "serde", derive(serde::Serialize, serde::Deserialize))]
808#[cfg_attr(feature = "serde", serde(rename_all = "camelCase"))]
809pub struct VertexBufferLayout<'a> {
810    /// The stride, in bytes, between elements of this buffer.
811    pub array_stride: wgt::BufferAddress,
812    /// How often this vertex buffer is "stepped" forward.
813    pub step_mode: wgt::VertexStepMode,
814    /// The list of attributes which comprise a single vertex.
815    pub attributes: Cow<'a, [wgt::VertexAttribute]>,
816}
817
818/// A null vertex buffer layout that may be placed in unused slots.
819impl Default for VertexBufferLayout<'_> {
820    fn default() -> Self {
821        Self {
822            array_stride: Default::default(),
823            step_mode: Default::default(),
824            attributes: Cow::Borrowed(&[]),
825        }
826    }
827}
828
829/// Describes the vertex process in a render pipeline.
830#[derive(Clone, Debug)]
831#[cfg_attr(feature = "serde", derive(serde::Serialize, serde::Deserialize))]
832/// cbindgen:ignore
833pub struct VertexState<'a, SM = Arc<ShaderModule>> {
834    /// The compiled vertex stage and its entry point.
835    pub stage: ProgrammableStageDescriptor<'a, SM>,
836    /// The format of any vertex buffers used with this pipeline.
837    pub buffers: Cow<'a, [Option<VertexBufferLayout<'a>>]>,
838}
839
840/// Describes fragment processing in a render pipeline.
841#[derive(Clone, Debug)]
842#[cfg_attr(feature = "serde", derive(serde::Serialize, serde::Deserialize))]
843/// cbindgen:ignore
844pub struct FragmentState<'a, SM = Arc<ShaderModule>> {
845    /// The compiled fragment stage and its entry point.
846    pub stage: ProgrammableStageDescriptor<'a, SM>,
847    /// The effect of draw calls on the color aspect of the output target.
848    pub targets: Cow<'a, [Option<wgt::ColorTargetState>]>,
849}
850
851/// Describes the task shader in a mesh shader pipeline.
852#[derive(Clone, Debug)]
853#[cfg_attr(feature = "serde", derive(serde::Serialize, serde::Deserialize))]
854pub struct TaskState<'a, SM = Arc<ShaderModule>> {
855    /// The compiled task stage and its entry point.
856    pub stage: ProgrammableStageDescriptor<'a, SM>,
857}
858
859/// Describes the mesh shader in a mesh shader pipeline.
860#[derive(Clone, Debug)]
861#[cfg_attr(feature = "serde", derive(serde::Serialize, serde::Deserialize))]
862pub struct MeshState<'a, SM = Arc<ShaderModule>> {
863    /// The compiled mesh stage and its entry point.
864    pub stage: ProgrammableStageDescriptor<'a, SM>,
865}
866
867/// Describes a vertex processor for either a conventional or mesh shading
868/// pipeline architecture.
869///
870/// This is not a public API. It is for use by `player` only. The public APIs
871/// are [`VertexState`], [`TaskState`], and [`MeshState`].
872///
873/// cbindgen:ignore
874#[doc(hidden)]
875#[derive(Clone, Debug)]
876#[cfg_attr(feature = "serde", derive(serde::Serialize, serde::Deserialize))]
877pub enum RenderPipelineVertexProcessor<'a, SM = Arc<ShaderModule>> {
878    Vertex(VertexState<'a, SM>),
879    Mesh(Option<TaskState<'a, SM>>, MeshState<'a, SM>),
880}
881
882/// Describes a render (graphics) pipeline.
883#[derive(Clone, Debug)]
884#[cfg_attr(feature = "serde", derive(serde::Serialize, serde::Deserialize))]
885pub struct RenderPipelineDescriptor<
886    'a,
887    PLL = Arc<PipelineLayout>,
888    SM = Arc<ShaderModule>,
889    PLC = Arc<PipelineCache>,
890> {
891    pub label: Label<'a>,
892    /// The layout of bind groups for this pipeline.
893    pub layout: Option<PLL>,
894    /// The vertex processing state for this pipeline.
895    pub vertex: VertexState<'a, SM>,
896    /// The properties of the pipeline at the primitive assembly and rasterization level.
897    #[cfg_attr(feature = "serde", serde(default))]
898    pub primitive: wgt::PrimitiveState,
899    /// The effect of draw calls on the depth and stencil aspects of the output target, if any.
900    #[cfg_attr(feature = "serde", serde(default))]
901    pub depth_stencil: Option<wgt::DepthStencilState>,
902    /// The multi-sampling properties of the pipeline.
903    #[cfg_attr(feature = "serde", serde(default))]
904    pub multisample: wgt::MultisampleState,
905    /// The fragment processing state for this pipeline.
906    pub fragment: Option<FragmentState<'a, SM>>,
907    /// If the pipeline will be used with a multiview render pass, this indicates how many array
908    /// layers the attachments will have.
909    pub multiview_mask: Option<NonZeroU32>,
910    /// The pipeline cache to use when creating this pipeline.
911    pub cache: Option<PLC>,
912}
913/// Describes a mesh shader pipeline.
914#[derive(Clone, Debug)]
915#[cfg_attr(feature = "serde", derive(serde::Serialize, serde::Deserialize))]
916pub struct MeshPipelineDescriptor<
917    'a,
918    PLL = Arc<PipelineLayout>,
919    SM = Arc<ShaderModule>,
920    PLC = Arc<PipelineCache>,
921> {
922    pub label: Label<'a>,
923    /// The layout of bind groups for this pipeline.
924    pub layout: Option<PLL>,
925    /// The task processing state for this pipeline.
926    pub task: Option<TaskState<'a, SM>>,
927    /// The mesh processing state for this pipeline
928    pub mesh: MeshState<'a, SM>,
929    /// The properties of the pipeline at the primitive assembly and rasterization level.
930    #[cfg_attr(feature = "serde", serde(default))]
931    pub primitive: wgt::PrimitiveState,
932    /// The effect of draw calls on the depth and stencil aspects of the output target, if any.
933    #[cfg_attr(feature = "serde", serde(default))]
934    pub depth_stencil: Option<wgt::DepthStencilState>,
935    /// The multi-sampling properties of the pipeline.
936    #[cfg_attr(feature = "serde", serde(default))]
937    pub multisample: wgt::MultisampleState,
938    /// The fragment processing state for this pipeline.
939    pub fragment: Option<FragmentState<'a, SM>>,
940    /// If the pipeline will be used with a multiview render pass, this indicates how many array
941    /// layers the attachments will have.
942    pub multiview: Option<NonZeroU32>,
943    /// The pipeline cache to use when creating this pipeline.
944    pub cache: Option<PLC>,
945}
946
947/// Describes a render (graphics) pipeline, with either conventional or mesh
948/// shading architecture.
949///
950/// This is not a public API. It is for use by `player` only. The public APIs
951/// are [`RenderPipelineDescriptor`] and [`MeshPipelineDescriptor`].
952///
953/// cbindgen:ignore
954#[doc(hidden)]
955#[derive(Clone, Debug)]
956#[cfg_attr(feature = "serde", derive(serde::Serialize, serde::Deserialize))]
957pub struct GeneralRenderPipelineDescriptor<
958    'a,
959    PLL = Arc<PipelineLayout>,
960    SM = Arc<ShaderModule>,
961    PLC = Arc<PipelineCache>,
962> {
963    pub label: Label<'a>,
964    /// The layout of bind groups for this pipeline.
965    pub layout: Option<PLL>,
966    /// The vertex processing state for this pipeline.
967    pub vertex: RenderPipelineVertexProcessor<'a, SM>,
968    /// The properties of the pipeline at the primitive assembly and rasterization level.
969    #[cfg_attr(feature = "serde", serde(default))]
970    pub primitive: wgt::PrimitiveState,
971    /// The effect of draw calls on the depth and stencil aspects of the output target, if any.
972    #[cfg_attr(feature = "serde", serde(default))]
973    pub depth_stencil: Option<wgt::DepthStencilState>,
974    /// The multi-sampling properties of the pipeline.
975    #[cfg_attr(feature = "serde", serde(default))]
976    pub multisample: wgt::MultisampleState,
977    /// The fragment processing state for this pipeline.
978    pub fragment: Option<FragmentState<'a, SM>>,
979    /// If the pipeline will be used with a multiview render pass, this indicates how many array
980    /// layers the attachments will have.
981    pub multiview_mask: Option<NonZeroU32>,
982    /// The pipeline cache to use when creating this pipeline.
983    pub cache: Option<PLC>,
984}
985impl<'a, PLL, SM, PLC> From<RenderPipelineDescriptor<'a, PLL, SM, PLC>>
986    for GeneralRenderPipelineDescriptor<'a, PLL, SM, PLC>
987{
988    fn from(value: RenderPipelineDescriptor<'a, PLL, SM, PLC>) -> Self {
989        Self {
990            label: value.label,
991            layout: value.layout,
992            vertex: RenderPipelineVertexProcessor::Vertex(value.vertex),
993            primitive: value.primitive,
994            depth_stencil: value.depth_stencil,
995            multisample: value.multisample,
996            fragment: value.fragment,
997            multiview_mask: value.multiview_mask,
998            cache: value.cache,
999        }
1000    }
1001}
1002impl<'a, PLL, SM, PLC> From<MeshPipelineDescriptor<'a, PLL, SM, PLC>>
1003    for GeneralRenderPipelineDescriptor<'a, PLL, SM, PLC>
1004{
1005    fn from(value: MeshPipelineDescriptor<'a, PLL, SM, PLC>) -> Self {
1006        Self {
1007            label: value.label,
1008            layout: value.layout,
1009            vertex: RenderPipelineVertexProcessor::Mesh(value.task, value.mesh),
1010            primitive: value.primitive,
1011            depth_stencil: value.depth_stencil,
1012            multisample: value.multisample,
1013            fragment: value.fragment,
1014            multiview_mask: value.multiview,
1015            cache: value.cache,
1016        }
1017    }
1018}
1019
1020/// Not a public API. For use by `player` only.
1021///
1022/// cbindgen:ignore
1023pub type ResolvedGeneralRenderPipelineDescriptor<'a> =
1024    GeneralRenderPipelineDescriptor<'a, Arc<PipelineLayout>, Arc<ShaderModule>, Arc<PipelineCache>>;
1025
1026#[derive(Clone, Debug)]
1027#[cfg_attr(feature = "serde", derive(serde::Serialize, serde::Deserialize))]
1028pub struct PipelineCacheDescriptor<'a> {
1029    pub label: Label<'a>,
1030    pub data: Option<Cow<'a, [u8]>>,
1031    pub fallback: bool,
1032}
1033
1034#[derive(Clone, Debug, Error)]
1035#[non_exhaustive]
1036pub enum ColorStateError {
1037    #[error("Format {0:?} is not renderable")]
1038    FormatNotRenderable(wgt::TextureFormat),
1039    #[error("Format {0:?} is not blendable")]
1040    FormatNotBlendable(wgt::TextureFormat),
1041    #[error("Format {0:?} does not have a color aspect")]
1042    FormatNotColor(wgt::TextureFormat),
1043    #[error("Sample count {0} is not supported by format {1:?} on this device. The WebGPU spec guarantees {2:?} samples are supported by this format. With the TEXTURE_ADAPTER_SPECIFIC_FORMAT_FEATURES feature your device supports {3:?}.")]
1044    InvalidSampleCount(u32, wgt::TextureFormat, Vec<u32>, Vec<u32>),
1045    #[error("Output format {pipeline} is incompatible with the shader {shader}")]
1046    IncompatibleFormat {
1047        pipeline: validation::NumericType,
1048        shader: validation::NumericType,
1049    },
1050    #[error("Invalid write mask {0:?}")]
1051    InvalidWriteMask(wgt::ColorWrites),
1052    #[error("Using the blend factor {factor:?} for render target {target} is not possible. Only the first render target may be used when dual-source blending.")]
1053    BlendFactorOnUnsupportedTarget {
1054        factor: wgt::BlendFactor,
1055        target: u32,
1056    },
1057    #[error("The {which} blend factor {factor:?} is not valid because the shader output does have an alpha channel.")]
1058    InvalidAlphaBlend {
1059        which: &'static str,
1060        factor: wgt::BlendFactor,
1061    },
1062    #[error(
1063        "Blend factor {factor:?} for render target {target} is not valid. Blend factor must be `one` when using min/max blend operations."
1064    )]
1065    InvalidMinMaxBlendFactor {
1066        factor: wgt::BlendFactor,
1067        target: u32,
1068    },
1069    #[error("Shader does not produce an output at this index")]
1070    OutputNotPresent,
1071}
1072
1073#[derive(Clone, Debug, Error)]
1074#[non_exhaustive]
1075pub enum DepthStencilStateError {
1076    #[error("Format {0:?} is not renderable")]
1077    FormatNotRenderable(wgt::TextureFormat),
1078    #[error("Format {0:?} is not a depth/stencil format")]
1079    FormatNotDepthOrStencil(wgt::TextureFormat),
1080    #[error("Format {0:?} does not have a depth aspect, but depth test/write is enabled")]
1081    FormatNotDepth(wgt::TextureFormat),
1082    #[error("Format {0:?} does not have a stencil aspect, but stencil test/write is enabled")]
1083    FormatNotStencil(wgt::TextureFormat),
1084    #[error("Sample count {0} is not supported by format {1:?} on this device. The WebGPU spec guarantees {2:?} samples are supported by this format. With the TEXTURE_ADAPTER_SPECIFIC_FORMAT_FEATURES feature your device supports {3:?}.")]
1085    InvalidSampleCount(u32, wgt::TextureFormat, Vec<u32>, Vec<u32>),
1086    #[error("Depth bias is not compatible with non-triangle topology {0:?}")]
1087    DepthBiasWithIncompatibleTopology(wgt::PrimitiveTopology),
1088    #[error("Depth compare function must be specified for depth format {0:?}")]
1089    MissingDepthCompare(wgt::TextureFormat),
1090    #[error("Depth write enabled must be specified for depth format {0:?}")]
1091    MissingDepthWriteEnabled(wgt::TextureFormat),
1092}
1093
1094/// Errors specific to render pipeline creation.
1095///
1096/// These are usually returned as [`CreatePipelineError::Render`].
1097#[derive(Clone, Debug, Error)]
1098#[non_exhaustive]
1099pub enum RenderError {
1100    #[error(transparent)]
1101    ColorAttachment(#[from] ColorAttachmentError),
1102    #[error("Color state [{0}] is invalid")]
1103    ColorState(u8, #[source] ColorStateError),
1104    #[error("Depth/stencil state is invalid")]
1105    DepthStencilState(#[from] DepthStencilStateError),
1106    #[error("Invalid sample count {0}")]
1107    InvalidSampleCount(u32),
1108    #[error("The number of vertex buffers {given} exceeds the limit {limit}")]
1109    TooManyVertexBuffers { given: u32, limit: u32 },
1110    #[error("The number of bind groups + vertex buffers {given} exceeds the limit {limit}")]
1111    TooManyBindGroupsPlusVertexBuffers { given: u32, limit: u32 },
1112    #[error("The number of vertex-stage buffers and acceleration structures {given} exceeds the limit {limit}")]
1113    TooManyBuffersAndAccelerationStructuresInVertexStage { given: u32, limit: u32 },
1114    #[error("The total number of vertex attributes {given} exceeds the limit {limit}")]
1115    TooManyVertexAttributes { given: u32, limit: u32 },
1116    #[error("Vertex attribute location {given} must be less than limit {limit}")]
1117    VertexAttributeLocationTooLarge { given: u32, limit: u32 },
1118    #[error("Vertex buffer {index} stride {given} exceeds the limit {limit}")]
1119    VertexStrideTooLarge { index: u32, given: u32, limit: u32 },
1120    #[error("Vertex attribute at location {location} stride {given} exceeds the limit {limit}")]
1121    VertexAttributeStrideTooLarge {
1122        location: wgt::ShaderLocation,
1123        given: u32,
1124        limit: u32,
1125    },
1126    #[error("Vertex buffer {index} stride {stride} does not respect `VERTEX_ALIGNMENT`")]
1127    UnalignedVertexStride {
1128        index: u32,
1129        stride: wgt::BufferAddress,
1130    },
1131    #[error("Vertex attribute at location {location} has invalid offset {offset}")]
1132    InvalidVertexAttributeOffset {
1133        location: wgt::ShaderLocation,
1134        offset: wgt::BufferAddress,
1135    },
1136    #[error("Two or more vertex attributes were assigned to the same location in the shader: {0}")]
1137    ShaderLocationClash(u32),
1138    #[error("Strip index format was not set to None but to {strip_index_format:?} while using the non-strip topology {topology:?}")]
1139    StripIndexFormatForNonStripTopology {
1140        strip_index_format: Option<wgt::IndexFormat>,
1141        topology: wgt::PrimitiveTopology,
1142    },
1143    #[error("Conservative Rasterization is only supported for wgt::PolygonMode::Fill")]
1144    ConservativeRasterizationNonFillPolygonMode,
1145    #[error("In the provided shader, the type given for group {group} binding {binding} has a size of {size}. As the device does not support `DownlevelFlags::BUFFER_BINDINGS_NOT_16_BYTE_ALIGNED`, the type must have a size that is a multiple of 16 bytes.")]
1146    UnalignedShader { group: u32, binding: u32, size: u64 },
1147    #[error("Dual-source blending requires exactly one color target, but {count} color targets are present")]
1148    DualSourceBlendingWithMultipleColorTargets { count: usize },
1149    #[error("{}", concat!(
1150        "At least one color attachment or depth-stencil attachment was expected, ",
1151        "but no render target for the pipeline was specified."
1152    ))]
1153    NoTargetSpecified,
1154}
1155
1156impl WebGpuError for RenderError {
1157    fn webgpu_error_type(&self) -> ErrorType {
1158        match self {
1159            Self::ColorAttachment(_)
1160            | Self::ColorState(_, _)
1161            | Self::DepthStencilState(_)
1162            | Self::InvalidSampleCount(_)
1163            | Self::TooManyVertexBuffers { .. }
1164            | Self::TooManyBindGroupsPlusVertexBuffers { .. }
1165            | Self::TooManyBuffersAndAccelerationStructuresInVertexStage { .. }
1166            | Self::TooManyVertexAttributes { .. }
1167            | Self::VertexAttributeLocationTooLarge { .. }
1168            | Self::VertexStrideTooLarge { .. }
1169            | Self::UnalignedVertexStride { .. }
1170            | Self::InvalidVertexAttributeOffset { .. }
1171            | Self::ShaderLocationClash(_)
1172            | Self::StripIndexFormatForNonStripTopology { .. }
1173            | Self::ConservativeRasterizationNonFillPolygonMode
1174            | Self::UnalignedShader { .. }
1175            | Self::DualSourceBlendingWithMultipleColorTargets { .. }
1176            | Self::NoTargetSpecified
1177            | Self::VertexAttributeStrideTooLarge { .. } => ErrorType::Validation,
1178        }
1179    }
1180}
1181
1182bitflags::bitflags! {
1183    #[repr(transparent)]
1184    #[derive(Debug, Copy, Clone, PartialEq, Eq, Hash)]
1185    pub struct PipelineFlags: u32 {
1186        const BLEND_CONSTANT = 1 << 0;
1187        const STENCIL_REFERENCE = 1 << 1;
1188        const WRITES_DEPTH = 1 << 2;
1189        const WRITES_STENCIL = 1 << 3;
1190    }
1191}
1192
1193/// How a render pipeline will retrieve attributes from a particular vertex buffer.
1194#[derive(Clone, Copy, Debug)]
1195pub struct VertexStep {
1196    /// The byte stride in the buffer between one attribute value and the next.
1197    pub stride: wgt::BufferAddress,
1198
1199    /// The byte size required to fit the last vertex in the stream.
1200    pub last_stride: wgt::BufferAddress,
1201
1202    /// Whether the buffer is indexed by vertex number or instance number.
1203    pub mode: wgt::VertexStepMode,
1204}
1205
1206impl Default for VertexStep {
1207    fn default() -> Self {
1208        Self {
1209            stride: 0,
1210            last_stride: 0,
1211            mode: wgt::VertexStepMode::Vertex,
1212        }
1213    }
1214}
1215
1216#[derive(Debug)]
1217pub(crate) struct RenderPipelineState {
1218    pub(crate) raw: ManuallyDrop<Box<dyn hal::DynRenderPipeline>>,
1219    pub(crate) layout: Arc<PipelineLayout>,
1220}
1221
1222#[derive(Debug)]
1223pub struct RenderPipeline {
1224    pub(crate) state: ResourceState<RenderPipelineState>,
1225    pub(crate) device: Arc<Device>,
1226    pub(crate) _shader_modules: ArrayVec<Arc<ShaderModule>, { hal::MAX_CONCURRENT_SHADER_STAGES }>,
1227    pub(crate) pass_context: RenderPassContext,
1228    pub(crate) flags: PipelineFlags,
1229    pub(crate) topology: wgt::PrimitiveTopology,
1230    pub(crate) strip_index_format: Option<wgt::IndexFormat>,
1231    pub(crate) vertex_steps: Vec<Option<VertexStep>>,
1232    pub(crate) late_sized_buffer_groups: ArrayVec<LateSizedBufferGroup, { hal::MAX_BIND_GROUPS }>,
1233    pub(crate) immediate_slots_required: naga::valid::ImmediateSlots,
1234    /// The `label` from the descriptor used to create the resource.
1235    pub(crate) label: String,
1236    pub(crate) tracking_data: TrackingData,
1237    /// Whether this is a mesh shader pipeline
1238    pub(crate) is_mesh: bool,
1239    pub(crate) has_task_shader: bool,
1240}
1241
1242impl Drop for RenderPipeline {
1243    #[allow(trivial_casts)]
1244    fn drop(&mut self) {
1245        profiling::scope!("RenderPipeline::drop");
1246        api_log!("RenderPipeline::drop {:?}", self as *const _);
1247        resource_log!("Destroy raw {}", self.error_ident());
1248        #[cfg(feature = "trace")]
1249        {
1250            use crate::device::trace;
1251            if let Some(t) = self.device.trace.lock().as_mut() {
1252                t.add(trace::Action::DropRenderPipeline(unsafe {
1253                    trace::to_trace(self)
1254                }));
1255            }
1256        }
1257        let ResourceState::Valid(state) = &mut self.state else {
1258            return;
1259        };
1260        // SAFETY: We are in the Drop impl and we don't use self.raw anymore after this point.
1261        let raw = unsafe { ManuallyDrop::take(&mut state.raw) };
1262        unsafe {
1263            self.device.raw().destroy_render_pipeline(raw);
1264        }
1265    }
1266}
1267
1268crate::impl_resource_type!(RenderPipeline);
1269crate::impl_labeled!(RenderPipeline);
1270crate::impl_parent_device!(RenderPipeline);
1271crate::impl_storage_item!(RenderPipeline);
1272crate::impl_trackable!(RenderPipeline);
1273
1274impl RenderPipeline {
1275    pub(crate) fn raw(&self) -> Result<&dyn hal::DynRenderPipeline, InvalidResourceError> {
1276        let ResourceState::Valid(state) = &self.state else {
1277            return Err(InvalidResourceError(self.error_ident()));
1278        };
1279        Ok(state.raw.as_ref())
1280    }
1281
1282    pub(crate) fn layout(&self) -> Result<&Arc<PipelineLayout>, InvalidResourceError> {
1283        let ResourceState::Valid(state) = &self.state else {
1284            return Err(InvalidResourceError(self.error_ident()));
1285        };
1286        Ok(&state.layout)
1287    }
1288
1289    pub(crate) fn check_valid(&self) -> Result<(), InvalidResourceError> {
1290        let ResourceState::Valid(_) = &self.state else {
1291            return Err(InvalidResourceError(self.error_ident()));
1292        };
1293        Ok(())
1294    }
1295
1296    pub(crate) fn invalid(device: Arc<Device>, label: String) -> Arc<Self> {
1297        Arc::new(Self {
1298            tracking_data: TrackingData::new(device.tracker_indices.render_pipelines.clone()),
1299            state: ResourceState::Invalid,
1300            device,
1301            _shader_modules: ArrayVec::new(),
1302            pass_context: RenderPassContext {
1303                attachments: AttachmentData {
1304                    colors: ArrayVec::new(),
1305                    resolves: ArrayVec::new(),
1306                    depth_stencil: None,
1307                },
1308                sample_count: 0,
1309                multiview_mask: None,
1310            },
1311            flags: PipelineFlags::empty(),
1312            topology: wgt::PrimitiveTopology::TriangleList,
1313            strip_index_format: None,
1314            vertex_steps: Vec::new(),
1315            late_sized_buffer_groups: ArrayVec::new(),
1316            immediate_slots_required: naga::valid::ImmediateSlots::default(),
1317            label,
1318            is_mesh: false,
1319            has_task_shader: false,
1320        })
1321    }
1322
1323    pub fn get_bind_group_layout_inner(
1324        self: &Arc<Self>,
1325        index: u32,
1326    ) -> Result<Arc<BindGroupLayout>, GetBindGroupLayoutError> {
1327        self.layout()?.get_bind_group_layout(index, self.into())
1328    }
1329
1330    pub fn get_bind_group_layout(self: &Arc<Self>, index: u32) -> Arc<BindGroupLayout> {
1331        let bgl = self
1332            .get_bind_group_layout_inner(index)
1333            .unwrap_or_else(|err| {
1334                self.device
1335                    .handle_error_nolabel(err, "RenderPipeline::get_bind_group_layout");
1336                BindGroupLayout::invalid(&self.device, String::new())
1337            });
1338        #[cfg(feature = "trace")]
1339        if let Some(ref mut trace) = *self.device.trace.lock() {
1340            use crate::device::trace;
1341            use trace::IntoTrace;
1342            trace.add(trace::Action::GetRenderPipelineBindGroupLayout {
1343                id: bgl.to_trace(),
1344                pipeline: self.to_trace(),
1345                index,
1346            });
1347        };
1348        bgl
1349    }
1350}
1351
1352#[cfg(test)]
1353mod tests {
1354    use super::*;
1355
1356    fn passthrough_interface(entry_point_names: &[&str]) -> PassthroughInterface {
1357        PassthroughInterface {
1358            entry_point_names: entry_point_names
1359                .iter()
1360                .map(|name| (*name).to_owned())
1361                .collect(),
1362        }
1363    }
1364
1365    #[test]
1366    fn select_implicit_passthrough_entry_point() {
1367        let empty = passthrough_interface(&[]);
1368        assert!(matches!(
1369            finalize_passthrough_entry_point_name(&empty, None),
1370            Err(validation::StageError::NoEntryPoints)
1371        ));
1372
1373        let single = passthrough_interface(&["main"]);
1374        assert_eq!(
1375            finalize_passthrough_entry_point_name(&single, None).unwrap(),
1376            "main"
1377        );
1378
1379        let multiple = passthrough_interface(&["vertex", "fragment"]);
1380        assert!(matches!(
1381            finalize_passthrough_entry_point_name(&multiple, None),
1382            Err(validation::StageError::AmbiguousEntryPoint)
1383        ));
1384    }
1385
1386    #[test]
1387    fn select_explicit_passthrough_entry_point() {
1388        let interface = passthrough_interface(&["main"]);
1389        assert_eq!(
1390            finalize_passthrough_entry_point_name(&interface, Some("main")).unwrap(),
1391            "main"
1392        );
1393        assert!(matches!(
1394            finalize_passthrough_entry_point_name(&interface, Some("missing")),
1395            Err(validation::StageError::NoEntryPointWithName(name)) if name == "missing"
1396        ));
1397    }
1398}