Merge pull request #104666 from allenwp/color-encoding-docs

Update color encoding documentation

Author: Repiteo

doc/classes/BaseMaterial3D.xml

@@ -66,7 +66,7 @@
 			If the texture appears unexpectedly too dark or too bright, check [member albedo_texture_force_srgb].
 		</member>
 		<member name="albedo_texture_force_srgb" type="bool" setter="set_flag" getter="get_flag" default="false" keywords="diffuse_texture_force_srgb">
-			If [code]true[/code], forces a conversion of the [member albedo_texture] from sRGB color space to linear color space. See also [member vertex_color_is_srgb].
+			If [code]true[/code], forces a conversion of the [member albedo_texture] from nonlinear sRGB encoding to linear encoding. See also [member vertex_color_is_srgb].
 			This should only be enabled when needed (typically when using a [ViewportTexture] as [member albedo_texture]). If [member albedo_texture_force_srgb] is [code]true[/code] when it shouldn't be, the texture will appear to be too dark. If [member albedo_texture_force_srgb] is [code]false[/code] when it shouldn't be, the texture will appear to be too bright.
 		</member>
 		<member name="albedo_texture_msdf" type="bool" setter="set_flag" getter="get_flag" default="false" keywords="diffuse_texture_force_srgb">
@@ -480,7 +480,7 @@
 			If [code]true[/code], triplanar mapping for [code]UV2[/code] is calculated in world space rather than object local space. See also [member uv2_triplanar].
 		</member>
 		<member name="vertex_color_is_srgb" type="bool" setter="set_flag" getter="get_flag" default="false">
-			If [code]true[/code], vertex colors are considered to be stored in sRGB color space and are converted to linear color space during rendering. If [code]false[/code], vertex colors are considered to be stored in linear color space and are rendered as-is. See also [member albedo_texture_force_srgb].
+			If [code]true[/code], vertex colors are considered to be stored in nonlinear sRGB encoding and are converted to linear encoding during rendering. If [code]false[/code], vertex colors are considered to be stored in linear encoding and are rendered as-is. See also [member albedo_texture_force_srgb].
 			[b]Note:[/b] Only effective when using the Forward+ and Mobile rendering methods, not Compatibility.
 		</member>
 		<member name="vertex_color_use_as_albedo" type="bool" setter="set_flag" getter="get_flag" default="false">
@@ -706,7 +706,7 @@
 			Set [code]ALBEDO[/code] to the per-vertex color specified in the mesh.
 		</constant>
 		<constant name="FLAG_SRGB_VERTEX_COLOR" value="2" enum="Flags">
-			Vertex colors are considered to be stored in sRGB color space and are converted to linear color space during rendering. See also [member vertex_color_is_srgb].
+			Vertex colors are considered to be stored in nonlinear sRGB encoding and are converted to linear encoding during rendering. See also [member vertex_color_is_srgb].
 			[b]Note:[/b] Only effective when using the Forward+ and Mobile rendering methods.
 		</constant>
 		<constant name="FLAG_USE_POINT_SIZE" value="3" enum="Flags">
@@ -737,7 +737,7 @@
 			Use [code]UV2[/code] coordinates to look up from the [member emission_texture].
 		</constant>
 		<constant name="FLAG_ALBEDO_TEXTURE_FORCE_SRGB" value="12" enum="Flags">
-			Forces the shader to convert albedo from sRGB space to linear space. See also [member albedo_texture_force_srgb].
+			Forces the shader to convert albedo from nonlinear sRGB encoding to linear encoding. See also [member albedo_texture_force_srgb].
 		</constant>
 		<constant name="FLAG_DONT_RECEIVE_SHADOWS" value="13" enum="Flags">
 			Disables receiving shadows from other objects.

doc/classes/Color.xml

@@ -5,10 +5,11 @@
 	</brief_description>
 	<description>
 		A color represented in RGBA format by a red ([member r]), green ([member g]), blue ([member b]), and alpha ([member a]) component. Each component is a 32-bit floating-point value, usually ranging from [code]0.0[/code] to [code]1.0[/code]. Some properties (such as [member CanvasItem.modulate]) may support values greater than [code]1.0[/code], for overbright or HDR (High Dynamic Range) colors.
