parallaxAdd (thisFile, scrollSpeedX, scrollSpeedY);


Loads an image from the file handle thisFile and uses it as a parallax layer, visible behind the background image. Parallax layers can scroll at different speeds to the background image, giving the illusion of depth to a scene as it moves.

The value scrollSpeedX specifies how fast the parallax image will move as a percentage of the the background image as it scrolls. For example, if scrollSpeedX is 50, for every 2 pixels the main scene moves the parallax layer will move only 1. If you specify a scroll speed in this way, the width of the image must be a power of two (i.e. the width must be 1, 2, 4, 8, 16, 32, 64, 128, 256, 512, 1024, 2048 etc. pixels) in order for proper tiling to occur... that is, the image will repeat horizontally. The same is true of scrollSpeedY which specifies how fast the image moves vertically as a percentage of the movement of the main scene - if a value is specified here, the height of the image must be a power of 2.

There is one special value which can be used in the place of either scrollSpeedX or scrollSpeedY or neither or both at any time - and that value is the word AUTOFIT. If scrollSpeedX is AUTOFIT, the horizontal scrolling speed of the parallax layer is calculated automatically (and consequently, there's no way the image will need to repeat, so the width need not be a power of 2). However, a new rule is imposed if using this setting - the image must be as wide as, or wider than, the game window. If scrollSpeedY is AUTOFIT, the vertical scrolling speed of the layer is calculated automatically and the height need not be a power of 2 - however, the height of the image must be greater than or equal to the height of the game window. Got all that? Good.

One more thing - you can have multiple parallax layers at once, each with its own pair of scrolling speeds. The most recently added parallax layer will be visible through any areas of the scenery coloured bright cyan (0, 255, 255 or #00FFFF). (Except for 32-bit images, where the alpha channel is used!) Should there be a further parallax layer, it will be visible through any regions of the most recent coloured bright cyan, and so on, and so on. So, when loading multiple layers using this function, start with the furthest away. Also, for a realistic effect, make any layers that are further away scroll more slowly than those that are nearer the scene.

Return value:

No return value.


# The width and height of each of these must be a
# power of 2...

parallaxAdd ('stars.tga', 10, 10);
parallaxAdd ('mountains.tga', 25, 25);

# This image must be at least as wide and tall as
# the game window...

parallaxAdd ('town roofs.tga', AUTOFIT, AUTOFIT);

See also:

Scrolling Scenes