|
Introduction
Two specific functions will be described in this chapter. First, MADRIX Script provides a function to be able to retrieve the content of a specific area of the matrix. Second, there is a function which is able to draw pixels onto the matrix using the obtained data array(s) as source.
Retrieving Content Of The Matrix
The function GetPixelArea retrieves data from the matrix and stores it into a 2-dimensional array of colors. Data is stored in the background at a certain position of the virtual matrix.
void GetPixelArea(matrix[][], int xSrc, int ySrc, int w, int h,
int xDst, int yDst)
Explanation:
| ▪ | matrix[] is a 2-dimensional array of colors in which the content of the virtual matrix is saved. |
| ▪ | xSrc, ySrc describe the position of the source area (upper left corner). The default values are 0. |
| ▪ | w, h describe the width and height of the source area. The default values are -1.
A value of -1 means that the whole width or height of the virtual matrix will be retrieved (the complete matrix). |
| ▪ | xDst and yDst describe the position of the destination area (upper left corner). The default values are 0.
The retrieved array will be stored in the background. It will be stored at a certain position of a matrix in the background. As such, you can define an individual target destination.
This behavior allows you, for example, to retrieve multiple source areas by calling GetPixelArea several times and to draw them only once by calling DrawPixelArea one time (see below).
If your array is larger than your target destination allows, it will be reduced to fit the size of the virtual matrix. |
| ▪ | In order to retrieve the whole matrix into the given array, it is possible to just call: |
color matrix[][];
GetPixelArea(matrix);
| ▪ | Summary: You can store the complete virtual matrix or only parts of it in a array. The array can be stored at the default position or an individual position. The array is stored on a matrix in the background. The background matrix acts as source for DrawPixelArea. It can contain several arrays. |
Drawing Content Onto The Matrix
The function DrawPixelArea copies data from a 2-dimensional array of colors from the background and renders it onto the actual matrix.
void DrawPixelArea(matrix[][], int xDst, int yDst, int w, int h,
int xSrc, int ySrc, color filter)
Explanation:
| ▪ | matrix[] is a 2-dimensional array of colors that holds the source for DrawPixelArea. Use GetPixelArea as described above to retrieve the data. |
| ▪ | xDst, yDst describe the destination area. The default values are 0.
This allows you to draw the array onto the default position of your virtual matrix or an individual position.
If the source array is larger than your target destination allows, it will be reduced to fit the size of the virtual matrix. |
| ▪ | w, h describe the width and height of the render area. The default values are -1.
A value of -1 means that the whole width or height of the given array will be copied to the virtual matrix (the complete array). |
| ▪ | xSrc, ySrc describe the source area. The default values are 0.
DrawPixelArea can use and render the complete background matrix that was retrieved with GetPixelArea. Or it can only access and render a certain part of it. |
| ▪ | color filter is an multiplicative color filter of the data type color. The default values are 255, 255, 255.
By defining a color, these color values will be let through and all other colors will be filtered out. |
| ▪ | In order to draw the whole matrix it is possible to call: |
color matrix[][];
DrawPixelArea(matrix);
| ▪ | Summary: DrawPixelArea can access the background matrix that was created with GetPixelArea. With DrawPixelArea you can render the complete array or only parts of it onto your virtual matrix. The array can be drawn at the default or an individual position. |
| ▪ | (For the drawing operation, it is assumed that the array describes a rectangular area in which every single line has the same number of columns.) |
Example
DrawPixelArea
The first example for the MAS Script Effect will simply draw a small, red square in the upper left corner of the matrix with a green center. The colors drawn are defined in the array variable matrix[][] in InitEffect.
@scriptname="";
@author="";
@version="";
@description="";
color matrix[][];
void InitEffect()
{
matrix[0][0]=RED;
matrix[0][1]=RED;
matrix[0][2]=RED;
matrix[0][3]=RED;
matrix[1][0]=RED;
matrix[1][1]=GREEN;
matrix[1][2]=GREEN;
matrix[1][3]=RED;
matrix[2][0]=RED;
matrix[2][1]=GREEN;
matrix[2][2]=GREEN;
matrix[2][3]=RED;
matrix[3][0]=RED;
matrix[3][1]=RED;
matrix[3][2]=RED;
matrix[3][3]=RED;
}
void RenderEffect()
{
DrawPixelArea(matrix, 0, 0, -1, -1, 0, 0, WHITE);
}
|