flash.filters

Class DisplacementMapFilter

Object


public class DisplacementMapFilter
extends BitmapFilter

Player version: Flash Player 8

The DisplacementMapFilter class uses the pixel values from the specified BitmapData object (called the displacement map image) to perform a displacement of an object on the Stage, such as a MovieClip instance. You can use this filter to achieve a warped or mottled effect on a BitmapData or MovieClip instance.

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

To apply filters to movie clips at runtime, use the filters property. Setting the filters property of an object does not modify the object and can be undone by clearing the filters property.

To apply filters to BitmapData instances, use the BitmapData.applyFilter() method. Calling applyFilter() on a BitmapData object modifies that BitmapData object and cannot be undone.

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.

The filter uses the following formula:

dstPixel[x, y] = srcPixel[x + ((componentX(x, y) - 128) * scaleX) / 256, y + ((componentY(x, y) - 128) * scaleY) / 256]

where componentX(x, y) gets the componentX color value from the mapBitmap property at (x - mapPoint.x ,y - mapPoint.y).

The map image used by the filter is scaled to match the Stage scaling. It is not scaled in any way when the object itself is scaled.

This filter supports Stage scaling, but not general scaling, rotation, or skewing. If the object itself is scaled (if x-scale and y-scale are not 100%), the filter effect is not scaled. It is scaled only when the Stage is zoomed in.

Here is how the DisplacementMapFilter class works. For each pixel (x,y) in the destination bitmap, the DisplacementMapFilter class does the following:
  1. Gets the color from (x,y) in the map bitmap
  2. Calculates an offset based on that color
  3. Looks up that offset location (x+dx,y+dy) in the source bitmap
  4. Writes that pixel to the destination(x,y), if boundary conditions permit

A filter is not applied if the resulting image would exceed 2880 pixels in width or height. For example, if you zoom in on a large movie clip with a filter applied, the filter is turned off if the resulting image reaches the 2880-pixel limit.

See also
flash.display.BitmapData.applyFilter, MovieClip.filters, MovieClip.cacheAsBitmap



Property Summary
alpha : Number
Specifies the alpha transparency value to use for out-of-bounds displacements.
color : Number
Specifies what color to use for out-of-bounds displacements.
componentX : Number
Describes which color channel to use in the map image to displace the x result.
componentY : Number
Describes which color channel to use in the map image to displace the y result.
mapBitmap : BitmapData
A BitmapData object containing the displacement map data.
mapPoint : Point
A flash.geom.Point value that contains the offset of the upper-left corner of the target movie clip from the upper-left corner of the map image.
mode : String
The mode for the filter.
scaleX : Number
The multiplier to use to scale the x displacement result from the map calculation.
scaleY : Number
The multiplier to use to scale the y displacement result from the map calculation.

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


Constructor Summary
DisplacementMapFilter(mapBitmap:BitmapData, mapPoint:Point, componentX:Number, componentY:Number, scaleX:Number, scaleY:Number, [mode:String], [color:Number], [alpha:Number])
Initializes a DisplacementMapFilter instance with the specified parameters.


Method Summary
clone() : DisplacementMapFilter
Returns a copy of this filter object.

Methods inherited from class BitmapFilter
clone

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


Property Detail

alpha Property

public alpha : Number

Player version: Flash Player 8

Specifies the alpha transparency value to use for out-of-bounds displacements. This is specified as a normalized value from 0.0 to 1.0. For example, .25 sets a transparency value of 25%. The default is 0. Use this property if the mode property is set to 3, COLOR.

Example
The following example modifies the out-of-range alpha property on the existing MovieClip filteredMc to 0x00FF00 when a user clicks it.
import flash.filters.DisplacementMapFilter;
import flash.display.BitmapData;
import flash.geom.Point;
import flash.geom.Matrix;
import flash.geom.ColorTransform;

var filteredMc:MovieClip = createDisplacementMapRectangle();

filteredMc.onPress = function() {
    var filter:DisplacementMapFilter = this.filters[0];
    filter.scaleY = 25;
    filter.mode = "color";
    filter.alpha = .25;
    this.filters = new Array(filter);
}

function createDisplacementMapRectangle():MovieClip {
    var mapBitmap:BitmapData = createGradientBitmap(300, 80, 0xFF000000, "radial");
    var filter:DisplacementMapFilter = new DisplacementMapFilter(mapBitmap, new Point(-30, -30), 1, 1, 10, 10, "wrap", 0x000000, 0x000000);

    var txtBlock:MovieClip = createTextBlock();
    txtBlock._x = 30;
    txtBlock._y = 30;
    
    txtBlock.filters = new Array(filter);

    return txtBlock;
}

