ActionScript 3.0 Language and Components Reference | All Packages | All Classes | Language Elements | Index | Appendixes | Conventions | Frames No Frames |
ShaderFilter

Package | flash.filters
Class | public class ShaderFilter
Inheritance | ShaderFilter BitmapFilter Object

Language Version : | ActionScript 3.0

Player Version : | Flash Player 10

The ShaderFilter class applies a filter by executing a shader on the object being filtered. The filtered object is used as an input to the shader, and the shader output becomes the filter result.

To create a new filter, use the constructor `new ShaderFilter()`. The use of filters depends on the object to which you apply the filter:

- To apply filters to movie clips, text fields, buttons, and video, use the `filters` property (inherited from DisplayObject). Setting the `filters` property of an object does not modify the object, and you can remove the filter by clearing the `filters` property.
- To apply filters to BitmapData objects, 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.

If you apply a filter to a display object, the value of the `cacheAsBitmap` property of the object is set to true. If you remove 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 (if the `scaleX` and `scaleY` properties are not set to 100%), the filter is not scaled. It is scaled only when the user zooms 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.

To specify the Shader instance to use with the filter, pass the Shader instance as an argument to the `ShaderFilter()` constructor, or set it as the value of the `shader` property.

To allow the shader output to extend beyond the bounds of the filtered object, use the `leftExtension`, `rightExtension`, `topExtension`, and `bottomExtension` properties.

View the examples

See also

flash.display.DisplayObject.filters
flash.display.DisplayObject.cacheAsBitmap
flash.display.BitmapData.applyFilter()
flash.display.Shader

Public Properties
Hide Inherited Public Properties
Show Inherited Public Properties

| Property | Defined By
--- | --- | ---
|  | bottomExtension : int The growth in pixels on the bottom side of the target object. | ShaderFilter
|  | constructor : Object A reference to the class object or constructor function for a given object instance. | Object
|  | leftExtension : int The growth in pixels on the left side of the target object. | ShaderFilter
|  | prototype : Object [static] A reference to the prototype object of a class or function object. | Object
|  | rightExtension : int The growth in pixels on the right side of the target object. | ShaderFilter
|  | shader : Shader The shader to use for this filter. | ShaderFilter
|  | topExtension : int The growth in pixels on the top side of the target object. | ShaderFilter

Public Methods
Hide Inherited Public Methods
Show Inherited Public Methods

| Method | Defined By
--- | --- | ---
|  | ShaderFilter(shader:Shader = null) Creates a new shader filter. | ShaderFilter
|  | clone():BitmapFilter Returns a BitmapFilter object that is an exact copy of the original BitmapFilter object. | BitmapFilter
|  | hasOwnProperty(name:String):Boolean Indicates whether an object has a specified property defined. | Object
|  | isPrototypeOf(theClass:Object):Boolean Indicates whether an instance of the Object class is in the prototype chain of the object specified as the parameter. | Object
|  | propertyIsEnumerable(name:String):Boolean Indicates whether the specified property exists and is enumerable. | Object
|  | setPropertyIsEnumerable(name:String, isEnum:Boolean = true):void Sets the availability of a dynamic property for loop operations. | Object
|  | toString():String Returns the string representation of the specified object. | Object
|  | valueOf():Object Returns the primitive value of the specified object. | Object

Property Detail

bottomExtension | property

`bottomExtension:int` [read-write]

Language Version : | ActionScript 3.0

Player Version : | Flash Player 10

The growth in pixels on the bottom side of the target object.

The growth is the area beyond the bounds of the target object that is passed to the shader during execution. At execution time Flash Player computes the normal bounds of a movie clip and extends the bounds based on the `leftExtension`, `rightExtension`, `topExtension`, and `bottomExtension` values.

The default value is `0`.

Implementation
`public function get bottomExtension():int`
`public function set bottomExtension(value:int):void`

leftExtension | property |

`leftExtension:int` [read-write]

Language Version : | ActionScript 3.0

Player Version : | Flash Player 10

The growth in pixels on the left side of the target object.

The growth is the area beyond the bounds of the target object that is passed to the shader during execution. At execution time Flash Player computes the normal bounds of a movie clip and extends the bounds based on the `leftExtension`, `rightExtension`, `topExtension`, and `bottomExtension` values.

The default value is `0`.

Implementation
`public function get leftExtension():int`
`public function set leftExtension(value:int):void`

rightExtension | property |

`rightExtension:int` [read-write]

Language Version : | ActionScript 3.0

