gallium/docs: Vertex data formats.

I'm not sure if I really got it right. This seems like one of those
"Duh, of course it works that way" things, but I'd like the
documentation to be readable by people not acquainted with OGL/D3D.

1 files changed, 38 insertions, 3 deletions

diff --git a/src/gallium/docs/source/cso/velems.rst b/src/gallium/docs/source/cso/velems.rst
index 92cde014fb..978ad4a243 100644
--- a/src/gallium/docs/source/cso/velems.rst
+++ b/src/gallium/docs/source/cso/velems.rst
@@ -3,9 +3,44 @@
 Vertex Elements
 ===============
 
-This state controls format etc. of the input attributes contained
-in the pipe_vertex_buffer(s). There's one pipe_vertex_element array member
-for each input attribute.
+This state controls the format of the input attributes contained in
+pipe_vertex_buffers. There is one pipe_vertex_element array member for each
+input attribute.
+
+Input Formats
+-------------
+
+Gallium supports a diverse range of formats for vertex data. Drivers are
+guaranteed to support 32-bit floating-point vectors of one to four components.
+Additionally, they may support the following formats:
+
+* Integers, signed or unsigned, normalized or non-normalized, 8, 16, or 32
+  bits wide
+* Floating-point, 16, 32, or 64 bits wide
+
+At this time, support for varied vertex data formats is limited by driver
+deficiencies. It is planned to support a single uniform set of formats for all
+Gallium drivers at some point.
+
+Rather than attempt to specify every small nuance of behavior, Gallium uses a
+very simple set of rules for padding out unspecified components. If an input
+uses less than four components, it will be padded out with the constant vector
+``(0, 0, 0, 1)``.
+
+Fog, point size, the facing bit, and edgeflags, all are in the standard format
+of ``(x, 0, 0, 1)``, and so only the first component of those inputs is used.
+
+Position
+%%%%%%%%
+
+Vertex position may be specified with two to four components. Using less than
+two components is not allowed.
+
+Colors
+%%%%%%
+
+Colors, both front- and back-facing, may omit the alpha component, only using
+three components. Using less than three components is not allowed.
 
 Members
 -------