Blitting and caching movie clips in Flash

Blitting is a higher-performance alternative to using the built-in display list in Adobe Flash for drawing objects on the Stage. This technique involves copying the individual pixels of an existing image directly on to the screen—a bit like painting all of your game's spaceships and monsters onto a canvas.

Working manually with pixels is more complicated than using the display list, but the improvement in performance more than makes up for the extra effort. For situations where there are many objects moving around the Stage, you must usually choose either a smooth frame rate or a small memory footprint. With blitting you can have both.

The basic concepts of blitting are covered in Rendering game assets in ActionScript using blitting techniques and Flash Builder 4 by Renaun Erickson. In this tutorial, you'll learn how to cache an animated movie clip symbol as an array of bitmaps and then blit it to the screen, all within the Flash authoring environment.

Note: Throughout this tutorial, I use the term global to refer to any public instance variable that is defined outside of all functions and whose scope is the entire document class.

To start, you'll need a movie clip on the Stage. Think of it as an artist's reference:

1. Download the sample ZIP file and extract it to your hard drive.
2. Open Blitting.fla in your Flash authoring environment. Its document class is set to the DocumentClass.as file and its library contains an animated movie clip called BlockFace.
3. Open DocumentClass.as, create a new global BlockFace instance, and add it to the left side of the Stage. Your code should look like this:

Note: Code changes are highlighted as shown.

4. Save the file and choose Control > Test Movie to test the movie and make sure it is working (see Figure 1).

5. Prepare a canvas to which you can blit copies of this face (a canvas is just a rectangular Bitmap object filled with a single color). Here is the new code:

If you test the movie now, you'll see no visible change to the SWF yet. Bitmaps don't contain pixels themselves, BitmapData objects do. Bitmaps merely display the pixels that are inside a given BitmapData object.

6. Create a BitmapData object, fill it with a solid color, and link the canvas bitmap to it:

7. Test the movie; you'll see that the gray canvas takes up the whole Stage and covers the movie clip.
8. To get around this for now, just move it 275 pixels to the right by replacing this:

with the following:

9. Save your changes and test the movie (see Figure 2).

Blitting the movie clip to the canvas

There are two steps involved in actually blitting an object to the canvas. Essentially, you just draw an image of whatever you want to blit into a new BitmapData object, and then copy the pixels from that object on to the canvas:

1. Create a new BitmapData object to hold an image of BlockFace, and draw an image of the BlockFace instance into this object. Your DocumentClass() function should now look like this:

2. The next step is to copy the pixels from this BitmapData object into the canvas's BitmapData object. The function for this is called copyPixels (appropriately enough) and requires three arguments:
   • The BitmapData object to copy from
   • A Rectangle that defines the region of that BitmapData to copy
   • A Point that defines where to position the copied pixels
3. Create a Rectangle that's the same width and height as blockFace so that the entire image is copied.
4. Define a Point to specify the desired location of the blitted image.
5. Call the copyPixels() function on your canvas's BitmapData. Your DocumentClass() function will now look like this:

6. Add import flash.geom.Point up at the top of your code with the other import statements.
7. Save your changes and test your movie; you'll see two faces (see Figure 3).

Animating the blitted image

This is a good start. However, since you blitted the image just once, only the left face animates. The blitted face doesn't animate for the same reason the screenshots in this tutorial don't animate: the pixels were copied at a specific moment, and they aren't being changed over time.

If you blit the face every frame, it will animate exactly like the movie clip. The easiest way to do that is to move all the blitting code to an ENTER_FRAME event handler:

1. Import the Event class by adding the following line up at the top of the code with the other import statements:

2. Add a new ENTER_FRAME event listener in the constructor by adding the following line just after the line that calls canvasBitmapData.copyPixels():

3. Create the corresponding event handler and move all the blitting code into it (delete the matching lines from the DocumentClass() function):

4. Run your SWF now, and you'll see both faces animate in unison. So far, so good—but there's a small problem. Each image is being blitted over the previous image.
5. Add the following line right at the end of your onEnterFrame function:

