Graphics Management with Bitmap Sheets

Introduction

This tutorial is a loose follow-up to an article I wrote detailing how to maximise render performance for the iPhone Packager. It outlined, with some simple examples, the use of bitmap sheets to load and render bitmap images as opposed to using Flash’s vector rendering engine.

I had also written an ActionScript 3 library to handle the loading and management of bitmap sheets, but due to the limited scope of the original article it wasn’t actually covered.

With Apple lifting their restrictions on the Packager for iPhone, and Adobe releasing both Flash Player 10.1 and AIR for Android, the use of bitmaps within Flash projects is once again a hot topic. I therefore felt the time was right to release my bitmap sheet library and detail how to use it.

I’ll lead you through the steps required to load bitmap sheets and detail how to obtain the data used to represent each of the bitmaps within the sheets.

If you understand the concepts involved and/or are a competent developer then you may actually want to skip the detailed steps and simply jump to the installation instructions and then onto the code examples at the end of this tutorial. There are also some more complete code examples bundled along with the library.

Requirements

To make the most of this tutorial, you’ll need the following software and files:

• Flash Professional CS5
• The bitmap sheet library: bitmap_sheet_library.zip

Installing the Code Library

To publish and run the code examples within this tutorial you will need to add the code library to your FLA’s publish settings.

1. Unzip bitmap_sheets_library.zip to your local drive.
2. From your current FLA file, select File | Publish Settings...
3. From the Publish Settings pane, select the Flash tab.
4. Ensure that the Script version is set to ActionScript 3.0.
5. Click on the Settings... button next to the Script version.
6. From within the Advanced ActionScript 3.0 Settings pane, click on the Library path tab.
7. Click on the Browse to SWC file, browse to, and select the bitmap_sheets.swc file.
8. Click OK to exit from the Advanced ActionScript 3.0 Settings pane.
9. Click OK to exit from the Publish Settings pane.

Working with Bitmap Sheets

So you’ve created a sheet of bitmaps that you’d like to cut-out and store in memory. Here’s how a typical bitmap sheet might look.

It’s a simple 2 x 2 grid-shaped layout with each image covering 268 x 268 pixels. For the purpose of this tutorial let’s assume that the bitmap sheet is saved relative to your FLA at bitmap_sheets/monkey_sheet.png.

The following code will load the bitmap sheet and specify a rectangular region for each of its images. The code will also assigned a name to each image that you can use at a later date to quickly retreive a particular image’s bitmap data.

import com.ccaleb.utils.gfx.BitmapSheet;
import com.ccaleb.utils.gfx.Rectangles;
import com.ccaleb.utils.gfx.Names;
import flash.events.Event;
import flash.net.URLRequest;
 
var bs :BitmapSheet = new BitmapSheet();
bs.setRegions(
    new <Rectangle>[
        new Rectangle( 0, 0, 268, 268 ),  new Rectangle( 268, 0, 268, 268 ),
        new Rectangle( 0, 268, 268, 268 ), new Rectangle( 268, 268, 268, 268 ) ],
    new <String>[ "monkey1", "monkey2", "monkey3", "monkey4" ]
);
bs.addEventListener( Event.COMPLETE, loaded );
bs.load( new URLRequest( "bitmap_sheets/monkey_sheet.png" ) );
 
function loaded( e :Event ) :void
{
    trace( "The bitmap sheet has been loaded." );
}

The steps required to set-up and load a bitmap sheet are fairly straight forward and are listed below:

1. Create a BitmapSheet instance.
2. Specify the regions to cut-out from the sheet and give each region a unique name.
3. Add event listeners to the BitmapSheet instance.
4. Load the bitmap sheet.

Let’s look at the code in more detail.

Creating a BitmapSheet Instance

For every bitmap sheet you wish to load, create a separate instance of the BitmapSheet class. This tutorial’s example code creates an instance and assigns it to a local variable name bs:

