Creating and applying filters

Filters allow you to apply a range of effects to bitmap and display
objects, ranging from drop shadows to bevels and blurs. Each filter
is defined as a class, so applying filters involves creating instances
of filter objects, which is no different from constructing any other
object. Once you’ve created an instance of a filter object, it can
easily be applied to a display object by using the object’s
filters
property,
or in the case of a BitmapData object, by using the
applyFilter()
method.

Creating a filter

To create a
filter object, simply call the constructor method of your selected
filter class. For example, to create a DropShadowFilter object,
use the following code:

Although not shown here, the
DropShadowFilter()
constructor
(like all the filter classes’ constructors) accepts several optional
parameters that can be used to customize the appearance of the filter
effect.

Applying a filter

Once you've constructed a filter
object, you can apply it to a display object or a BitmapData object;
how you apply the filter depends on the object to which you’re applying
it.

Applying a filter to a display object

When you apply filter effects
to a display object, you apply them through the
filters
property.
The
filters
property of a display object is an
Array instance, whose elements are the filter objects applied to
the display object. To apply a single filter to a display object,
create the filter instance, add it to an Array instance, and assign
that Array object to the display object’s
filters
property:

import flash.display.Bitmap;
import flash.display.BitmapData;
import flash.filters.DropShadowFilter;
// Create a bitmapData object and render it to screen
var myBitmapData:BitmapData = new BitmapData(100,100,false,0xFFFF3300);
var myDisplayObject:Bitmap = new Bitmap(myBitmapData);
addChild(myDisplayObject);
// Create a DropShadowFilter instance.
var dropShadow:DropShadowFilter = new DropShadowFilter();
// Create the filters array, adding the filter to the array by passing it as
// a parameter to the Array() constructor.
var filtersArray:Array = new Array(dropShadow);
// Assign the filters array to the display object to apply the filter.
myDisplayObject.filters = filtersArray;

If you want
to assign multiple filters to the object, simply add all the filters
to the Array instance before assigning it to the
filters
property.
You can add multiple objects to an Array by passing them as parameters
to its constructor. For example, this code applies a bevel filter
and a glow filter to the previously created display object:

When you’re
creating the array containing the filters, you can create it using
the
new Array()
constructor (as shown in the previous
examples) or you can use Array literal syntax, wrapping the filters
in square brackets (
[]
). For instance, this line
of code:

var filters:Array = new Array(dropShadow, blur);

does
the same thing as this line of code:

var filters:Array = [dropShadow, blur];

If
you apply multiple filters to display objects, they are applied
in a cumulative, sequential manner. For example, if a filters array
has two elements, a bevel filter added first and a drop shadow filter
added second, the drop shadow filter is applied to both the bevel
filter and the display object. This is because of the drop shadow
filter’s second position in the filters array. If you want to apply
filters in a noncumulative manner, apply each filter to a new copy
of the display object.

If you’re only assigning one or a few
filters to a display object, you can create the filter instance
and assign it to the object in a single statement. For example,
the following line of code applies a blur filter to a display object
called
myDisplayObject
:

myDisplayObject.filters = [new BlurFilter()];

The
previous code creates an Array instance using Array literal syntax
(square braces), creates a BlurFilter instance as an element in
the Array, and assigns that Array to the
filters
property
of the display object named
myDisplayObject
.

Removing filters from a display object

Removing all filters from a
display object is as simple as assigning a null value to the
filters
property:

myDisplayObject.filters = null;

If
you’ve applied multiple filters to an object and want to remove
only one of the filters, you must go through several steps to change
the
filters
property array. For more information,
see
Potential issues for working with filters
.

Applying a filter to a BitmapData object

Applying a filter to a
BitmapData object requires the use of the BitmapData object’s
applyFilter()
method:

The
applyFilter()
method
applies a filter to a source BitmapData object, producing a new,
filtered image. This method does not modify the original source
image; instead, the result of the filter being applied to the source
image is stored in the BitmapData instance on which the
applyFilter()
method
is called.

How filters work

Display
object filtering works by caching a copy of the original object
as a transparent bitmap.

Once a filter has been applied to a display object, the runtime
caches the object as a bitmap for as long as the object has a valid
filter list. This source bitmap is then used as the original image
for all subsequently applied filter effects.

