wgpu/api/
render_pipeline.rs

1use std::num::NonZeroU32;
2
3use crate::*;
4
5/// Handle to a rendering (graphics) pipeline.
6///
7/// A `RenderPipeline` object represents a graphics pipeline and its stages, bindings, vertex
8/// buffers and targets. It can be created with [`Device::create_render_pipeline`].
9///
10/// Corresponds to [WebGPU `GPURenderPipeline`](https://gpuweb.github.io/gpuweb/#render-pipeline).
11#[derive(Debug, Clone)]
12pub struct RenderPipeline {
13    pub(crate) inner: dispatch::DispatchRenderPipeline,
14}
15#[cfg(send_sync)]
16static_assertions::assert_impl_all!(RenderPipeline: Send, Sync);
17
18crate::cmp::impl_eq_ord_hash_proxy!(RenderPipeline => .inner);
19
20impl RenderPipeline {
21    /// Get an object representing the bind group layout at a given index.
22    ///
23    /// If this pipeline was created with a [default layout][RenderPipelineDescriptor::layout], then
24    /// bind groups created with the returned `BindGroupLayout` can only be used with this pipeline.
25    ///
26    /// This method will raise a validation error if there is no bind group layout at `index`.
27    pub fn get_bind_group_layout(&self, index: u32) -> BindGroupLayout {
28        let layout = self.inner.get_bind_group_layout(index);
29        BindGroupLayout { inner: layout }
30    }
31}
32
33/// Describes how the vertex buffer is interpreted.
34///
35/// For use in [`VertexState`].
36///
37/// Corresponds to [WebGPU `GPUVertexBufferLayout`](
38/// https://gpuweb.github.io/gpuweb/#dictdef-gpuvertexbufferlayout).
39#[derive(Clone, Debug, Hash, Eq, PartialEq)]
40pub struct VertexBufferLayout<'a> {
41    /// The stride, in bytes, between elements of this buffer.
42    pub array_stride: BufferAddress,
43    /// How often this vertex buffer is "stepped" forward.
44    pub step_mode: VertexStepMode,
45    /// The list of attributes which comprise a single vertex.
46    pub attributes: &'a [VertexAttribute],
47}
48static_assertions::assert_impl_all!(VertexBufferLayout<'_>: Send, Sync);
49
50/// Describes the vertex processing in a render pipeline.
51///
52/// For use in [`RenderPipelineDescriptor`].
53///
54/// Corresponds to [WebGPU `GPUVertexState`](
55/// https://gpuweb.github.io/gpuweb/#dictdef-gpuvertexstate).
56#[derive(Clone, Debug)]
57pub struct VertexState<'a> {
58    /// The compiled shader module for this stage.
59    pub module: &'a ShaderModule,
60    /// The name of the entry point in the compiled shader to use.
61    ///
62    /// If [`Some`], there must be a vertex-stage shader entry point with this name in `module`.
63    /// Otherwise, expect exactly one vertex-stage entry point in `module`, which will be
64    /// selected.
65    // NOTE: keep phrasing in sync. with `ComputePipelineDescriptor::entry_point`
66    // NOTE: keep phrasing in sync. with `FragmentState::entry_point`
67    pub entry_point: Option<&'a str>,
68    /// Advanced options for when this pipeline is compiled
69    ///
70    /// This implements `Default`, and for most users can be set to `Default::default()`
71    pub compilation_options: PipelineCompilationOptions<'a>,
72    /// The format of any vertex buffers used with this pipeline.
73    pub buffers: &'a [VertexBufferLayout<'a>],
74}
75#[cfg(send_sync)]
76static_assertions::assert_impl_all!(VertexState<'_>: Send, Sync);
77
78/// Describes the fragment processing in a render pipeline.
79///
80/// For use in [`RenderPipelineDescriptor`].
81///
82/// Corresponds to [WebGPU `GPUFragmentState`](
83/// https://gpuweb.github.io/gpuweb/#dictdef-gpufragmentstate).
84#[derive(Clone, Debug)]
85pub struct FragmentState<'a> {
86    /// The compiled shader module for this stage.
87    pub module: &'a ShaderModule,
88    /// The name of the entry point in the compiled shader to use.
89    ///
90    /// If [`Some`], there must be a `@fragment` shader entry point with this name in `module`.
91    /// Otherwise, expect exactly one fragment-stage entry point in `module`, which will be
92    /// selected.
93    // NOTE: keep phrasing in sync. with `ComputePipelineDescriptor::entry_point`
94    // NOTE: keep phrasing in sync. with `VertexState::entry_point`
95    pub entry_point: Option<&'a str>,
96    /// Advanced options for when this pipeline is compiled
97    ///
98    /// This implements `Default`, and for most users can be set to `Default::default()`
99    pub compilation_options: PipelineCompilationOptions<'a>,
100    /// The color state of the render targets.
101    pub targets: &'a [Option<ColorTargetState>],
102}
103#[cfg(send_sync)]
104static_assertions::assert_impl_all!(FragmentState<'_>: Send, Sync);
105
106/// Describes a render (graphics) pipeline.
107///
108/// For use with [`Device::create_render_pipeline`].
109///
110/// Corresponds to [WebGPU `GPURenderPipelineDescriptor`](
111/// https://gpuweb.github.io/gpuweb/#dictdef-gpurenderpipelinedescriptor).
112#[derive(Clone, Debug)]
113pub struct RenderPipelineDescriptor<'a> {
114    /// Debug label of the pipeline. This will show up in graphics debuggers for easy identification.
115    pub label: Label<'a>,
116    /// The layout of bind groups for this pipeline.
117    ///
118    /// If this is set, then [`Device::create_render_pipeline`] will raise a validation error if
119    /// the layout doesn't match what the shader module(s) expect.
120    ///
121    /// Using the same [`PipelineLayout`] for many [`RenderPipeline`] or [`ComputePipeline`]
122    /// pipelines guarantees that you don't have to rebind any resources when switching between
123    /// those pipelines.
124    ///
125    /// ## Default pipeline layout
126    ///
127    /// If `layout` is `None`, then the pipeline has a [default layout] created and used instead.
128    /// The default layout is deduced from the shader modules.
129    ///
130    /// You can use [`RenderPipeline::get_bind_group_layout`] to create bind groups for use with the
131    /// default layout. However, these bind groups cannot be used with any other pipelines. This is
132    /// convenient for simple pipelines, but using an explicit layout is recommended in most cases.
133    ///
134    /// [default layout]: https://www.w3.org/TR/webgpu/#default-pipeline-layout
135    pub layout: Option<&'a PipelineLayout>,
136    /// The compiled vertex stage, its entry point, and the input buffers layout.
137    pub vertex: VertexState<'a>,
138    /// The properties of the pipeline at the primitive assembly and rasterization level.
139    pub primitive: PrimitiveState,
140    /// The effect of draw calls on the depth and stencil aspects of the output target, if any.
141    pub depth_stencil: Option<DepthStencilState>,
142    /// The multi-sampling properties of the pipeline.
143    pub multisample: MultisampleState,
144    /// The compiled fragment stage, its entry point, and the color targets.
145    pub fragment: Option<FragmentState<'a>>,
146    /// If the pipeline will be used with a multiview render pass, this indicates how many array
147    /// layers the attachments will have.
148    pub multiview: Option<NonZeroU32>,
149    /// The pipeline cache to use when creating this pipeline.
150    pub cache: Option<&'a PipelineCache>,
151}
152#[cfg(send_sync)]
153static_assertions::assert_impl_all!(RenderPipelineDescriptor<'_>: Send, Sync);
wgpu/api/render_pipeline.rs

wgpu/api/
render_pipeline.rs
