API | Images

These functions handle the loading and display of image files.

About the imageData object

Perlenspiel's image and sprite functions employ a common object format to represent the structure and data of a 2-dimensional image. This imageData object contains six properties:

If the imageData was generated by a call to PS.imageLoad(), the .source property contains the filename string that was passed into that call. If the data was generated by PS.imageCapture(), .source contains the constant PS.GRID.

The .id property is set to a string that uniquely identifies the imageData object. If the data was generated by a call to PS.imageLoad(), this identifer will be identical to the string returned by that call.

The .width and .height properties indicate the width and height of the imageData in pixels.

The .pixelSize property indicates the format of the imageData's pixel data. Legal values of pixelSize are 1, 2, 3 or 4.

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

Color accuracy

Certain image file formats, notably .png and .jpg, often contain embedded color profile data that affects the way colors are interpreted when they are loaded into Perlenspiel.

If you load an image containing color profile data using PS.imageLoad(), the color values that appear in the .data property of the resulting imageData object probably won't match the values reported by your image editing software (such as Photoshop). This can be extremely annoying if you need the color data extracted from your images to exactly match specific values.

There are two ways around this problem:

  1. Don't use .png or .jpg files for images in which exact color values are important. Use .gif or .bmp files instead. These formats do not include embedded color profile data.
  2. Use one of the many tools available, such as pngcrush for Windows, that can strip embedded color profile data out of .png and .jpg files.

NOTE: Recent builds of Firefox do not interpreting the color values in .bmp files accurately. Files in .gif format work fine. For maximum compatibility, use .gif files to store images with critical color values.

 

PS.imageLoad ( filename, exec, format )

PS.imageLoad() loads an image file into an image object.

Parameters:

  1. filename : string
  2. exec : function
  3. (optional) format : 1, 2, 3, 4 or PS.DEFAULT

Returns: string or PS.ERROR

PS.imageLoad() attempts to asynchronously load the image specified by filename, which should be the name of a valid .bmp, .png or .jpg image. The name can be specified relative to the directory in which the associated script file is stored, or it can be a fully qualified filename.

If you need to extract specific color values from your images, be sure to read the information on color accuracy above.

The exec parameter must be a valid JavaScript function expecting at least one argument. When the image specified by filename is successfully loaded, this function is called with its first argument set to an image object containing the loaded image, or PS.ERROR if an error occurs.

The optional format parameter specifies the pixel format of the data that will be returned in the image object. Legal values for this parameter are 1, 2, 3, 4 or PS.DEFAULT. Refer to the image object documentation for an explanation of this parameter.

If format is PS.DEFAULT or not supplied, the default data format (4) is used.

Usage notes

1. PS.imageLoad() returns PS.ERROR if an obvious parameter error is detected. However, because file loads are asynchronous, any actual loading errors occur after PS.imageLoad() returns. This means that PS.imageLoad() returns a file identifier even if the file subsequently fails to load. To detect loading errors, inspect the parameter of your exec function, which will be PS.ERROR if something went wrong during the load. A system error message will also appear in the event of a failed load.