Player Version : | Flash Player 10

The growth in pixels on the right side of the target object.

The growth is the area beyond the bounds of the target object that is passed to the shader during execution. At execution time Flash Player computes the normal bounds of a movie clip and extends the bounds based on the `leftExtension`, `rightExtension`, `topExtension`, and `bottomExtension` values.

The default value is `0`.

Implementation
`public function get rightExtension():int`
`public function set rightExtension(value:int):void`

shader | property |

`shader:Shader` [read-write]

Language Version : | ActionScript 3.0

Player Version : | Flash Player 10

The shader to use for this filter.

The Shader assigned to the `shader` property must specify at least one `image4` input. The input does not need to be specified in code using the associated ShaderInput object's `input` property. Instead, the object to which the filter is applied is automatically used as the first input (the input with `index` 0). A shader used as a filter can specify more than one input, in which case any additional input must be specified by setting its ShaderInput instance's `input` property.

When you assign a Shader instance to this property the shader is copied internally and the filter operation uses that internal copy, not a reference to the original shader. Any changes made to the shader, such as changing a parameter value, input, or bytecode, are not applied to the copied shader that's used for the filter. To make it so that shader changes are taken into account in the filter output, you must reassign the Shader instance to the `shader` property.

Implementation
`public function get shader():Shader`
`public function set shader(value:Shader):void`

topExtension | property |

`topExtension:int` [read-write]

Language Version : | ActionScript 3.0

Player Version : | Flash Player 10

The growth in pixels on the top side of the target object.

The growth is the area beyond the bounds of the target object that is passed to the shader during execution. At execution time Flash Player computes the normal bounds of a movie clip and extends the bounds based on the `leftExtension`, `rightExtension`, `topExtension`, and `bottomExtension` values.

The default value is `0`.

Implementation
`public function get topExtension():int`
`public function set topExtension(value:int):void`
Constructor Detail

ShaderFilter | () | Constructor

`public function ShaderFilter(shader:Shader = null)`

Language Version : | ActionScript 3.0

Player Version : | Flash Player 10

Creates a new shader filter.

Parameters

| `shader:Shader` (default = `null`)`` — The Shader to use for this filter. For details and limitations that the shader must conform to, see the description for the `shader` property.

See also

shader
Examples How to use examples
ShaderFilterExample.1.as
The following example loads a shader and uses it as the `shader` property of a ShaderFilter. The code draws a circle in a Sprite instance and adds it to the stage. When the shader loads, the shader filter is applied to that Sprite.

Note that this example assumes there's a shader bytecode file named "gradient.hbc" in the same directory as the output directory for the application.

    //
    // Source code for the shader:
    //
    <languageVersion : 1.0;>

    kernel DoNothing
    <
        nameSpace: "Adobe::Example";
        version: 1;
        description: "Applies a gradient across the red channel of the input image.";
    >
    {
        input image4 src;
        output pixel4 dst;

        parameter float width
        <
            description: "The width of the image to which the shader is applied.";
            minValue: 0.0;
        >;

        void evaluatePixel()
        {
            pixel4 temp = sampleNearest(src, outCoord());
            temp.r = 1.0 - (outCoord().x * (1.0 / width));
            dst = temp;
        }
    }

    //
    // ActionScript source code:
    //
    package {
        import flash.display.Shader;
        import flash.display.Sprite;
        import flash.events.Event;
        import flash.filters.ShaderFilter;
        import flash.net.URLLoader;
        import flash.net.URLLoaderDataFormat;
        import flash.net.URLRequest;

        public class ShaderFilterExample extends Sprite {

            private var loader:URLLoader;
            private var s:Sprite;

            public function ShaderFilterExample() {
                loader = new URLLoader();
                loader.dataFormat = URLLoaderDataFormat.BINARY;
                loader.addEventListener(Event.COMPLETE, loadCompleteHandler);
                loader.load(new URLRequest("gradient.hbc"));

                s = new Sprite();
                s.graphics.beginFill(0x009900);
                s.graphics.drawCircle(100, 100, 100);
                addChild(s);
            }

            private function loadCompleteHandler(event:Event):void {
                var shader:Shader = new Shader(loader.data);
                shader.data.width.value = [s.width];

                var gradientFilter:ShaderFilter = new ShaderFilter(shader);
                s.filters = [gradientFilter];
            }
        }
    }

Submit Feedback on LiveDocs
© 2004-2008 Adobe Systems Incorporated. All rights reserved.
Tue May 20 2008, 04:02 AM -07:00