Recipe 10.5. Applying Basic Filters

Problem

You want to apply basic filters such as drop shadows, blurs, glows, and bevels.

Solution

Construct a new filter object and assign it to the filters array of a display object.

Discussion

The flash.filters package contains the following basic filter classes: DropShadowFilter, BlurFilter, GlowFilter, BevelFilter, GradientGlowFilter, and GradientBevelFilter. We distinguish the preceding list as basic filters because they don't require additional display objects to apply as part of surface mapping or matrices to apply for complex transforms. Each of the basic filter classes consist of fairly straightforward properties that have straightforward effects on the display objects to which the filters are applied. For example, the DropShadowFilter class allows you to change the drop shadow offset, color, and the amount of blur applied to the shadow by way of properties (and parameters passed to the constructor).

Since basic filters are discussed in the Flash and Flex documentation, we won't discuss unnecessary details of how to construct and change the basic properties of those classes.

Once you've constructed a filter object, you can apply it to a display object by using the object's filters property. The filters property is an array of filter objects. The following applies a drop shadow to a display object called sampleSprite:

sampleSprite.filters = [new DropShadowFilter(  )];

When you assign an array of filters to the filters property of a display object, the array is copied rather than referenced. That means that any changes to the array or the filters in the array won't have an effect on the display object until it has been reassigned, as shown in the following example:

var dropShadow:DropShadowFilter = new DropShadowFilter(  );
var sampleFilters:Array = [dropShadow];

// Applies the drop shadow.
sampleSprite.filters = sampleFilters;

// Change the color of the drop shadow to white. However, since the actual filter 
// applied to sampleSprite is a copy of dropShadow this doesn't have an effect
// on sampleSprite.
dropShadow.color = 0xFFFFFF;

// Add a glow filter to the array. However, since the array assigned to sampleSprite 
// is a copy of sampleFilters there is no effect on sampleSprite.
sampleFilters.push(new GlowFilter(  ));

// Reassign sampleFilters to the filters property of sampleSprite. Now the updates 
// to the drop shadow and the array (the addition of the glow filter) affect the 
// display object.
sampleSprite.filters = sampleFilters;

Likewise, when you read the value of the filters property for a display object, it always returns a copy of the filters array. That means you cannot use methods of the Array class directly with the filters property to add or remove filters.

var dropShadow:DropShadowFilter = new DropShadowFilter(  );

// Applies the drop shadow.
sampleSprite.filters = [dropShadow];

// This does not add a glow filter.
sampleSprite.filters.push(new GlowFilter(  ));

// Instead, you have to copy the current filters array, append the new filter, 
// and reassign the array.
var sampleFilters:Array = sampleSprite.filters;
sampleFilters.push(new GlowFilter(  ));
sampleSprite.filters = sampleFilters;

The effects of the filters property are cumulative such that each filter in the array is applied in sequence. For example, if the filters array has two elements, a drop shadow, and a glow filter, then the glow (since it is second in the array) is applied to the effect of the object with the drop shadow filter applied to it.

If you want to apply filters non-cumulatively, you have to apply each filter to a new copy of the display object. Consider the following example that applies a drop shadow and a glow filter to the same object. The glow filter is applied to the entire surface, including the drop shadow, which generally is not the intended effect, since in most cases you'd presumably want to apply all filter effects to the original shape rather than having them apply cumulatively.

var box:Sprite = new Sprite(  );
box.graphics.lineStyle(  );
box.graphics.beginFill(0xFFFFFF);
box.graphics.drawRect(0, 0, 100, 100);
box.graphics.endFill(  );
addChild(box);
box.filters = [new DropShadowFilter(10), new GlowFilter(  )];

The following draws two boxes, and applies the glow to one and a drop shadow filter to a copy with the knockout property set to TRue:

var box:Sprite = new Sprite(  );
box.graphics.lineStyle(  );
box.graphics.beginFill(0xFFFFFF);
box.graphics.drawRect(0, 0, 100, 100);
box.graphics.endFill(  );
var boxShadow:Sprite = new Sprite(  );
boxShadow.graphics.lineStyle(  );
boxShadow.graphics.beginFill(0xFFFFFF);
boxShadow.graphics.drawRect(0, 0, 100, 100);
boxShadow.graphics.endFill(  );
addChild(boxShadow);
addChild(box);
box.filters = [new GlowFilter(  )];
boxShadow.filters = [new DropShadowFilter(10, 45, 0, 1, 4, 4, 1, 1, false, true)];

The knockout property is available for the majority of the basic filters, and it applies the filter while hiding the original shape. For example, if you enable the knockout property for a drop shadow filter, the result is just the drop shadow without the original shape to which the filter was applied. This is useful in many scenarios, including when you want to composite several filters in a noncumulative manner, as in the preceding example. In the preceding example, the knockout property is set to TRue from the DropShadowFilter constructor. You can consult the documentation for each of the basic filters to learn about the exact parameters for the constructors.

The filters can be cleared from a display object by assigning an empty array or null to the filters property of the object:

sampleSprite.filters = [];