# 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.

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:
  - TiledGrid3D and TiledGrid3DAction for `tiled` grids
  - Grid3D and Grid3DAction for `non-tiled` grids

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

...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).

...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).

# 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:
  - grid3d_actions
And all the TiledGrid3DAction actions here:
  - tiledgrid_actions

# 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 ) )