Aug 08 2009
[AS3] Applying BitmapFilters In The Correct Order
In the flash.filters package, you can find several image filter effects you can apply to any DisplayObject instance – BevelFilter, BlurFilter, ColorMatrixFilter, ConvolutionFilter, DisplacementMapFilter, DropShadowFilter, GlowFilter, GradientBevelFilter, and GradientGlowFilter.
To apply one or more of these image filter effects to a display object, set the filters property of the respective DisplayObject instance to an Array containing the filter object(s).
Single Effect
For example, to give a Sprite a drop shadow:
var sp:Sprite = new Sprite(); sp.graphics.beginFill(0x0000FF); sp.graphics.drawRect(0,0,20,20); sp.graphics.endFill(); sp.x = 10; sp.y = 10; addChild(sp); sp.filters = [new DropShadowFilter()]; // flash.filters.DropShadowFilter
To give the Sprite a glow effect:
sp.filters = [new GlowFilter()]; // flash.filters.GlowFilter
Take note that after setting the filters property to an array, modifying the array itself will have no effect on the display object. In order to modify the filter effects on the display object, you must set the filters property:
sp.filters = [new DropShadowFilter()]; sp.filters[0] = new GlowFilter(); // NO EFFECT! sp.filters = [new GlowFilter()];
Composite Effect
If you are applying more than one effect to the same instance, take careful note of the index order of the filter objects in the array. The effects are applied in the same order as their index order in the array, ie the filter object in index position 0 is applied first, followed by the filter in position 1, and so on. Swapping the positions of the filter objects in the array will obviously give you different results.
sp.filters = [new GlowFilter(), new DropShadowFilter()]; // Glow, followed by DropShadow
If we change the positions:
sp.filters = [new DropShadowFilter(), new GlowFilter()]; // DropShadow, followed by Glow
Notice that the Glow now wraps around the DropShadow as well, because the drop shadow is drawn first, and so when the glow is drawn, it is rendered around the whole image which includes the drop shadow.
Therefore, when applying multiple image filter effects to the same display object, always take careful note of their index order in the filters array.
Adobe Flash IDE
The above applies when setting filters during run-time via ActionScript. If you are creating artwork using the Adobe Flash authoring IDE and applying filters via the Filters Panel, you can adjust the order of the effects by moving a filter up/down the list in the panel (click-and-hold on a filter, then drag and move it up/down to change its position in the list).
Reminder:
The cacheAsBitmap property of a display object is automatically set to true whenever you apply a filter to it (when its filters property is not null), ie thecacheAsBitmap property is reported as true for that display object, even if you set the property to false. If you clear all filters for a display object, the cacheAsBitmap setting changes to what it was last set to.
Hi Sunny,
This is a very nice, straightforward, and clear example of using DisplayObject.filters. Would you like to post a link to it in the Adobe documentation? The Adobe tech writing team is always looking for nice examples that the ActionScript community would like to share with other readers. I like your example because it highlights key points, like setting the filters field rather than just changing the array. I also like the pictures illustrating the array order.
The link to DisplayObject.filters is at:
http://help.adobe.com/en_US/AS3LCR/Flash_10.0/flash/display/DisplayObject.html#filters
Just scroll down to the bottom of the page to post a comment. You need to login with your Adobe member ID to post.
Thanks,
Jackie Levy
Adobe Systems, Inc.
Technical Writer – API and Developer documents
Thanks Jackie, I have posted the link as requested. Also, please feel free to integrate the examples into your documentation if you wish or as deem fit. I really doubt many people read the comments at the end of that very long page of the Adobe documentation.
If I may make a suggestion, perhaps the Adobe documentation site could provide individual pages for each class member? Much like how the PHP docs site is organized. That will make comments more relevant to the page in question and perhaps invite more community participation too.