diff --git a/VERSION b/VERSION index 5a11be7..c35fa3f 100644 --- a/VERSION +++ b/VERSION @@ -1 +1 @@ -0.2311.91312 +0.2311.91336 diff --git a/src/Colour/Colour.php b/src/Colour/Colour.php index c031a7f..37a78a8 100644 --- a/src/Colour/Colour.php +++ b/src/Colour/Colour.php @@ -1,21 +1,57 @@ getRed() + self::LUMINANCE_WEIGHT_GREEN * $this->getGreen() + self::LUMINANCE_WEIGHT_BLUE * $this->getBlue(); } + /** + * Checks whether this colour is on the brighter side of things. + * + * @return bool true if this colour would not be very legible on a light background. + */ public function isLight(): bool { return $this->getLuminance() > self::READABILITY_THRESHOLD; } + /** + * Checks whether this colour is on the darker side of things. + * + * @return bool true if this colour would not be very legible on a dark background. + */ public function isDark(): bool { return $this->getLuminance() <= self::READABILITY_THRESHOLD; } private static ColourNull $none; + /** + * Gets an empty colour. + * + * @return Colour A global instance of ColourNull. + */ public static function none(): Colour { return self::$none; } + /** + * Mixes two colours. + * 0.0 -> Entirely $colour1 + * 0.5 -> Midpoint between $colour1 and $colour2 + * 1.0 -> Entirely $colour2 + * + * @param Colour $colour1 Starting colour. + * @param Colour $colour2 Ending colour. + * @param float $weight Weight of $colour2. + * @return Colour Mixed colour. + */ public static function mix(Colour $colour1, Colour $colour2, float $weight): Colour { $weight = min(1, max(0, $weight)); @@ -65,18 +132,42 @@ abstract class Colour implements Stringable { private const MSZ_INHERIT = 0x40000000; + /** + * Creates a Colour object from raw Misuzu format. + * + * If bit 31 is set the global instance of ColourNull will always be returned, + * otherwise an instance of ColourRGB will be created using the fromRawRGB method (top 8 bits ignored). + * + * @param int $raw Raw RGB colour in Misuzu format. + * @return Colour Colour instance representing the Misuzu colour. + */ public static function fromMisuzu(int $raw): Colour { if($raw & self::MSZ_INHERIT) return self::$none; return ColourRGB::fromRawRGB($raw); } + /** + * Converts a Colour object to raw Misuzu format. + * + * If shouldInherit is true, an integer with only bit 31 will be returned, + * otherwise a raw RGB value will be returned. + * + * @param Colour $colour Colour to be converted to raw Misuzu format. + * @return int Raw Misuzu format colour. + */ public static function toMisuzu(Colour $colour): int { if($colour->shouldInherit()) return self::MSZ_INHERIT; return ($colour->getRed() << 16) | ($colour->getGreen() << 8) | $colour->getBlue(); } + /** + * Attempts to parse a CSS format colour. + * + * @param ?string $value CSS format colour. + * @return Colour Parsed CSS colour. + */ public static function parse(?string $value): Colour { if($value === null) return self::$none; @@ -205,6 +296,7 @@ abstract class Colour implements Stringable { return self::$none; } + /** @internal */ public static function init(): void { self::$none = new ColourNull; } diff --git a/src/Colour/ColourHSL.php b/src/Colour/ColourHSL.php index abd34b6..b3f5bdf 100644 --- a/src/Colour/ColourHSL.php +++ b/src/Colour/ColourHSL.php @@ -1,10 +1,13 @@ hue = $hue; $this->saturation = max(0.0, min(1.0, $saturation)); @@ -64,14 +73,29 @@ class ColourHSL extends Colour { return $this->blue; } + /** + * Retrieves the Hue component. + * + * @return float Hue rotation value. + */ public function getHue(): float { return $this->hue; } + /** + * Retrieves the Saturation component. + * + * @return float Saturation value. + */ public function getSaturation(): float { return $this->saturation; } + /** + * Retrieves the lightness component. + * + * @return float Lightness value. + */ public function getLightness(): float { return $this->lightness; } @@ -97,6 +121,12 @@ class ColourHSL extends Colour { return sprintf('hsl(%sdeg, %s%%, %s%%)', $hue, $sat, $lig); } + /** + * Converts any other colour to a ColourHSL. + * + * @param Colour $colour Original colour. + * @return ColourHSL Converted colour. + */ public static function convert(Colour $colour): ColourHSL { if($colour instanceof ColourHSL) return $colour; diff --git a/src/Colour/ColourNamed.php b/src/Colour/ColourNamed.php index 221689f..8efc124 100644 --- a/src/Colour/ColourNamed.php +++ b/src/Colour/ColourNamed.php @@ -1,10 +1,13 @@ name = strtolower($name); @@ -28,10 +34,20 @@ class ColourNamed extends Colour { } } + /** + * Retrieves the CSS name of this colour. + * + * @return string CSS name. + */ public function getName(): string { return $this->name; } + /** + * Retrieves whether this CSS colour is transparent. + * + * @return bool true if the colour is transparent. + */ public function isTransparent(): bool { return $this->transparent; } @@ -60,14 +76,26 @@ class ColourNamed extends Colour { return $this->name; } + /** + * Returns all supported CSS colour names. + * + * @return string[] All supported CSS colour names. + */ public static function getNames(): array { return array_keys(self::COLOURS); } + /** + * Checks whether a CSS colour name is supported. + * + * @param string $name CSS colour name. + * @return bool true if the colour name is supported. + */ public static function isValidName(string $name): bool { return array_key_exists($name, self::COLOURS); } + /** @var array */ private const COLOURS = [ // CSS Level 1 'black' => 0x000000, diff --git a/src/Colour/ColourNull.php b/src/Colour/ColourNull.php index 6e80a95..4c10de6 100644 --- a/src/Colour/ColourNull.php +++ b/src/Colour/ColourNull.php @@ -1,10 +1,15 @@ red = max(0, min(255, $red)); $this->green = max(0, min(255, $green)); @@ -46,6 +55,12 @@ class ColourRGB extends Colour { return sprintf('#%02x%02x%02x', $this->red, $this->green, $this->blue); } + /** + * Create a ColourRGB instance from a raw RGB value. + * + * @param int $raw A raw RGB colour in 0xRRGGBB format. + * @return ColourRGB An instance of ColourRGB. + */ public static function fromRawRGB(int $raw): ColourRGB { return new ColourRGB( (($raw >> 16) & 0xFF), @@ -55,6 +70,12 @@ class ColourRGB extends Colour { ); } + /** + * Create a ColourRGB instance from a raw ARGB value. + * + * @param int $raw A raw ARGB colour in 0xAARRGGBB format. + * @return ColourRGB An instance of ColourRGB. + */ public static function fromRawARGB(int $raw): ColourRGB { return new ColourRGB( (($raw >> 16) & 0xFF), @@ -64,6 +85,12 @@ class ColourRGB extends Colour { ); } + /** + * Create a ColourRGB instance from a raw RGBA value. + * + * @param int $raw A raw RGBA colour in 0xRRGGBBAA format. + * @return ColourRGB An instance of ColourRGB. + */ public static function fromRawRGBA(int $raw): ColourRGB { return new ColourRGB( (($raw >> 24) & 0xFF), @@ -73,6 +100,12 @@ class ColourRGB extends Colour { ); } + /** + * Converts any other colour to a ColourRGB. + * + * @param Colour $colour Original colour. + * @return ColourRGB Converted colour. + */ public static function convert(Colour $colour): ColourRGB { if($colour instanceof ColourRGB) return $colour;