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

[Marek Olšák]

SSCALED/USCALED are integer which appear as float in shaders (e.g. as
a floating-point vertex shader input). Every type except UINT/SINT
appears as float in shaders and therefore can be used as a type of a
non-integer (=floating-point) vertex shader input, non-integer
sampler, and non-integer render target.

Examples:

glColorPointer(GL_INT) is SNORM.
glVertexPointer(GL_INT) is SSCALED.
glVertexAttribPointer(GL_INT, normalized) is SSCALED or SNORM
depending on the normalized flag.
glVertexAttribIPointer(GL_INT) is SINT.

Marek

On Mon, Jun 3, 2013 at 6:14 PM, Adam Jackson <ajax at redhat.com> wrote:
> 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
>
> _______________________________________________
> mesa-dev mailing list
> mesa-dev at lists.freedesktop.org
> http://lists.freedesktop.org/mailman/listinfo/mesa-dev