Effects

Effects are a special kind of actions. Instead of modifying normal attributes like opacity, color, position, rotation, or scale, they modify a new kind of attribute: the grid attribute.

A grid attribute is like a matrix, it is a network of lines that cross each other to form a series of squares or rectangles.

These special actions render any CocosNode object (Layer, Scene, etc.) into the grid, and you can transform the grid by moving it's vertices.

There are 2 kind of grids: tiled grids and non-tiled grids. The difference is that the tiled grid is composed of individual tiles while the non-tiled grid is composed of vertex.

tiled_and_nontiled_grid.png

The grids has 2 dimensions: rows and columns, but each vertex of the grid has 3 dimension: x, y and z. So you can create 2d or 3d effects by transforming a tiled-grid-3D or a grid-3D grid.

You can improve the quality of the effect by increasing the size of the grid, but the effect's speed will decrease.

A grid of size (16,12) will run fast in most computers but it won't look pretty well. And a grid of (32,24) will look pretty well, but in won't run fast in some old computers.

How they work

Each frame the screen is rendered into a texture. This texture is transformed into a vertex array and this vertex array (the grid!) is transformed by the grid effects. Finally the vertex array is rendered into the screen.

For more information about the internals refer to:

For example, if you have an scene or layer that renders this image:

original_image.png

...we can transform that image into this one using the Ripple3D action. As you can see from the wired image, it is using a grid of 32x24 squares, and the grid is non-tiled (all the squares are together).

effect_ripple3d.png effect_ripple3d_grid.png

...or we can transform it into this one using the FadeOutTRTiles action. As you can see from the wired image, it is using a grid of 16x12 squares, and the grid is tiled (all the squares/tiles can be separated).

effect_fadeouttiles.png effect_fadeouttiles_grid.png

3D actions

Action names that has the '3D' characters on it's name means that they produce a 3D visual effects by modifying the z-coordinate of the grid.

If you're going to use any '3D' action, probably you will want to enable the OpenGL depth test. An easy way to do that is by calling the Director's set_depth_test method.

Index of grid effects

You can find all the Grid3DAction actions here:
And all the TiledGrid3DAction actions here:

Examples

Some examples:

# effect applied on a Scene
    scene.do( Twirl( grid=(16,12), duration=4) )

# effect applied on a Layer
    layer1.do( Lens3D( grid=(32,24), duration=5 )

# effect applied on a different Layer
    layer2.do( Waves( grid=(16,12), duration=4) + Liquid( grid=(16,12), duration=5 ) )