Add API for HSL conversion

Math ported pretty much 1:1 from https://en.wikipedia.org/wiki/HSL_and_HSV
Style doesn't match the existing HSV code exactly, but should be close enough.

core/math/color.cpp

@@ -188,6 +188,32 @@ float Color::get_v() const {
 	return max;
 }
 
+float Color::get_hsl_h() const {
+	return get_h();
+}
+
+float Color::get_hsl_s() const {
+	float min = MIN(MIN(r, g), b);
+	float max = MAX(MAX(r, g), b);
+
+	float mid = (min + max) / 2.0f;
+
+	if (mid == 0.0f || mid == 1.0f) {
+		return 0.0f;
+	}
+
+	float delta = max - min;
+
+	return delta / (1.0f - Math::abs(2.0f * mid - 1.0f));
+}
+
+float Color::get_hsl_l() const {
+	float min = MIN(MIN(r, g), b);
+	float max = MAX(MAX(r, g), b);
+
+	return (min + max) / 2.0f;
+}
+
 void Color::set_hsv(float p_h, float p_s, float p_v, float p_alpha) {
 	int i;
 	float f, p, q, t;
@@ -242,6 +268,59 @@ void Color::set_hsv(float p_h, float p_s, float p_v, float p_alpha) {
 	}
 }
 
