API | Grid

These commands determine the dimensions, background and shadow color of the grid, and the selection of grid planes.

 

PS.gridSize ( width, height )

PS.gridSize() creates a new grid with the specified dimensions, and/or returns the current dimensions of the grid.

Parameters:

  1. (optional) width : integer, PS.CURRENT or PS.DEFAULT
  2. (optional) height : integer, PS.CURRENT or PS.DEFAULT

Returns: object or PS.ERROR

Default: { width : 8, height : 8 }

The optional width and height parameters indicate the number of columns and rows in the grid, respectively. Allowable values are 1 to 32 inclusive. Values outside this range are clamped.

Specifying PS.CURRENT in either parameter causes that dimension of the grid to maintain its current value. Specifying PS.DEFAULT changes that dimension to its default value (8).

All attributes of any previously established grid (including all planes above 0) are deleted. The color and faders of the grid and status line are reset to their default values. The default grid plane is reset to zero (0).

The beads on the new grid are reset to all default values:

If no parameters are supplied to PS.gridSize(), the current grid dimensions are returned without affecting the grid.

Usage

PS.gridSize() is normally called in response to the PS.init() engine event, to establish the initial dimensions of the grid. However, it can be called anytime during the course of play.

Return value

PS.gridSize() returns an object containing the following properties:

These properties indicate the current width and height of the grid.

PS.ERROR is returned if an error occurs.

// EXAMPLE:
// Using PS.gridSize() inside PS.init()

PS.init = function ( options ) {
 // set up a 16 x 16 grid

 PS.gridSize( 16, 16 );
};

 

PS.gridColor ( color )

PS.gridColor() changes or inspects the background color of the grid.

Parameters:

  1. (optional) color : color expression, PS.CURRENT or PS.DEFAULT

Returns : integer or PS.ERROR

Default : PS.COLOR_WHITE

The optional color parameter can be supplied in any of the four Perlenspiel color expression formats.

If color is PS.DEFAULT, the default color (PS.COLOR_WHITE) is applied. If color is PS.CURRENT or not supplied, the color is not changed.

Return value

PS.gridColor() returns a RGB triplet integer indicating the current grid color.

PS.ERROR is returned if an error occurs.

// EXAMPLE:
// Using PS.gridSize() and PS.gridColor()

PS.init = function ( system, options ) {
 // set up a 10 x 10 grid

 PS.gridSize( 10, 10 );

 // set background color to blue

 PS.gridColor( PS.COLOR_BLUE );
};

 

PS.gridFade ( rate, options )

PS.gridFade() changes or inspects the color fade effect of the grid.

Parameters:

  1. (optional) rate : integer, PS.CURRENT or PS.DEFAULT
  2. (optional) options : object, PS.CURRENT or PS.DEFAULT

Returns : object or PS.ERROR

Default : { rate : 0, rgb : null, onEnd : null, params : null }

By default, the PS.gridColor() command changes the color of the grid instantly. You can make the color fade smoothly from one hue to the next by using PS.gridFade().

Once a fade effect is assigned to the grid with PS.gridFade(), all subsequent calls to PS.gridColor() will smoothly fade from the current color (or an optionally specified color) to the new color.

The optional rate parameter(s) specifies the rate of the fade effect in 60ths of a second.

If rate is less than 1 or PS.DEFAULT, the grid fade effect is disabled. If rate is PS.CURRENT or not supplied, the grid fade rate is not changed.

The optional options parameter specifies additional fade options. It should be an object with one or more of the following properties:

.rgb

The optional .rgb property specifies the initial color of the fade effect. It should be an RGB triplet integer in the range 0-0xFFFFFF inclusive. Values outside this range are clamped. Non-integral values are floored.

If .rgb is PS.DEFAULT, null or not supplied, the current grid color is used as the starting color. If .rgb is PS.CURRENT, the currently assigned start color is not changed.

.onStep

The optional .onStep property specifies a function that will be called immediately before each step of the color fade is executed. Three arguments are passed to this function in the following order:

  1. An integer indicating the total number of steps in the fade
  2. A zero-based integer indicating the current fade step
  3. An RGB triplet integer indicating the current step color

Any values specified by the .params property (see below) are passed to the function as additional arguments, following the three noted above.

The value returned by the .onStep function determines how the fade effect will proceed.

If .onStep is PS.DEFAULT, null, or not supplied, the default behavior (no function call) is used. If .onStep is PS.CURRENT, the currently assigned function is not changed.

.onEnd

The optional .onEnd property specifies a function that will be called when the fade effect is completed. Any values specified by the .params property (see below) are passed to this function as arguments.

