docs/isl: Add detailed documentation about isl formats

Part-of: <https://gitlab.freedesktop.org/mesa/mesa/-/merge_requests/11366>

2 files changed, 229 insertions, 0 deletions

diff --git a/docs/isl/formats.rst b/docs/isl/formats.rst
new file mode 100644
index 00000000000..71a32158d8c
--- /dev/null
+++ b/docs/isl/formats.rst
@@ -0,0 +1,228 @@
+Surface Formats
+===============
+
+A surface format describes the encoding of color information into the actual
+data stored in memory.  Surface formats in isl are specified via the
+:cpp:enum:`isl_format` enum.  A complete list of surface formats is included at
+the end of this chapter.
+
+In general, a surface format definition consists of two parts: encoding and
+layout.
+
+Data Encoding
+-------------
+
+There are several different ways that one can encode a number (or vector) into
+a binary form, and each makes different trade-offs.  By default, most color
+values lie in the range [0, 1], so one of the most common encodings for color
+data is unsigned normalized where the range of an unsigned integer of a
+particular size is mapped linearly onto the interval [0, 1]. While normalized
+is certainly the most common representation for color data, not all data is
+color data, and not all values are nicely bounded.  The possible data encodings
+are specified by :cpp:enum:`isl_base_type`:
+
+.. doxygenenum:: isl_base_type
+
+Data Layout
+-----------
+
+The different data layouts fall into two categories: array and packed.  When an
+array layout is used, the components are stored sequentially in an array of the
+given encoding.  For instance, if the data is encoded in an 8-bit RGBA array
+format the data is stored in an array of type :c:type:`uint8_t` where the blue
+component of the :c:expr:`i`'th color value is accessed as:
+
+.. code-block:: C
+
+   uint8_t r = ((uint8_t *)data)[i * 4 + 0];
+   uint8_t g = ((uint8_t *)data)[i * 4 + 1];
+   uint8_t b = ((uint8_t *)data)[i * 4 + 2];
+   uint8_t a = ((uint8_t *)data)[i * 4 + 3];
+
+Array formats are popular because of their simplicity.  However, they are
+limited to formats where all components have the same size and fit in
+a standard C data type.
+
+Packed formats, on the other hand, are encoded with the entire color value
+packed into a single 8, 16, or 32-bit value.  The components are specified by
+which bits they occupy within that value.  For instance, with the popular
+:c:expr:`RGB565` format, each :c:type:`vec3` takes up 16 bits and the
+:c:expr:`i`'th color value is accessed as:
+
+.. code-block:: C
+
+   uint8_t r = (*(uint16_t *)data >> 0) & 0x1f;
+   uint8_t g = (*(uint16_t *)data >> 5) & 0x3f;
+   uint8_t b = (*(uint16_t *)data >> 11) & 0x1f;
+
+Packed formats are useful because they allow you to specify formats with uneven
+component sizes such as :c:expr:`RGBA1010102` or where the components are
+smaller than 8 bits such as :c:expr:`RGB565` discussed above.  It does,
+however, come with the restriction that the entire vector must fit within 8,
+16, or 32 bits.
+
+One has to be careful when reasoning about packed formats because it is easy to
+get the color order wrong.  With array formats, the channel ordering is usually
+implied directly from the format name with :c:expr:`RGBA8888` storing the
+formats as in the first example and :c:expr:`BGRA8888` storing them in the BGRA
+ordering.  Packed formats, however, are not as simple because some
+specifications choose to use a MSB to LSB ordering and others LSB to MSB.  One
+must be careful to pay attention to the enum in question in order to avoid
+getting them backwards.
+
+From an API perspective, both types of formats are available.  In Vulkan, the
+formats that are of the form :c:enumerator:`VK_FORMAT_xxx_PACKEDn` are packed
+formats where the entire color fits in :c:expr:`n` bits and formats without the
+:c:expr:`_PACKEDn` suffix are array formats.  In GL, if you specify one of the
+base types such as :c:enumerator:`GL_FLOAT` you get an array format but if you
+specify a packed type such as :c:enumerator:`GL_UNSIGNED_INT_8_8_8_8_REV` you
+get a packed format.
+
+The following table provides a summary of the bit orderings of different packed
+format specifications.  The bit ordering is relative to the reading of the enum
+name from left to right.
+
+=====================  ==============
+Component               Left → Right
+=====================  ==============
+GL                       MSB → LSB
+Vulkan                   MSB → LSB
+mesa_format              LSB → MSB
+Intel surface format     LSB → MSB
+=====================  ==============
+
+Understanding sRGB
+------------------
+
+The sRGB colorspace is one of the least tractable concepts in the entire world
+of surfaces and formats.  Most texture formats are stored in a linear
+colorspace where the floating-point value corresponds linearly to intensity
+values.  The sRGB color space, on the other hand, is non-linear and provides
+greater precision in the lower-intensity (darker) end of the spectrum.  The
+relationship between linear and sRGB is governed by the following continuous
+bijection:
+
+.. math::
+
+   c_l =
+   \begin{cases}
+   \frac{c_s}{12.92}                            &\text{if } c_s \le 0.04045 \\\\
+   \left(\frac{c_s + 0.055}{1.055}\right)^{2.4} &\text{if } c_s > 0.04045
+   \end{cases}
+
+where :math:`c_l` is the linear color and :math:`c_s` is the color in sRGB.
+It is important to note that, when an alpha channel is present, the alpha
+channel is always stored in the linear colorspace.
+
+The key to understanding sRGB is to think about it starting from the physical
+display.  All displays work natively in sRGB.  On older displays, there isn't
+so much a conversion operation as a fact of how the hardware works.  All
+display hardware has a natural gamma curve required to get from linear to the
+signal level required to generate the correct color.  On older CRT displays,
+the gamma curve of your average CRT is approximately the sRGB curve.  More
+modern display hardware has support for additional gamma curves to try and get
+accurate colors but, for the sake of compatibility, everything still operates
+in sRGB.  When an image is sent to the X server, X passes the pixels on to the
+display verbatim without doing any conversions.  (Fun fact: When dealing with
+translucent windows, X blends in the wrong colorspace.)  This means that the
+image into which you are rendering will always be interpreted as if it were in
+the sRGB colorspace.
+
+When sampling from a texture, the value returned to the shader is in the linear
+colorspace.  The conversion from sRGB happens as part of sampling. In OpenGL,
+thanks mostly to history, there are various knobs for determining when you
+should or should not encode or decode sRGB.  In 2007, GL_EXT_texture_sRGB added
+support for sRGB texture formats and was included in OpenGL 2.1.  In 2010,
+GL_EXT_texture_sRGB_decode added a flag to allow you to disable texture
+decoding so that the shader received the data still in the sRGB colorspace.
+Then, in 2012, GL_ARB_texture_view came along and made
+GL_EXT_texture_sRGB_decode` simultaneously obsolete and very confusing.  Now,
+thanks to the combination of extensions, you can upload a texture as linear,
+create an sRGB view of it and ask that sRGB not be decoded.  What format is it
+in again?
+
+The situation with render targets is a bit different.  Historically, you got
+your render target from the window system (which is always sRGB) and the spec
+said nothing whatsoever about encoding.  All render targets were sRGB because
+that's how monitors worked and application writers were expected to understand
+that their final rendering needed to be in sRGB.  However, with the advent of
+EXT_framebuffer_object this was no longer true.  Also, sRGB was causing
+problems with blending because GL was blind to the fact that the output was
+sRGB and blending was occurring in the wrong colorspace. In 2006, a set of
+EXT_framebuffer_sRGB extensions added support (on both the GL and window-system
+sides) for detecting whether a particular framebuffer was in sRGB and
+instructing GL to do the conversion into the sRGB colorspace as the final step
+prior to writing out to the render target.  Enabling sRGB also implied that
+blending would occur in the linear colorspace prior to sRGB conversion and
+would therefore be more accurate.  When sRGB was added to the OpenGL ES spec in
+3.1, they added the query for sRGB but did not add the flag to allow you to
+turn it on and off.
+
+In Vulkan, this is all much more straightforward.  Your format is sRGB or it
+isn't.  If you have an sRGB image and you don't want sRGB decoding to happen
+when you sample from it, you simply create a c:struct:`VkImageView` that has
+the appropriate linear format and the data will be treated as linear and not
+converted.  Similarly for render targets, blending always happens in the same
+colorspace as the shader output and you determine whether or not you want sRGB
+conversion by the format of the c:struct:`VkImageView` used as the render
+target.
+
+Surface Format Introspection API
+--------------------------------
+
+ISL provides an API for introspecting the :cpp:enum:`isl_format` enum and
+getting various bits of information about a format.  ISL provides helpers for
+introspecting both the data layout of an cpp:enum:`isl_format` and the
+capabilities of that format for a particular piece of Intel hardware.
+
+Format Layout Introspection
+^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+To get the layout of a given :cpp:enum:`isl_format`, call
+:cpp:func:`isl_format_get_layout`:
+
+.. doxygenfunction:: isl_format_get_layout
+
+.. doxygenstruct:: isl_format_layout
+   :members:
+
+.. doxygenstruct:: isl_channel_layout
+   :members:
+
+There are also quite a few helpers for many of the common cases that allow you
+to avoid using :cpp:struct:`isl_format_layout` manually.  There are a lot of
+them so we won't include a full list here.  Look at isl.h for more details.
+
+Hardware Format Support Introspection
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+This is provided by means of a table located in isl_format.c.  Looking at the
+table directly is often useful for understanding HW support for various
+formats.  However, for the purposes of code cleanliness, the table is not
+exposed directly and, instead, hardware support information is exposed via
+a set of helper functions:
+
+.. doxygenfunction:: isl_format_supports_rendering
+.. doxygenfunction:: isl_format_supports_alpha_blending
+.. doxygenfunction:: isl_format_supports_sampling
+.. doxygenfunction:: isl_format_supports_filtering
+.. doxygenfunction:: isl_format_supports_vertex_fetch
+.. doxygenfunction:: isl_format_supports_typed_writes
+.. doxygenfunction:: isl_format_supports_typed_reads
+.. doxygenfunction:: isl_format_supports_ccs_d
+.. doxygenfunction:: isl_format_supports_ccs_e
+.. doxygenfunction:: isl_format_supports_multisampling
+.. doxygenfunction:: isl_formats_are_ccs_e_compatible
+
+Surface Format Enums
+--------------------
+
+Everything in ISL is done in terms of the :cpp:enum:`isl_format` enum. However,
+for the sake of interacting with other parts of Mesa, we provide a helper for
+converting a :cpp:enum:`pipe_format` to an :cpp:enum:`isl_format`:
+
+.. doxygenfunction:: isl_format_for_pipe_format
+
+The :cpp:enum:`isl_format` enum is as follows:
+
+.. doxygenenum:: isl_format
diff --git a/docs/isl/index.rst b/docs/isl/index.rst
index e3dbd694a19..74dbcda171d 100644
--- a/docs/isl/index.rst
+++ b/docs/isl/index.rst
@@ -10,6 +10,7 @@ Chery.
    :maxdepth: 2
 
    units
+   formats
 
 The core representation of a surface in ISL is :cpp:struct:`isl_surf`.