6. Save the change and test your movie (see Figure 4).

Because the blitted image is being copied on top of the old pixels each time, you can still see the old image beneath it. As explained in Renaun's article, you can fix this by simply repainting the whole canvas gray at the start of each frame.

7. Use the same fillRect call you used earlier to paint the entire canvas gray; add the following line at the start of your onEnterFrame() function:

Good, that fixes it. Now that you know it's not an issue anymore, you can remove the line that moves the face every frame.

8. Delete blockFace.y = blockFace.y + 1; from onEnterFrame().

Creating multiple copies

How about blitting a couple more copies of the face to the canvas? All you need to do is duplicate the actual blitting code from your onEnterFrame() function and change the positions of the new faces:

This is a clumsy way of doing it. Flash will give you a few warnings about duplicate variable definitions but it will compile a working SWF nonetheless (see Figure 5).

The method used to animate the three faces is messy and far from optimal, so in this section you'll learn how to cache these objects, saving the pixels from the original BlockFace movie clip so that you don't have to draw them to three BitmapData objects every single frame.

Removing unnecessary repetition

If you read through that duplicated code in the onEnterFrame() function, you'll see that there are two parts of the code that don't need to be copied and pasted.

The first is the section below, in which the BlockFace object gets drawn to the BitmapData object:

The second part is the code that defines the rectangle of pixels to copy from the BlockFace object's BitmapData:

Delete the second and third occurrences of these lines of code so that they are run only once per frame. This won't affect the SWF, and by removing them you can eliminate the Flash compiler warnings they generated. Also change the second and third instances of var destinationPoint:Point to simply destinationPoint.

The onEnterFrame() event handler should now look like this:

In fact, you could even move the code concerning areaRectangle into the constructor, rather than having it run every single frame.

What else could be removed? Well, you have to repaint the canvas every frame to stop the trail effect, so that has to stay. Likewise destinationPoint has to be set once for each blitted face and must be updated every frame in case the original face moves, so that has to be kept too.

The rest of the code handles the actual copying of the pixels from the original face to the canvas and it has to be repeated. Obviously that can't be changed or you wouldn't see anything. Or can it?

Remember, that section of the code is in two parts—the pixels aren't copied directly from the face to the canvas. First, the face is drawn onto the BitmapData object as a bunch of pixels; second, the pixels are copied from this BitmapData object onto the canvas. The second part cannot be removed, but the first part could certainly be improved.

Instead of drawing the face to the BitmapData object every frame, you could create a number of BitmapData objects in the constructor and draw one frame of the face's animation to each of them. Then, all the onEnterFrame() function has to do is select the correct BitmapData object and copy the pixels from it to the canvas! That involves more work in the constructor function but it really cuts down on the work done each frame. Even better, it means you can remove the BlockFace movie clip, so Flash Player won't have to render it each frame and all animation will be handled via blitting.

Caching the first frame

As a test, try caching only the first frame to begin with:

1. Move the following lines into the constructor function:

Now you've cached the pixels of the first frame of the animation to blockFaceBitmapData; you're no longer drawing them from the BlockFace movie clip every frame.

2. You will need to change blockFaceBitmapData into a global variable, of course, or the code in the onEnterFrame function won't be able to access it.
3. While you're at it, you may as well do the same thing with the lines that set up the areaRectangle.
4. Remember to change areaRectangle to a global variable as well. Your code will then look like this:

