CAAT.Foundation.SpriteImage

This function creates the base object to hold Actor images. When setting a background image, if a plain call to diretor.getImage("img_name") is called, the result will be encapsulated in one instance of CAAT.SpriteImage.

The basic usage form, is to define a grid of subimages out of an image object. For example: var si= new CAAT.SpriteImage().initialize( director.getImage("img"), rows, columns ) will set an image as an array of rows*columns sub-images. After calling the method, the attributes spriteImage.singleWidth, spriteImage.singleHeight will give each subimage's dimension.

The way to assign an image to an actor is by calling actor.setBackgroundImage( si, resize );. If resize is true (default value), the actor size will be set to that of the sprite image subimage size. That means, for an image 200x200 pixels, and an spriteImage of 4x2, the actor will be resized to 200/2 by 200/4 pixels. The default subimage selected as actor image will the the zero index, or the first subimage.

From this point, you can select any of the SpriteImage subimages as actor background by calling actor.setSpriteIndex(index). index is a value in the rango 0..rows*columns-1.

You can share the same sprite image among different actors to save some resources. To do so, a call to actor.setBackgroundImage should be called the following way: actor.setBackgroundImage( spriteImage.getRef() );. Otherwise, when changing the spriteImage's sprite index, it will be changed for every actor.

A good feature of CAAT.SpriteImage actor, is the capability to define animation sequences. A call to actor.setAnimationImageIndex( [] ). The array parameter are index values to the SpriteImage's sub images. The combination of this method and actor.setChangeFPS( millis ) is a perfect fit to create sprite animations.

Another feature of an actor sprite image is the call to the method actor.setImageTransformation( value ). Values can be the following CAAT.Foundation.SpriteImage.

More initialization functions:

The previous functions are all (but the initialization) proxied to the SpriteImage instance through out the actor object instance. But there're more initialization methods.

SpriteImage.initializeFromMap( image, map ) defines an atlas image. The format of the map parameter is an object of the form:

                        {
                            id : {
                                x       : <number>,
                                y       : <number>,
                                width   : <number>,
                                height  : <number>
                            },
                            ...
                        }
                        

This output can be automatically generated with this tool. It can only be use to extract individual sprites out of an atlas image.

This function, assumes a sprite image of size 1 row, and chars.length columns. This function relies on the function spriteImage.initializeAsFontMap.

For example, this function could be called like: spriteImage.initializeAsMonoTypeFontMap( director.getImage("img"), "0123456789" ) to have defined a numbers font.

The resulting spriteImage, is initialized in a way so that a call to spriteImage.drawString( ctx, str, x, y ) can be performed. Characters in str that weren't defined in the initializeAsMonoTypeFontMap chars parameter won't be renderer on screen.

This function assumes a sprite image of 1 row and a number of non equal columns. The map parameter has the following structure:

                            [
                                c       : <char>,
                                width   : <number> // character width in pixels
                            ]