Functions

Working With Functions

▪A script/macro in MADRIX Script consists of a set of functions.

▪Some of these functions are required and called by MADRIX.

▪Others may be used to split the script into smaller parts.

▪Functions form small parts of a script and hold a number of statements.

▪They can be called from other parts of the script in order to execute their statements.

▪Having statements used outside of functions is not allowed in MADRIX Script.

Creating Functions

Functions consist of a head and a body. The head describes the name of the function, its parameters, and its return value. Whereas, the body includes a block of statements, like this one:

void function(int p)
{
    if(p * p > 2)
         do something;
         do something more;
} 
 

The first data type, stated in front of the function, describes the kind of value the function returns and it may be of any known data type. In the case above, no value is returned by the function and therefore void is declared. The actual name of the function can be any name that follows the rules of identifiers in MADRIX Script as was discussed above. But it has to be unique. It is not allowed to have several functions with the same name or with the name of global variables or constants.

The parameter list following the name of the function may be left empty, but it is necessary to keep the brackets (). Different parameters are separated by comma. A parameter can take on any data type possible. Here are three examples for function declarations:

void setPixel(int point[])
{
    do something
}
 
int[] CreatePoint(int x, int y)
{
    do something
}
 
string getTag()
{
    do something
} 
 

Passing Parameters In MADRIX Script

Parameters are always passed via copy by value (The exception are »arrays). This means that a parameter may be used as another local variable of a function. Changing the value of a variable does not change the variable the caller has provided.
Note: A reference is created for arrays. Hence, changing an array results also in changing the array of the caller.

void testFunc(int i, int ia[])
{
    i = 5;
    for(int n = 0; n < i; n++)
    {
        ia[n] = n * n;
    }
}
 
 
void RenderEffect()
{
    int testArray[];
    int len = 2;
    testFunc(len, testArray);
}
 
 

In testFunc the parameter i is set to 5 and the array that is passed is filled with several values. After the return of the function in RenderEffect, the array is now filled with the values set in testFunc. Whereas the variable len has not changed and still has a value of 2.

Note: Passed parameters are always copied to a function, while this is not the case with arrays.

Returning A Value

To return a value, the return statement must be used followed by an expression. The given expression must result in the same or at least a compatible data type of the declared function's type. It must be the last statement of any function which returns a value unequal to void. In addition, return can be used to leave a function early. For void functions return will be used without an expression. Here are some examples:

int[] CreatePoint(int x, int y)
{
 int res[] = {x, y};
 return(res);
}
 
 
string getTag()
{
 date d = GetDate();
 switch(d.weekday)
 {
         case 0: return("Sunday"); break;
         case 1: return("Monday"); break;
         case 2: return("Tuesday"); break;
         case 3: return("Wednesday"); break;
         case 4: return("Thursday"); break;
         case 5: return("Friday"); break;
         case 6: return("Saturday"); break;
 }
 return("unknown day");
}
 
 
 
 

Functions Called By MADRIX

▪Each macro or script includes a number of predefined functions called by MADRIX.

▪If a function is not needed by a script, it is not necessary to implement it. A message is printed out if one of them is missing. This is not an error, but only an information for the developer of the script.

▪Please note that each component of the MADRIX Script language (MAS Script Effect, Effect Macros, Storage Place Macro, Global Macro) may include a different combination of these five functions as this is just an overview:

void InitEffect()
void RenderEffect()
void PreRenderEffect()
void PostRenderEffect()
 
void MatrixSizeChanged()
 
 

▪More information is available in the corresponding chapters.
Learn more »MAS Script Effect
Learn more »Macros for Effects
Learn more »Storage Place Macro
Learn more »Global Macro

Further Information

▪There are a lot of functions which can be used in MADRIX Script for different functionality (e.g., to draw objects the matrix, get the data of the sound analysis, or mathematical functions).

▪Learn more »List Of Functions (Alphabetical Order)