-		Colors can be created in various ways: By the various [Color] constructors, by static methods such as [method from_hsv], and by using a name from the set of standardized colors based on [url=https://en.wikipedia.org/wiki/X11_color_names]X11 color names[/url] with the addition of [constant TRANSPARENT]. GDScript also provides [method @GDScript.Color8], which uses integers from [code]0[/code] to [code]255[/code] and doesn't support overbright colors.
-		Color data may be stored in many color spaces and encodings. The [method srgb_to_linear] and [method linear_to_srgb] methods can convert between nonlinear sRGB encoding and linear RGB encoding.
-		[b]Note:[/b] In a boolean context, a Color will evaluate to [code]false[/code] if it is equal to [code]Color(0, 0, 0, 1)[/code] (opaque black). Otherwise, a Color will always evaluate to [code]true[/code].
+		Colors can be created in a number of ways: By the various [Color] constructors, by static methods such as [method from_hsv], and by using a name from the set of standardized colors based on [url=https://en.wikipedia.org/wiki/X11_color_names]X11 color names[/url] with the addition of [constant TRANSPARENT]. GDScript also provides [method @GDScript.Color8], which uses integers from [code]0[/code] to [code]255[/code] and doesn't support overbright colors.
 		[url=https://raw.githubusercontent.com/godotengine/godot-docs/master/img/color_constants.png]Color constants cheatsheet[/url]
+		Although [Color] may be used to store values of any encoding, the red ([member r]), green ([member g]), and blue ([member b]) properties of [Color] are expected by Godot to be encoded using the [url=https://en.wikipedia.org/wiki/SRGB#Transfer_function_(%22gamma%22)]nonlinear sRGB transfer function[/url] unless otherwise stated. This color encoding is used by many traditional art and web tools, making it easy to match colors between Godot and these tools. Godot uses [url=https://en.wikipedia.org/wiki/Rec._709]Rec. ITU-R BT.709[/url] color primaries, which are used by the sRGB standard.
+		All physical simulation, such as lighting calculations, and colorimetry transformations, such as [method get_luminance], must be performed on linearly encoded values to produce correct results. When performing these calculations, convert [Color] to and from linear encoding using [method srgb_to_linear] and [method linear_to_srgb].
+		[b]Note:[/b] In a boolean context, a Color will evaluate to [code]false[/code] if it is equal to [code]Color(0, 0, 0, 1)[/code] (opaque black). Otherwise, a Color will always evaluate to [code]true[/code].
 	</description>
 	<tutorials>
 		<link title="2D GD Paint Demo">https://godotengine.org/asset-library/asset/2768</link>
@@ -214,7 +215,7 @@
 			<return type="float" />
 			<description>
 				Returns the light intensity of the color, as a value between 0.0 and 1.0 (inclusive). This is useful when determining light or dark color. Colors with a luminance smaller than 0.5 can be generally considered dark.
-				[b]Note:[/b] [method get_luminance] relies on the color being in the linear color space to return an accurate relative luminance value. If the color is in the sRGB color space, use [method srgb_to_linear] to convert it to the linear color space first.
+				[b]Note:[/b] [method get_luminance] relies on the color using linear encoding to return an accurate relative luminance value. If the color uses the default nonlinear sRGB encoding, use [method srgb_to_linear] to convert it to linear encoding first.
 			</description>
 		</method>
 		<method name="hex" qualifiers="static">
@@ -364,15 +365,15 @@
 		<method name="linear_to_srgb" qualifiers="const">
 			<return type="Color" />
 			<description>
-				Returns the color converted to the [url=https://en.wikipedia.org/wiki/SRGB]sRGB[/url] color space. This method assumes the original color is in the linear color space. See also [method srgb_to_linear] which performs the opposite operation.
-				[b]Note:[/b] The color's [member a]lpha channel is not affected. The alpha channel is always stored with linear encoding, regardless of the color space of the other color channels.
+				Returns a copy of the color that is encoded using the [url=https://en.wikipedia.org/wiki/SRGB]nonlinear sRGB transfer function[/url]. This method requires the original color to use linear encoding. See also [method srgb_to_linear] which performs the opposite operation.
+				[b]Note:[/b] The color's [member a]lpha channel is not affected. The alpha channel is always stored with linear encoding, regardless of the encoding of the other color channels.
 			</description>
 		</method>
 		<method name="srgb_to_linear" qualifiers="const">
 			<return type="Color" />
 			<description>
-				Returns the color converted to the linear color space. This method assumes the original color already is in the sRGB color space. See also [method linear_to_srgb] which performs the opposite operation.
-				[b]Note:[/b] The color's [member a]lpha channel is not affected. The alpha channel is always stored with linear encoding, regardless of the color space of the other color channels.
+				Returns a copy of the color that uses linear encoding. This method requires the original color to be encoded using the [url=https://en.wikipedia.org/wiki/SRGB]nonlinear sRGB transfer function[/url]. See also [method linear_to_srgb] which performs the opposite operation.
+				[b]Note:[/b] The color's [member a]lpha channel is not affected. The alpha channel is always stored with linear encoding, regardless of the encoding of the other color channels.
 			</description>
 		</method>
 		<method name="to_abgr32" qualifiers="const">
@@ -495,7 +496,7 @@
 	<members>
 		<member name="a" type="float" setter="" getter="" default="1.0">
 			The color's alpha component, typically on the range of 0 to 1. A value of 0 means that the color is fully transparent. A value of 1 means that the color is fully opaque.
-			[b]Note:[/b] The alpha channel is always stored with linear encoding, regardless of the color space of the other color channels. The [method linear_to_srgb] and [method srgb_to_linear] methods do not affect the alpha channel.
+			[b]Note:[/b] The alpha channel is always stored with linear encoding, regardless of the encoding of the other color channels. The [method linear_to_srgb] and [method srgb_to_linear] methods do not affect the alpha channel.
 		</member>
 		<member name="a8" type="int" setter="" getter="" default="255">
 			Wrapper for [member a] that uses the range 0 to 255, instead of 0 to 1.

doc/classes/ColorPicker.xml

@@ -74,7 +74,7 @@
 			If [code]true[/code], shows an alpha channel slider (opacity).
 		</member>
 		<member name="edit_intensity" type="bool" setter="set_edit_intensity" getter="is_editing_intensity" default="true">
-			If [code]true[/code], shows an intensity slider. The intensity is applied as follows: multiply the color by [code]2 ** intensity[/code] in linear RGB space, and then convert it back to sRGB.
+			If [code]true[/code], shows an intensity slider. The intensity is applied as follows: convert the color to linear encoding, multiply it by [code]2 ** intensity[/code], and then convert it back to nonlinear sRGB encoding.
 		</member>
 		<member name="hex_visible" type="bool" setter="set_hex_visible" getter="is_hex_visible" default="true">
 			If [code]true[/code], the hex color code input field is visible.

doc/classes/Gradient.xml

@@ -82,7 +82,7 @@
 			[b]Note:[/b] Setting this property updates all colors at once. To update any color individually use [method set_color].
 		</member>
 		<member name="interpolation_color_space" type="int" setter="set_interpolation_color_space" getter="get_interpolation_color_space" enum="Gradient.ColorSpace" default="0">
-			The color space used to interpolate between points of the gradient. It does not affect the returned colors, which will always be in sRGB space.
+			The color space used to interpolate between points of the gradient. It does not affect the returned colors, which will always use nonlinear sRGB encoding.
 			[b]Note:[/b] This setting has no effect when [member interpolation_mode] is set to [constant GRADIENT_INTERPOLATE_CONSTANT].
 		</member>
 		<member name="interpolation_mode" type="int" setter="set_interpolation_mode" getter="get_interpolation_mode" enum="Gradient.InterpolationMode" default="0">

doc/classes/Image.xml

@@ -325,7 +325,7 @@
 		<method name="linear_to_srgb">
 			<return type="void" />
 			<description>
-				Converts the entire image from the linear colorspace to the sRGB colorspace. Only works on images with [constant FORMAT_RGB8] or [constant FORMAT_RGBA8] formats.
+				Converts the entire image from linear encoding to nonlinear sRGB encoding by using a lookup table. Only works on images with [constant FORMAT_RGB8] or [constant FORMAT_RGBA8] formats.
 			</description>
 		</method>
 		<method name="load">
@@ -450,7 +450,7 @@
 		<method name="rgbe_to_srgb">
 			<return type="Image" />
 			<description>
-				Converts a standard RGBE (Red Green Blue Exponent) image to an sRGB image.
+				Converts a standard linear RGBE (Red Green Blue Exponent) image to an image that uses nonlinear sRGB encoding.
 			</description>
 		</method>
 		<method name="rotate_90">
@@ -618,7 +618,8 @@
 		<method name="srgb_to_linear">
 			<return type="void" />
 			<description>
-				Converts the raw data from the sRGB colorspace to a linear scale. Only works on images with [constant FORMAT_RGB8] or [constant FORMAT_RGBA8] formats.
+				Converts the raw data from nonlinear sRGB encoding to linear encoding using a lookup table. Only works on images with [constant FORMAT_RGB8] or [constant FORMAT_RGBA8] formats.
+				[b]Note:[/b] The 8-bit formats required by this method are not suitable for storing linearly encoded values; a significant amount of color information will be lost in darker values. To maintain image quality, this method should not be used.
 			</description>
 		</method>
 	</methods>
@@ -648,11 +649,11 @@
 		</constant>
 		<constant name="FORMAT_RGB8" value="4" enum="Format">
 			OpenGL texture format [code]RGB[/code] with three components, each with a bitdepth of 8.
-			[b]Note:[/b] When creating an [ImageTexture], an sRGB to linear color space conversion is performed.
+			[b]Note:[/b] When creating an [ImageTexture], a nonlinear sRGB to linear encoding conversion is performed.
 		</constant>
 		<constant name="FORMAT_RGBA8" value="5" enum="Format">
 			OpenGL texture format [code]RGBA[/code] with four components, each with a bitdepth of 8.
-			[b]Note:[/b] When creating an [ImageTexture], an sRGB to linear color space conversion is performed.
+			[b]Note:[/b] When creating an [ImageTexture], a nonlinear sRGB to linear encoding conversion is performed.
 		</constant>
 		<constant name="FORMAT_RGBA4444" value="6" enum="Format">
 			OpenGL texture format [code]RGBA[/code] with four components, each with a bitdepth of 4.
@@ -689,15 +690,15 @@
 		</constant>
 		<constant name="FORMAT_DXT1" value="17" enum="Format">
 			The [url=https://en.wikipedia.org/wiki/S3_Texture_Compression]S3TC[/url] texture format that uses Block Compression 1, and is the smallest variation of S3TC, only providing 1 bit of alpha and color data being premultiplied with alpha.
-			[b]Note:[/b] When creating an [ImageTexture], an sRGB to linear color space conversion is performed.
+			[b]Note:[/b] When creating an [ImageTexture], a nonlinear sRGB to linear encoding conversion is performed.
 		</constant>
 		<constant name="FORMAT_DXT3" value="18" enum="Format">
 			The [url=https://en.wikipedia.org/wiki/S3_Texture_Compression]S3TC[/url] texture format that uses Block Compression 2, and color data is interpreted as not having been premultiplied by alpha. Well suited for images with sharp alpha transitions between translucent and opaque areas.
-			[b]Note:[/b] When creating an [ImageTexture], an sRGB to linear color space conversion is performed.
+			[b]Note:[/b] When creating an [ImageTexture], a nonlinear sRGB to linear encoding conversion is performed.
 		</constant>
 		<constant name="FORMAT_DXT5" value="19" enum="Format">
 			The [url=https://en.wikipedia.org/wiki/S3_Texture_Compression]S3TC[/url] texture format also known as Block Compression 3 or BC3 that contains 64 bits of alpha channel data followed by 64 bits of DXT1-encoded color data. Color data is not premultiplied by alpha, same as DXT3. DXT5 generally produces superior results for transparent gradients compared to DXT3.
-			[b]Note:[/b] When creating an [ImageTexture], an sRGB to linear color space conversion is performed.
+			[b]Note:[/b] When creating an [ImageTexture], a nonlinear sRGB to linear encoding conversion is performed.
 		</constant>
 		<constant name="FORMAT_RGTC_R" value="20" enum="Format">
 			Texture format that uses [url=https://www.khronos.org/opengl/wiki/Red_Green_Texture_Compression]Red Green Texture Compression[/url], normalizing the red channel data using the same compression algorithm that DXT5 uses for the alpha channel.
@@ -707,7 +708,7 @@
 		</constant>
 		<constant name="FORMAT_BPTC_RGBA" value="22" enum="Format">
 			Texture format that uses [url=https://www.khronos.org/opengl/wiki/BPTC_Texture_Compression]BPTC[/url] compression with unsigned normalized RGBA components.
-			[b]Note:[/b] When creating an [ImageTexture], an sRGB to linear color space conversion is performed.
+			[b]Note:[/b] When creating an [ImageTexture], a nonlinear sRGB to linear encoding conversion is performed.
 		</constant>
 		<constant name="FORMAT_BPTC_RGBF" value="23" enum="Format">
 			Texture format that uses [url=https://www.khronos.org/opengl/wiki/BPTC_Texture_Compression]BPTC[/url] compression with signed floating-point RGB components.
@@ -732,15 +733,15 @@
 		</constant>
 		<constant name="FORMAT_ETC2_RGB8" value="30" enum="Format">
 			[url=https://en.wikipedia.org/wiki/Ericsson_Texture_Compression#ETC2_and_EAC]Ericsson Texture Compression format 2[/url] ([code]RGB8[/code] variant), which is a follow-up of ETC1 and compresses RGB888 data.
-			[b]Note:[/b] When creating an [ImageTexture], an sRGB to linear color space conversion is performed.
+			[b]Note:[/b] When creating an [ImageTexture], a nonlinear sRGB to linear encoding conversion is performed.
 		</constant>
 		<constant name="FORMAT_ETC2_RGBA8" value="31" enum="Format">
 			[url=https://en.wikipedia.org/wiki/Ericsson_Texture_Compression#ETC2_and_EAC]Ericsson Texture Compression format 2[/url] ([code]RGBA8[/code]variant), which compresses RGBA8888 data with full alpha support.
-			[b]Note:[/b] When creating an [ImageTexture], an sRGB to linear color space conversion is performed.
+			[b]Note:[/b] When creating an [ImageTexture], a nonlinear sRGB to linear encoding conversion is performed.
 		</constant>
 		<constant name="FORMAT_ETC2_RGB8A1" value="32" enum="Format">
 			[url=https://en.wikipedia.org/wiki/Ericsson_Texture_Compression#ETC2_and_EAC]Ericsson Texture Compression format 2[/url] ([code]RGB8_PUNCHTHROUGH_ALPHA1[/code] variant), which compresses RGBA data to make alpha either fully transparent or fully opaque.
-			[b]Note:[/b] When creating an [ImageTexture], an sRGB to linear color space conversion is performed.
+			[b]Note:[/b] When creating an [ImageTexture], a nonlinear sRGB to linear encoding conversion is performed.
 		</constant>
 		<constant name="FORMAT_ETC2_RA_AS_RG" value="33" enum="Format">
 			[url=https://en.wikipedia.org/wiki/Ericsson_Texture_Compression#ETC2_and_EAC]Ericsson Texture Compression format 2[/url] ([code]RGBA8[/code] variant), which compresses RA data and interprets it as two channels (red and green). See also [constant FORMAT_ETC2_RGBA8].
@@ -831,7 +832,7 @@
 			Source texture (before compression) is a regular texture. Default for all textures.
 		</constant>
 		<constant name="COMPRESS_SOURCE_SRGB" value="1" enum="CompressSource">
-			Source texture (before compression) is in sRGB space.
+			Source texture (before compression) uses nonlinear sRGB encoding.
 		</constant>
 		<constant name="COMPRESS_SOURCE_NORMAL" value="2" enum="CompressSource">
 			Source texture (before compression) is a normal texture (e.g. it can be compressed into two channels).