[Mesa-dev] [PATCH] gallium: Document format name conventions

[Adam Jackson]

Other things to maybe add:

- More detail on FOURCC formats, or at least a link
- SSCALED/USCALED?  Not sure what they're meant to be really

Signed-off-by: Adam Jackson <ajax at redhat.com>
---
 src/gallium/docs/format.rst | 39 +++++++++++++++++++++++++++++++++++++++
 1 file changed, 39 insertions(+)
 create mode 100644 src/gallium/docs/format.rst

diff --git a/src/gallium/docs/format.rst b/src/gallium/docs/format.rst
new file mode 100644
index 0000000..e6de569
--- /dev/null
+++ b/src/gallium/docs/format.rst
@@ -0,0 +1,39 @@
+Formats in gallium
+==================
+
+Gallium format names mostly follow D3D10 conventions, with some extensions.
+
+Format names like XnYnZnWn have the X component in the lowest-address n bits
+and the W component in the highest-address n bits; for B8G8R8A8, byte 0 is
+blue and byte 3 is red.  Note that platform endianness is not considered
+in this definition.
+
+Format suffixes affect the interpretation of the channel:
+
+- ``SINT``:     N bit signed integer [-2^(N-1) ... 2^(N-1) - 1]
+- ``SNORM``:    N bit signed integer normalized to [-1 ... 1]
+- ``FIXED``:    Signed fixed point integer, (N/2 - 1) bits of mantissa
+- ``FLOAT``:    N bit IEEE754 float
+- ``NORM``:     Normalized integers, signed or unsigned per channel
+- ``UINT``:     N bit unsigned integer [0 ... 2^N - 1]
+- ``UNORM``:    N bit unsigned integer normalized to [0 ... 1]
+
+There are two exceptions for ``FLOAT``.  ``R9G9B9E5_FLOAT`` is nine bits
+each of red green and blue mantissa, with a shared five bit exponent.
+``R11G11B10_FLOAT`` is five bits of exponent and five or six bits of mantissa
+for each color channel.
+
+For the ``NORM`` suffix, the signedness of each channel is indicated with an
+S or U after the number of channel bits, as in ``R5SG5SB6U_NORM``.
+
+The ``SRGB`` suffix is like ``UNORM`` in range, but in the sRGB colorspace.
+
+Compressed formats are named first by the compression format string (``DXT1``,
+``ETC1``, etc), followed by a format-specific subtype.  Refer to the
+appropriate compression spec for details.
+
+Formats used in video playback are named by their FOURCC code.
+
+Format names with an embedded underscore are subsampled.  ``R8G8_B8G8`` is a
+single 32-bit block of two pixels, where the R and B values are repeated in
+both pixels.
-- 
1.8.2.1