flash.filters.BlurFilter

Package	flash.filters
Class	public class BlurFilter
Inheritance	BlurFilter BitmapFilter Object

Player version:

Flash Player 8

The BlurFilter class lets you apply a blur visual effect to a variety of objects in Flash. A blur effect softens the details of an image. You can produce blurs that range from a softly unfocused look to a Gaussian blur, a hazy appearance like viewing an image through semi-opaque glass. When the quality property of this filter is set to 1, the result is a softly unfocused look. When the quality property is set to 3, it approximates a Gaussian blur filter.

The use of filters depends on the object to which you apply the filter:

To apply filters to movie clips, text fields, and buttons at runtime, use the filters property. Setting the filters property of an object does not modify the object, and you can undo the setting by clearing the filters property.
To apply filters to BitmapData instances, use the BitmapData.applyFilter() method. Calling applyFilter on a BitmapData object takes the source BitmapData object and the filter object and generates a filtered image as a result.

You can also apply filter effects to images and video at authoring time. For more information, see your authoring documentation.

If you apply a filter to a movie clip or button, the cacheAsBitmap property of the movie clip or button is set to true. If you clear all filters, the original value of cacheAsBitmap is restored.

This filter supports stage scaling. However, it does not support general scaling, rotation, and skewing. If the object itself is scaled (_xscale and _yscale are not 100%), the filter effect is not scaled. It is scaled only when you zoom in on the Stage.

A filter is not applied if the resulting image exceeds 2880 pixels in width or height. If, for example, you zoom in on a large movie clip with a filter applied, the filter is turned off if the resulting image exceeds the limit of 2880 pixels.

	Properties inherited from class Object
	`__proto__, __resolve, constructor, prototype`

	Methods inherited from class BitmapFilter
	`clone`

	Methods inherited from class Object
	`addProperty, hasOwnProperty, isPropertyEnumerable, isPrototypeOf, registerClass, toString, unwatch, valueOf, watch`

Property detail

blurX

property

public var blurX:Number

Player version:

Flash Player 8

The amount of horizontal blur. Valid values are from 0 to 255 (floating point). The default value is 4. Values that are a power of 2 (such as 2, 4, 8, 16 and 32) are optimized to render more quickly than other values.

Example
The following example changes the blurX property on an existing MovieClip instance when a user clicks it.

import flash.filters.BlurFilter;
var mc:MovieClip = createBlurFilterRectangle("BlurFilterBlurX");
mc.onRelease = function() {
    var filter:BlurFilter = this.filters[0];
    filter.blurX = 200;
    this.filters = new Array(filter);
}

function createBlurFilterRectangle(name:String):MovieClip {
    var rect:MovieClip = this.createEmptyMovieClip(name, this.getNextHighestDepth());
    var w:Number = 100;
    var h:Number = 100;
    rect.beginFill(0x003366);
    rect.lineTo(w, 0);
    rect.lineTo(w, h);
    rect.lineTo(0, h);
    rect.lineTo(0, 0);
    rect._x = 20;
    rect._y = 20;

    var filter:BlurFilter = new BlurFilter(30, 30, 2);
    var filterArray:Array = new Array();
    filterArray.push(filter);
    rect.filters = filterArray;
    return rect;
}

blurY

property

public var blurY:Number

Player version:

Flash Player 8

The amount of vertical blur. Valid values are from 0 to 255 (floating point). The default value is 4. Values that are a power of 2 (such as 2, 4, 8, 16 and 32) are optimized to render more quickly than other values.

Example
The following example changes the blurY property on an existing MovieClip instance when a user clicks it.

import flash.filters.BlurFilter;
var mc:MovieClip = createBlurFilterRectangle("BlurFilterBlurY");
mc.onRelease = function() {
    var filter:BlurFilter = this.filters[0];
    filter.blurY = 200;
    this.filters = new Array(filter);
}

function createBlurFilterRectangle(name:String):MovieClip {
    var rect:MovieClip = this.createEmptyMovieClip(name, this.getNextHighestDepth());
    var w:Number = 100;
    var h:Number = 100;
    rect.beginFill(0x003366);
    rect.lineTo(w, 0);
    rect.lineTo(w, h);
    rect.lineTo(0, h);
    rect.lineTo(0, 0);
    rect._x = 20;
    rect._y = 20;

    var filter:BlurFilter = new BlurFilter(30, 30, 2);
    var filterArray:Array = new Array();
    filterArray.push(filter);
    rect.filters = filterArray;
    return rect;
}

quality

property

public var quality:Number

Player version:

Flash Player 8

The number of times to perform the blur. Valid values are from 0-15. The default value is 1, which is equivalent to low quality. A value of 2 is medium quality. A value of 3 is high quality and approximates a Gaussian blur.

For most applications, a quality value of 1, 2, or 3 is sufficient. Although you can use additional numeric values up to 15 to increase the number of times the blur is applied, thus getting a more blurred effect, be aware that higher values are rendered more slowly. Instead of increasing the value of quality, you can often get a similar effect, and with faster rendering, by simply increasing the values of blurX and blurY.

Example
The following example creates a rectangle and applies a blur filter with a quality value of 1 to the rectangle. When you click the rectangle, the quality increases to 3, and the rectangle becomes more blurry.