Each display object usually contains two bitmaps: one with the
original unfiltered source display object and another for the final
image after filtering. The final image is used when rendering. As
long as the display object does not change, the final image does
not need updating.

Potential issues for working with filters

There are several potential sources of confusion or trouble to
keep in mind when you’re working with filters.

Filters and bitmap caching

To apply a filter to a display object,
bitmap caching must be enabled for that object. When you apply a
filter to a display object whose
cacheAsBitmap
property
is set to
false
, the object’s
cacheAsBitmap
property
is automatically set to
true
. If you later remove
all the filters from the display object, the
cacheAsBitmap
property
is reset to the last value it was set to.

Changing filters at run time

If a display object already has one
or more filters applied to it, you can’t change the set of filters
by adding additional filters to or removing filters from the
filters
property
array. Instead, to add to or change the set of filters being applied,
you must make your changes to a separate array, then assign that
array to the filters property of the display object for the filters
to be applied to the object. The simplest way to do this is to read
the
filters
property array into an Array variable
and make your modifications to this temporary array. You then reassign
this array back to the
filters
property of the
display object. In more complex cases, you might need to keep a
separate master array of filters. You make any changes to that master
filter array, and reassign the master array to the display object’s
filters
property
after each change.

Adding an additional filter

The following code demonstrates the
process of adding an additional filter to a display object that
already has one or more filters applied to it. Initially, a glow filter
is applied to the display object named
myDisplayObject
;
later, when the display object is clicked, the
addFilters()
function
is called. In this function, two additional filters are applied
to
myDisplayObject
:

Removing one filter from a set of filters

If a display object has
multiple filters applied to it, and you want to remove one of the
filters while the other filters continue to be applied to the object,
you copy the filters into a temporary array, remove the unwanted
filter from that array, and reassign the temporary array to the
display object’s
filters
property. Several ways
to remove one or more elements from any array are described in
Retrieving values and removing array elements
.

The most straightforward situation is to
remove the top-most filter on the object (the last filter applied
to the object). You use the Array class’s
pop()
method
to remove the filter from the array:

// Example of removing the top-most filter from a display object
// named "filteredObject".
var tempFilters:Array = filteredObject.filters;
// Remove the last element from the Array (the top-most filter).
tempFilters.pop();
// Apply the new set of filters to the display object.
filteredObject.filters = tempFilters;

Similarly,
to remove the bottom-most filter (the first one applied to the object) you
use the same code, substituting the Array class’s
shift()
method
in place of the
pop()
method.

To remove a
filter from the middle of an array of filters (assuming that the
array has more than two filters) you can use the
splice()
method.
You must know the index (the position in the array) of the filter
you want to remove. For example, the following code removes the
second filter (the filter at index 1) from a display object:

// Example of removing a filter from the middle of a stack of filters
// applied to a display object named "filteredObject".
var tempFilters:Array = filteredObject.filters;
// Remove the second filter from the array. It's the item at index 1
// because Array indexes start from 0.
// The first "1" indicates the index of the filter to remove; the
// second "1" indicates how many elements to remove.
tempFilters.splice(1, 1);
// Apply the new set of filters to the display object.
filteredObject.filters = tempFilters;

Determining a filter’s index

You need to know which filter to remove
from the array, so that you know the index of the filter. You must
either know (by virtue of the way the application is designed),
or calculate the index of the filter to remove.

The best approach
is to design your application so that the filter you want to remove
is always in the same position in the set of filters. For example,
if you have a single display object with a convolution filter and
a drop-shadow filter applied to it (in that order), and you want
to remove the drop-shadow filter but keep the convolution filter,
the filter is in a known position (the top-most filter) so that
you can know ahead of time which Array method to use (in this case
Array.pop()
to
remove the drop-shadow filter).

If the filter you want to
remove is always a certain type, but not necessarily always in the
same position in the set of filters, you can check the data type
of each filter in the array to determine which one to remove. For
example, the following code determines which of a set of filters
is a glow filter, and removes that filter from the set.

