From 00b80537c8abb9fd290f676a1dfadee298a89bd4 Mon Sep 17 00:00:00 2001
From: Jim Blandy <jimb@red-bean.com>
Date: Sat, 21 May 2022 18:35:54 -0700
Subject: [PATCH] Document `VertexStepMode`.

---
 wgpu-types/src/lib.rs | 53 ++++++++++++++++++++++++++++++++++++++++++-
 1 file changed, 52 insertions(+), 1 deletion(-)

diff --git a/wgpu-types/src/lib.rs b/wgpu-types/src/lib.rs
index 986f8397bd1..bb2d5541863 100644
--- a/wgpu-types/src/lib.rs
+++ b/wgpu-types/src/lib.rs
@@ -2515,10 +2515,61 @@ impl CompareFunction {
     }
 }
 
-/// Rate that determines when vertex data is advanced.
+/// Whether a vertex buffer is indexed by vertex or by instance.
+///
+/// Consider a call to [`RenderPass::draw`] like this:
+///
+/// ```ignore
+/// render_pass.draw(vertices, instances)
+/// ```
+///
+/// where `vertices` is a `Range<u32>` of vertex indices, and
+/// `instances` is a `Range<u32>` of instance indices.
+///
+/// For this call, `wgpu` invokes the vertex shader entry point once
+/// for every possible `(v, i)` pair where `v` is drawn from
+/// `vertices`, and `i` is drawn from `instances`.
+///
+/// Each vertex buffer has a `VertexStepMode`, given by the
+/// [`step_mode`] field of its [`VertexBufferLayout`] provided when
+/// the pipeline was created.  Vertex buffers whose step mode is
+/// [`Vertex`] use `v` as the index into their contents, whereas
+/// buffers whose step mode is [`Instance`] use `i`. The indicated
+/// buffer element then contributes zero or more attribute values for
+/// the vertex shader to consume, based on the
+/// [`VertexBufferLayout`]'s [`attributes`] list.
+///
+/// You can visualize all the vertex shader results as a matrix with a
+/// row for each `i` from `instances`, and with a column for each `v`
+/// from `vertices`. In one sense, `v` and `i` are symmetrical: both
+/// are used to index vertex buffers and provide attribute values.
+/// But the key difference between `v` and `i` is that line and
+/// triangle primitives are built from the values of each row, along
+/// which `i` is constant and `v` varies, not the columns.
+///
+/// An indexed draw call works similarly:
+///
+/// ```ignore
+/// render_pass.draw_indexed(indices, base_vertex, instances)
+/// ```
+///
+/// The only difference is that `v` values are drawn from the contents
+/// of the index buffer&mdash;specifically, the subrange of the index
+/// buffer given by `indices`&mdash;instead of simply being sequential
+/// integers, as they are in a `draw` call.
+///
+/// A non-instanced call, where `instances` is `0..1`, is simply a
+/// matrix with only one row.
 ///
 /// Corresponds to [WebGPU `GPUVertexStepMode`](
 /// https://gpuweb.github.io/gpuweb/#enumdef-gpuvertexstepmode).
+///
+/// [`RenderPass::draw`]: ../wgpu/struct.RenderPass.html#method.draw
+/// [`VertexBufferLayout`]: ../wgpu/struct.VertexBufferLayout.html
+/// [`step_mode`]: ../wgpu/struct.VertexBufferLayout.html#structfield.step_mode
+/// [`attributes`]: ../wgpu/struct.VertexBufferLayout.html#structfield.attributes
+/// [`Vertex`]: VertexStepMode::Vertex
+/// [`Instance`]: VertexStepMode::Instance
 #[repr(C)]
 #[derive(Copy, Clone, Debug, Hash, Eq, PartialEq)]
 #[cfg_attr(feature = "trace", derive(Serialize))]