wgpu_types/
vertex.rs

1//! Types for defining vertex attributes and their buffers.
2
3use nt::VertexFormat;
4#[cfg(any(feature = "serde", test))]
5use serde::{Deserialize, Serialize};
6
7use crate::{link_to_wgpu_docs, link_to_wgpu_item};
8
9#[cfg(doc)]
10use crate::Features;
11
12/// Whether a vertex buffer is indexed by vertex or by instance.
13///
14/// Consider a call to [`RenderPass::draw`] like this:
15///
16/// ```ignore
17/// render_pass.draw(vertices, instances)
18/// ```
19///
20/// where `vertices` is a `Range<u32>` of vertex indices, and
21/// `instances` is a `Range<u32>` of instance indices.
22///
23/// For this call, `wgpu` invokes the vertex shader entry point once
24/// for every possible `(v, i)` pair, where `v` is drawn from
25/// `vertices` and `i` is drawn from `instances`. These invocations
26/// may happen in any order, and will usually run in parallel.
27///
28/// Each vertex buffer has a step mode, established by the
29/// [`step_mode`] field of its [`VertexBufferLayout`], given when the
30/// pipeline was created. Buffers whose step mode is [`Vertex`] use
31/// `v` as the index into their contents, whereas buffers whose step
32/// mode is [`Instance`] use `i`. The indicated buffer element then
33/// contributes zero or more attribute values for the `(v, i)` vertex
34/// shader invocation to use, based on the [`VertexBufferLayout`]'s
35/// [`attributes`] list.
36///
37/// You can visualize the results from all these vertex shader
38/// invocations as a matrix with a row for each `i` from `instances`,
39/// and with a column for each `v` from `vertices`. In one sense, `v`
40/// and `i` are symmetrical: both are used to index vertex buffers and
41/// provide attribute values.  But the key difference between `v` and
42/// `i` is that line and triangle primitives are built from the values
43/// of each row, along which `i` is constant and `v` varies, not the
44/// columns.
45///
46/// An indexed draw call works similarly:
47///
48/// ```ignore
49/// render_pass.draw_indexed(indices, base_vertex, instances)
50/// ```
51///
52/// The only difference is that `v` values are drawn from the contents
53/// of the index buffer&mdash;specifically, the subrange of the index
54/// buffer given by `indices`&mdash;instead of simply being sequential
55/// integers, as they are in a `draw` call.
56///
57/// A non-instanced call, where `instances` is `0..1`, is simply a
58/// matrix with only one row.
59///
60/// Corresponds to [WebGPU `GPUVertexStepMode`](
61/// https://gpuweb.github.io/gpuweb/#enumdef-gpuvertexstepmode).
62///
63#[doc = link_to_wgpu_docs!(["`RenderPass::draw`"]: "struct.RenderPass.html#method.draw")]
64#[doc = link_to_wgpu_item!(struct VertexBufferLayout)]
65#[doc = link_to_wgpu_docs!(["`step_mode`"]: "struct.VertexBufferLayout.html#structfield.step_mode")]
66#[doc = link_to_wgpu_docs!(["`attributes`"]: "struct.VertexBufferLayout.html#structfield.attributes")]
67/// [`Vertex`]: VertexStepMode::Vertex
68/// [`Instance`]: VertexStepMode::Instance
69#[repr(C)]
70#[derive(Copy, Clone, Debug, Default, Hash, Eq, PartialEq)]
71#[cfg_attr(feature = "serde", derive(Serialize, Deserialize))]
72#[cfg_attr(feature = "serde", serde(rename_all = "kebab-case"))]
73pub enum VertexStepMode {
74    /// Vertex data is advanced every vertex.
75    #[default]
76    Vertex = 0,
77    /// Vertex data is advanced every instance.
78    Instance = 1,
79}
80
81/// Vertex inputs (attributes) to shaders.
82///
83/// These are used to specify the individual attributes within a [`VertexBufferLayout`].
84/// See its documentation for an example.
85///
86/// The [`vertex_attr_array!`] macro can help create these with appropriate offsets.
87///
88/// Corresponds to [WebGPU `GPUVertexAttribute`](
89/// https://gpuweb.github.io/gpuweb/#dictdef-gpuvertexattribute).
90///
91#[doc = link_to_wgpu_docs!(["`vertex_attr_array!`"]: "macro.vertex_attr_array.html")]
92#[doc = link_to_wgpu_item!(struct VertexBufferLayout)]
93#[repr(C)]
94#[derive(Clone, Copy, Debug, PartialEq, Eq, Hash)]
95#[cfg_attr(feature = "serde", derive(Serialize, Deserialize))]
96#[cfg_attr(feature = "serde", serde(rename_all = "camelCase"))]
97pub struct VertexAttribute {
98    /// Format of the input
99    pub format: VertexFormat,
100    /// Byte offset of the start of the input
101    pub offset: crate::BufferAddress,
102    /// Location for this input. Must match the location in the shader.
103    pub shader_location: crate::ShaderLocation,
104}
wgpu_types/vertex.rs

wgpu_types/
vertex.rs