function createGradientBitmap(w:Number, h:Number, bgColor:Number, type:String, hide:Boolean):BitmapData {
    var mc:MovieClip = this.createEmptyMovieClip("mc", 1);
    var matrix:Matrix = new Matrix();
    matrix.createGradientBox(w, h, 0, 0, 0);

    mc.beginGradientFill(type, [0xFF0000, 0x0000FF], [100, 100], [0x55, 0x99], matrix, "pad");        
    mc.lineTo(w, 0);
    mc.lineTo(w, h);
    mc.lineTo(0, h);
    mc.lineTo(0, 0);
    mc.endFill();
    (hide == true) ? mc._alpha = 0 : mc._alpha = 100;
    
    var bmp:BitmapData = new BitmapData(w, h, true, bgColor);
        bmp.draw(mc, new Matrix(), new ColorTransform(), "normal", bmp.rectangle, true);
    mc.attachBitmap(bmp, this.getNextHighestDepth());
    
    return bmp;
}

function createTextBlock():MovieClip {
    var txtBlock:MovieClip = this.createEmptyMovieClip("txtBlock", this.getNextHighestDepth());
    txtBlock.createTextField("txt", this.getNextHighestDepth(), 0, 0, 300, 80);
    txtBlock.txt.text = "watch the text bend with the displacement map";
    return txtBlock;
}


color Property

public color : Number

Player version: Flash Player 8

Specifies what color to use for out-of-bounds displacements. The valid range of displacements is 0.0 to 1.0. Values are in hexadecimal format. The default value for color is 0. Use this property if the mode property is set to 3, COLOR.

Example
The following example modifies the out-of-range color property on the existing MovieClip filteredMc to 0x00FF00 when a user clicks it.
import flash.filters.DisplacementMapFilter;
import flash.display.BitmapData;
import flash.geom.Point;
import flash.geom.Matrix;
import flash.geom.ColorTransform;

var filteredMc:MovieClip = createDisplacementMapRectangle();

filteredMc.onPress = function() {
    var filter:DisplacementMapFilter = this.filters[0];
    filter.scaleY = 25;
    filter.mode = "color";
    filter.alpha = .25;
    filter.color = 0x00FF00;
    this.filters = new Array(filter);
}

function createDisplacementMapRectangle():MovieClip {
    var mapBitmap:BitmapData = createGradientBitmap(300, 80, 0xFF000000, "radial");
    var filter:DisplacementMapFilter = new DisplacementMapFilter(mapBitmap, new Point(-30, -30), 1, 1, 10, 10, "wrap", 0x000000, 0x000000);

    var txtBlock:MovieClip = createTextBlock();
    txtBlock._x = 30;
    txtBlock._y = 30;
    
    txtBlock.filters = new Array(filter);

    return txtBlock;
}

function createGradientBitmap(w:Number, h:Number, bgColor:Number, type:String, hide:Boolean):BitmapData {
    var mc:MovieClip = this.createEmptyMovieClip("mc", 1);
    var matrix:Matrix = new Matrix();
    matrix.createGradientBox(w, h, 0, 0, 0);

    mc.beginGradientFill(type, [0xFF0000, 0x0000FF], [100, 100], [0x55, 0x99], matrix, "pad");        
    mc.lineTo(w, 0);
    mc.lineTo(w, h);
    mc.lineTo(0, h);
    mc.lineTo(0, 0);
    mc.endFill();
    (hide == true) ? mc._alpha = 0 : mc._alpha = 100;
    
    var bmp:BitmapData = new BitmapData(w, h, true, bgColor);
        bmp.draw(mc, new Matrix(), new ColorTransform(), "normal", bmp.rectangle, true);
    mc.attachBitmap(bmp, this.getNextHighestDepth());
    
    return bmp;
}

function createTextBlock():MovieClip {
    var txtBlock:MovieClip = this.createEmptyMovieClip("txtBlock", this.getNextHighestDepth());
    txtBlock.createTextField("txt", this.getNextHighestDepth(), 0, 0, 300, 80);
    txtBlock.txt.text = "watch the text bend with the displacement map";
    return txtBlock;
}


componentX Property

public componentX : Number

Player version: Flash Player 8

Describes which color channel to use in the map image to displace the x result. Possible values are 1 (red), 2 (green), 4 (blue), and 8 (alpha).

Example
The following example changes the componentX property on the existing MovieClip filteredMc when a user clicks it. The value changes from 1 to 4, which changes the color channel from red to blue.
import flash.filters.DisplacementMapFilter;
import flash.display.BitmapData;
import flash.geom.Point;
import flash.geom.Matrix;
import flash.geom.ColorTransform;