var bs :BitmapSheet = new BitmapSheet();

Remember to import the BitmapSheet class before using it. Its fully qualified class name is com.ccaleb.utils.gfx.BitmapSheet.

Specify the Regions

As stated, the bitmap sheet contains 4 bitmaps, with each consuming a 40 x 40 rectangular region. The bitmaps are contained within a 2 x 2 grid-like layout. The rectangular regions representing each of these bitmaps should be passed to your BitmapSheet instance. Each bitmap should also be assigned a unique string identifier. The code below illustrates this:

bs.setRegions(
    new <Rectangle>[
        new Rectangle( 0, 0, 268, 268 ),  new Rectangle( 268, 0, 268, 268 ),
        new Rectangle( 0, 268, 268, 268 ), new Rectangle( 268, 268, 268, 268 ) ],
    new <String>[ "monkey1", "monkey2", "monkey3", "monkey4" ]
);

The code above declares to your BitmapSheet instance that your bitmap sheet is cut into the following named rectangular regions:

monkey1: (   0,   0 ) to ( 268, 268 )
monkey2: ( 268,   0 ) to ( 536, 268 )
monkey3: (   0, 268 ) to ( 268, 536 )
monkey4: ( 268, 268 ) to ( 536, 536 )

Don’t get confused by Flash’s Rectangle class. The first two parameters specify the x and y position of the top-left corner of the rectangle. The last two parameters specify the width and height of the rectangle.

Therefore new Rectangle( 268, 268, 268, 268) represents a rectangle with a top-left corner of( 268, 268 ) and a bottom right-hand corner of ( 536, 536 ).

Adding Event Listeners

You need to be notified when the bitmap sheet has been loaded, so remember to listen for the COMPLETE event that gets dispatched:

bs.addEventListener( Event.COMPLETE, loaded );

The line of code above makes a call to a method named loaded() once the bitmap sheet has been loaded. The loaded() method is shown below:

function loaded( e :Event ) :void
{
    trace( "The bitmap sheet has been loaded." );
}

Load the Bitmap Sheet

The final thing to do is make a call to the load() method:

bs.load( new URLRequest( "bitmap_sheets/monkey_sheet.png" ) );

The bitmap will be loaded and the regions will be stored with the sheet.

It’s also possible, and is probably more desirable, to load a bitmap sheet that is sitting within the library of the Flash IDE.

Using Flash Professional CS5, import a bitmap into your library and right-click on it. From the context menu select Properties... From the Bitmap Properties panel that appears, click on the ActionScript tab. Click on Export for ActionScript and enter a unique class name you’d like to assign to the bitmap.

For example, if you assigned the class name MonkeySheet to the bitmap then the following line of code would load it into your bitmap sheet instance:

bs.load( new MonkeySheet() );

One important thing to note. The bitmap sheet has not yet been cut into separate regions yet. The code that has been written so far only loads the sheet and stores the information required to cut-up the bitmap sheet. We’ll cover cutting-up the bitmap sheet soon enough, but first let’s back track a little.

Generating Regions

Take a look at the code required to specify the regions again:

bs.setRegions(
    new <Rectangle>[
        new Rectangle( 0, 0, 268, 268 ),  new Rectangle( 268, 0, 268, 268 ),
        new Rectangle( 0, 268, 268, 268 ), new Rectangle( 268, 268, 268, 268 ) ],
    new <String>[ "monkey1", "monkey2", "monkey3", "monkey4" ]
);

It certainly isn’t a lot of code but it could be if the bitmap sheet contained many more regions. For example a 10 x 10 grid would require 100 Rectangle objects to be specified and would be prone to error when typing out the data.

There are helper classes to help generate the vector array of Rectangle objects and name strings.

Let’s start with the vector array of Rectangle objects. A helper class called Rectangles is available that can be used to generate your vector array.

The Rectangles class provides a static method named create() that generates and returns the vector array. The method expects the following four parameters:

