CAAT.Foundation.Actor

Caching actors as bitmaps

The method cacheAsBitmap(time, strategy) creates an image representation of the actor the method is invoked for. The main objective is to cache complex drawing routines into an image to avoid recreating it constantly. It is suited for example for TextActors whom drawing operations are quite expensive or for any custom drawing actor.

The time parameter is used to specify at what virtual time you'd like to have the actor cached. CAAT uses a timeline for each scene, so different time values could give different cached images.

The strategy parameter can be either

CAAT.Foundation.Actor.CACHE_SIMPLE

CAAT.Foundation.Actor.CACHE_DEEP

CACHE_SIMPLE means the cache will only be applied to the Actor or Container. CACHE_DEEP for a container means that the Container and all of its children will be cached in the same image. This can dramatically speed drawing operations at the cost of creating new in-memory images.

Any CAAT.Foundation.Actor instance already takes care of drawing the cached image instead of the stroked/filled text. It is developers responsibility to do it if the paint or paintActorGL methods have been overridden.

The method stopCacheAsBitmap() will make the actor not being cached anymore, and its paint method will be called again.

As it was expected, the cached image will be wrapped into a CAAT.Foundation.SpriteImage of one row by one column. That means if the cached image is to be accessed in a webGL environment (or just needs be accessed) it could be obtained the associated HTMLCanvasElement by calling actor.backgroundImage.image.

In the following example, a container is being cachedAsBitmap. On the left, it uses CACHE_SIMPLE, which means that the container caches itself, but still makes calls to animate and paint its children. The proof about it, is that the container is smaller than its children but still shows completely the children.

In the right, it uses CACHE_DEEP. The container and its children have been cached in an image, preventing CAAT from traversing the container and its children for animation and painting. That's the reason why the content is clipped, since it was drawn in an smaller image than needed.

Example

The following example shows some leaning cached text actors.



                function __scene(director) {

                    var scene= director.createScene();

                    var t1= text( director, scene, CAAT.Foundation.Actor.CACHE_SIMPLE, "CACHE_SIMPLE" );
                    var t2= text( director, scene, CAAT.Foundation.Actor.CACHE_DEEP, "CACHE_DEEP" );

                    t1.centerAt( director.width/2/2, director.height/2 );
                    t2.centerAt( director.width/2/2 + director.width/2, director.height/2 );

                    scene.addChild(t1);
                    scene.addChild(t2);

                }

                function text(director, scene, hint, name) {

                    var cc1 = new CAAT.Foundation.ActorContainer( ).
                            setBounds(0, 100, 300, 300).
                            enableEvents(false);

                    cc1.addBehavior(
                            new CAAT.Behavior.RotateBehavior().
                                    setCycle(true).
                                    setFrameTime(0, 4000).
                                    setValues(-Math.PI / 8, Math.PI / 8, .50, 0).    // anchor at 50%, 0%
                                    setInterpolator(
                                    new CAAT.Behavior.Interpolator().createExponentialInOutInterpolator(3, true))
                            );

                    var gradient = director.ctx.createLinearGradient(0, 0, 0, 50);
                    gradient.addColorStop(0, '#00ff00');
                    gradient.addColorStop(0.5, 'red');
                    gradient.addColorStop(1, 'blue');

                    var font= "36px sans-serif";

                    var text = new CAAT.Foundation.UI.TextActor().
                            setFont(font).
                            setText("This Container").
                            setAlign("center").
                            setTextFillStyle(gradient).
                            setOutline(true).
                            setOutlineColor('white');
                    cc1.addChild(text.setLocation(cc1.width / 2, 0));

                    var text2 = new CAAT.Foundation.UI.TextActor().
                            setFont(font).
                            setText("is Cached as Bitmap").
                            setAlign("center").
                            setTextFillStyle(gradient).
                            setOutline(true).
                            setOutlineColor('white');
                    cc1.addChild(text2.setLocation(cc1.width/2, 50));

                    var text4 = new CAAT.Foundation.UI.TextActor().
                            setFont(font).
                            setText("Using " + name).
                            setAlign("center").
                            setTextFillStyle(gradient).
                            setOutline(true).
                            setOutlineColor('white');
                    cc1.addChild( text4.setLocation(cc1.width/2, 100) );

                    var text3 = new CAAT.Foundation.UI.TextActor().
                            setFont(font).
                            setText("as caching strategy").
                            setAlign("center").
                            setTextFillStyle(gradient).
                            setOutline(true).
                            setOutlineColor('white');
                    cc1.addChild(text3.setLocation(cc1.width/2, 150));

                    cc1.cacheAsBitmap(1000,hint);

                    return cc1;
                }

                function __init()   {

                    var director = new CAAT.Foundation.Director().
                            initialize(700,500, document.getElementById('_c1'));

                    __scene(director);

                    CAAT.loop(30);
                }

                __init();