Using Variables

Introduction

In order to use a variable it must be declared first. This is done by stating the data type of the variable and a name, followed by a semicolon. Furthermore, it is possible to initialize them during the declaration using an equal sign. This means that a particular value can be assigned to the variable already during initialization. Here are some examples:

int i;

float f;

int k = 4;

string text = "Hello World";

int width = GetMatrixWidth();

A structure is initialized with a list of expressions separated by comma and written in curly brackets.

color white = {255, 255, 255, 255, 0};

color red = {255};

date d = {24, 11, 1980};

If not all elements of a structure are initialized, the rest will be set to 0.

Constants

It is also possible to declare a variable as a constant. Those variables cannot be changed while the script is running and must be initialized during their declaration. They may be used to simplify the reading of the script code. For example, there is a global constant called PI. To declare a variable as a constant use the keyword const

const int width = 10;

const int maxPixel = 20 * width;

Global And Local Variables

A variable exists within the block in which it has been defined. This may be a function or a block like it is described in statements. It does not exist outside this area. A variable i, which was defined in the function RenderEffect, does not exist in any other function. Whenever such a block is entered, due to a function call, a loop or something different, the variable is re-initialized. Because of that, a local variable loses its assigned value between two calls of the function.

Global variables on the other hand are available within the whole script, beginning with when they are defined. They can be used to hold data during the run of a script. Global variables do also exist between two calls of RenderEffect. If the script needs to hold data between to runs, global variables are the correct way to do this.

int g_iPos = 0;

void RenderEffect()

{

    SetPixel(WHITE, g_iPos, 0);

    g_iPos = (g_iPos + 1) % GetMatrixWidth();

}

g_iPos is increased by 1 each time the script is called. It is used to determine the new position of a pixel set to white.

void InitEffect()

{

    g_iPos = 0;

}

int g_iPos = 0;

void RenderEffect()

{

    SetPixel(WHITE, g_iPos, 0);

    g_iPos = (g_iPos + 1) % GetMatrixWidth();

}

This script will fail since g_iPos is unknown in function InitEffect. It has been declared after this function. In this way, only RenderEffect can use it.

Saving Data

Effects in MADRIX can be stored in a single file or in a whole MADRIX Setup file. Furthermore, it is possible to change a Storage Place to show another effect. If a script effect is reloaded with a compiled and running script, InitEffect is called and the script starts from the beginning. Sometimes it is useful that a script does not start from its beginning (for example, a black matrix) but from the same state where it was when it has been stored or the Storage Place has been changed.

The values of global variables do not only remain between two calls of a script, but may be stored when the effect is saved, too. Therefore, the variable should be declared as persistent.

persistent int g_iPos;

Whenever the script is saved, the content of g_iPos is also saved. It is loaded again, when the script is loaded. This loading procedure is executed after InitEffect has been called. Even if the variable is originally initialized in InitEffect, it will contain the saved data after InitEffect has been called, nevertheless.

More Information

In MADRIX Script several constants are defined by default. They may be used to make the source code more legible. The summary contains an »overview with all available global variables and constants.