| 1 |
Formats in gallium |
| 2 |
================== |
| 3 |
|
| 4 |
Gallium format names mostly follow D3D10 conventions, with some extensions. |
| 5 |
|
| 6 |
Format names like XnYnZnWn have the X component in the lowest-address n bits |
| 7 |
and the W component in the highest-address n bits; for B8G8R8A8, byte 0 is |
| 8 |
blue and byte 3 is alpha. Note that platform endianness is not considered |
| 9 |
in this definition. In C:: |
| 10 |
|
| 11 |
struct x8y8z8w8 { uint8_t x, y, z, w; }; |
| 12 |
|
| 13 |
Format aliases like XYZWstrq are (s+t+r+q)-bit integers in host endianness, |
| 14 |
with the X component in the s least-significant bits of the integer. In C:: |
| 15 |
|
| 16 |
uint32_t xyzw8888 = (x << 0) | (y << 8) | (z << 16) | (w << 24); |
| 17 |
|
| 18 |
Format suffixes affect the interpretation of the channel: |
| 19 |
|
| 20 |
- ``SINT``: N bit signed integer [-2^(N-1) ... 2^(N-1) - 1] |
| 21 |
- ``SNORM``: N bit signed integer normalized to [-1 ... 1] |
| 22 |
- ``SSCALED``: N bit signed integer [-2^(N-1) ... 2^(N-1) - 1] |
| 23 |
- ``FIXED``: Signed fixed point integer, (N/2 - 1) bits of mantissa |
| 24 |
- ``FLOAT``: N bit IEEE754 float |
| 25 |
- ``NORM``: Normalized integers, signed or unsigned per channel |
| 26 |
- ``UINT``: N bit unsigned integer [0 ... 2^N - 1] |
| 27 |
- ``UNORM``: N bit unsigned integer normalized to [0 ... 1] |
| 28 |
- ``USCALED``: N bit unsigned integer [0 ... 2^N - 1] |
| 29 |
|
| 30 |
The difference between ``SINT`` and ``SSCALED`` is that the former are pure |
| 31 |
integers in shaders, while the latter are floats; likewise for ``UINT`` versus |
| 32 |
``USCALED``. |
| 33 |
|
| 34 |
There are two exceptions for ``FLOAT``. ``R9G9B9E5_FLOAT`` is nine bits |
| 35 |
each of red green and blue mantissa, with a shared five bit exponent. |
| 36 |
``R11G11B10_FLOAT`` is five bits of exponent and five or six bits of mantissa |
| 37 |
for each color channel. |
| 38 |
|
| 39 |
For the ``NORM`` suffix, the signedness of each channel is indicated with an |
| 40 |
S or U after the number of channel bits, as in ``R5SG5SB6U_NORM``. |
| 41 |
|
| 42 |
The ``SRGB`` suffix is like ``UNORM`` in range, but in the sRGB colorspace. |
| 43 |
|
| 44 |
Compressed formats are named first by the compression format string (``DXT1``, |
| 45 |
``ETC1``, etc), followed by a format-specific subtype. Refer to the |
| 46 |
appropriate compression spec for details. |
| 47 |
|
| 48 |
Formats used in video playback are named by their FOURCC code. |
| 49 |
|
| 50 |
Format names with an embedded underscore are subsampled. ``R8G8_B8G8`` is a |
| 51 |
single 32-bit block of two pixels, where the R and B values are repeated in |
| 52 |
both pixels. |
| 53 |
|
| 54 |
Index buffers do not have a natural format in Gallium structures. For purposes |
| 55 |
of ``is_format_supported`` queries, the formats ``R8_UINT``, ``R16_UINT``, and |
| 56 |
``R32_UINT`` are used with ``PIPE_BIND_INDEX_BUFFER`` for 8-bit, 16-bit, and |
| 57 |
32-bit index buffers respectively. |
| 58 |
|
| 59 |
References |
| 60 |
---------- |
| 61 |
|
| 62 |
DirectX Graphics Infrastructure documentation on DXGI_FORMAT enum: |
| 63 |
https://learn.microsoft.com/en-us/windows/win32/api/dxgiformat/ne-dxgiformat-dxgi_format |
| 64 |
|
| 65 |
FOURCC codes for YUV formats: |
| 66 |
http://web.archive.org/web/20220523043110/https://www.fourcc.org/yuv/ |