Colorspace.js (system script)

From Spheriki

The system script colorspace.js provides an alternate color object to replace Sphere's standard color object. The alternate color object supports these color models:

CMY (cyan, magenta, yellow) - same as the famous CMYK model (the K is irrelevant for screen output).
HSI (hue, saturation, intensity) - also known as HSL (hue, saturation, luminance).
RGB (red, green, blue) - which is the model used by Sphere's standard color object.

1 Usage
2 Variables and functions of colorspace.js
3 Examples
4 Notes
5 External links

[edit]

Usage

RequireSystemScript("colorspace.js");

[edit]

Variables and functions of colorspace.js

Object constructor Color(red, green, blue [, alpha])
- Parameters are the same as the parameters of CreateColor() (which creates a standard color object).
- Properties of objects of Color type:
  - red, green, blue - color components according to the RGB model (values from 0 to 255).
  - cyan, magenta, yellow - color components according to the CMY model (values from 0 to 255).
  - hue, saturation, intensity - color components according to the HSI model (values from 0 to 1, except 'hue', which ranges from 0 to 2Pi).
  - alpha - alpha value of the color.
- Methods of objects of Color type:
  - clone() - returns a copy of the object.
  - toString() - returns a string containing the properties of the object.

[edit]

Examples

To define the color red using the CMY model, type:

 RequireSystemScript("colorspace.js");
 
 // The color created by the constructor is white - which won't matter in our case.
 var MyColor     = new Color(255, 255, 255);
 
 // The following lines set the CMY values. The white color is "overwritten".
 MyColor.cyan    = 0;
 MyColor.magenta = 255;
 MyColor.yellow  = 255;</pre>

As a result the object properties holding the RGB values will automatically be set to red=255, green=0, blue=0. The properties which are HSI components will be set to hue=0, saturation=1, intensity=1/3.

You can also use the HSL model to define red:

 RequireSystemScript("colorspace.js");
 
 var MyColor        = new Color(255, 255, 255);
 
 MyColor.intensity  = 1/3;
 MyColor.saturation = 1;
 MyColor.hue        = 0;

The color will be red, even though the RGB values won't be absolutely exact due to rounding errors (R will be around 245.9 for example).

The next example will draw a color spectrum using the HSI model:

 RequireSystemScript("colorspace.js");
 
 var scrW     = GetScreenWidth();
 var scrH     = GetScreenHeight();
   
 var c        = new Color(255, 255, 255);
 c.intensity  = 1/3;
 c.saturation = 1;
 
 for (var y=0; y<scrH; y++) {
   c.hue = 2*Math.PI/scrH * y;
     Line(0, y, scrW-1, y, CreateColor(c.red, c.green, c.blue));
 }
 
 FlipScreen();
 GetKey();

[edit]

Notes

I'm not sure wether it's always necessary, but I recommend never to omit the 'red', 'green', 'blue' parameters of the Color() constructor.
If the value of a color component is out of range, it is automatically set to the minimal/maximal value of that component.
The color object of colorspace.js can't be used as a parameter of Sphere functions that require a standard color object. In this case you'll have to convert the alternate color object to a standard one, i.e.:

 MyColor     = new Color(255, 127, 0);
 SphereColor = CreateColor(MyColor.red, MyColor.green, MyColor.blue, MyColor.alpha);
 Rectangle(0, 0, 100, 100, SphereColor);

Using the HSI system can be tricky sometimes. Changing the hue of a white color object for example won't do anything because its saturation is 0. This is why it can be relevant in which order you set hue, saturation, intensity.

[edit]