// Example of removing a glow filter from a set of filters, where the
//filter you want to remove is the only GlowFilter instance applied
// to the filtered object.
var tempFilters:Array = filteredObject.filters;
// Loop through the filters to find the index of the GlowFilter instance.
var glowIndex:int;
var numFilters:int = tempFilters.length;
for (var i:int = 0; i < numFilters; i++)
{
if (tempFilters[i] is GlowFilter)
{
glowIndex = i;
break;
}
}
// Remove the glow filter from the array.
tempFilters.splice(glowIndex, 1);
// Apply the new set of filters to the display object.
filteredObject.filters = tempFilters;

In a more complex
case, such as if the filter to remove is selected at runtime, the best
approach is to keep a separate, persistent copy of the filter array
that serves as the master list of filters. Any time you make a change
to the set of filters, change the master list then apply that filter
array as the
filters
property of the display object.

For
example, in the following code listing, multiple convolution filters
are applied to a display object to create different visual effects,
and at a later point in the application one of those filters is
removed while the others are retained. In this case, the code keeps
a master copy of the filters array, as well as a reference to the filter
to remove. Finding and removing the specific filter is similar to
the preceding approach, except that instead of making a temporary
copy of the filters array, the master copy is manipulated and then
applied to the display object.

// Example of removing a filter from a set of
// filters, where there may be more than one
// of that type of filter applied to the filtered
// object, and you only want to remove one.
// A master list of filters is stored in a separate,
// persistent Array variable.
var masterFilterList:Array;
// At some point, you store a reference to the filter you
// want to remove.
var filterToRemove:ConvolutionFilter;
// ... assume the filters have been added to masterFilterList,
// which is then assigned as the filteredObject.filters:
filteredObject.filters = masterFilterList;
// ... later, when it's time to remove the filter, this code gets called:
// Loop through the filters to find the index of masterFilterList.
var removeIndex:int = -1;
var numFilters:int = masterFilterList.length;
for (var i:int = 0; i < numFilters; i++)
{
if (masterFilterList[i] == filterToRemove)
{
removeIndex = i;
break;
}
}
if (removeIndex >= 0)
{
// Remove the filter from the array.
masterFilterList.splice(removeIndex, 1);
// Apply the new set of filters to the display object.
filteredObject.filters = masterFilterList;
}

In this approach (when you’re comparing a stored
filter reference to the items in the filters array to determine
which filter to remove), you
must
keep a separate copy of
the filters array—the code does not work if you compare the stored
filter reference to the elements in a temporary array copied from
the display object’s
filters
property. This is
because internally, when you assign an array to the
filters
property,
the runtime makes a copy of each filter object in the array. Those
copies (rather than the original objects) are applied to the display
object, and when you read the
filters
property
into a temporary array, the temporary array contains references
to the copied filter objects rather than references to the original
filter objects. Consequently, if in the preceding example you try
to determine the index of
filterToRemove
by comparing
it to the filters in a temporary filters array, no match is found.

Filters and object transformations

No filtered region—a drop shadow,
for example—outside of a display object’s bounding box rectangle
is considered to be part of the surface for the purposes of hit
detection (determining if an instance overlaps or intersects with
another instance). Because the DisplayObject class’s hit detection
methods are vector-based, you cannot perform a hit detection on
the bitmap result. For example, if you apply a bevel filter to a
button instance, hit detection is not available on the beveled portion
of the instance.

Scaling, rotating, and skewing are not supported
by filters; if the filtered display object itself is scaled (if
scaleX
and
scaleY
are
not 100%), the filter effect does not scale with the instance. This
means that the original shape of the instance rotates, scales, or
skews; however, the filter does not rotate, scale, or skew with the
instance.

You can animate an instance with a filter to create
realistic effects, or nest instances and use the BitmapData class
to animate filters to achieve this effect.

Filters and Bitmap objects

When you apply any filter to a BitmapData
object, the
cacheAsBitmap
property is automatically
set to
true
. In this way, the filter is actually
applied to the copy of the object rather than to the original.

This
copy is then placed on the main display (over the original object)
as close as possible to the nearest pixel. If the bounds of the
original bitmap change, the filtered copy bitmap is recreated from
the original, rather than being stretched or distorted.

If
you clear all filters for a display object, the
cacheAsBitmap
property
is reset to what it was before the filter was applied.

Twitter™ and Facebook posts are not covered under the terms of Creative Commons.