Learning 06: Color expression

Many of the commands you’ll use to make Perlenspiel games involve changing the color of elements.

Before studying these commands, it’s important to understand how color works in Perlenspiel, and how to correctly specify the colors you want to use.

Perlenspiel operates in 24-bit RGB colorspace.

RGB means that colors are defined using three values, one for each of the primary colors: red, green and blue. By mixing these colors in different proportions, a wide range of visible hues can be represented, as the diagram below demonstrates.

[RGB color chart]

24-bit means that eight binary bits (one byte) are used to specify each of the three primary colors. A byte can store 256 unique values, usually expressed as a whole number or integer between 0 and 255 inclusive.

Because three 8-bit values are used to define each color, Perlenspiel projects can employ (256 * 256 * 256) or 16,777,216 distinct hues.

Color commands

Eight Perlenspiel commands let you control the color of elements:

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

Which format you use depends on the needs of your project and personal preference. Examples of using each format are provided below.

 

Explicit parameter format

The three primary color values can be expressed as an explicit sequence of comma-separated parameters, provided in red, green, blue order.

Each value should be an integer in the range 0 to 255 inclusive. Values outside this range are clamped: if you specify a value less than zero, it will be automatically raised to zero, and if you specify a value greater than 255, it will be automatically reduced to 255. Non-integral values (such as 55.3) are floored: any digits to the left of the decimal point are changed to zero.

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

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

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

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

// Change grid background to black

PS.gridColor( 0, 0, 0 );

// Change bead at x, y to autumn orange

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

 

RGB triplet format

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

(red * 65,536) + (green * 256) + blue

An RGB triplet should be an integer in the range 0 to 16,777,215 (0xFFFFFF) inclusive. Values outside this range are clamped. Non-integral values are floored.

If a triplet is specified as PS.DEFAULT, the default element color is used. If a value is PS.CURRENT or not supplied, the color is not changed.

RGB triplets are especially handy if you understand hexadecimal (base 16) number notation. In hex, the colors in a triplet value are arranged according to this pattern:

0xRRGGBB

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

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

Several commonly used RGB triplets are predefined as Perlenspiel constants:

These constants can be used anywhere an RGB triplet is accepted or returned.

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

// Change grid background to black

PS.gridColor( 0x000000 );

// Change bead color to autumn orange

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

// Change bead color using a predefined constant

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

 

Array format

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

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

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

If any value is PS.DEFAULT, the default value for that component is used. If a value is PS.CURRENT, 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 grid background to black

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

// Change bead to autumn orange

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

 

RGB object format

A color can also be expressed as a JavaScript 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).

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 an RGB 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 grid background to black (two ways)

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

// Change bead to autumn orange (two ways)

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

 

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:  

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.

 

Terms to know

Next: Grid size, color and shadow