wgpu/api/
render_pipeline.rs

Help
1use core::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    #[cfg(custom)]
33    /// Returns custom implementation of RenderPipeline (if custom backend and is internally T)
34    pub fn as_custom<T: custom::RenderPipelineInterface>(&self) -> Option<&T> {
35        self.inner.as_custom()
36    }
37}
38
39/// Specifies an interpretation of the bytes of a vertex buffer as vertex attributes.
40///
41/// Use this in a [`RenderPipelineDescriptor`] to describe the format of the vertex buffers that
42/// are passed to [`RenderPass::set_vertex_buffer()`].
43///
44/// Corresponds to [WebGPU `GPUVertexBufferLayout`](
45/// https://gpuweb.github.io/gpuweb/#dictdef-gpuvertexbufferlayout).
46///
47/// # Example
48///
49/// The following example defines a `struct` with three fields,
50/// and a [`VertexBufferLayout`] that contains [`VertexAttribute`]s for each field,
51/// using the [`vertex_attr_array!`] macro to compute attribute offsets:
52///
53/// ```
54/// #[repr(C, packed)]
55/// struct Vertex {
56///     foo: [f32; 2],
57///     bar: f32,
58///     baz: [u16; 4],
59/// }
60///
61/// impl Vertex {
62///     /// Layout to use with a buffer whose contents are a `[Vertex]`.
63///     pub const LAYOUT: wgpu::VertexBufferLayout<'static> = wgpu::VertexBufferLayout {
64///         array_stride: size_of::<Self>() as wgpu::BufferAddress,
65///         step_mode: wgpu::VertexStepMode::Vertex,
66///         attributes: &wgpu::vertex_attr_array![
67///             0 => Float32x2,
68///             1 => Float32,
69///             2 => Uint16x4,
70///         ],
71///     };
72/// }
73///
74/// # assert_eq!(Vertex::LAYOUT.attributes[2].offset, Vertex::LAYOUT.array_stride - 2 * 4);
75#[derive(Clone, Debug, Hash, Eq, PartialEq)]
76pub struct VertexBufferLayout<'a> {
77    /// The stride, in bytes, between elements of this buffer (between vertices).
78    ///
79    /// This must be a multiple of [`VERTEX_ALIGNMENT`].
80    pub array_stride: BufferAddress,
81    /// How often this vertex buffer is "stepped" forward.
82    pub step_mode: VertexStepMode,
83    /// The list of attributes which comprise a single vertex.
84    pub attributes: &'a [VertexAttribute],
85}
86static_assertions::assert_impl_all!(VertexBufferLayout<'_>: Send, Sync);
87
88/// Describes the vertex processing in a render pipeline.
89///
90/// For use in [`RenderPipelineDescriptor`].
91///
92/// Corresponds to [WebGPU `GPUVertexState`](
93/// https://gpuweb.github.io/gpuweb/#dictdef-gpuvertexstate).
94#[derive(Clone, Debug)]
95pub struct VertexState<'a> {
96    /// The compiled shader module for this stage.
97    pub module: &'a ShaderModule,
98    /// The name of the entry point in the compiled shader to use.
99    ///
100    /// If [`Some`], there must be a vertex-stage shader entry point with this name in `module`.
101    /// Otherwise, expect exactly one vertex-stage entry point in `module`, which will be
102    /// selected.
103    // NOTE: keep phrasing in sync. with `ComputePipelineDescriptor::entry_point`
104    // NOTE: keep phrasing in sync. with `FragmentState::entry_point`
105    pub entry_point: Option<&'a str>,
106    /// Advanced options for when this pipeline is compiled
107    ///
108    /// This implements `Default`, and for most users can be set to `Default::default()`
109    pub compilation_options: PipelineCompilationOptions<'a>,
110    /// The format of any vertex buffers used with this pipeline via
111    /// [`RenderPass::set_vertex_buffer()`].
112    ///
113    /// The attribute locations and types specified in this layout must match the
114    /// locations and types of the inputs to the `entry_point` function.
115    pub buffers: &'a [VertexBufferLayout<'a>],
116}
117#[cfg(send_sync)]
118static_assertions::assert_impl_all!(VertexState<'_>: Send, Sync);
119
120/// Describes the fragment processing in a render pipeline.
121///
122/// For use in [`RenderPipelineDescriptor`].
123///
124/// Corresponds to [WebGPU `GPUFragmentState`](
125/// https://gpuweb.github.io/gpuweb/#dictdef-gpufragmentstate).
126#[derive(Clone, Debug)]
127pub struct FragmentState<'a> {
128    /// The compiled shader module for this stage.
129    pub module: &'a ShaderModule,
130    /// The name of the entry point in the compiled shader to use.
131    ///
132    /// If [`Some`], there must be a `@fragment` shader entry point with this name in `module`.
133    /// Otherwise, expect exactly one fragment-stage entry point in `module`, which will be
134    /// selected.
135    // NOTE: keep phrasing in sync. with `ComputePipelineDescriptor::entry_point`
136    // NOTE: keep phrasing in sync. with `VertexState::entry_point`
137    pub entry_point: Option<&'a str>,
138    /// Advanced options for when this pipeline is compiled
139    ///
140    /// This implements `Default`, and for most users can be set to `Default::default()`
141    pub compilation_options: PipelineCompilationOptions<'a>,
142    /// The color state of the render targets.
143    pub targets: &'a [Option<ColorTargetState>],
144}
145#[cfg(send_sync)]
146static_assertions::assert_impl_all!(FragmentState<'_>: Send, Sync);
147
148/// Describes the task shader stage in a mesh shader pipeline.
149///
150/// For use in [`MeshPipelineDescriptor`]
151#[derive(Clone, Debug)]
152pub struct TaskState<'a> {
153    /// The compiled shader module for this stage.
154    pub module: &'a ShaderModule,
155    /// The name of the entry point in the compiled shader to use.
156    ///
157    /// If [`Some`], there must be a vertex-stage shader entry point with this name in `module`.
158    /// Otherwise, expect exactly one vertex-stage entry point in `module`, which will be
159    /// selected.
160    pub entry_point: Option<&'a str>,
161    /// Advanced options for when this pipeline is compiled
162    ///
163    /// This implements `Default`, and for most users can be set to `Default::default()`
164    pub compilation_options: PipelineCompilationOptions<'a>,
165}
166#[cfg(send_sync)]
167static_assertions::assert_impl_all!(TaskState<'_>: Send, Sync);
168
169/// Describes the mesh shader stage in a mesh shader pipeline.
170///
171/// For use in [`MeshPipelineDescriptor`]
172#[derive(Clone, Debug)]
173pub struct MeshState<'a> {
174    /// The compiled shader module for this stage.
175    pub module: &'a ShaderModule,
176    /// The name of the entry point in the compiled shader to use.
177    ///
178    /// If [`Some`], there must be a vertex-stage shader entry point with this name in `module`.
179    /// Otherwise, expect exactly one vertex-stage entry point in `module`, which will be
180    /// selected.
181    pub entry_point: Option<&'a str>,
182    /// Advanced options for when this pipeline is compiled
183    ///
184    /// This implements `Default`, and for most users can be set to `Default::default()`
185    pub compilation_options: PipelineCompilationOptions<'a>,
186}
187#[cfg(send_sync)]
188static_assertions::assert_impl_all!(MeshState<'_>: Send, Sync);
189
190/// Describes a render (graphics) pipeline.
191///
192/// For use with [`Device::create_render_pipeline`].
193///
194/// Corresponds to [WebGPU `GPURenderPipelineDescriptor`](
195/// https://gpuweb.github.io/gpuweb/#dictdef-gpurenderpipelinedescriptor).
196#[derive(Clone, Debug)]
197pub struct RenderPipelineDescriptor<'a> {
198    /// Debug label of the pipeline. This will show up in graphics debuggers for easy identification.
199    pub label: Label<'a>,
200    /// The layout of bind groups for this pipeline.
201    ///
202    /// If this is set, then [`Device::create_render_pipeline`] will raise a validation error if
203    /// the layout doesn't match what the shader module(s) expect.
204    ///
205    /// Using the same [`PipelineLayout`] for many [`RenderPipeline`] or [`ComputePipeline`]
206    /// pipelines guarantees that you don't have to rebind any resources when switching between
207    /// those pipelines.
208    ///
209    /// ## Default pipeline layout
210    ///
211    /// If `layout` is `None`, then the pipeline has a [default layout] created and used instead.
212    /// The default layout is deduced from the shader modules.
213    ///
214    /// You can use [`RenderPipeline::get_bind_group_layout`] to create bind groups for use with the
215    /// default layout. However, these bind groups cannot be used with any other pipelines. This is
216    /// convenient for simple pipelines, but using an explicit layout is recommended in most cases.
217    ///
218    /// [default layout]: https://www.w3.org/TR/webgpu/#default-pipeline-layout
219    pub layout: Option<&'a PipelineLayout>,
220    /// The compiled vertex stage, its entry point, and the input buffers layout.
221    pub vertex: VertexState<'a>,
222    /// The properties of the pipeline at the primitive assembly and rasterization level.
223    pub primitive: PrimitiveState,
224    /// The effect of draw calls on the depth and stencil aspects of the output target, if any.
225    pub depth_stencil: Option<DepthStencilState>,
226    /// The multi-sampling properties of the pipeline.
227    pub multisample: MultisampleState,
228    /// The compiled fragment stage, its entry point, and the color targets.
229    pub fragment: Option<FragmentState<'a>>,
230    /// If the pipeline will be used with a multiview render pass, this indicates how many array
231    /// layers the attachments will have.
232    pub multiview: Option<NonZeroU32>,
233    /// The pipeline cache to use when creating this pipeline.
234    pub cache: Option<&'a PipelineCache>,
235}
236#[cfg(send_sync)]
237static_assertions::assert_impl_all!(RenderPipelineDescriptor<'_>: Send, Sync);
238
239/// Describes a mesh shader (graphics) pipeline.
240///
241/// For use with [`Device::create_mesh_pipeline`].
242#[derive(Clone, Debug)]
243pub struct MeshPipelineDescriptor<'a> {
244    /// Debug label of the pipeline. This will show up in graphics debuggers for easy identification.
245    pub label: Label<'a>,
246    /// The layout of bind groups for this pipeline.
247    ///
248    /// If this is set, then [`Device::create_render_pipeline`] will raise a validation error if
249    /// the layout doesn't match what the shader module(s) expect.
250    ///
251    /// Using the same [`PipelineLayout`] for many [`RenderPipeline`] or [`ComputePipeline`]
252    /// pipelines guarantees that you don't have to rebind any resources when switching between
253    /// those pipelines.
254    ///
255    /// ## Default pipeline layout
256    ///
257    /// If `layout` is `None`, then the pipeline has a [default layout] created and used instead.
258    /// The default layout is deduced from the shader modules.
259    ///
260    /// You can use [`RenderPipeline::get_bind_group_layout`] to create bind groups for use with the
261    /// default layout. However, these bind groups cannot be used with any other pipelines. This is
262    /// convenient for simple pipelines, but using an explicit layout is recommended in most cases.
263    ///
264    /// [default layout]: https://www.w3.org/TR/webgpu/#default-pipeline-layout
265    pub layout: Option<&'a PipelineLayout>,
266    /// The compiled task stage, its entry point, and the color targets.
267    pub task: Option<TaskState<'a>>,
268    /// The compiled mesh stage and its entry point
269    pub mesh: MeshState<'a>,
270    /// The properties of the pipeline at the primitive assembly and rasterization level.
271    pub primitive: PrimitiveState,
272    /// The effect of draw calls on the depth and stencil aspects of the output target, if any.
273    pub depth_stencil: Option<DepthStencilState>,
274    /// The multi-sampling properties of the pipeline.
275    pub multisample: MultisampleState,
276    /// The compiled fragment stage, its entry point, and the color targets.
277    pub fragment: Option<FragmentState<'a>>,
278    /// If the pipeline will be used with a multiview render pass, this indicates how many array
279    /// layers the attachments will have.
280    pub multiview: Option<NonZeroU32>,
281    /// The pipeline cache to use when creating this pipeline.
282    pub cache: Option<&'a PipelineCache>,
283}
284#[cfg(send_sync)]
285static_assertions::assert_impl_all!(MeshPipelineDescriptor<'_>: Send, Sync);
wgpu/api/render_pipeline.rs

wgpu/api/
render_pipeline.rs
