Controlling A Script Via Frame ID

Using The Frame ID

The Frame ID is a special feature that is only supported by some effects. These effects are:

Using the Frame ID makes sense when the effect generates a sequence of visuals, which will repeat itself after a while. A user of MADRIX could forward or rewind effects. Hence, the Frame ID influences the position (and/or speed) of the  listed effects. As mentioned above, this can also be used for effects, which are written as a Script in the MAS Script Effect.

You will not have access to the individual Frame IDs generated by MADRIX. Instead, you can simply add values to the current Frame ID, which is unkown to you.
Example:
Let's assume the current Frame ID is 0. Add 50 frames and the new result is 50.
Let's assume further that another Frame ID is 2500. Add 50 and the new result is 2550.
In both cases, adding 50 will have the same result: the position is skipped by 50.

For our script from the last chapter, the sequence of pictures was one complete movement of the rectangle over the whole matrix. Now, imagine an effect which clears/fills the matrix with different colors defined by a color table. This effect could use the Frame ID to index the color table in order to determine which color to use next.

In order to use Frame IDs, we need to know the number of frames an effect produces that will be repeated. The next step is to tell MADRIX this number of frames. MADRIX needs this number to be able to generate the Frame IDs (including 0), but excluding the given number of those frames. The last step is to determine the current Frame ID when the effect is rendered in order to draw the appropriate picture. The number of frames we need is set and received by:

The current Frame ID can be retrieved by a call of:

And here is our script using Frame ID. As you can see, it is much simpler and shorter since we do not need to check if the rectangle has left the matrix. Furthermore, the rectangle will be moved almost automatically by MADRIX.

int g_ypos;

int g_rectSize[] = {4, 4}; //size of the rectangle

void MatrixSizeChanged()

{

    g_ypos = GetMatrixHeight() / 2 - g_rectSize[1] / 2; //the number of frames we have

    SetFrameCount((float)(GetMatrixWidth() + 2 * g_rectSize[0]));

}

void InitEffect()

{

    MatrixSizeChanged();

}

void RenderEffect()

{

    Clear();

    FillPixelRect(WHITE, (int)GetFrameId()-rectSize[0], g_ypos, g_rectSize[0], g_rectSize[1]);

}

Explanation:

This script uses the Frame ID as position x for the rectangle.

First, we need to determine and set the number of frames we produce. This is done in the function MatrixSizeChanged. Since we want to move the rectangle over the whole matrix and the rectangle shall move in and out of it, we calculate our number of frames as:

In order to let it move into the matrix, we subtract the width of the rectangle from the Frame ID so that position x is:

This is done in the last line of the script.

Now, this script can be controlled per Frame ID. Since the calculation of the Frame ID includes the current Speed Master and the set speed, this script is able to run for- and backwards and very fast.

Setting The Frame ID

It is also possible to set a new Frame ID using the following function.

void SetFrameId(float id)

This may be useful to have more control over a running script.

Another Way To Use the Frame ID

The following script fills the matrix with the colors red, green, and blue. It uses the Frame ID to index the color table in order to determine which color should be used to fill the matrix. Simply run this script and move the Speed Master into both directions. You will be able to see that the order of the colors will change. You may see that the effect runs backwards if the Speed Master is set to negative values.

color g_colTab[] = {

    {255, 0, 0, 0},        //red

    {  0,255,0, 0}, //green

    {  0, 0,255,0}  //blue

};

void InitEffect()

{

    SetFrameCount((float)(g_colTab.length));

    SetBpm(30);

}

void RenderEffect()

{

    Clear(g_colTab[(int)GetFrameId()]);

}