helix.color
Module with classes and functions for working with color values.
There are structs for representation Red Green Blue color (Color3),
RGB+Alpha color (Color4) and Hue Saturation Luminance triple (HSL).
All components of those structs are float values, not integers.
Rationale is that under different circumstances it is necessary to
work with different standards of integer representation. Frequently
one byte-wise integer layout needed for one API and another for second.
One can require XRGB order, another BGRA. So it's better to operate with
floats and to convert them to integer just when it is necessary.
Normal range for float components' values is [0; 1]. Normal range for integer
values is [0; 255] for Color3 and Color4, and [0; 240] for HSL. Each struct
has several methods to convert native float representation to integer and
back.
Authors:
Victor Nakoryakov, nail-mail[at]mail.ru
- enum
ByteOrder
;
- Defines bytes orders for float to uint conversions.
-
XRGB
XBGR
RGBX
BGRX
ARGB
ABGR
RGBA
BGRA
- template
Color
(float_t)
- Wrapper template to provide possibility to use different float types
in implemented structs and routines.
- struct
HSL
;
- Hue, Saturation, Luminance triple.
- float_t
h
;
- Hue.
- float_t
s
;
- Saturation.
- float_t
l
;
- Luminance.
- HSL
opCall
(float_t h, float_t s, float_t l);
- Method to construct struct in C-like syntax.
Examples:
HSL hsl = HSL(0.1, 0.2, 0.3);
- void
set
(float_t h, float_t s, float_t l);
- Sets components to values of passed arguments.
- uint
hi
();
uint
si
();
uint
li
();
- Returns:
Integer value of corresponding component in range [0; 240].
- void
hi
(uint h);
void
si
(uint s);
void
li
(uint l);
- Set components to values of passed arguments. It is assumed that values of
arguments are in range [0; 240].
- bool
opEquals
(HSL hsl);
- Component-wise equality operator.
- Color3
toColor3
();
- Returns:
Color3 representing the same color as this triple.
- bool
equal
(HSL a, HSL b, int relprec = defrelprec, int absprec = defabsprec);
- Approximate equality function.
Params:
- struct
Color3
;
- Red, Green, Blue triple.
- float_t
r
;
- Red.
- float_t
g
;
- Green.
- float_t
b
;
- Blue.
- Color3
nan
;
- Color3 with all components seted to NaN.
- Color3
opCall
(float_t r, float_t g, float_t b);
- Method to construct color in C-like syntax.
Examples:
Color3 c = Color3(0.1, 0.2, 0.3);
- Color3
opCall
(uint src, ByteOrder order);
- Method to construct color in C-like syntax from value specified
in uint parameter.
Params:
uint src |
uint to extract value from. |
ByteOrder order |
specifies byte-wise order in src. |
Examples:
Color3 c = Color3(0x00FFEEDD, ByteOrder.XRGB);
- void
set
(float_t r, float_t g, float_t b);
- Sets components to values of passed arguments.
- void
set
(uint src, ByteOrder order = ByteOrder.XRGB);
- Sets components according to color packed in src uint argument.
Params:
uint src |
uint to extract value from. |
ByteOrder order |
specifies byte-wise component layout in src. |
- bool
isnormal
();
- Returns:
Whether all components are normalized numbers.
- int
ri
();
int
gi
();
int
bi
();
- Returns:
Integer value of corresponding component.
Float value 0 is mapped to integer 0. Float value 1 is mapped to
integer 255.
- void
ri
(int r);
void
gi
(int g);
void
bi
(int b);
- Sets corresponding component value to mapped value of passed argument.
Integer value 0 is mapped to float 0. Integer value 255 is mapped to
float 1.
- uint
toUint
(ByteOrder order);
- Returns:
This color packed to uint.
Params:
ByteOrder order |
specifies byte-wise component layout in src. |
Throws:
AssertError if any component is out of range [0; 1] and module was
compiled with asserts.
- HSL
toHSL
();
- Returns:
HSL triple representing same color as this.
- float_t*
ptr
();
- Returns:
float_t pointer to r component of this color. It's like a ptr method for arrays.
- bool
opEquals
(Color3 v);
Color3
opNeg
();
Color3
opAdd
(Color3 v);
void
opAddAssign
(Color3 v);
Color3
opSub
(Color3 v);
void
opSubAssign
(Color3 v);
Color3
opMul
(real k);
void
opMulAssign
(real k);
Color3
opMulr
(real k);
Color3
opDiv
(real k);
void
opDivAssign
(real k);
- Standard operators that have meaning exactly the same as for Vector3, i.e. do
component-wise operations.
Note that division operators do no cheks of value of k, so in case of division
by 0 result vector will have infinity components. You can check this with isnormal()
method.
- void
clampBelow
(float_t inf = 0);
- Sets all components less than inf to inf.
- Color3
clampedBelow
(float_t inf = 0);
- Returns:
Copy of this color with all components less than inf seted to inf.
- void
clampAbove
(float_t sup = 1);
- Sets all components greater than sup to sup.
- Color3
clampedAbove
(float_t sup = 1);
- Returns:
Copy of this color with all components greater than sup seted to sup.
- void
clamp
(float_t inf = 0, float_t sup = 1);
- Sets all components less than inf to inf and
all components greater than sup to sup.
- Color3
clamped
(float_t inf = 0, float_t sup = 1);
- Returns:
Copy of this color with all components less than inf seted to inf
and all components greater than sup seted to sup.
- Color3f
toColor3f
();
- Returns:
Copy of this color with float type components.
- Color3d
toColor3d
();
- Returns:
Copy of this color with double type components.
- Color3r
toColor3r
();
- Returns:
Copy of this color with real type components.
- Color4
rgb0
();
Color4
rgb1
();
- Routines known as swizzling.
Returns:
New color constructed from this one and having component values
that correspond to method name.
- bool
equal
(Color3 a, Color3 b, int relprec = defrelprec, int absprec = defabsprec);
- Approximate equality function.
Params:
- alias
lerp
;
- Introduces linear interpolation function for Color3.
- struct
Color4
;
- Red, Green, Blue triple with additional Alpha component.
- float_t
r
;
- Red.
- float_t
g
;
- Green.
- float_t
b
;
- Blue.
- float_t
a
;
- Alpha.
- Color4
nan
;
- Color4 with all components seted to NaN.
- Color4
opCall
(float_t r, float_t g, float_t b, float_t a);
Color4
opCall
(Color3 rgb, float_t a = 1);
- Methods to construct color in C-like syntax.
Examples:
Color4 c1 = Color4(0.1, 0.2, 0.3, 1);
Color3 rgb = Color3(0, 0, 0.5);
Color4 c2 = Color4(rgb, 1);
- Color4
opCall
(uint src, ByteOrder order);
- Method to construct color in C-like syntax from value specified
in uint parameter.
Params:
uint src |
uint to extract value from. |
ByteOrder order |
specifies byte-wise order in src. |
Examples:
Color4 c = Color4(0x99FFEEDD, ByteOrder.ARGB);
- void
set
(float_t r, float_t g, float_t b, float_t a);
void
set
(Color3 rgb, float_t a);
- Set components to values of passed arguments.
- void
set
(uint src, ByteOrder order = ByteOrder.ARGB);
- Sets components according to color packed in src uint argument.
Params:
uint src |
uint to extract value from. |
ByteOrder order |
specifies byte-wise layout in src. |
- bool
isnormal
();
- Returns:
Whether all components are normalized numbers.
- int
ri
();
int
gi
();
int
bi
();
int
ai
();
- Returns:
Integer value of corresponding component.
Float value 0 is mapped to integer 0. Float value 1 is mapped to
integer 255.
- void
ri
(int r);
void
gi
(int g);
void
bi
(int b);
void
ai
(int a);
- Sets corresponding component value to mapped value of passed argument.
Integer value 0 is mapped to float 0. Integer value 255 is mapped to
float 1.
- uint
toUint
(ByteOrder order);
- Returns:
This color packed to uint.
Params:
ByteOrder order |
specifies byte-wise component layout in src. |
Throws:
AssertError if any component is out of range [0; 1] and
module was compiled with asserts.
- HSL
toHSL
();
- Returns:
HSL triple representing same color as this.
Alpha value is ignored.
- float_t*
ptr
();
- Returns:
float_t pointer to r component of this color. It's like a ptr method for arrays.
- bool
opEquals
(Color4 v);
Color4
opNeg
();
Color4
opAdd
(Color4 v);
void
opAddAssign
(Color4 v);
Color4
opSub
(Color4 v);
void
opSubAssign
(Color4 v);
Color4
opMul
(real k);
void
opMulAssign
(real k);
Color4
opMulr
(real k);
Color4
opDiv
(real k);
void
opDivAssign
(real k);
- Standard operators that have meaning exactly the same as for Vector4, i.e. do
component-wise operations. So alpha component equaly in rights takes place in all
operations, to affect just RGB part use swizzling operations.
Note that division operators do no cheks of value of k, so in case of division
by 0 result vector will have infinity components. You can check this with isnormal()
method.
- void
clampBelow
(float_t inf = 0);
- Sets all components less than inf to inf.
- Color4
clampedBelow
(float_t inf = 0);
- Returns:
Copy of this color with all components less than inf seted to inf.
- void
clampAbove
(float_t sup = 1);
- Sets all components greater than sup to sup.
- Color4
clampedAbove
(float_t sup = 1);
- Returns:
Copy of this color with all components greater than sup seted to sup.
- void
clamp
(float_t inf = 0, float_t sup = 1);
- Sets all components less than inf to inf and
all components greater than sup to sup.
- Color4
clamped
(float_t inf = 0, float_t sup = 1);
- Returns:
Copy of this color with all components less than inf seted to inf
and all components greater than sup seted to sup.
- Color4f
toColor4f
();
- Returns:
Copy of this color with float type components.
- Color4d
toColor4d
();
- Returns:
Copy of this color with double type components.
- Color4r
toColor4r
();
- Returns:
Copy of this color with real type components.
- Color3
rgb
();
- Routine known as swizzling.
Returns:
Color3 representing RGB part of this color.
- void
rgb
(Color3
rgb
);
- Routine known as swizzling.
Sets RGB part components to values of passed rgb argument's components.
- bool
equal
(Color4 a, Color4 b, int relprec = defrelprec, int absprec = defabsprec);
- Approximate equality function.
Params:
- alias
lerp
;
- Introduces linear interpolation function for Color4.
|