var filteredMc:MovieClip = createDisplacementMapRectangle();
    
filteredMc.onPress = function() {
    var filter:DisplacementMapFilter = this.filters[0];
    filter.componentX = 4;
    this.filters = new Array(filter);
}


function createDisplacementMapRectangle():MovieClip {
    var mapBitmap:BitmapData = createGradientBitmap(300, 80, 0xFF000000, "radial");
    var filter:DisplacementMapFilter = new DisplacementMapFilter(mapBitmap, new Point(-30, -30), 1, 1, 10, 10, "wrap", 0x000000, 0x000000);

    var txtBlock:MovieClip = createTextBlock();
    txtBlock._x = 30;
    txtBlock._y = 30;
    
    txtBlock.filters = new Array(filter);

    return txtBlock;
}

function createGradientBitmap(w:Number, h:Number, bgColor:Number, type:String, hide:Boolean):BitmapData {
    var mc:MovieClip = this.createEmptyMovieClip("mc", 1);
    var matrix:Matrix = new Matrix();
    matrix.createGradientBox(w, h, 0, 0, 0);

    mc.beginGradientFill(type, [0xFF0000, 0x0000FF], [100, 100], [0x55, 0x99], matrix, "pad");        
    mc.lineTo(w, 0);
    mc.lineTo(w, h);
    mc.lineTo(0, h);
    mc.lineTo(0, 0);
    mc.endFill();
    (hide == true) ? mc._alpha = 0 : mc._alpha = 100;
    
    var bmp:BitmapData = new BitmapData(w, h, true, bgColor);
        bmp.draw(mc, new Matrix(), new ColorTransform(), "normal", bmp.rectangle, true);
    mc.attachBitmap(bmp, this.getNextHighestDepth());
    
    return bmp;
}

function createTextBlock():MovieClip {
    var txtBlock:MovieClip = this.createEmptyMovieClip("txtBlock", this.getNextHighestDepth());
    txtBlock.createTextField("txt", this.getNextHighestDepth(), 0, 0, 300, 80);
    txtBlock.txt.text = "watch the text bend with the displacement map";
    return txtBlock;
}

See also
BitmapData class

componentY Property

public componentY : Number

Player version: Flash Player 8

Describes which color channel to use in the map image to displace the y result. Possible values are 1 (red), 2 (green), 4 (blue), and 8 (alpha).

Example
The following example changes the componentY property on the existing MovieClip filteredMc when a user clicks it. The value changes from 1 to 4, which changes the color channel from red to blue.
import flash.filters.DisplacementMapFilter;
import flash.display.BitmapData;
import flash.geom.Point;
import flash.geom.Matrix;
import flash.geom.ColorTransform;

var filteredMc:MovieClip = createDisplacementMapRectangle();
    
filteredMc.onPress = function() {
    var filter:DisplacementMapFilter = this.filters[0];
    filter.componentY = 4;
    this.filters = new Array(filter);
}

function createDisplacementMapRectangle():MovieClip {
    var mapBitmap:BitmapData = createGradientBitmap(300, 80, 0xFF000000, "radial");
    var filter:DisplacementMapFilter = new DisplacementMapFilter(mapBitmap, new Point(-30, -30), 1, 1, 10, 10, "wrap", 0x000000, 0x000000);

    var txtBlock:MovieClip = createTextBlock();
    txtBlock._x = 30;
    txtBlock._y = 30;
    
    txtBlock.filters = new Array(filter);

    return txtBlock;
}

function createGradientBitmap(w:Number, h:Number, bgColor:Number, type:String, hide:Boolean):BitmapData {
    var mc:MovieClip = this.createEmptyMovieClip("mc", 1);
    var matrix:Matrix = new Matrix();
    matrix.createGradientBox(w, h, 0, 0, 0);

    mc.beginGradientFill(type, [0xFF0000, 0x0000FF], [100, 100], [0x55, 0x99], matrix, "pad");        
    mc.lineTo(w, 0);
    mc.lineTo(w, h);
    mc.lineTo(0, h);
    mc.lineTo(0, 0);
    mc.endFill();
    (hide == true) ? mc._alpha = 0 : mc._alpha = 100;
    
    var bmp:BitmapData = new BitmapData(w, h, true, bgColor);
        bmp.draw(mc, new Matrix(), new ColorTransform(), "normal", bmp.rectangle, true);
    mc.attachBitmap(bmp, this.getNextHighestDepth());
    
    return bmp;
}

