Built-in Rules for Bitmap Caching

Flash guides you through best practices of using bitmap caching through some built-in restrictions. Basically, Flash Player takes care of you by either turning on or turning off bitmap caching automatically in several important circumstances.

Size Limits

Because it can use excessive amounts of memory, bitmap caching will not work if the dimensions of a cached movie clip are larger (or become larger) than 2880 pixels in either width or height. Flash Player restricts you from using bitmap caching for larger-than-2880 bitmaps to minimize excessive memory use. Why? Because a 2880 x 2880 pixel movie clip that is cached will use up roughly 32MB of memory. Four of these cached movie clips with those same dimensions could potentially fill up a computer’s memory and crash the machine.

Filters

It is worth noting here, that if you apply a filter effect to a movie clip either in the Flash authoring environment or through ActionScript, then bitmap caching is automatically turned on, and the cacheAsBitmap property will always return true. This happens even if you turned bitmap caching off—either in the authoring environment or with ActionScript. To prove this, create a new movie clip, give it an instance name of scrollingMovieclip, and add the following code to the first frame of the main Timeline:

var blur=new flash.filters.BlurFilter(3,3,3); //Gaussian blur
 scrollingMovieclip.filters=[blur];
 trace(scrollingMovieclip.cacheAsBitmap); //outputs 'true' 

When all of the filters effects are removed from a movie clip, the cacheAsBitmap property will return to its previous state. So for example, if bitmap caching is turned off for a movie clip but it has filters applied to it, then removing all of those filters from the movie clip will turn bitmap caching off again:

scrollingMovieClip.filters=undefined; 
trace(scrollingMovieclip.cacheAsBitmap); //outputs 'false' 

Loading External Content

When you load an external Flash movie or image into a cached movie clip using ActionScript, bitmap caching is automatically turned off. This is because when Flash loads a movie clip, it totally resets it, deleting all variables inside it, removing all child movie clips, and setting all movie clip properties back to their default values.

To prove it, try the following code:

/* 
 This code fixes the onLoad bug, that is that 
anyMovieclip.onLoad event handler is deleted 
when loading external content into a movie clip
 */ 

 _global.s_onLoad=function(f)
 {
     if(onLoadManager == undefined)
     {
         _global.onLoadManager={}; 
    }
     onLoadManager[this] =f;
 } 

 _global.g_onLoad=function()
 {
     return onLoadManager[this];
 }

  MovieClip.prototype.addProperty('onLoad', g_onLoad, s_onLoad);

  this.createEmptyMovieClip("scrollingMovieclip",this.getNextHighestDepth());
 scrollingMovieclip.onLoad=function()
 {
 	trace(this.cacheAsBitmap); 
        //when the photo is loaded, show that bitmap caching was turned off
 } 

 scrollingMoveclip.cacheAsBitmap=true;
 scrollingMovieclip.loadMovie("photo.jpg"); 

Collision Detection

Finally, results from hit-testing code using MovieClip.hitTest will not be affected by bitmap caching, as hit-testing is still calculated based upon the vector data of a movie clip, not the generated bitmap that you actually see. To prove this, create a new movie clip and draw a circle inside it, drag it onto the first frame of the main Timeline, and give it an instance name of circle_mc. Now add the following code to the first frame of the main Timeline:

circle_mc.onMouseMove=function() 
{ 
	trace("hit: "+this.hitTest(_root._xmouse,_root._ymouse,true)); 
}
 circle_mc.cacheAsBitmap=true;