Perlenspiel 3.3 | API

Color basics

Web browsers and the apps that run in them, including Perlenspiel, operate in 24-bit RGB colorspace.

A colorspace refers to the total number of visually unique colors that can be displayed by a device or application. This is also known as the color gamut of the device.

RGB stands for red, green and blue, the three primary colors which, when additively mixed in different proportions, can produce many (but not all) of the hues visible to the human eye.

24-bit refers to the amount of binary data available to encode each color, thereby determining the size of the colorspace.

[RGB color wheel] Colors available in 24-bit RGB. There are many.

The 24 bits used to specify colors in a web browser are all significant, and are allocated equally between the three primary colors: 8 bits for red, 8 for green, and 8 for blue.

An 8-bit binary number, commonly known as a “byte,” can express a range of 256 unique values. Because each color is defined by combining three independent 8-bit values (red, green and blue), the total number of unique colors available in Perlenspiel is (256 * 256 * 256), or 16,777,216 distinct hues.

Color expression

Several Perlenspiel commands let you specify the color of elements:

PS.color ( x, y, color )
PS.borderColor ( x, y, color )
PS.glyphColor ( x, y, color )
PS.gridColor ( color )
PS.gridShadow ( color )
PS.statusColor ( color )
PS.spriteSolidColor ( sprite, color )

The optional color parameter of these commands can be expressed using any of four different formats:

Explicit parameter format
RGB triplet format
Array format
Object format

Examples of how to use each format are provided below.

1. Explicit parameter format

Explicit parameter format uses a sequence of three comma-separated parameters, one for each primary color, provided in red, green, blue order.

Each parameter should be an integer in the range 0 to 255 inclusive. Values outside this range are clamped. Non-integral values are floored.

If a parameter is specified as PS.DEFAULT, the default value for the corresponding color component is used. If a parameter is PS.CURRENT, the current value of the corresponding color component is not changed.

Use the RGB color widget below to obtain the explicit red, green and blue values corresponding to various colors.

NOTE: If only one integer parameter is supplied for the color parameter, it is interpreted as an RGB triplet value (see below). If two integer parameters are supplied, they are interpreted as the red and green components of a color, with the missing blue component assumed to be PS.CURRENT.

// EXAMPLE
// Using explicit parameters
// to express color

// Change bead to autumn orange

PS.color( x, y, 255, 192, 64 );

// Change only the green component of a bead color

PS.color( x, y, PS.CURRENT, 192, PS.CURRENT );

// Change grid background to black

PS.gridColor( 0, 0, 0 );

2. RGB triplet format

An RGB triplet combines the red, green and blue components of a color into a single integer value, using this formula:

(red * 65536) + (green * 256) + blue

NOTE: The API provides a utility function, PS.makeRGB(), you can use to perform this calculation.

A triplet color should be an integer in the range 0 to 16777215 (0xFFFFFF) inclusive. Values outside this range are clamped. Non-integral values are floored.

If color is PS.DEFAULT, the default element color is used. If color is PS.CURRENT or not supplied, the color is not changed.

RGB triplets are especially easy to use if you understand hexadecimal (base 16) number notation. In hexadecimal (or “hex”) notation, the three primary color values are arranged in a integer value like this:

0xRRGGBB

The RR hex digits contain the red component value, GG the green and BB the blue. The 0x prefix is required to inform JavaScript that the value is being specified in hex format.

Use the RGB color widget below to obtain RGB triplet values for various colors.

Several commonly used RGB triplets are predefined as Perlenspiel constants.

// EXAMPLES
// Using an RGB triplet to express color

// Change bead color to autumn orange

PS.color( x, y, 0xFFC040 );

// Change bead color using a predefined API constant

PS.color( x, y, PS.COLOR_RED );

// Create and use a custom RGB triplet constant
// using PS.makeRGB()

var MY_COLOR_AUTUMN = PS.makeRGB( 255, 192, 48 );

PS.color( x, y, MY_COLOR_AUTUMN );

// Change grid background to black

PS.gridColor( 0x000000 );

3. Array format

You can specify the components of a color in the first three elements of an array, as follows:

array[0] = red component
array[1] = green component
array[2] = blue component

Each component should be an integer in the range 0 to 255 inclusive. Values outside this range are clamped. Non-integral values are floored.

If any component is PS.DEFAULT, the default value for that component is used. If a component is PS.CURRENT, the value of that component is not changed.

If the array contains fewer than three elements, or any of the first three elements in the array are undefined, the missing elements are interpreted as PS.CURRENT.

Any array elements beyond the first three are ignored.

// EXAMPLE
// Using arrays to express color

// Change bead to autumn orange

PS.color( x, y, [ 255, 192, 64 ] );

// Change grid background to black

PS.gridColor( [ 0, 0, 0 ] );

4. Object format

A color parameter can also be expressed as an object containing any of the following properties:

.r : integer, PS.CURRENT or PS.DEFAULT
.g : integer, PS.CURRENT or PS.DEFAULT
.b : integer, PS.CURRENT or PS.DEFAULT
.rgb: integer, PS.CURRENT or PS.DEFAULT

The .r, .g and .b properties represent the red, green and blue color components, respectively. They should be integers in the range 0 to 255 inclusive. Values outside this range are clamped. Non-integral values are floored.

If any component property is PS.DEFAULT, the default value for that component is used. If a component is PS.CURRENT or not supplied, that component is not changed.

If an .rgb property is supplied, it is interpreted as an RGB triplet (see above). It should be an integer in the range 0 to 16777215 (0xFFFFFF) inclusive. Values outside this range are clamped. Non-integral values are floored.

If .rgb is PS.DEFAULT, the default element color is used. If .rgb is PS.CURRENT, the color is not changed.

An .rgb property takes priority over any .r, .g or .b properties. If a valid .rgb property is supplied in a color object, its color is assigned to the associated element, and the values of any .r, .g or .b properties are ignored.

// EXAMPLE
// Using object properties to express color

// Change bead to autumn orange (two ways)

PS.color( x, y, { r : 255, g : 192, b : 64 } );
PS.color( x, y, { rgb : 0xFFC040 } );

// Change grid background to black (two ways)

PS.gridColor( { r : 0, g : 0, b : 0 } );
PS.gridColor( { rgb : 0x000000 } );

RGB color widget

Use this handy widget from JSColor.com to experiment with RGB color values.

Click on the RBG Triplet box below to begin.

RGB Triplet: (JavaScript hexadecimal format)

R, G, B: R: G: B: Decimal Hex

The JSColor widget is Copyright © 2008– Jan Odvárko – East Desire, and is released for use by open-source projects under the GNU GPL v3 (General Public License, version 3). Refer to the Perlenspiel 3.3 Devkit for complete documentation of the GNU GPL v3, together with additional usage conditions and warranty information.