This PR builds on top of @aaronfranke's merged PR #104410.

This PR adds additional detail to the Color class description, including information about color primaries. It states clearly that Color is expected to use the nonlinear sRGB transfer function for R, G, and B values unless stated otherwise by documentation.

To reviewers:

This PR is somewhat a proposal and somewhat a discussion. I felt that it would be better to present my proposed changes in the form of a PR instead of a proposal.

I have added a note about the srgb parameter of TextureStorage::texture_get_native_handle and TextureStorage::texture_get_rd_texture, but I don't know if I've written this correctly.

The problem with the "color space" term

With upcoming HDR output support and eventual and inevitable wide colour gamut support, I believe it is valuable to be more precise with our terminology regarding colour. Of specific concern is the term "color space", which I have found to be a loose term that often describes both colour gamut (which relates to colour primaries) and colour data encoding/format and/or transfer function. Graphics APIs often combine these attributes into what they call a "color space" (see VkColorSpaceKHR). But sometimes colour scientists will intentionally not refer to data format/encoding or transfer functions when describing what a "color space" is:

Source: From Texture to Display: The Color Pipeline of a Pixel in Unreal Engine | Unreal Fest 2024

After quite a few months immersing myself in the field of colour science, I have developed a strong belief that the term "color space" is simply too ambiguous to be useful, especially in technical writing and collaboration between a diverse group of collaborators. I propose that this specific term should generally be avoided and only used with care and an understanding that it is ambiguous. This PR implements this proposed approach.

Acceptable terminology

• A Color is encoded using the nonlinear sRGB transfer function
• A Color uses nonlinear sRGB encoding (shorthand of above)
• A Color uses linear encoding

Why "nonlinear sRGB encoding" instead of "sRGB encoding"?

Using the term "nonlinear" to describe the nonlinear sRGB transfer function helps the reader understand this encoding is related to the linear/nonlinear attribute of RGB values and is not related to the colour gamut. This is especially important with the sRGB standard, which describes both a colour gamut and a transfer function that is used for encoding. Additionally, in Edward Giorgianni and Thomas Madden's book "Digital Color Management" (which provided foundational concepts to the ACES colour system), the term "colour encoding" is sometimes used to describe the the mapping of a colour stimulus (a spectral distribution) to a linear tristimulus value using CIE colour matching functions. This means that "sRGB encoding" could be interpreted to mean "encoding a colour stimulous into linear values using CIE colour matching with the sRGB colour primaries". For this reason, adding "nonlinear" makes it more clear to people from every field that the "nonlinear sRGB encoding" shorthand simply means "encoding using the nonlinear sRGB transfer function".

Gradient and color picker classes

I have left these two classes somewhat unchanged: They still use the "color space" term, and I believe that these are two uncommon scenarios where "color space" is not problematic (for example, OKHSL is very much a "color space" -- it is more than just an encoding and gamut). Once other colour primaries are implemented, this might need to be revisited.

Remaining work

• Search for other places in the docs that should have details about linear encoding being necessary
• Ensure Compatibility rendering method behaviour (regarding using nonlinear sRGB values for lighting calculations) is documented somewhere
• Separate PR: update tutorial documentation to match class documentation terminology
• Ensure that shader documentation correctly assumes sRGB values and suggests linear when needed for correct simulation
• Review source_color docs and behaviour with 2D HDR
• Ensure material vertex color is correctly documented and handled