IMPORTANT: Webkit-based browsers, such as Chrome and Edge, are picky about security. By default, they will not load resources (including image and audio files) that (1) do not reside on an actual HTTP server, and (2) do not share the root filepath of any script that tries to access them. This means that you have to install all of your scripts, images and audio files on a live server, in the same root filepath, before you can test or deploy an application using these browsers. (It's possible to reconfigure the browsers to avoid this necessity, but this is not recommended.)

A basic application directory might look like this:

game.html (the Perlenspiel web page)
game.js (your game script)
images/ (a folder for your image files)
audio/ (a folder for your custom audio files, if any)

Firefox is currently more lenient about security. Resource files don't need to be on a server, or share the same root filepath. This may change in the future.

Return value

PS.imageLoad() returns a string that uniquely identifies the loaded image file. This string also appears in the .id property of the image object created by the call.

A new identifier is generated by each call to PS.imageLoad(). If you load the same image file more than once for some reason, each load instance will be assigned a different identifier.

PS.ERROR is returned if an error occurs.

See below for an example of how to use PS.imageLoad().

 

PS.imageBlit ( image, xpos, ypos, region )

PS.imageBlit() blits an image object to the current grid plane at the specified coordinates.

Parameters:

  1. image : object
  2. xpos : integer
  3. ypos : integer
  4. (optional) region : object

Returns: true, false or PS.ERROR

The required image parameter must be a reference to an image object, such as those passed into the loader function of a successful PS.imageLoad() call, or the object returned by a call to PS.imageCapture().

The required xpos and ypos parameters specify the position on the grid where the top left corner of the image will be located. They can be any positive or negative integers. Non-integral values are floored.

The optional region parameter specifies a zero-based rectangular region inside the image that will be used for the blit. It should be an object containing any of the following properties:

The .left property should be an integer between zero (0) and (image.width - 1), inclusive. Non-integral values are floored. An error occurs if .left is greater than or equal to image.width. If .left is less than zero, PS.DEFAULT or not supplied, the value zero (0) is used.

The .top property should be an integer between zero (0) and (image.height - 1), inclusive. Non-integral values are floored. An error occurs if .top is greater than or equal to image.height. If .top is less than zero, PS.DEFAULT or not supplied, the value zero (0) is used.

The .width property should be an integer between one (1) and image.width, inclusive. Non-integral values are floored. If .width is less than one (1), PS.DEFAULT, not supplied, or (.width - .left) is greater than image.width, the value (image.width - .left) is used.

The .height property should be an integer between one (1) and image.height, inclusive. Non-integral values are floored. If .height is less than one (1), PS.DEFAULT, not supplied, or (.height - .top) is greater than image.height, the value (image.height - .top) is used.

If region is PS.DEFAULT or not supplied, the entire image is blitted to the grid.

Usage notes

1. The xpos and ypos parameters can be negative, or larger than the current grid. If this happens, some or all of the blitted image will not be visible.

2. Existing bead borders and glyphs are not affected when drawing with PS.imageBlit().

3. When using PS.imageBlit() with an image object containing alpha data (formats 2 and 4), 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 assigned to the beads affected by PS.imageBlit() is not changed.

Return value

PS.imageBlit() returns true if any part of image was actually drawn to the grid, or false if nothing was drawn.

PS.ERROR is returned if an error occurs.

// EXAMPLE:
// Bit an image file onto the grid

PS.init = function( system, options ) {
 // set up 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
 // finished loading

 PS.imageLoad( "kitten.bmp", myLoader );
};

// This is the image loader function

function myLoader( image ) {
 // The image argument of myLoader() is passed
 // an image object representing kitten.bmp

 // Blit the entire image to the grid
 // with its top left corner at 0, 0

 PS.imageBlit( image, 0, 0 );
};

 

PS.imageCapture ( format, region )

PS.imageCapture() creates an image object based on the current bead colors in the grid.

Parameters:

  1. (optional) format : integer or PS.DEFAULT
  2. (optional) region : object or PS.DEFAULT

Returns: object or PS.ERROR

The optional format parameter specifies the pixel format of the data that will be returned in the image object. Legal values for this parameter are 1, 2, 3, 4 or PS.DEFAULT. Refer to the image object documentation for an explanation of this parameter.

If format is PS.DEFAULT or not supplied, the default format (3) is used.

The optional region parameter specifies a zero-based rectangular region of the grid that will be used to create the image object. It should be an object containing any of the following properties:

The .left property should be an integer between zero (0) and (grid_width - 1), inclusive. Non-integral values are floored. An error occurs if .left is greater than or equal to the grid width. If .left is less than zero, PS.DEFAULT or not supplied, the value zero (0) is used.

The .top property should be an integer between zero (0) and (grid_height - 1), inclusive. Non-integral values are floored. An error occurs if .top is greater than or equal to the grid height. If .top is less than zero, PS.DEFAULT or not supplied, the value zero (0) is used.

The .width property should be an integer between one (1) and the grid width, inclusive. Non-integral values are floored. If .width is less than one (1), PS.DEFAULT, not supplied, or (.width - .left) is greater than the grid width, the value (grid_width - .left) is used.

The .height property should be an integer between one (1) and the grid height, inclusive. Non-integral values are floored. If .height is less than one (1), PS.DEFAULT, not supplied, or (.height - .top) is greater than the grid height, the value (grid_height - .top) is used.

If region is PS.DEFAULT or not supplied, the entire grid is used.

Usage notes

1. The image returned by PS.imageCapture() represents the visible state of the grid, taking into effect all image planes, alpha transparency, sprites, etc.

2. The value returned by PS.imageCapture() can be passed to any Perlenspiel function expecting an image object.

Return value

PS.imageCapture() returns an image object in the specified format, representing the current bead colors of the grid.

PS.ERROR is returned if an error occurs.

 

PS.imageDump ( image, region, format, length, hex )

PS.imageDump() outputs a formatted text representation of an image object into the debugger.

Parameters:

  1. image : object
  2. (optional) region : object or PS.DEFAULT
  3. (optional) format : integer or PS.DEFAULT
  4. (optional) length : integer or PS.DEFAULT
  5. (optional) hex : boolean or PS.DEFAULT

Returns: PS.DONE or PS.ERROR

The required image parameter must be a reference to a valid image object.

The optional region parameter specifies a zero-based rectangular region inside the image that will be used for the dump. It should be an object containing any of the following properties:

The .left property should be an integer between zero (0) and (image.width - 1), inclusive. Non-integral values are floored. An error occurs if .left is greater than or equal to image.width. If .left is less than zero, PS.DEFAULT or not supplied, the value zero (0) is used.

The .top property should be an integer between zero (0) and (image.height - 1), inclusive. Non-integral values are floored. An error occurs if .top is greater than or equal to image.height. If .top is less than zero, PS.DEFAULT or not supplied, the value zero (0) is used.

The .width property should be an integer between one (1) and image.width, inclusive. Non-integral values are floored. If .width is less than one (1), PS.DEFAULT, not supplied, or (.width - .left) is greater than image.width, the value (image.width - .left) is used.

The .height property should be an integer between one (1) and image.height, inclusive. Non-integral values are floored. If .height is less than one (1), PS.DEFAULT, not supplied, or (.height - .top) is greater than image.height, the value (image.height - .top) is used.

If region is PS.DEFAULT or not supplied, the entire image is dumped.

The optional format parameter specifies the pixel format of the data that will be returned in the image object. Legal values for this parameter are 1, 2, 3, 4 or PS.DEFAULT. Refer to the image object documentation for an explanation of this parameter.

If format is PS.DEFAULT or not supplied, image.pixelSize is used.

The optional length parameter specifies the number of pixels that will be included in each line of debugger output. It should be a positive integer between one (1) and (image.width * image.height), inclusive. Values outside this range are clamped. Non-integral values are floored.

If length is PS.DEFAULT or not supplied, the value image.width is used.

The optional hex parameter specifies the numeric base of the pixel data values. If hex is true, any non-zero number, PS.DEFAULT or not supplied, the data is output in hexadecimal (base 16). If hex is false or zero (0), the data is output in decimal (base 10).

Usage notes

The text dumped into the debugger by PS.imageDump() is formatted as a valid JavaScript representation of the specified image object.

You can cut and paste this text into your source code, assign it to a variable or property, and thereafter use that variable or property as a parameter to any Perlenspiel function expecting an image object. This technique effectively “hardwires” the image into your code, eliminating the need to load an image file during a game.

Return value

PS.imageDump() returns PS.DONE if the call is successful, else PS.ERROR.

// EXAMPLE:
// Load an image file and dump it to the debugger

PS.init = function( system, options ) {
 // set up 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
 // finished loading

 PS.imageLoad( "zombie.bmp", myLoader );
};

// This is the image loader function

function myLoader( image ) {
 // The image argument of myLoader() is passed
 // an image object representing zombie.bmp

 // Dump the image object to the debugger
 // so you can inspect, cut and/or paste it

 PS.imageDump( image );
};