• The width of each rectangle.
• The height of each rectangle.
• The horizontal rectangle count.
• The vertical rectangle count.

Therefore the vector array of Rectangle objects from the code example above could be replaced with the following:

Rectangles.create( 268, 268, 2, 2 )

Remember to import the Rectangles class before using it. Its fully qualified class name is com.ccaleb.utils.gfx.Rectangles.

Generating Names

Generating a unique name for each bitmap is also fairly easy and again saves time and reduces the chance of errors being introduced.

This time use the Names class, which has its own static create() method. It expects the following 3 parameters:

• The number of names to generate.
• The base string to use for each name.
• The start index to use when appending a unique number to each name.

The previous code example had the following string names explicitly listed:

• monkey1, monkey2, monkey3, monkey4

We want to generate four names, therefore the first argument to pass to create() is 4. Each name contains the string monkey, which is what will be passed as the second argument. The first name is appended with the number one, meaning 1 should be passed as the third argument.

Therefore we could replace the vector array of string objects from the code above with the following:

Names.create( 4, "monkey", 1 );

Again, remember to import the class before using it. Its fully qualified name is com.ccaleb.utils.gfx.Names.

The final version of the setRegions() call is shown below:

bs.setRegions(
    Rectangles.create( 268, 268, 2, 2 ),
    Names.create( 4, "monkey", 1 )
)

Using the Rectangle and Names helper classes helps produce, not only compact, but reliable code.

Working with the Bitmap Library

Okay, so we have a sprite sheet but it’s still to be chopped up and stored in memory. The BitmapLibrary class will help here.

Put simply, you pass bitmap sheets to the bitmap library and it breaks each sheet into a collection of bitmaps that you can access via the library. You can access a bitmap by using the unique name you assigned to it or by using its index position within the library.

The following code creates a bitmap library and feeds it the bitmap sheet created previously:

import com.ccaleb.utils.gfx.BitmapLibrary;
 
var bl :BitmapLibrary = new BitmapLibrary();
bl.addBitmapSheet( bs );
 
bs.destroy();
bs = null;

You can add as many bitmap sheets as you like to the library. Each will be cut into bitmaps and stored internally within the library. Notice that the bitmap sheet is destroyed after it has been passed to the bitmap library. After the library has cut-out the bitmaps the sheet is no longer required and can be freed from memory.

Accessing the bitmap data

There are various ways you can access the bitmap data from a bitmap manager:

• Using the unique name assigned to the bitmap data.
• Using the bitmap data’s index position within the bitmap manager.

Using an index position to access the bitmap data is faster but a bitmap’s index position isn’t always easy to know. Let’s look at using the bitmap’s unique name first:

var bmData :BitmapData = bl.getBitmapData( "monkey1" );

The line above retrieves a reference to the bitmap data associated with monkey1.

The monkey1 bitmap was the first region in this tutorial’s bitmap sheet. Therefore we know its index position within the bitmap library will be 0 and its bitmap data can be accessed like this:

var bmData :BitmapData = bl.getBitmapData( 0 );

Of course in a more complex application it may not be wise to assume the position of a bitmap within the bitmap library. You could of course query the bitmap library for certain index positions and then use those values at a convenient time. The getIndex() method provides this functionality and its use is shown below where a looping monkey animation is created:

// Store the index positions for the first and last frames.
var firstFrameIndex :int = bl.getIndex( "monkey1" );
var lastFrameIndex  :int = bl.getIndex( "monkey4" );
var currFrameIndex  :int = firstFrameIndex;
 
// Create a monkey sprite.
var monkey :Bitmap = new Bitmap();
monkey.x = 100;
monkey.y = 100;
monkey.bitmapData = bl.getBitmapData( currFrameIndex );
monkey.addEventListener( Event.ENTER_FRAME, updateMonkey );
 
addChild( monkey );
 