function createTextBlock():MovieClip {
    var txtBlock:MovieClip = this.createEmptyMovieClip("txtBlock", this.getNextHighestDepth());
    txtBlock.createTextField("txt", this.getNextHighestDepth(), 0, 0, 300, 80);
    txtBlock.txt.text = "watch the text bend with the displacement map";
    return txtBlock;
}

See also
BitmapData class

mapBitmap Property

public mapBitmap : BitmapData

Player version: Flash Player 8

A BitmapData object containing the displacement map data.

The mapBitmap property cannot be changed by directly modifying its value. Instead, you must get a reference to mapBitmap, make the change to the reference, and then set mapBitmap to the reference.

Example
The following example changes the mapBitmap property on the existing MovieClip filteredMc when a user clicks it.
import flash.filters.DisplacementMapFilter;
import flash.display.BitmapData;
import flash.geom.Point;
import flash.geom.Matrix;
import flash.geom.ColorTransform;

var filteredMc:MovieClip = createDisplacementMapRectangle();
var scope:Object = this;

filteredMc.onPress = function() {
    var filter:DisplacementMapFilter = this.filters[0];
    filter.mapBitmap = scope.createGradientBitmap(300, 80, 0xFF000000, "linear");
    this.filters = new Array(filter);
}

function createDisplacementMapRectangle():MovieClip {
    var mapBitmap:BitmapData = createGradientBitmap(300, 80, 0xFF000000, "radial");
    var filter:DisplacementMapFilter = new DisplacementMapFilter(mapBitmap, new Point(-30, -30), 1, 1, 10, 10, "wrap", 0x000000, 0x000000);

    var txtBlock:MovieClip = createTextBlock();
    txtBlock._x = 30;
    txtBlock._y = 30;
    
    txtBlock.filters = new Array(filter);

    return txtBlock;
}

function createGradientBitmap(w:Number, h:Number, bgColor:Number, type:String, hide:Boolean):BitmapData {
    var mc:MovieClip = this.createEmptyMovieClip("mc", 1);
    var matrix:Matrix = new Matrix();
    matrix.createGradientBox(w, h, 0, 0, 0);

    mc.beginGradientFill(type, [0xFF0000, 0x0000FF], [100, 100], [0x55, 0x99], matrix, "pad");        
    mc.lineTo(w, 0);
    mc.lineTo(w, h);
    mc.lineTo(0, h);
    mc.lineTo(0, 0);
    mc.endFill();
    (hide == true) ? mc._alpha = 0 : mc._alpha = 100;
    
    var bmp:BitmapData = new BitmapData(w, h, true, bgColor);
        bmp.draw(mc, new Matrix(), new ColorTransform(), "normal", bmp.rectangle, true);
    mc.attachBitmap(bmp, this.getNextHighestDepth());
    
    return bmp;
}

function createTextBlock():MovieClip {
    var txtBlock:MovieClip = this.createEmptyMovieClip("txtBlock", this.getNextHighestDepth());
    txtBlock.createTextField("txt", this.getNextHighestDepth(), 0, 0, 300, 80);
    txtBlock.txt.text = "watch the text bend with the displacement map";
    return txtBlock;
}

See also
flash.display.BitmapData

mapPoint Property

public mapPoint : Point

Player version: Flash Player 8

A flash.geom.Point value that contains the offset of the upper-left corner of the target movie clip from the upper-left corner of the map image.

The mapPoint property cannot be changed by directly modifying its value. Instead, you must get a reference to mapPoint, make the change to the reference, and then set mapPoint to the reference.

Example
The following example changes the mapPoint property on the existing MovieClip filteredMc when a user clicks it.
import flash.filters.DisplacementMapFilter;
import flash.display.BitmapData;
import flash.geom.Point;
import flash.geom.Matrix;
import flash.geom.ColorTransform;

var filteredMc:MovieClip = createDisplacementMapRectangle();

filteredMc.onPress = function() {
    var filter:DisplacementMapFilter = this.filters[0];
    filter.mapPoint = new Point(-30, -40);
    this.filters = new Array(filter);
    this._x = 30;
    this._y = 40;
}

function createDisplacementMapRectangle():MovieClip {
    var mapBitmap:BitmapData = createGradientBitmap(300, 80, 0xFF000000, "radial");
    var filter:DisplacementMapFilter = new DisplacementMapFilter(mapBitmap, new Point(-30, -30), 1, 1, 10, 10, "wrap", 0x000000, 0x000000);

    var txtBlock:MovieClip = createTextBlock();
    txtBlock._x = 30;
    txtBlock._y = 30;
    
    txtBlock.filters = new Array(filter);

    return txtBlock;
}

