wgpu_types/
vertex.rs

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

wgpu_types/
vertex.rs
