CAAT.Actor

Background Images

An actor instance now can have a background image. Initially this feature was delegated to Image or Sprite actor instances but in order to allow css rendering, it had to be implemented back into CAAT.Actor instances. CAAT.ImageActor and CAAT.SpriteActor classes are still valid but if fully CSS compatibility is pursued, they should not be used.

In order to set the background image, the method setBackgroundImage(image,set_actor_size_as_image_size) must be called.

The image parameter can be either an HTMLImageElement or a CAAT.SpriteImage instance. An HTMLCanvasElement instance is only suitable when selecting a non DOM+CSS renderer.

The SpriteImage object encapsulates an image and treats the image as if it was composed by a bidimensional array of subimages. In fact, when passing an instance of HTMLImageElement or HTMLCanvasElement as parameter it is transparently encapsulated into an SpriteImage or 1 row by 1 column in size. The SpriteImage allows to identify by index every subimage of the array.

By using this class as image holder, certain capabilities can be given to the background image:

setAnimationImageIndex( array_of_integers )
Define an array of indices over the spriteImage instance. This generates a sprite sequence.
setChangeFPS( number_of_milliseconds )
If set, the actor will automatically change background image to the next SpriteImage's subimage in sequence of the ones defined in the methos setAnimationImageIndex.
setSpriteIndex( integer )
If no sprite sequence is defined, this method will make the actor draw on its background the specified SpriteImage's subimage.
setBackgroundImageOffset( offset_x, offset_y )
Set a displacement value to apply to the SpriteImage's subimage.
setImageTransformation
Draw the actor's background transformed by one of these values:
- TR_NONE (default value)
- TR_FLIP_HORIZONTAL
- TR_FLIP_VERTICAL
- TR_FLIP_ALL
- TR_FIXED_TO_SIZE

If a given SpriteImage instance must be shared among multiple actors (two or more), creating new SpriteImage instances for every actor can be a waste of resources. The method getRef() can be used instead so that only one SpriteImage instance is created, and upon a call to setBackgroundImage a spriteImage.getRef() parameter should bu supplied.

Example

The following example shows the creation of actors on mousemove over a container. Every of this new actors has an spriteImage instance of a single stars image which is reused among every star actor instance.

The image used in this code is the following: , so setting a SpriteImage of one row by six columns will treat each image's piece as an independent star.

            function __scene(director) {

                var scene= director.createScene();

                var bg= new CAAT.ActorContainer().
                        setBounds(0,0,director.width,director.height).
                        setFillStyle('#000');

                scene.addChild(bg);

                // create a sprite image of 1 row by 6 columns
                var starsImage= new CAAT.SpriteImage().
                        initialize(director.getImage('stars'), 1,6 );

                var T= 1000;

                var mouseStars= function(mouseEvent) {

                    var actorStar= new CAAT.Actor().
                        // set background image to be a reference of a SpriteImage instance
                        // and set actor's size equal to a SpriteImage's subimage size
                            setBackgroundImage(
                                starsImage.getRef(), true ).
                        // set background as a random SpriteImage's subimage.
                            setSpriteIndex( (Math.random()*6)>>0 ).
                        // center the actor on mouse position
                            centerOn( mouseEvent.x, mouseEvent.y).
                        // when the actor expires, remove in from the director
                            setDiscardable(true).
                        // avoid mouse event handling.
                            enableEvents(false).
                        // make this actor last to T milliseconds (1000)
                            setFrameTime(scene.time, T).
                        // add a scaling behavior
                            addBehavior(
                                new CAAT.ScaleBehavior().
                                    setFrameTime(scene.time, T).
                                    setValues( 1,5, 1,5 ).
                                    setInterpolator(
                                        new CAAT.Interpolator().createExponentialInInterpolator(
                                            3,
                                            false)
                                    )
                            ).
                        // add an alpha behavior so the actor takes 1000 ms to fade out to zero alpha
                            addBehavior(
                                new CAAT.AlphaBehavior().
                                    setFrameTime(scene.time, T).
                                    setValues( 1, 0 ) );

                    // add the actor.
                    bg.addChild(actorStar);
                };

                // set background's mouse handlers.
                bg.mouseMove= mouseStars;
                bg.mouseDrag= mouseStars;
            }

            function __init()   {

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

                new CAAT.ImagePreloader().loadImages(
                    [
                        {id:'stars',    url:'../demos/demo-resources/img/stars.png'}
                    ],
                    function( counter, images ) {
                        director.setImagesCache(images);
                        __scene(director);
                    }
                );

                CAAT.loop(60);
            }

            __init();