cacheAsBitmap (MovieClip.cacheAsBitmap property) -- Version 8

If set to true, Flash Player caches an internal bitmap representation of the movie clip. This can increase performance for movie clips that contain complex vector content.

All vector data for a movie clip that has a cached bitmap is drawn to the bitmap instead of to the main Stage. The bitmap is then copied to the main Stage as unstretched, unrotated pixels snapped to the nearest pixel boundaries. Pixels are mapped one to one with the parent object. If the bounds of the bitmap change, the bitmap is recreated instead of being stretched.

No internal bitmap is created unless the cacheAsBitmap property is set to true.

After you set a movie clip's cacheAsBitmap property to true, the rendering does not change, however the movie clip performs pixel snapping automatically. The animation speed can be significantly faster, depending on the complexity of the vector content.

The cacheAsBitmap property is automatically set to true whenever you apply a filter to a movie clip (when its filter array is not empty). If a movie clip has a filter applied to it, cacheAsBitmap is reported as true for that movie clip, even if you set the property to false. If you clear all filters for a movie clip, the cacheAsBitmap setting changes to what it was last set to.

In the following cases a movie clip does not use a bitmap even if the cacheAsBitmap property is set to true, and instead renders the movie clip from vector data:

The cacheAsBitmap property is best used with movie clips that have mostly static content and that do not scale and rotate frequently. With such movie clips, cacheAsBitmap can lead to performance increases when the movie clip is translated (when its x and y position is changed).

Example

The following example applies a drop shadow to a movie clip instance. It then traces the value of the cacheAsBitmap property which is set to true when a filter is applied.

import flash.filters.DropShadowFilter;

var container:MovieClip = setUpShape();
trace(container.cacheAsBitmap); // false
var dropShadow:DropShadowFilter = new DropShadowFilter(6, 45, 0x000000, 50, 5, 5, 1, 2, false, false, false); 
container.filters = new Array(dropShadow);
trace(container.cacheAsBitmap); // true

function setUpShape():MovieClip {
    var mc:MovieClip = this.createEmptyMovieClip("container", this.getNextHighestDepth());
    mc._x = 10;
    mc._y = 10;
    var w:Number = 50;
    var h:Number = 50;
    mc.beginFill(0xFFCC00);
    mc.lineTo(w, 0);
    mc.lineTo(w, h);
    mc.lineTo(0, h);
    mc.lineTo(0, 0);
    mc.endFill();
    return mc;
}

Comments

ShawnJC said on Sep 13, 2005 at 8:10 PM :

It would be nice to include a generic example of turning cachAsBitmap on/off as well as the example to apply a filter to the movieClip, since this is the main place I went to see how to use cacheAsBitmap.

Jay4 said on Sep 15, 2005 at 3:21 PM :

Hello ShawnJC, an example of this can be found in the Flash Samples section of the Flash Help system. Navigate to Flash Samples > ActionScript > Bitmap caching with ActionScript, or visit http://livedocs.macromedia.com/flash/8/main/00001077.html.

Brian Sexton said on Oct 2, 2005 at 10:59 AM :

> If set to true, Flash Player caches an internal bitmap representation of the movie clip.

It would be nice to see some more information posted about the extent of that caching: When set to true for a MovieClip, does cacheAsBitmap result in every frame of that MovieClip being cached, only the first frame, or perhaps something else?

No screen name said on Oct 5, 2005 at 5:48 PM :

Can I export bitmap data to an application outside of the FlashPlayer in any way?

rhodesbe said on Nov 11, 2005 at 8:51 AM :

Be careful, I've found that using cacheAsBitmap with a Mask can cause artifacts to occur in your movie.

Check out my post on FlashKit for full explanation:
http://www.flashkit.com/board/showthread.php?t=659058

FraMais said on Dec 15, 2005 at 3:49 AM :

I think the difference between "cacheAsBitmap" and "use runtime bitmap chaching" (in the Flash Properties panel) is not very clear. Does cacheAsBitmap work on runtime too or on compile-time?

No screen name said on Apr 26, 2007 at 10:58 AM :

found through testing, if you apply "cacheAsBitmap = true" to a movie
clip, you have to set "cachAsBitmap = false" before removing the movie
clip. Otherwise the movie clip stays in memory.... boo.

dzedward said on May 9, 2007 at 8:45 AM :

im using this to mask a movie clip, it doesnt mover or anything, is only to create a reflection type affect...but it doesnt work in IE..works fine in firefox and safari

feodor.org said on May 30, 2007 at 3:25 AM :

Is it possible to work with a cached bitmap as with bitmapData?
Why not? Is it possible in Flash 9?

cacheAsBitmap (MovieClip.cacheAsBitmap property)

Example

See also

Comments