function createGradientBitmap(w:Number, h:Number, bgColor:Number, type:String, hide:Boolean):BitmapData {
    var mc:MovieClip = this.createEmptyMovieClip("mc", 1);
    var matrix:Matrix = new Matrix();
    matrix.createGradientBox(w, h, 0, 0, 0);

    mc.beginGradientFill(type, [0xFF0000, 0x0000FF], [100, 100], [0x55, 0x99], matrix, "pad");        
    mc.lineTo(w, 0);
    mc.lineTo(w, h);
    mc.lineTo(0, h);
    mc.lineTo(0, 0);
    mc.endFill();
    (hide == true) ? mc._alpha = 0 : mc._alpha = 100;
    
    var bmp:BitmapData = new BitmapData(w, h, true, bgColor);
        bmp.draw(mc, new Matrix(), new ColorTransform(), "normal", bmp.rectangle, true);
    mc.attachBitmap(bmp, this.getNextHighestDepth());
    
    return bmp;
}

function createTextBlock():MovieClip {
    var txtBlock:MovieClip = this.createEmptyMovieClip("txtBlock", this.getNextHighestDepth());
    txtBlock.createTextField("txt", this.getNextHighestDepth(), 0, 0, 300, 80);
    txtBlock.txt.text = "watch the text bend with the displacement map";
    return txtBlock;
}

See also
flash.geom.Point

mode Property

public mode : String

Player version: Flash Player 8

The mode for the filter. Possible values are the following:

Example
The following example modifies scaleY to create a displacement value that is out of range and then changes the mode property on the existing MovieClip filteredMc to ignore when a user clicks it.
import flash.filters.DisplacementMapFilter;
import flash.display.BitmapData;
import flash.geom.Point;
import flash.geom.Matrix;
import flash.geom.ColorTransform;

var filteredMc:MovieClip = createDisplacementMapRectangle();

filteredMc.onPress = function() {
    var filter:DisplacementMapFilter = this.filters[0];
    filter.scaleY = 25;
    filter.mode = "ignore";
    this.filters = new Array(filter);
}

function createDisplacementMapRectangle():MovieClip {
    var mapBitmap:BitmapData = createGradientBitmap(300, 80, 0xFF000000, "radial");
    var filter:DisplacementMapFilter = new DisplacementMapFilter(mapBitmap, new Point(-30, -30), 1, 1, 10, 10, "wrap", 0x000000, 0x000000);

    var txtBlock:MovieClip = createTextBlock();
    txtBlock._x = 30;
    txtBlock._y = 30;
    
    txtBlock.filters = new Array(filter);

    return txtBlock;
}

function createGradientBitmap(w:Number, h:Number, bgColor:Number, type:String, hide:Boolean):BitmapData {
    var mc:MovieClip = this.createEmptyMovieClip("mc", 1);
    var matrix:Matrix = new Matrix();
    matrix.createGradientBox(w, h, 0, 0, 0);

    mc.beginGradientFill(type, [0xFF0000, 0x0000FF], [100, 100], [0x55, 0x99], matrix, "pad");        
    mc.lineTo(w, 0);
    mc.lineTo(w, h);
    mc.lineTo(0, h);
    mc.lineTo(0, 0);
    mc.endFill();
    (hide == true) ? mc._alpha = 0 : mc._alpha = 100;
    
    var bmp:BitmapData = new BitmapData(w, h, true, bgColor);
        bmp.draw(mc, new Matrix(), new ColorTransform(), "normal", bmp.rectangle, true);
    mc.attachBitmap(bmp, this.getNextHighestDepth());
    
    return bmp;
}

function createTextBlock():MovieClip {
    var txtBlock:MovieClip = this.createEmptyMovieClip("txtBlock", this.getNextHighestDepth());
    txtBlock.createTextField("txt", this.getNextHighestDepth(), 0, 0, 300, 80);
    txtBlock.txt.text = "watch the text bend with the displacement map";
    return txtBlock;
}


scaleX Property

public scaleX : Number

Player version: Flash Player 8

The multiplier to use to scale the x displacement result from the map calculation.

Example
The following example changes the scaleX property on the existing MovieClip filteredMc when a user clicks it.
import flash.filters.DisplacementMapFilter;
import flash.display.BitmapData;
import flash.geom.Point;
import flash.geom.Matrix;
import flash.geom.ColorTransform;

var filteredMc:MovieClip = createDisplacementMapRectangle();

filteredMc.onPress = function() {
    var filter:DisplacementMapFilter = this.filters[0];
    filter.scaleX = 5;
    this.filters = new Array(filter);
}

