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