docs/isl/formats.rst - third_party/mesa - Git at Google

 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
	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