PS.ImageLoad ( file, func, format )

Loads an image file, and calls a function after loading with data extracted from the image.

Parameters:

1. file : string
2. func : function
3. (optional) format : integer

Returns: id : string or PS.ERROR

PS.ImageLoad() attempts to asynchronously load the specified image. If the load is successful, the specified function is called when the load is complete.

The file parameter must be a string matching the filename of a valid .png or .jpg image.

The func parameter must be a valid Javascript function expecting exactly one parameter. This parameter will expose the data extracted from the loaded image (see below)

The optional format parameter specifies the pixel format of the extracted data. Legal values for this parameter are 1, 3, 4 or PS.DEFAULT.

• If format is 1, each pixel in the image is provided as a single integer in the range 0 to 0xFFFFFF, representing a multiplexed RGB value.
• If format is 3 (the default), each pixel is provided as a series of three separate integers in the range of 0-255, representing the red, green and blue color components.
• If format is 4, each pixel is represented by a series of three integers for the color components, followed by a float in the range 0-1.0 for the alpha value.

The ImageData object

The ImageData object passed through the loader function's parameter is a table containing six named elements, file, id, width, height, pixelSize and data.

The file parameter is the filename of the loaded image, the same as the one passed to the associated PS.ImageLoad() call.

The id parameter is a unique string identifier, the same as the one returned by the associated PS.ImageLoad() call. NOTE: A new identifer is generated by each call to PS.ImageLoad(). If you load the same image more than once for some reason, each load instance will be assigned a different identifer.

The width and height elements are integers that describe the width and height of the image in pixels.

The pixelSize element indicates the format of the extracted data. The value will be 1, 3 or 4, corresponding to one of the pixel formats described above.

The data element is a flat array containing (width * height * pixelSize) values. Each successive series of pixelSize values describes a single pixel. The pixel data is arranged in order of increasing rows, beginning with row 0.

If the call to PS.ImageLoad() succeeds, the return value is the unique string identifier that will be assigned to the ImageData object passed into the loader function. PS.ERROR is returned if it fails.

PS.ImageBlit ( imgdata, x, y, left, top, width, height )

Blits an imageData object to the grid at the specified coordinates.

Parameters:

1. imgdata : imageData
2. (optional) x : integer
3. (optional) y : integer
4. (optional) left : integer
5. (optional) top : integer
6. (optional) width : integer
7. (optional) height : integer

Returns: boolean

The imgdata parameter must be an ImageData object of the type sent to the loader function of a PS.ImageLoad() call (see above).

The optional x and y parameters specify the position of the top left corner of the image on the grid.

If the specified x and/or y parameters are negative, only the portion of the source image overlapping the grid will be displayed. If x is equal to or greater than the current grid width, or y is equal to or greater than the current grid height, nothing happens and true is returned

If PS.DEFAULT is supplied for either parameter, the value 0 is used. If no x and y parameters are specified, the image is positioned at the top left corner of the grid (0, 0).

The optional left, top, width and height parameters specify a zero-based rectangular region within the source image that will be copied to the grid. To use this feature, all four parameters must be specified as follows:

• The left parameter must be in the range of 0 to (imgdata.width-1) inclusive.
• The top parameter must be in the range of 0 to (imgdata.height-1) inclusive.
• The width parameter must be in the range of 1 to (imgdata.width-left) inclusive.
• The height parameter must be in the range of 1 to (imgdata.height-top) inclusive.

If either width or height is less than 1, nothing happens and true is returned. If any parameter is invalid, nothing happens and PS.ERROR is returned.

When using PS.ImageBlit() with imgData containing alpha data, the image is transparently blended against the beads currently on the grid. The transparency calculation takes into account the effect of alpha values already assigned to the beads on the grid; that is, the calculation is based on the alpha-adjusted color of the existing beads. However, regardless of whether or not a blitted image includes alpha, the alpha value assigned to the beads affected by PS.ImageBlit() is not changed.

The return value of PS.ImageBlit() is true if the call is successful, or PS.ERROR if it fails.

Notes

1. Images without alpha (pixel formats 1 or 3) are drawn faster.

2. Bead borders and glyphs are still displayed when drawing with PS.ImageBlit(). For better performance, set border widths to zero and remove any glyphs on the beads you're targeting.

3. Beads do not flash when they are changed by PS.ImageBlit(), even when flashing is enabled.

4. Inactive beads are not affected. They always display the background color of the grid.

Example

This example shows how to blit an image file onto the grid.

PS.Init = function ( options )
{
    // set up a 32 x 32 grid

    PS.GridSize( 32, 32 );

    // Load the image file
    // Parameter 1 is your image file
    // Parameter 2 is the function that
    // will be called when the image is
    // completely done loading

    PS.ImageLoad( "image.png", Loader );
};

// This is the image loader function

function Loader ( data )
{
    // The data parameter contains
    // an ImageData object
    // extracted from the image

    // Blit the data to the grid

    PS.ImageBlit(data);
};