[Proposal] New ColorHelper API

[Avid29]

Approved from Discussion

https://discord.com/channels/372137812037730304/1430217634204356608

Problem Statement

The current ColorHelper API is unintuitive for an object-oriented environment and poorly utilizes the HsvColor and HslColor.

Overview

Proposed ColorHelper API

public static class ColorHelper
{
  public static Color ParseColor(string colorString);
}

public static class ColorExtensions
{
  public static int ToInt(this Color color);  

  public static HslColor ToHsl(this Color color);

  public static HsvColor ToHsv(this Color color);
}

public struct HslColor
{
  // The properties will apply clamps on set to restrict the values to a valid range
  public double H { readonly get; set;}
  public double S { readonly get; set;}
  public double L { readonly get; set;}
  public double A { readonly get; set;}

  public static HslColor Create(double hue, double saturation, double lightness, double alpha = 1);

  public Color ToColor();

  public string ToString(); // hsv(hue, sat, lightness)

  // Cast operators
  public static implicit operator Color(HslColor color);
  public static explicit operator HslColor(Color color);
  public static explicit operator HslColor(HsvColor color);
}

public struct HsvColor
{
  // The properties will apply clamps on set to restrict the values to a valid range
  public double H { readonly get; set;}
  public double S { readonly get; set;}
  public double V { readonly get; set;}
  public double A { readonly get; set;}

  public static HsvColor Create(double hue, double saturation, double value, double alpha = 1);

  public Color ToColor();

  public string ToString(); // hsv(hue, sat, value)

  // Cast operators
  public static implicit operator Color(HsvColor color);
  public static explicit operator HsvColor(Color color);
  public static explicit operator HsvColor(HslColor color);
}

Breaking Changes

Due to its nature as an API change, this proposal would introduce breaking changes. However, each of these changes can be easily remedied by a simple change in function call or by utilizing a casting operation.

Method changes

• ToHex(this Color color) - Redundant with ToString()
• ToColor(this string colorString) - Replaced with ColorHelper.ParseColor(string colorString)
• ColorHelper.FromHsl(double hue, ...) - Replaced with (Color)HslColor.Create(double hue, ...) (NOTE: The cast could be done implicitly)
• ColorHelper.FromHsv(double hue, ...) - Replaced with (Color)HsvColor.Create(double hue, ...) (NOTE: The cast could be done implicitly)

Struct changes

All members of the HslColor and HsvColor structs were public fields with no constraints in value.
These have been replaced with properties that have been restricted to valid ranges for the property. If a developer had been relying on invalid ranges or behavior related to the members being fields, this will no longer work.

These changes also mean that the struct must be given a value before being used.

For example, the following code would be valid before but would now say that hsl is not defined on the second line.

HslColor hsl;
hsl.H = 240;