Map An Effect

Functionality

MADRIX provides the possibility to map an effect to different areas of the matrix. Setting effect mapping parameters is also available using  additional functions.

The functions discussed in this chapter provide almost the same functionality as the Map dialog used for effects in MADRIX. Therefore, the functionality of mapping is thoroughly discussed in the MADRIX manual. This manual only describes the functions provided by the scripting engine of MADRIX to manipulate map and tile settings of an effect.

Settings

Using Absolute Values

One possibility is the function MapEffectPixel. You will have to set the values of this function in pixels. It is declared as follows:

void MapEffectPixel(int x, int y, int w, int h)

x, y are the start coordinates to determine where the effect should be started on the virtual matrix. Negative values are allowed, too. w, h describe the size of the mapped matrix. Any value higher than 0 is valid. For example, to map the effect on 20, 10 with a size of 50 x 40 pixels, just write the following:

MapEffectPixel(20, 10, 50, 40);

Using Relative Values

Another possibility is the function MapEffectVector. It uses relative values between 0.0 and 1.0. Hereby, 1.0 represents the full size of the matrix. The declaration is the following:

void MapEffectVector(float x, float y, float w, float h) 

x, y are the start coordinates to determine where the effect should be started on the virtual matrix. You can also use negative values. w, h describe the size of the mapped matrix. Here is an example: To map the effect using half the matrix size, centered, call the function as follows:

MapEffectVector(0.25, 0.25, 0.5, 0.5);

The following example uses negative start values. With negative coordinates the mapped matrix starts outside of the virtual matrix and has a height and width of 100% of the virtual matrix.

MapEffectVector(-0.5, -0.5, 1.0, 1.0);

Another possibility is to set the size of the mapped matrix to a larger size than the virtual matrix has. For that, you will have to use values greater than 1 for width and height. Negative values are not allowed.

Side Effects

If the effect matrix is mapped using a mapping function and you are changing the values for the width and height in your script, the effect will be reinitialized and restarted, beginning with a call of the function InitEffect. If the mapping only changes the position of the effect, the effect will not be reinitialized and restarted.

Getting The Current Map Settings

If you want to retrieve the values for the mapping, you should use the two functions GetMapPixel and GetMapVector. They are defined like this:

int GetMapPixel(int map[])
int GetMapVector(float map[])

Both functions return false if no mapping is set. And both functions return true if mapping is set. The parameter map is a field which retrieves the mapping settings as follows:

This field can be found in the Map Effect dialog of MADRIX because it represent Pos X, Pos Y, sixe x, and Size Y in the section "Map (Position/Size)".

x, y describe the start coordinates and width, height describe the size of the mapped matrix. If false is returned, mapping is not activated and the standard values for x, y, width, and height (0.0, 0.0, 1.0, 1.0) are activate. Here is an example to show this. Just paste the source code into the MAS Script effect, use the map dialog and the Script Output window will display the information.

@scriptname="";

@author="";

@version="";

@description="";

void InitEffect()

{

}

void RenderEffect()

{

 float map[];

 int result=GetMapVector( map);

 if(result==0)

         WriteText("mapping not used");

 else

    WriteText("mapping is used, map x: "+ (string)map[0]+", map y: 
    "+(string)map[1] +", map width: "+(string)map[2]+", map height: "+(string)map[3]);

}

Ask If Mapping Is Activated

The function int IsMapped() returns true if mapping is active, or false if it is deactivated. Those are also the values the function GetMap returns.

Full Example

The following example fills the matrix with a random color which is changed every tenth call of the script. Furthermore, the effect is moved inside the matrix using mapping.

persistent float g_x;

persistent float g_y;

persistent int mode;

persistent int change;

persistent color g_col;

void InitEffect()

{

    //start in upper left corner

    g_x = -0.5;

    g_y = -0.5;

    change = 10;

    //fill matrix with the color used last

    DoPreRender();

}

void PreRenderEffect()

{

    /*

        ensures that after reloading (e.g. changing storage place)

        the matrix is filled with the color used last

    */

    Clear(g_col);

}

void RenderEffect()

{

    if(change++ >= 10)

    {

        color c = {random(0, 255), random(0, 255), random(0, 255), 

         random(0, 255), random(128 / 2, 128 * 2)};

        g_col = c;

        Clear(c);

        change = 0;

    }

    mapEffect();

}

void mapEffect()

{

    const float move  = 0.01;

    switch(mode)

    {

        case 0:

            g_y += move;

            if(g_y > 0.5)

            {

                g_y = 0.5;

                mode = 1;

            }

        break;

        case 1:

            g_x += move;

            if(g_x > 0.5)

            {

                g_x = 0.5;

                mode = 2;

            }

        break;

        case 2:

            g_y -= move;

            if(g_y < -0.5)

            {

                g_y = -0.5;

                mode = 3;

            }

            break;

    case 3:

            g_x -= move;

            if(g_x < -0.5)

            {

                g_x = -0.5;

                mode = 0;

            }

            break;

    }//switch[mode]

    MapEffectVector(g_x, g_y, 1.0, 1.0);

}