|
Functions |
Print Previous Next |
|
Working With Functions A script in MADRIX Script consists of a set of functions. Some of them are necessary and called by MADRIX. Others may be used to split the script into smaller parts. Functions form a 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 Parameter are always passed via copy by value. (The exception are fields.) 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. Please note: For fields a reference is created. Hence, changing a field results also in changing the field 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 testField[]; int len = 2; testFunc(len, testField); }
In testFunc the parameter i is set to 5 and the field that is passed is filled with several values. After the return of the function in RenderEffect, the field is now filled with the values set in testFunc. Whereas the variable len has not changed and still has a value of 2. Please note: Passed parameters are always copied to a function, while this is not the case with fields.
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 There are several functions called by MADRIX in order to let the script react to different events.
If a function is not needed by a script, it is not necessary to implement it. Regarding InitEffect and RenderEffect 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, Macros, Main Output Macro, Storage Place Macro) may include a different combination of these five functions as this is just an overview. InitEffect InitEffect is called by MADRIX whenever the script needs to be initialized. This is the case after compiling and starting a new script or when the user pressed the "Start" button of the Script editor. A script can assume that any global variable is initialized with 0 and that any global field is empty as long as it has not been initialized with any value. This function is the right place to initialize global variables, reset any fields, set the speed of an effect, or whatever is necessary to (re)start the script. RenderEffect This function is called whenever the effect needs to be rendered. The number of calls per second depends on the currently set speed of the effect. It can be received with the help of thefunction GetSpeed and set with the function SetSpeed. This is the right place to calculate the effect and draw it onto the matrix. PreRenderEffect This function is called directly before RenderEffect. In contrast to the other functions, this one is requested by a script. In order to have this function called, you have to call DoPreRender. It may be used if the script has to initialize any settings before an effect is rendered. void InitEffect() { DoPreRender(); } void PreRenderEffect() { color c = {random(0, 255), random(0, 255)}; Clear(c); }
This example uses the function PreRenderEffect to fill the matrix once after initializing a random color for this task. PostRenderEffect This function is called directly after RenderEffect. After an effect has been rendered completely, certain functions might want to be called. That could be a filter, for example. MartrixSizeChanged MatixSizeChanged is called after the size of the matrix has been changed. This may be due to a change to the matrix settings. Or because new map settings were set, e.g. caused by the call of a map function.
Further Information There are a lot of functions which can be used to draw objects the matrix, get the data of the sound analysis, or mathematical functions which can be used by a script. The summary contains a complete list about all available functions within MADRIX Script.
|