import flash.filters.BlurFilter;
var mc:MovieClip = createBlurFilterRectangle("BlurFilterQuality");
mc.onRelease = function() {
    var filter:BlurFilter = this.filters[0];
    filter.quality = 3;
    this.filters = new Array(filter);
}

function createBlurFilterRectangle(name:String):MovieClip {
    var rect:MovieClip = this.createEmptyMovieClip(name, this.getNextHighestDepth());
    var w:Number = 100;
    var h:Number = 100;
    rect.beginFill(0x003366);
    rect.lineTo(w, 0);
    rect.lineTo(w, h);
    rect.lineTo(0, h);
    rect.lineTo(0, 0);
    rect._x = 20;
    rect._y = 20;

    var filter:BlurFilter = new BlurFilter(30, 30, 1);
    var filterArray:Array = new Array();
    filterArray.push(filter);
    rect.filters = filterArray;
    return rect;
}

Constructor detail

BlurFilter

()

constructor

public function BlurFilter([blurX:Number], [blurY:Number], [quality:Number])

Player version:

Flash Player 8

Initializes the filter with the specified parameters. The default values create a soft, unfocused image.

Parameters

	`blurX:Number` [optional] — The amount to blur horizontally. Valid values are from 0 to 255 (floating-point value). The default value is 4. Values that are a power of 2 (such as 2, 4, 8, 16 and 32) are optimized to render more quickly than other values.

	`blurY:Number` [optional] — The amount to blur vertically. Valid values are from 0 to 255 (floating-point value). The default value is 4. Values that are a power of 2 (such as 2, 4, 8, 16 and 32) are optimized to render more quickly than other values.

	`quality:Number` [optional] — The number of times to apply the filter. The default value is 1, which is equivalent to low quality. A value of 2 is medium quality, and a value of 3 is high quality and approximates a Gaussian blur.

Example
The following example instantiates a new BlurFilter constructor and applies it to a flat, rectangular shape:

import flash.filters.BlurFilter;
var rect:MovieClip = createRectangle(100, 100, 0x003366, "BlurFilterExample");

var blurX:Number = 30;
var blurY:Number = 30;
var quality:Number = 3;

var filter:BlurFilter = new BlurFilter(blurX, blurY, quality);
var filterArray:Array = new Array();
filterArray.push(filter);
rect.filters = filterArray;

function createRectangle(w:Number, h:Number, bgColor:Number, name:String):MovieClip {
    var mc:MovieClip = this.createEmptyMovieClip(name, this.getNextHighestDepth());
    mc.beginFill(bgColor);
    mc.lineTo(w, 0);
    mc.lineTo(w, h);
    mc.lineTo(0, h);
    mc.lineTo(0, 0);
    mc._x = 20;
    mc._y = 20;
    return mc;
}

Method detail

clone

()

method

public function clone():BlurFilter

Player version:

Flash Player 8

Returns a copy of this filter object.

Returns

BlurFilter — A new BlurFilter instance with all the same properties as the original BlurFilter instance.

Example
The following example creates three BlurFilter objects and compares them. You can create the filter_1 object by using the BlurFilter constructor. You can create the filter_2 object by setting it equal to filter_1. You can create the clonedFilter object by cloning filter_1. Notice that although filter_2 evaluates as being equal to filter_1, clonedFilter does not, even though it contains the same values as filter_1.

import flash.filters.BlurFilter;

var filter_1:BlurFilter = new BlurFilter(30, 30, 2);
var filter_2:BlurFilter = filter_1;
var clonedFilter:BlurFilter = filter_1.clone();

trace(filter_1 == filter_2);        // true
trace(filter_1 == clonedFilter);    // false

for(var i in filter_1) {
    trace(">> " + i + ": " + filter_1[i]);
    // >> clone: [type Function]
    // >> quality: 2
    // >> blurY: 30
    // >> blurX: 30
}

for(var i in clonedFilter) {
    trace(">> " + i + ": " + clonedFilter[i]);
    // >> clone: [type Function]
    // >> quality: 2
    // >> blurY: 30
    // >> blurX: 30
}

To further demonstrate the relationships between filter_1, filter_2, and clonedFilter, the following example modifies the quality property of filter_1. Modifying quality demonstrates that the clone() method creates a new instance based on values of the filter_1 instead of referring to the values.

import flash.filters.BlurFilter;

var filter_1:BlurFilter = new BlurFilter(30, 30, 2);
var filter_2:BlurFilter = filter_1;
var clonedFilter:BlurFilter = filter_1.clone();

trace(filter_1.quality);            // 2
trace(filter_2.quality);            // 2
trace(clonedFilter.quality);        // 2

filter_1.quality = 1;

trace(filter_1.quality);            // 1
trace(filter_2.quality);            // 1
trace(clonedFilter.quality);        // 2

Flash CS5 ActionScript 2.0 Language Reference	All Packages \| All Classes \| Language Elements \| Index \| Appendixes \| Frames No Frames
Class BlurFilter	Properties \| Methods

	Property
		blurX : Number The amount of horizontal blur.
		blurY : Number The amount of vertical blur.
		quality : Number The number of times to perform the blur.

	Method
		BlurFilter([blurX:Number], [blurY:Number], [quality:Number]) Initializes the filter with the specified parameters.
		clone():BlurFilter Returns a copy of this filter object.