+void Color::set_hsl(float p_h, float p_s, float p_l, float p_alpha) {
+	a = p_alpha;
+
+	if (p_s == 0.0f) {
+		// Achromatic (gray)
+		r = g = b = p_l;
+		return;
+	}
+
+	p_h *= 6.0f;
+	p_h = Math::fmod(p_h, 6.0f);
+
+	float c = (1.0f - Math::abs(2.0f * p_l - 1.0f)) * p_s;
+	float x = c * (1.0f - Math::abs(Math::fmod(p_h, 2.0f) - 1.0f));
+	float m = p_l - c / 2.0f;
+
+	c += m;
+	x += m;
+
+	switch ((int)p_h) {
+		case 0: // Red is the dominant color
+			r = c;
+			g = x;
+			b = m;
+			break;
+		case 1: // Green is the dominant color
+			r = x;
+			g = c;
+			b = m;
+			break;
+		case 2:
+			r = m;
+			g = c;
+			b = x;
+			break;
+		case 3: // Blue is the dominant color
+			r = m;
+			g = x;
+			b = c;
+			break;
+		case 4:
+			r = x;
+			g = m;
+			b = c;
+			break;
+		default: // (5) Red is the dominant color
+			r = c;
+			g = m;
+			b = x;
+			break;
+	}
+}
+
 void Color::set_ok_hsl(float p_h, float p_s, float p_l, float p_alpha) {
 	ok_color::HSL hsl;
 	hsl.h = p_h;
@@ -468,6 +547,12 @@ Color Color::from_hsv(float p_h, float p_s, float p_v, float p_alpha) {
 	return c;
 }
 
+Color Color::from_hsl(float p_h, float p_s, float p_l, float p_alpha) {
+	Color c;
+	c.set_hsl(p_h, p_s, p_l, p_alpha);
+	return c;
+}
+
 Color Color::from_rgbe9995(uint32_t p_rgbe) {
 	float r = p_rgbe & 0x1ff;
 	float g = (p_rgbe >> 9) & 0x1ff;

core/math/color.h

@@ -57,6 +57,10 @@ struct _NO_DISCARD_ Color {
 	float get_s() const;
 	float get_v() const;
 	void set_hsv(float p_h, float p_s, float p_v, float p_alpha = 1.0f);
+	float get_hsl_h() const;
+	float get_hsl_s() const;
+	float get_hsl_l() const;
+	void set_hsl(float p_h, float p_s, float p_l, float p_alpha = 1.0f);
 	float get_ok_hsl_h() const;
 	float get_ok_hsl_s() const;
 	float get_ok_hsl_l() const;
@@ -198,6 +202,7 @@ struct _NO_DISCARD_ Color {
 	static Color get_named_color(int p_idx);
 	static Color from_string(const String &p_string, const Color &p_default);
 	static Color from_hsv(float p_h, float p_s, float p_v, float p_alpha = 1.0f);
+	static Color from_hsl(float p_h, float p_s, float p_l, float p_alpha = 1.0f);
 	static Color from_ok_hsl(float p_h, float p_s, float p_l, float p_alpha = 1.0f);
 	static Color from_rgbe9995(uint32_t p_rgbe);
 
@@ -217,6 +222,9 @@ struct _NO_DISCARD_ Color {
 	_FORCE_INLINE_ void set_h(float p_h) { set_hsv(p_h, get_s(), get_v(), a); }
 	_FORCE_INLINE_ void set_s(float p_s) { set_hsv(get_h(), p_s, get_v(), a); }
 	_FORCE_INLINE_ void set_v(float p_v) { set_hsv(get_h(), get_s(), p_v, a); }
+	_FORCE_INLINE_ void set_hsl_h(float p_h) { set_hsl(p_h, get_hsl_s(), get_hsl_l(), a); }
+	_FORCE_INLINE_ void set_hsl_s(float p_s) { set_hsl(get_hsl_h(), p_s, get_hsl_l(), a); }
+	_FORCE_INLINE_ void set_hsl_l(float p_l) { set_hsl(get_hsl_h(), get_hsl_s(), p_l, a); }
 	_FORCE_INLINE_ void set_ok_hsl_h(float p_h) { set_ok_hsl(p_h, get_ok_hsl_s(), get_ok_hsl_l(), a); }
 	_FORCE_INLINE_ void set_ok_hsl_s(float p_s) { set_ok_hsl(get_ok_hsl_h(), p_s, get_ok_hsl_l(), a); }
 	_FORCE_INLINE_ void set_ok_hsl_l(float p_l) { set_ok_hsl(get_ok_hsl_h(), get_ok_hsl_s(), p_l, a); }

core/variant/variant_call.cpp

@@ -2000,6 +2000,7 @@ static void _register_variant_builtin_methods() {
 	bind_static_method(Color, html_is_valid, sarray("color"), varray());
 	bind_static_method(Color, from_string, sarray("str", "default"), varray());
 	bind_static_method(Color, from_hsv, sarray("h", "s", "v", "alpha"), varray(1.0));
+	bind_static_method(Color, from_hsl, sarray("h", "s", "l", "alpha"), varray(1.0));
 	bind_static_method(Color, from_ok_hsl, sarray("h", "s", "l", "alpha"), varray(1.0));
 
 	bind_static_method(Color, from_rgbe9995, sarray("rgbe"), varray());

core/variant/variant_setget.cpp

@@ -139,6 +139,10 @@ void register_named_setters_getters() {
 	REGISTER_MEMBER(Color, h);
 	REGISTER_MEMBER(Color, s);
 	REGISTER_MEMBER(Color, v);
+
+	REGISTER_MEMBER(Color, hsl_h);
+	REGISTER_MEMBER(Color, hsl_s);
+	REGISTER_MEMBER(Color, hsl_l);
 }
 
 void unregister_named_setters_getters() {

core/variant/variant_setget.h

@@ -344,6 +344,10 @@ SETGET_NUMBER_STRUCT_FUNC(Color, double, h, set_h, get_h)
 SETGET_NUMBER_STRUCT_FUNC(Color, double, s, set_s, get_s)
 SETGET_NUMBER_STRUCT_FUNC(Color, double, v, set_v, get_v)
 
+SETGET_NUMBER_STRUCT_FUNC(Color, double, hsl_h, set_hsl_h, get_hsl_h)
+SETGET_NUMBER_STRUCT_FUNC(Color, double, hsl_s, set_hsl_s, get_hsl_s)
+SETGET_NUMBER_STRUCT_FUNC(Color, double, hsl_l, set_hsl_l, get_hsl_l)
+
 SETGET_NUMBER_STRUCT_FUNC(Color, double, ok_hsl_h, set_ok_hsl_h, get_ok_hsl_h)
 SETGET_NUMBER_STRUCT_FUNC(Color, double, ok_hsl_s, set_ok_hsl_s, get_ok_hsl_s)
 SETGET_NUMBER_STRUCT_FUNC(Color, double, ok_hsl_l, set_ok_hsl_l, get_ok_hsl_l)

doc/classes/Color.xml

@@ -141,6 +141,24 @@
 				[/codeblocks]
 			</description>
 		</method>
+		<method name="from_hsl" qualifiers="static">
+			<return type="Color" />
+			<param index="0" name="h" type="float" />
+			<param index="1" name="s" type="float" />
+			<param index="2" name="l" type="float" />
+			<param index="3" name="alpha" type="float" default="1.0" />
+			<description>
+				Constructs a color from an [url=https://en.wikipedia.org/wiki/HSL_and_HSV]HSL profile[/url]. The hue ([param h]), saturation ([param s]), and lightness ([param l]) are typically between 0.0 and 1.0.
+				[codeblocks]
+				[gdscript]
+				var color = Color.from_hsl(0.58, 0.5, 0.79, 0.8)
+				[/gdscript]
+				[csharp]
+				var color = Color.FromHsl(0.58f, 0.5f, 0.79f, 0.8f);
+				[/csharp]
+				[/codeblocks]
+			</description>
+		</method>
 		<method name="from_hsv" qualifiers="static">
 			<return type="Color" />
 			<param index="0" name="h" type="float" />
@@ -493,6 +511,15 @@
 		<member name="h" type="float" setter="" getter="" default="0.0">
 			The HSV hue of this color, on the range 0 to 1.
 		</member>
+		<member name="hsl_h" type="float" setter="" getter="" default="0.0">
+			The HSL hue of this color, on the range 0 to 1.
+		</member>
+		<member name="hsl_l" type="float" setter="" getter="" default="0.0">
+			The HSL lightness of this color, on the range 0 to 1.
+		</member>
+		<member name="hsl_s" type="float" setter="" getter="" default="0.0">
+			The HSL saturation of this color, on the range 0 to 1.
+		</member>
 		<member name="r" type="float" setter="" getter="" default="0.0">
 			The color's red component, typically on the range of 0 to 1.
 		</member>

modules/mono/glue/GodotSharp/GodotSharp/Core/Color.cs

@@ -187,6 +187,69 @@ namespace Godot
             }
         }
 
+        /// <summary>
+        /// The HSL hue of this color, on the range 0 to 1.
+        /// </summary>
+        /// <value>Getting is a long process, refer to the source code for details. Setting uses <see cref="FromHsl"/>.</value>
+        public float HslH
+        {
+            readonly get
+            {
+                return H;
+            }
+            set
+            {
+                this = FromHsl(value, HslS, HslL, A);
+            }
+        }
+
+        /// <summary>
+        /// The HSL saturation of this color, on the range 0 to 1.
+        /// </summary>
+        /// <value>Getting is equivalent to the ratio between the min and max RGB value. Setting uses <see cref="FromHsl"/>.</value>
+        public float HslS
+        {
+            readonly get
+            {
+                float max = Math.Max(R, Math.Max(G, B));
+                float min = Math.Min(R, Math.Min(G, B));
+
+                float mid = (max + min) / 2.0f;
+
+                if (mid == 0.0f || mid == 1.0f)
+                {
+                    return 0.0f;
+                }
+
+                float delta = max - min;
+
+                return delta / (1.0f - Math.Abs(2.0f * mid - 1.0f));
+            }
+            set
+            {
+                this = FromHsl(HslH, value, HslL, A);
+            }
+        }
+
+        /// <summary>
+        /// The HSL lightness of this color, on the range 0 to 1.
+        /// </summary>
+        /// <value>Getting is equivalent to using <see cref="Math.Max(float, float)"/> on the RGB components. Setting uses <see cref="FromHsl"/>.</value>
+        public float HslL
+        {
+            readonly get
+            {
+                float max = Math.Max(R, Math.Max(G, B));
+                float min = Math.Min(R, Math.Min(G, B));
+
+                return (max + min) / 2.0f;
+            }
+            set
+            {
+                this = FromHsl(HslH, HslS, value, A);
+            }
+        }
+
         /// <summary>
         /// 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
@@ -877,6 +940,104 @@ namespace Godot
             value = max;
         }
 
+        /// <summary>
+        /// Constructs a color from an HSL profile. The <paramref name="hue"/>,
+        /// <paramref name="saturation"/>, and <paramref name="lightness"/> are typically
+        /// between 0.0 and 1.0.
+        /// </summary>
+        /// <param name="hue">The HSL hue, typically on the range of 0 to 1.</param>
+        /// <param name="saturation">The HSL saturation, typically on the range of 0 to 1.</param>
+        /// <param name="lightness">The HSL lightness, typically on the range of 0 to 1.</param>
+        /// <param name="alpha">The alpha (transparency) value, typically on the range of 0 to 1.</param>
+        /// <returns>The constructed color.</returns>
+        public static Color FromHsl(float hue, float saturation, float lightness, float alpha = 1.0f)
+        {
+            if (saturation == 0.0f)
+            {
+                // Achromatic (gray)
+                return new Color(lightness, lightness, lightness, alpha);
+            }
+
+            hue *= 6.0f;
+            hue %= 6.0f;
+
+            float c = (1.0f - Math.Abs(2.0f * lightness - 1.0f)) * saturation;
+            float x = c * (1.0f - Math.Abs(hue % 2.0f - 1.0f));
+            float m = lightness - c / 2.0f;
+
+            c += m;
+            x += m;
+
+            switch ((int)hue)
+            {
+                case 0: // Red is the dominant color
+                    return new Color(c, x, m, alpha);
+                case 1: // Green is the dominant color
+                    return new Color(x, c, m, alpha);
+                case 2:
+                    return new Color(m, c, x, alpha);
+                case 3: // Blue is the dominant color
+                    return new Color(m, x, c, alpha);
+                case 4:
+                    return new Color(x, m, c, alpha);
+                default: // (5) Red is the dominant color
+                    return new Color(c, m, x, alpha);
+            }
+        }
+
+        /// <summary>
+        /// Converts a color to HSL values. This is equivalent to using each of
+        /// the <c>h</c>/<c>s</c>/<c>l</c> properties, but much more efficient.
+        /// </summary>
+        /// <param name="hue">Output parameter for the HSL hue.</param>
+        /// <param name="saturation">Output parameter for the HSL saturation.</param>
+        /// <param name="lightness">Output parameter for the HSL lightness.</param>
+        public readonly void ToHsl(out float hue, out float saturation, out float lightness)
+        {
+            float max = (float)Mathf.Max(R, Mathf.Max(G, B));
+            float min = (float)Mathf.Min(R, Mathf.Min(G, B));
+
+            float delta = max - min;
+
+            if (delta == 0.0f)
+            {
+                hue = 0.0f;
+            }
+            else
+            {
+                if (R == max)
+                {
+                    hue = (G - B) / delta; // Between yellow & magenta
+                }
+                else if (G == max)
+                {
+                    hue = 2.0f + ((B - R) / delta); // Between cyan & yellow
+                }
+                else
+                {
+                    hue = 4.0f + ((R - G) / delta); // Between magenta & cyan
+                }
+
+                hue /= 6.0f;
+
+                if (hue < 0.0f)
+                {
+                    hue += 1.0f;
+                }
+            }
+
+            lightness = (max + min) / 2.0f;
+
+            if (lightness == 0.0f || lightness == 1.0f)
+            {
+                saturation = 0.0f;
+            }
+            else
+            {
+                saturation = delta / (1.0f - Math.Abs(2.0f * lightness - 1.0f));
+            }
+        }
+
         private static int ParseCol4(ReadOnlySpan<char> str, int index)
         {
             char character = str[index];

tests/core/math/test_color.h

@@ -63,10 +63,14 @@ TEST_CASE("[Color] Constructor methods") {
 
 	const Color green_rgba = Color(0, 1, 0, 0.25);
 	const Color green_hsva = Color(0, 0, 0).from_hsv(120 / 360.0, 1, 1, 0.25);
+	const Color green_hsla = Color(0, 0, 0).from_hsl(120 / 360.0, 1, 0.5, 0.25);
 
 	CHECK_MESSAGE(
 			green_rgba.is_equal_approx(green_hsva),
 			"Creation with HSV notation should result in components approximately equal to the default constructor.");
+	CHECK_MESSAGE(
+			green_rgba.is_equal_approx(green_hsla),
+			"Creation with HSL notation should result in components approximately equal to the default constructor.");
 }
 
 TEST_CASE("[Color] Operators") {
@@ -109,6 +113,16 @@ TEST_CASE("[Color] Reading methods") {
 	CHECK_MESSAGE(
 			dark_blue.get_v() == doctest::Approx(0.5f),
 			"The returned HSV value should match the expected value.");
+
+	CHECK_MESSAGE(
+			dark_blue.get_hsl_h() == doctest::Approx(240.0f / 360.0f),
+			"The returned HSL hue should match the expected value.");
+	CHECK_MESSAGE(
+			dark_blue.get_hsl_s() == doctest::Approx(1.0f),
+			"The returned HSL saturation should match the expected value.");
+	CHECK_MESSAGE(
+			dark_blue.get_hsl_l() == doctest::Approx(0.25f),
+			"The returned HSL lightness should match the expected value.");
 }
 
 TEST_CASE("[Color] Conversion methods") {