function createDisplacementMapRectangle():MovieClip {
    var mapBitmap:BitmapData = createGradientBitmap(300, 80, 0xFF000000, "radial");
    var filter:DisplacementMapFilter = new DisplacementMapFilter(mapBitmap, new Point(-30, -30), 1, 1, 10, 10, "wrap", 0x000000, 0x000000);

    var txtBlock:MovieClip = createTextBlock();
    txtBlock._x = 30;
    txtBlock._y = 30;
    
    txtBlock.filters = new Array(filter);

    return txtBlock;
}

function createGradientBitmap(w:Number, h:Number, bgColor:Number, type:String, hide:Boolean):BitmapData {
    var mc:MovieClip = this.createEmptyMovieClip("mc", 1);
    var matrix:Matrix = new Matrix();
    matrix.createGradientBox(w, h, 0, 0, 0);

    mc.beginGradientFill(type, [0xFF0000, 0x0000FF], [100, 100], [0x55, 0x99], matrix, "pad");        
    mc.lineTo(w, 0);
    mc.lineTo(w, h);
    mc.lineTo(0, h);
    mc.lineTo(0, 0);
    mc.endFill();
    (hide == true) ? mc._alpha = 0 : mc._alpha = 100;
    
    var bmp:BitmapData = new BitmapData(w, h, true, bgColor);
        bmp.draw(mc, new Matrix(), new ColorTransform(), "normal", bmp.rectangle, true);
    mc.attachBitmap(bmp, this.getNextHighestDepth());
    
    return bmp;
}

function createTextBlock():MovieClip {
    var txtBlock:MovieClip = this.createEmptyMovieClip("txtBlock", this.getNextHighestDepth());
    txtBlock.createTextField("txt", this.getNextHighestDepth(), 0, 0, 300, 80);
    txtBlock.txt.text = "watch the text bend with the displacement map";
    return txtBlock;
}


scaleY Property

public scaleY : Number

Player version: Flash Player 8

The multiplier to use to scale the y displacement result from the map calculation.

Example
The following example changes the scaleY property on the existing MovieClip filteredMc when a user clicks it.
import flash.filters.DisplacementMapFilter;
import flash.display.BitmapData;
import flash.geom.Point;
import flash.geom.Matrix;
import flash.geom.ColorTransform;

var filteredMc:MovieClip = createDisplacementMapRectangle();
    
filteredMc.onPress = function() {
    var filter:DisplacementMapFilter = this.filters[0];
    filter.scaleY = 5;
    this.filters = new Array(filter);
}

function createDisplacementMapRectangle():MovieClip {
    var mapBitmap:BitmapData = createGradientBitmap(300, 80, 0xFF000000, "radial");
    var filter:DisplacementMapFilter = new DisplacementMapFilter(mapBitmap, new Point(-30, -30), 1, 1, 10, 10, "wrap", 0x000000, 0x000000);

    var txtBlock:MovieClip = createTextBlock();
    txtBlock._x = 30;
    txtBlock._y = 30;
    
    txtBlock.filters = new Array(filter);

    return txtBlock;
}

function createGradientBitmap(w:Number, h:Number, bgColor:Number, type:String, hide:Boolean):BitmapData {
    var mc:MovieClip = this.createEmptyMovieClip("mc", 1);
    var matrix:Matrix = new Matrix();
    matrix.createGradientBox(w, h, 0, 0, 0);

    mc.beginGradientFill(type, [0xFF0000, 0x0000FF], [100, 100], [0x55, 0x99], matrix, "pad");        
    mc.lineTo(w, 0);
    mc.lineTo(w, h);
    mc.lineTo(0, h);
    mc.lineTo(0, 0);
    mc.endFill();
    (hide == true) ? mc._alpha = 0 : mc._alpha = 100;
    
    var bmp:BitmapData = new BitmapData(w, h, true, bgColor);
        bmp.draw(mc, new Matrix(), new ColorTransform(), "normal", bmp.rectangle, true);
    mc.attachBitmap(bmp, this.getNextHighestDepth());
    
    return bmp;
}

function createTextBlock():MovieClip {
    var txtBlock:MovieClip = this.createEmptyMovieClip("txtBlock", this.getNextHighestDepth());
    txtBlock.createTextField("txt", this.getNextHighestDepth(), 0, 0, 300, 80);
    txtBlock.txt.text = "watch the text bend with the displacement map";
    return txtBlock;
}



Constructor Detail

DisplacementMapFilter Constructor

public DisplacementMapFilter(mapBitmap:BitmapData, mapPoint:Point, componentX:Number, componentY:Number, scaleX:Number, scaleY:Number, [mode:String], [color:Number], [alpha:Number])