If .onEnd is PS.DEFAULT, null, or not supplied, the default behavior (no function call) is used. If .onEnd is PS.CURRENT, the currently assigned function is not changed.

.params

The optional .params property specifies the additional parameters that will be passed to the functions specified by the .onStep and/or .onEnd properties. It should be an array containing any number of elements.

If .params is PS.DEFAULT, null, or not supplied, no additional parameters are passed to the .onStep and/or .onEnd functions. If .params is PS.CURRENT, the currently assigned parameters are not changed.

If options is PS.CURRENT or not supplied, the currently assigned fade settings are not changed.

If options is PS.DEFAULT, all fade settings (except for the fade rate) are reset to their default values.

Return value

PS.gridFade() returns an object with the following properties:

The .rate property indicates the current grid fade rate, zero (0) if disabled.

The .rgb property is an RGB triplet integer indicating the start color currently assigned to the fade, null if none.

The .onStep property indicates the .onStep function currently assigned to the fade, null if none.

The .onEnd property indicates the .onEnd function currently assigned to the fade, null if none.

The .params property is an array containing the additional parameters currently assigned to the .onStep and .onEnd functions, null if none.

PS.ERROR is returned if an error occurs.

// EXAMPLE:
// Fade grid color to a random color
// when the mouse is clicked

PS.init = function ( system, options ) {
 // set up a 10 x 10 grid

 PS.gridSize( 10, 10 );

 // set 2-sec fade rate and onEnd function

 PS.gridFade( 120, { onEnd : gridOnEnd } );
};

// onEnd function for grid fading

function gridOnEnd ( data ) {
 PS.statusText( "Grid fade complete" );
};

PS.touch = function ( x, y, data, options ) {
 // Erase status line

 PS.statusText( "" );

 // Change grid to random color

 PS.gridColor( PS._random( 0xFFFFFF ) );
};

 

PS.gridShadow ( show, color )

PS.gridShadow() changes or inspects the shadow color of the grid.

Parameters:

  1. show : boolean, PS.CURRENT or PS.DEFAULT
  2. (optional) color : color expression, PS.CURRENT or PS.DEFAULT

Returns : object or PS.ERROR

Default : { show : false, rgb : PS.COLOR_GRAY_LIGHT }

If the required show parameter is true or any non-zero number, the grid shadow is enabled.

If show is false, null, zero (0) or PS.DEFAULT, the grid shadow is disabled.

If show is PS.CURRENT, the grid shadow status is not changed.

The optional color parameter can be supplied in any of the four Perlenspiel color expression formats.

If color is PS.DEFAULT, the default color (PS.COLOR_GRAY_LIGHT) is applied. If color is PS.CURRENT or not supplied, the shadow color is not changed.

Return value

PS.gridShadow() returns an object with the following properties:

The .show property is true if the grid shadow is enabled, else false.

The .rgb property is an RGB triplet integer indicating the color currently assigned to the grid shadow.

PS.ERROR is returned if an error occurs.

// EXAMPLE:
// Using PS.gridSize(), PS.gridColor()
// and PS.shadowColor()

PS.init = function ( system, options ) {
 // set up a 10 x 10 grid

 PS.gridSize( 10, 10 );

 // set background color to red
 // set shadow color to yellow

 PS.gridColor( PS.COLOR_RED );
 PS.gridShadow( true, PS.COLOR_YELLOW );
};

 

PS.gridPlane ( plane )

PS.gridPlane() changes or inspects the current grid drawing plane.

Parameters:

  1. (optional) plane : integer, PS.CURRENT or PS.DEFAULT

Returns : integer or PS.ERROR

Default : 0

The optional plane parameter can be any positive integer. Values less than zero are clamped to zero. Non-integral values are floored.

If plane is PS.DEFAULT, the default plane (0) is used. If plane is PS.CURRENT or not supplied, the drawing plane is not changed.

Return value

PS.gridPlane() returns an integer indicating the current grid drawing plane.

PS.ERROR is returned if an error occurs.

 

PS.gridRefresh ()

PS.gridRefresh() forces a refresh of the entire grid.

Parameters: none

Returns : integer or PS.ERROR

Default : 0

To improve its efficiency, Perlenspiel delays bead rendering until it is likely to be needed. However, for debugging purposes, it is sometimes useful to force a grid refresh.

Call PS.gridRefresh() to immediately render all beads marked for refreshing.

Return value

PS.gridRefresh() returns an integer indicating the number of beads that were actually redrawn, zero (0) if none.

PS.ERROR is returned if an error occurs.