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.

Page was generated with on Tue Feb 21 11:32:52 2006