Flash CS3 Documentation

ActionScript 2.0 Language Reference > ActionScript classes > Button > cacheAsBitmap (Button.cacheAsBitmap property)

cacheAsBitmap (Button.cacheAsBitmap property)

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

For a button that has cacheAsBitmap set to true, Flash Player stores a bitmap representation for each of the four button states.

All vector data for a button that has a cached bitmap is drawn to the bitmap instead of 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 button's cacheAsBitmap property to true, the rendering does not change; however, the button 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 button (when its filter array is not empty), and if a button has a filter applied to it, cacheAsBitmap is reported as true for that button, even if you set the property to false. If you clear all filters for a button, the cacheAsBitmap setting changes to what it was last set to.

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

• When the bitmap is too large, that is, greater than 2880 pixels in either direction
• When the bitmap fails to allocate memory (due to an out of memory error)

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

Availability: ActionScript 1.0; Flash Player 8

Example

The following example applies a drop shadow to an existing Button instance named myButton. It then traces out the value of cacheAsBitmap, which is set to true when a filter is applied.

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

Flash CS3