Player version: Flash Player 8

Initializes a DisplacementMapFilter instance with the specified parameters.

Parameters
mapBitmap:BitmapData — A BitmapData object containing the displacement map data.
mapPoint:Point — A flash.geom.Point value that contains the offset of the upper-left corner of the target movie clip from the upper-left corner of the map image.
componentX:Number — Describes which color channel to use in the map image to displace the x result. Possible values are the following:
  • 1 (red)
  • 2 (green)
  • 4 (blue)
  • 8 (alpha)
componentY:Number — Describes which color channel to use in the map image to displace the y result. Possible values are the following:
  • 1 (red)
  • 2 (green)
  • 4 (blue)
  • 8 (alpha)
scaleX:Number — The multiplier to use to scale the x displacement result from the map calculation.
scaleY:Number — The multiplier to use to scale the y displacement result from the map calculation.
mode:String [optional] — The mode of the filter. Possible values are the following:
  • "wrap" — Wraps the displacement value to the other side of the source image.
  • "clamp" — Clamps the displacement value to the edge of the source image.
  • "ignore" — If the displacement value is out of range, ignores the displacement and uses the source pixel.
  • "color" — If the displacement value is outside the image, substitutes a pixel value composed of the alpha and color properties of the filter.
color:Number [optional] — Specifies the color to use for out-of-bounds displacements. The valid range of displacements is 0.0 to 1.0. Use this parameter if mode is set to "color".
alpha:Number [optional] — Specifies what alpha value to use for out-of-bounds displacements. This is specified as a normalized value from 0.0 to 1.0. For example, .25 sets a transparency value of 25%. The default is 1.0. Use this parameter if mode is set to "color".

Example
The following constructor function creates a new instance of the filter:
myFilter = new flash.filters.DisplacementMapFilter (mapBitmap, mapPoint, componentX, componentY, scale, [mode], [color], [alpha])

The following example instantiates a new DisplacementMapFilter with a radial gradient bitmap and applies it to the text containing MovieClip object txtBlock.
import flash.filters.DisplacementMapFilter;
import flash.display.BitmapData;
import flash.geom.Point;
import flash.geom.Matrix;
import flash.geom.ColorTransform;

var mapBitmap:BitmapData = createGradientBitmap(300, 80, 0xFF000000, "radial");

var mapPoint:Point = new Point(-30, -30);
var componentX:Number = 1;
var componentY:Number = 1;
var scaleX:Number = 10;
var scaleY:Number = 10;
var mode:String = "wrap";
var color:Number = 0x000000;
var alpha:Number = 0x000000;

var filter:DisplacementMapFilter = new DisplacementMapFilter(mapBitmap, mapPoint, componentX, componentY, scaleX, scaleY, mode, color, alpha);

var txtBlock:MovieClip = createTextBlock();
txtBlock._x = 30;
txtBlock._y = 30;

txtBlock.filters = new Array(filter);

function createGradientBitmap(w:Number, h:Number, bgColor:Number, type:String, hide:Boolean):BitmapData {
    var mc:MovieClip = this.createEmptyMovieClip("mc", 1);
    var matrix:Matrix = new Matrix();
    matrix.createGradientBox(w, h, 0, 0, 0);

    mc.beginGradientFill(type, [0xFF0000, 0x0000FF], [100, 100], [0x55, 0x99], matrix, "pad");        
    mc.lineTo(w, 0);
    mc.lineTo(w, h);
    mc.lineTo(0, h);
    mc.lineTo(0, 0);
    mc.endFill();
    (hide == true) ? mc._alpha = 0 : mc._alpha = 100;
    
    var bmp:BitmapData = new BitmapData(w, h, true, bgColor);
        bmp.draw(mc, new Matrix(), new ColorTransform(), "normal", bmp.rectangle, true);
    mc.attachBitmap(bmp, this.getNextHighestDepth());
    
    return bmp;
}

function createTextBlock():MovieClip {
    var txtBlock:MovieClip = this.createEmptyMovieClip("txtBlock", this.getNextHighestDepth());
        txtBlock.createTextField("txt", this.getNextHighestDepth(), 0, 0, 300, 80);
    txtBlock.txt.text = "watch the text bend with the displacement map";
    return txtBlock;
}



Method Detail

clone Method

public clone() : DisplacementMapFilter

Player version: Flash Player 8

Returns a copy of this filter object.

Returns
DisplacementMapFilter — A new DisplacementMapFilter instance with all the same properties as the original one.

