|
|
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 field(s) as source.
Retrieving Content Of The Matrix
The function GetPixelArea retrieves data from the matrix and stores it into a 2-dimensional field 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 field 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 field 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 field 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 field, 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 field. The field can be stored at the default position or an individual position. The field is stored on a matrix in the background. The background matrix acts as source for DrawPixelArea. It can contain several fields. |
Drawing Content Onto The Matrix
The function DrawPixelArea copies data from a 2-dimensional field 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 field 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 field onto the default position of your virtual matrix or an individual position.
If the source field 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 field will be copied to the virtual matrix (the complete field). |
| • | 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. |
| • | filter determines which color channels to draw. Default values are {255, 255, 255, 255, 255} for RGBWA. For more information, please see below. |
| • | 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 field or only parts of it onto your virtual matrix. The field can be drawn at the default or an individual position. |
| • | (For the drawing operation, it is assumed that the field describes a rectangular area in which every single line has the same number of columns.) |
Using Filters For Drawing
The filter can be used to leave different color channels of the matrix unchanged. The following example draws just the red and the alpha channel onto the matrix and leaves other channels unchanged:
color matrix[][];
color filter = {255, 0, 0, 0, 255};
DrawPixelArea(matrix, 0, 0, -1, -1, 0, 0, filter);
Examples
DrawPixelArea (Without Color Filter)
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 field 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);
}
DrawPixelArea (With Color Filter)
The second example for the MAS Script Effect uses a color filter. You will see that it filters the red color channel. As a result, the green center will remain, while the red square will not be displayed anymore.
@scriptname="";
@author="";
@version="";
@description="";
color matrix[][];
color filter = {0, 255, 255, 255};
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, filter);
}
|