The blitted faces will all appear (and they'll even move with the original face if you re-insert the line that moves it), but since you've only cached one frame, none of them animates. The next step, then, is to cache all of the frames.

Caching the entire movie clip

Rather than manually create dozens of individual BitmapData objects, you can use an array and a loop to automate the process:

1. Create a new global array by inserting the highlighted line right after the line that defines the document class:

2. Add the following line after the addChild(canvasBitmap); call:

You'll use this array to hold a number of BitmapData objects, one for each frame of the BlockFace movie clip.

3. Create a loop that iterates through all the frames in the BlockFace movie clip, draws each frame to a new BitmapData object (using the code you just moved into the constructor), and adds this object to the array. Here's what the code will look like:

You now have an array in which each element is a BitmapData object containing a frame of animation. Next, you need to get these BitmapData objects back out of the array and blit them to the canvas.

4. Add the following line to the start of your onEnterFrame() function:

It's very important to subtract 1 from the animation's current frame, since the first frame of an animation is numbered 1 but the first element of an array is numbered 0. Otherwise, when the animation reaches the last frame, there'll be no corresponding element in the array and you'll get an error.

5. Change the three lines that call copyPixels() so that they reference this new BitmapData object; for example:

6. Test the SWF (see Figure 6).

Success! All the faces animate.

Removing the MovieClip from the display list

Now that the blitted faces are animating from a cache, the original movie clip can be removed from the Stage and Flash Player won't have to render it anymore. However, there are a couple of references to blockFace in the onEnterFrame() function that you'll have to eliminate.

First, the code picks which element of the array to use based on the current frame of the movie clip, so you need to store this in another way:

1. Create a global integer variable to hold the current frame by inserting the highlighted line right after the line that defines the document class:

2. Alter your onEnterFrame() function to use this new variable rather than blockFace.currentFrame:

Note that all the destinationPoint objects are based on the location of blockFace. You can remove this reference by using exact numbers.

3. Replace this:

with the following line:

4. Replace this:

with the following line:

5. Replace this:

with the following line:

Finally, there are no references to blockFace outside the constructor.

6. Delete the addChild(blockFace) line and add the following line at the very end of the constructor function (this proves that it is no longer used elsewhere):

7. Test the SWF (see Figure 7).

All that's left to do now is move the canvas to its rightful place at the left edge of the screen:

1. Replace canvasBitmap.x = 275; with canvasBitmap.x = 0;.
2. If you want, you can change the canvas color to white by using the color code 0xFFFFFFFF instead of 0xFFDDDDDD.
3. You can also declare the blockFace and blockFaceBitmapData variables in the constructor, since they no longer need to be accessed anywhere else.

Where to go from here

Congratulations! You've managed to manually render and animate a movie clip that was created in Flash by manipulating the individual pixels. OK, so the final result doesn't look like anything you couldn't have achieved using the standard display list, but you've learned a powerful technique that will enable you to improve performance when you need to create more complex animations.

There is much more to blitting than I've covered in this article. Not all situations will be as simple as the example presented here. For example, if you want to cache the animation of a movie clip with varying frame sizes, you'll need to figure out the largest width and height of all the frames and create your BitmapData object at this size. If your movie clip's registration point is not at the top-left corner, you'll need to pass a transform matrix to the draw() function of your BitmapData.

You lose some functionality when blitting, too. Rotating and scaling is tricky; usually the best option is to precache all the frames multiple times, at all the different rotations and scales you'll need. Consider also that the display list allows you to rearrange the z-order of objects, automatically stop/start/skip animations, use 9-slice scaling, and so on. If you need any of this functionality when blitting, you'll have to code it yourself.

On the other hand, blitting allows for some cool graphical effects. For instance, if you apply a 10% fade to your canvas every frame instead of repainting it with a blank background, that trail goes from being an annoying bug to a cool feature.

It's important to remember that blitting is just one tool in your toolbox. Sometimes it will turn out to be the best choice (especially when you need to render a large number of objects and move them around the screen) but sometimes the flexibility of the display list will make that the better choice instead.

Here are some great resources for further reading:

• Ginger: ActionScript 3 bitmap animation engine
• Flixel: ActionScript 3 blit-based game development engine
• Bitmap programming: Chapter 26 of Essential ActionScript 3 by Colin Moock (O'Reilly Media, 2007)
• ActionScript 3 animation blog series: Excellent resource from 8bitrocket, on which much of this tutorial was based