Flash CS3 Documentation

Programming ActionScript 3.0 > Filtering display objects > Creating and applying filters > Applying a filter

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.

Subtopics

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:

import flash.filters.BevelFilter;
import flash.filters.GlowFilter;

// Create the filters and add them to an array.
var bevel:BevelFilter = new BevelFilter();
var glow:GlowFilter = new GlowFilter();
var filtersArray:Array = new Array(bevel, glow);

// Assign the filters array to the display object to apply the filter.
myDisplayObject.filters = filtersArray;

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, you must 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 instance, 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 new 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 Changing filters at run time.

Applying a filter to a BitmapData object

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

myBitmapData.applyFilter(sourceBitmapData);

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.

Flash CS3

Comments

Add Comment

BarkinB said on May 2, 2007 at 2:08 PM :

In the Removing Filters section we're referred to another page with this
link: "Changing filters at run time".

That page has no further info on removing individual filters, only how to
add filters. The way things are worded, I fully expected some example on
how to remove a single filter, but there is none. The section heading in
that page "Changing filters at run time" would be more accurate as
"Adding filters at run time".
Please either remove the link from this section, or beef up the example
with a way to remove a single filter.

Thanks.

adbe_paul said on May 8, 2007 at 4:24 PM :

@BarkinB:

Thanks for pointing this out. We'll update the documentation in the next release.

Note that technically there's no direct way to "remove a single filter", or to "add a single filter" for that matter. All you can do is replace the set of filters applied to an object with a different set of filters -- that's why the section that the link goes to is titled "Changing filters at run-time."

Nevertheless, as you pointed out, the wording definitely suggests that you'd find some content that isn't there -- namely, instructions on how to remove one filter from a set of filters. In the meantime, I've added a comment to that page with some examples of how to remove filters.

 

RSS feed | Send me an e-mail when comments are added to this page | Comment Report

Current page: http://livedocs.adobe.com/flash/9.0/main/00000194.html

Add Comment