Introduction
Three 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 similar function which retrieves the content of a specific screen area. Third, 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)
The function GetPixelArea3D retrieves data from the matrix and stores it into a 3-dimensional array of colors. Data is stored in the background at a certain position of the virtual matrix.
void GetPixelArea3D(matrix[][][], int xSrc, int ySrc, int zSrc, int w, int h,
int d, int xDst, int yDst, int zDst)
Explanation:
▪matrix[][] is a 2-dimensional array of colors in which the content of the virtual matrix is saved.
matrix[][][] is a 3-dimensional array of colors in which the content of the virtual matrix is saved.
▪xSrc, ySrc, zSrc describe the position of the source area (upper left front corner). The default values are 0.
▪w, h, d describe the width, height and depth of the source area. The default values are -1.
A value of -1 means that the whole width, height or depth of the virtual matrix will be retrieved (the complete matrix).
▪xDst, yDst, zDst describe the position of the destination area (upper left front 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[3D] several times and to draw them only once by calling DrawPixelArea[3D] 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[][]; //3D: color matrix[][][];
GetPixelArea(matrix); //3D: GetPixelArea3D(matrix);
▪Summary: You can store the complete virtual matrix or only parts of it in an 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[3D]. It can contain several arrays.
Retrieving Content Of The Screen
The function CaptureScreen retrieves data from the screen and stores it into a 2-dimensional array of colors. Data is stored in the background.
void CaptureScreen(matrix[][], int xSrc, int ySrc, int w, int h)
Explanation:
▪matrix[][] is a 2-dimensional array of colors in which the content of the screen is saved.
▪xSrc, ySrc describe the position of the source area (upper left corner).
▪w, h describe the width and height of the source area.
The retrieved array will be stored in the background.
If your array is larger than your target destination allows, it will be reduced to fit the size of the virtual matrix.
▪The function CaptureScreen can have a notable performance impact, depending on the size of the screen area and the hardware setup.
▪Summary: You can store the complete screen area or only parts of it in an array. The array is stored on a matrix in the background. The background matrix acts as source for DrawPixelArea.
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)
The function DrawPixelArea3D copies data from a 3-dimensional array of colors from the background and renders it onto the actual matrix.
void DrawPixelArea3D(matrix[][][], int xDst, int yDst, int zDst, int w, int h, int d,
int xSrc, int ySrc, int zSrc, color filter)
Explanation:
▪matrix[][] is a 2-dimensional array of colors that holds the source for DrawPixelArea. Use GetPixelArea or CaptureScreen as described above to retrieve the data.
matrix[][][] is a 3-dimensional array of colors that holds the source for DrawPixelArea3D. Use GetPixelArea3D as described above to retrieve the data.
▪xDst, yDst, zDst 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, d describe the width, height and depth of the render area. The default values are -1.
A value of -1 means that the whole width, height or depth of the given array will be copied to the virtual matrix (the complete array).
▪xSrc, ySrc, zSrc describe the source area. The default values are 0.
DrawPixelArea[3D] can use and render the complete background matrix that was retrieved with GetPixelArea[3D] or CaptureScreen. Or it can only access and render a certain part of it.
▪filter is a multiplicative color filter of the data type color. The default values are {255, 255, 255}.
By defining a color, these color values will be passed through and all other colors will be filtered out.
▪In order to draw the whole matrix it is possible to call:
color matrix[][]; //3D: color matrix[][][];
DrawPixelArea(matrix); //3D: DrawPixelArea3D(matrix);
▪Summary: DrawPixelArea[3D] can access the background matrix that was created with GetPixelArea[3D] or CaptureScreen. With DrawPixelArea[3D] 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 (or a box in 3D) 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);
}
|