v2: - Fix a channel name thinko (Michel Dänzer) - Elaborate on SCALED versus INT - Add links to DirectX and FOURCC docs
Signed-off-by: Adam Jackson <a...@redhat.com> --- src/gallium/docs/format.rst | 54 +++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 54 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..2514656 --- /dev/null +++ b/src/gallium/docs/format.rst @@ -0,0 +1,54 @@ +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 alpha. 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] +- ``SSCALED``: N bit signed integer [-2^(N-1) ... 2^(N-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] +- ``USCALED``: N bit unsigned integer [0 ... 2^N - 1] + +The difference between ``SINT`` and ``SSCALED`` is that the former are pure +integers in shaders, while the latter are floats; likewise for ``UINT`` versus +``USCALED``. + +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. + +References +---------- + +DirectX Graphics Infrastructure documentation on DXGI_FORMAT enum: +http://msdn.microsoft.com/en-us/library/windows/desktop/bb173059%28v=vs.85%29.aspx + +FOURCC codes for YUV formats: +http://www.fourcc.org/yuv.php -- 1.8.2.1 _______________________________________________ mesa-dev mailing list mesa-dev@lists.freedesktop.org http://lists.freedesktop.org/mailman/listinfo/mesa-dev