Example
The following example creates three DisplacementMapFilter objects and compares them: filter_1 is created by using the DisplacementMapFilter constructor; filter_2 is created by setting it equal to filter_1; and clonedFilter is created by cloning filter_1. Notice that although filter_2 evaluates as being equal to filter_1, clonedFilter, even though it contains the same values as filter_1, does not.
import flash.filters.DisplacementMapFilter;
import flash.display.BitmapData;
import flash.geom.Point;
import flash.geom.Matrix;
import flash.geom.ColorTransform;

var mapBitmap:BitmapData = createGradientBitmap(300, 80, 0xFF000000, "radial", true);

var filter_1:DisplacementMapFilter = new DisplacementMapFilter(mapBitmap, new Point(-30, -30), 1, 1, 10, 10, "wrap", 0x000000, 0x000000);
var filter_2:DisplacementMapFilter = filter_1;
var clonedFilter:DisplacementMapFilter = 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]
    // >> alpha: 0
    // >> color: 0
    // >> mode: wrap
    // >> scaleY: 10
    // >> scaleX: 10
    // >> componentY: 1
    // >> componentX: 1
    // >> mapPoint: (-30, -30)
    // >> mapBitmap: [object Object]
}

for(var i in clonedFilter) {
    trace(">> " + i + ": " + clonedFilter[i]);
    // >> clone: [type Function]
    // >> alpha: 0
    // >> color: 0
    // >> mode: wrap
    // >> scaleY: 10
    // >> scaleX: 10
    // >> componentY: 1
    // >> componentX: 1
    // >> mapPoint: (-30, -30)
    // >> mapBitmap: [object Object]
}        

function createGradientBitmap(w:Number, h:Number, bgColor:Number, type:String, hide:Boolean):BitmapData {
    var mc:MovieClip = this.createEmptyMovieClip("mc", 1);
    var matrix:Matrix = new Matrix();
    matrix.createGradientBox(w, h, 0, 0, 0);

    mc.beginGradientFill(type, [0xFF0000, 0x0000FF], [100, 100], [0x55, 0x99], matrix, "pad");        
    mc.lineTo(w, 0);
    mc.lineTo(w, h);
    mc.lineTo(0, h);
    mc.lineTo(0, 0);
    mc.endFill();
    (hide == true) ? mc._alpha = 0 : mc._alpha = 100;
    
    var bmp:BitmapData = new BitmapData(w, h, true, bgColor);
        bmp.draw(mc, new Matrix(), new ColorTransform(), "normal", bmp.rectangle, true);
    mc.attachBitmap(bmp, this.getNextHighestDepth());
    
    return bmp;
}
To further demonstrate the relationships between filter_1, filter_2, and clonedFilter, the following example modifies the mode property of filter_1. Modifying mode demonstrates that the clone() method creates a new instance based on values of filter_1 instead of pointing to them in reference.
import flash.filters.DisplacementMapFilter;
import flash.display.BitmapData;
import flash.geom.Point;
import flash.geom.Matrix;
import flash.geom.ColorTransform;

var mapBitmap:BitmapData = createGradientBitmap(300, 80, 0xFF000000, "radial", true);

var filter_1:DisplacementMapFilter = new DisplacementMapFilter(mapBitmap, new Point(-30, -30), 1, 1, 10, 10, "wrap", 0x000000, 0x000000);
var filter_2:DisplacementMapFilter = filter_1;
var clonedFilter:DisplacementMapFilter = filter_1.clone();

trace(filter_1.mode);            // wrap
trace(filter_2.mode);            // wrap
trace(clonedFilter.mode);        // wrap
    
filter_1.mode = "ignore";

trace(filter_1.mode);            // ignore
trace(filter_2.mode);            // ignore
trace(clonedFilter.mode);        // wrap

function createGradientBitmap(w:Number, h:Number, bgColor:Number, type:String, hide:Boolean):BitmapData {
    var mc:MovieClip = this.createEmptyMovieClip("mc", 1);
    var matrix:Matrix = new Matrix();
    matrix.createGradientBox(w, h, 0, 0, 0);

    mc.beginGradientFill(type, [0xFF0000, 0x0000FF], [100, 100], [0x55, 0x99], matrix, "pad");        
    mc.lineTo(w, 0);
    mc.lineTo(w, h);
    mc.lineTo(0, h);
    mc.lineTo(0, 0);
    mc.endFill();
    (hide == true) ? mc._alpha = 0 : mc._alpha = 100;
    
    var bmp:BitmapData = new BitmapData(w, h, true, bgColor);
        bmp.draw(mc, new Matrix(), new ColorTransform(), "normal", bmp.rectangle, true);
    mc.attachBitmap(bmp, this.getNextHighestDepth());
    
    return bmp;
}