// Update the monkey animation.
function updateMonkey( e :Event ) :void
{
    if( ++currFrameIndex > lastFrameIndex )
    {
        currFrameIndex = firstFrameIndex;
    }
 
    monkey.bitmapData = bl.getBitmapData( currFrameIndex );
}

Directly Accessing Bitmap Data

As a final option, you can directly access the vector array that is used to store the BitmapData objects. This provides the fastest access and is done via the public bitmaps property:

var bmData :BitmapData = bl.bitmaps[ 0 ];

The line of code above accesses the very first item stored in the library.

It’s also possible to determine the total number of items in the bitmap library and access the last one:

var count :uint = bl.bitmaps.length;
var bmData :BitmapData = bl.bitmaps[ count - 1 ]; // Remember: zero-indexing.

Where to Go From Here

You should now be ready to use the bitmap management API within your own ActionScript 3 projects. You may find this API particularly useful for iPhone and Android mobile development where bitmap intensive tasks can be passed to the device’s GPU for improved performance over complex vector shapes.

The following resources may also be of interest to you and help with the concepts discussed in this tutorial:

• Packager for iPhone: Render Perfomance
• Optimizing Performance for the Flash Platform
• Give me a MovieClip I’ll give you a sequence of Bitmaps!

For slightly more complete examples take a look at the section below.

Examples

Example 1

The following code loads a bitmap sheet that represents a 2 x 4 grid of 40 x 20 pixel regions. The regions will be named croc/snap2 to croc/snap9.

import com.ccaleb.crocdare.gfx.BitmapSheet;
import com.ccaleb.utils.gfx.Rectangles;
import com.ccaleb.utils.gfx.Names;
import flash.net.URLRequest;
import flash.events.Event;
import flash.events.IOErrorEvent;
 
var bs :BitmapSheet = new BitmapSheet();
bs.setRegions(
    Rectangles.create( 40, 20, 2, 4 ), // 2 x 4 grid of 268 x 268 pixel regions.
    Names.create( 8, "croc/snap", 2 )  // Creates "croc/snap2" to "croc/snap9".
);
bs.addEventListener( Event.COMPLETE, loaded );
bs.addEventListener( IOErrorEvent.IO_ERROR, loadError );
 
try
{
    bs.load( new URLRequest( "sprites/croc_sheet.png" );
}
catch( e :ArgumentError )
{
    trace( e.message );
}
 
function loaded( p_event :Event ) :void
{
    trace( "bitmap data: " + p_event.target.bitmapData );
}
 
function loadError( p_event :Event ) :void
{
    trace( "failed to load." );
}

Example 2

Adds a bitmap sheet to the bitmap library.

import com.ccaleb.crocdare.gfx.BitmapSheet;
import com.ccaleb.utils.gfx.BitmapLibrary;
import com.ccaleb.utils.gfx.errors.InvalidBitmapSheetError;
import com.ccaleb.utils.gfx.errors.DuplicateBitmapNameError;
 
var bl :BitmapLibrary = new BitmapLibrary();
 
try
{
    bl.addBitmapSheet( bitmapSheet );
}
catch( e : DuplicateBitmapNameError )
{
    trace( e.message );
    return;
}
catch( e :InvalidBitmapSheetError )
{
    trace( e.message );
    return;
}
 
trace( "Number of bitmaps in library: " + bl.bitmaps.length );
trace( "Index of bitmap 'croc4' is: " + bl.getIndex( "croc4" ) );

Example 3

Various ways of accessing the same bitmap data.

// Assuming croc3 is the 3rd item in the library.
var bmData :BitmapData = bl.getBitmapData( "croc3" );
bmData = bl.getBitmapData( 2 );
bmData = bl.bitmaps[ bl.getIndex( "croc3" ) ];
bmData = bl.bitmaps[ 2 ];

Acknowledgements

A big thanks to Steve Koran for his great concept drawings of Dare the monkey.