setBackgroundEffect and doBackgroundEffect

setBackgroundEffect and doBackgroundEffect

Syntax:

setBackgroundEffect (add, divide, array [, array...]);

doBackgroundEffect ();

Purpose:

The setBlankColour function is used to specify an effect which can be applied to the background image. The doBackgroundEffect function applies the current effect to the background. The parameters for the function are an add value, a divide value and one or more arrays (which you can think of as a matrix, should you wish). When an effect is applied, the following procedure happens for each pixel: SLUDGE adds up the colour values of each pixel and its surrounding pixels, weighted using the arrays you've specified. For example, if you specified one array, containing just the value 1, it would get the original red, green and blue values of that pixel. If you specified one array, containing the values 1 three times, it would get red, green and blue totals equivalent to the red, green and blue values of the pixel itself, plus the red, green and blue values of the pixels either side. These values are then divided by the divide value and finally the add value is added to each. These red, green and blue values are then used as the new colour for the pixel (clamped to the range 0 to 255). So to get an average of each pixel and it's left-hand and right-hand neighbours, you could say setBackgroundEffect (0, 3, newStack (1, 1, 1)). If multiple arrays are specified, these are used to also add the red, green and blue values from pixels the line above or below the pixel having its colour changed.

Return value:

No return values.

Example:

# Exactly the same as darkBackground - sets each pixel to half its current red, green and blue values
setBackgroundEffect (0, 2, newStack (1));

# Negative - sets each pixel to 255 minus its current red, green and blue values
setBackgroundEffect (255, 1, newStack (-1));

# Double vision - each pixel becomes the average of two pixels 13 pixels apart
setBackgroundEffect (0, 2, newStack (1,0,0,0,0,0,0,0,0,0,0,0,1));

# Soften - take a weighted average of pixels surrounding each pixel
setBackgroundEffect (0, 14, newStack (1,2,1), newStack (2,2,2), newStack (1,2,1));

# Brighten
setBackgroundEffect (10, 7, newStack (8));

# Emboss
setBackgroundEffect (128, 2, newStack (1,0), newStack(0,-1));

# Colour emboss
setBackgroundEffect (32, 2, newStack (1,0,0), newStack (0,2,0), newStack(0,0,-2));