Tutorial 6 - Overlays

Sample name: SampleOverlay
Script source code file: sample/overlay/main.lua

The goal of this tutorial is to show you

• how overlays work
• how to create overlays

New functions in this tutorial:

createOverlay()
setOverlayColor()
renderOverlay()

When you run sampleOverlay.exe you see an overlay displayed on the screen. If you click on it, its position changes randomly.

Open main.lua which is in /sample/overlay to take a look at the code.

First there are three variables: overlayId holds the id of the overlay, overlayX and overlayY are used to define the position of the overlay.

init()

In the first line, the variable overlayId is filled with the result of the function createOverlay which returns the id of the newly created overlay. The documentation describes the createOverlay functions as follows:

createOverlay

Description

Create overlay object

Definition

function createOverlay(string overlayName, string textureFilename)

Arguments

string	overlayName	overlay name
string	textureFilename	texture file name

Take note that you have to use the relative path to your file.

 overlayId = createOverlay("overlay", "sample/overlay/overlay.png");

The second line consists of the setOverlayColor function.
Try to comment it out by adding -- in front of the line. Save the script and run the program. You see that this sample also works without the setOverlayColor function. It isn’t needed to display an overlay, but it gives you the possibility to change its appearance. Here is how it is described in the documentation:

setOverlayColor

Description

Set overlay color

Definition

function setOverlayColor(integer overlayId, float red, float green, float blue, float alpha)

Arguments

integer	overlayId	overlay id
float	red	red value
float	green	green value
float	blue	blue value
float	alpha	alpha value

The used arguments in the example result in white with an opacity of 0.75.

 setOverlayColor(overlayId, 1, 1, 1, 0.75);

Try the arguments 1, 0, 0, 0.75, to see the difference.

mouseEvent()

This function runs every time you move the mouse or click on it. If the mouse is inactive this function isn’t executed. It provides the position of the cursor, and the state of the buttons which can be used within the function.
We first check, if the state of a mouse button is down, which is done by the isDown part of the if-construct. The rest of the if-construct is a simple hit test, it checks whether the cursor is within the overlay or not. If the if-construct returns true, you have clicked on the button. Then the overlayX and overlayY values are overwritten with a random number between 0.05 and 0.8.

function mouseEvent(posX, posY, isDown, isUp, button)   -- Check if overlay has been clicked   if isDown and posX > overlayX and posX < overlayX+0.16 and     posY > overlayY and posY < overlayY+0.04 then     overlayX = math.random(50, 800)/1000;     overlayY = math.random(50, 900)/1000;   end; end;

draw()

What happens here is essential : try commenting out the renderOverlay function once. If you run the sample now, nothing will be rendered at all. This function is needed to render an overlay. This allows you to display or hide components (e.g. menu options) depending on the state of your program.

Here is how the function is described in the documentation:

renderOverlay

Description

Render overlay

Definition

function renderOverlay(integer overlayId, float x1, float y1, float width, float height)

Arguments

integer	overlayId	overlay id
float	x	x position [0,1]
float	y	y position [0,1]
float	width	width [0,1]
float	height	height [0,1]

A width and height of 1 means that the overlay has exactly the size of the screen.

Since overlayX and overlayY change when you click on the overlay, it is instantly rendered in the new position.

function draw()   -- Render overlay   renderOverlay(overlayId, overlayX, overlayY, 0.16, 0.04); end;