flash/index
1
0
Fork 0
Code Issues Pull requests Packages Projects Releases Wiki Activity

Added documentation comments to the Colour classes.

Browse source
This commit is contained in:
flash 2023-11-09 13:36:45 +00:00
parent 41ac00e3e0
commit 96700f7044
6 changed files with 194 additions and 6 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

2
VERSION
View file

@ -1 +1 @@
0.2311.91312
0.2311.91336

94
src/Colour/Colour.php
View file

@ -1,21 +1,57 @@
<?php
// Colour.php
// Created: 2023-01-02
// Updated: 2023-09-15
// Updated: 2023-11-09
namespace Index\Colour;
use Stringable;
use Index\XNumber;
/**
* Abstract class for representing colours.
*/
abstract class Colour implements Stringable {
/**
* Retrieves the Red RGB byte.
*
* @return int A number ranging from 0 to 255.
*/
public abstract function getRed(): int;
/**
* Retrieves the Green RGB byte.
*
* @return int A number ranging from 0 to 255.
*/
public abstract function getGreen(): int;
/**
* Retrieves the Blue RGB byte.
*
* @return int A number ranging from 0 to 255.
*/
public abstract function getBlue(): int;
/**
* Retrieves the alpha component.
*
* @return float A number ranging from 0.0 to 1.0.
*/
public abstract function getAlpha(): float;
/**
* Whether this colour should be ignored and another should be used instead.
*
* @return bool true if this colour should be ignored.
*/
public abstract function shouldInherit(): bool;
/**
* Returns this colour in a format CSS understands.
*
* @return string CSS compatible colour.
*/
public abstract function __toString(): string;
private const READABILITY_THRESHOLD = 186.0;
@ -25,26 +61,57 @@ abstract class Colour implements Stringable {
// luminance shit might need further review
/**
* Calculates the luminance value of this colour.
*
* @return float Luminance value for this colour.
*/
public function getLuminance(): float {
return self::LUMINANCE_WEIGHT_RED * $this->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;
}

32
src/Colour/ColourHSL.php
View file

@ -1,10 +1,13 @@
<?php
// ColourHSL.php
// Created: 2023-01-02
// Updated: 2023-01-02
// Updated: 2023-11-09
namespace Index\Colour;
/**
* Represents a colour using Hue, Saturation and Lightness.
*/
class ColourHSL extends Colour {
private float $hue;
private float $saturation;
@ -15,6 +18,12 @@ class ColourHSL extends Colour {
private int $green;
private int $blue;
/**
* @param float $hue Hue property.
* @param float $saturation Saturation property.
* @param float $lightness Lightness property.
* @param float $alpha Alpha property.
*/
public function __construct(float $hue, float $saturation, float $lightness, float $alpha = 1.0) {
$this->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;

30
src/Colour/ColourNamed.php
View file

@ -1,10 +1,13 @@
<?php
// ColourNamed.php
// Created: 2023-01-02
// Updated: 2023-01-02
// Updated: 2023-11-09
namespace Index\Colour;
/**
* Represents a named CSS colour.
*/
class ColourNamed extends Colour {
private string $name;
private int $red = 0;
@ -12,6 +15,9 @@ class ColourNamed extends Colour {
private int $blue = 0;
private bool $transparent;
/**
* @param string $name CSS colour name.
*/
public function __construct(string $name) {
$this->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<string, int> */
private const COLOURS = [
// CSS Level 1
'black' => 0x000000,

7
src/Colour/ColourNull.php
View file

@ -1,10 +1,15 @@
<?php
// ColourNull.php
// Created: 2023-01-02
// Updated: 2023-01-02
// Updated: 2023-11-09
namespace Index\Colour;
/**
* Represents an empty colour.
*
* If possible, use Colour::empty() to get the global instance of this class.
*/
class ColourNull extends Colour {
public function getRed(): int {
return 0;

35
src/Colour/ColourRGB.php
View file

@ -1,16 +1,25 @@
<?php
// ColourRGB.php
// Created: 2023-01-02
// Updated: 2023-01-02
// Updated: 2023-11-09
namespace Index\Colour;
/**
* Represents an RGB colour.
*/
class ColourRGB extends Colour {
private int $red;
private int $green;
private int $blue;
private float $alpha;
/**
* @param int $red Red property.
* @param int $green Green property.
* @param int $blue Blue property.
* @param float $alpha Alpha property.
*/
public function __construct(int $red, int $green, int $blue, float $alpha = 1.0) {
$this->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;