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

Package | flash.filters
Class | public final class ColorMatrixFilter
Inheritance | ColorMatrixFilter BitmapFilter Object

Language Version : | ActionScript 3.0

Player Version : | Flash Player 9

The ColorMatrixFilter class lets you apply a 4 x 5 matrix transformation on the RGBA color and alpha values of every pixel in the input image to produce a result with a new set of RGBA color and alpha values. It allows saturation changes, hue rotation, luminance to alpha, and various other effects. You can apply the filter to any display object (that is, objects that inherit from the DisplayObject class), such as MovieClip, SimpleButton, TextField, and Video objects, as well as to BitmapData objects.

Note: For RGBA values, the most significant byte represents the red channel value, followed by green, blue, and then alpha.

To create a new color matrix filter, use the syntax `new ColorMatrixFilter()`. 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 `cacheAsBitmap` property of the display object is set to `true`. If you remove all filters, the original value of `cacheAsBitmap` is restored.

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.

View the examples

See also

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

Public Properties
Hide Inherited Public Properties
Show Inherited Public Properties

| Property | Defined By
--- | --- | ---
|  | constructor : Object A reference to the class object or constructor function for a given object instance. | Object
|  | matrix : Array An array of 20 items for 4 x 5 color transform. | ColorMatrixFilter
|  | prototype : Object [static] A reference to the prototype object of a class or function object. | Object

Public Methods
Hide Inherited Public Methods
Show Inherited Public Methods

| Method | Defined By
--- | --- | ---
|  | ColorMatrixFilter(matrix:Array = null) Initializes a new ColorMatrixFilter instance with the specified parameters. | ColorMatrixFilter
|  | clone():BitmapFilter Returns a copy of this filter object. | ColorMatrixFilter
|  | 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

matrix | property

`matrix:Array` [read-write]

Language Version : | ActionScript 3.0

Player Version : | Flash Player 9

An array of 20 items for 4 x 5 color transform. The `matrix` property cannot be changed by directly modifying its value (for example, `myFilter.matrix[2] = 1;`). Instead, you must get a reference to the array, make the change to the reference, and reset the value.

The color matrix filter separates each source pixel into its red, green, blue, and alpha components as srcR, srcG, srcB, srcA. To calculate the result of each of the four channels, the value of each pixel in the image is multiplied by the values in the transformation matrix. An offset, between -255 and 255, can optionally be added to each result (the fifth item in each row of the matrix). The filter combines each color component back into a single pixel and writes out the result. In the following formula, a[0] through a[19] correspond to entries 0 through 19 in the 20-item array that is passed to the `matrix` property:

     redResult   = (a[0]  * srcR) + (a[1]  * srcG) + (a[2]  * srcB) + (a[3]  * srcA) + a[4]
     greenResult = (a[5]  * srcR) + (a[6]  * srcG) + (a[7]  * srcB) + (a[8]  * srcA) + a[9]
     blueResult  = (a[10] * srcR) + (a[11] * srcG) + (a[12] * srcB) + (a[13] * srcA) + a[14]
     alphaResult = (a[15] * srcR) + (a[16] * srcG) + (a[17] * srcB) + (a[18] * srcA) + a[19]

For each color value in the array, a value of 1 is equal to 100% of that channel being sent to the output, preserving the value of the color channel.

The calculations are performed on unmultiplied color values. If the input graphic consists of premultiplied color values, those values are automatically converted into unmultiplied color values for this operation.

Two optimized modes are available:

Alpha only. When you pass to the filter a matrix that adjusts only the alpha component, as shown here, the filter optimizes its performance:

         1 0 0 0 0
         0 1 0 0 0
         0 0 1 0 0
         0 0 0 N 0  (where N is between 0.0 and 1.0)

Faster version. Available only with SSE/AltiVec accelerator-enabled processors, such as Intel® Pentium 3 and later and Apple® G4 and later. The accelerator is used when the multiplier terms are in the range -15.99 to 15.99 and the adder terms a[4], a[9], a[14], and a[19] are in the range -8000 to 8000.

Implementation
`public function get matrix():Array`
`public function set matrix(value:Array):void`
Throws

| `TypeError` — The Array is null when being set

Constructor Detail

ColorMatrixFilter | () | Constructor

`public function ColorMatrixFilter(matrix:Array = null)`

Language Version : | ActionScript 3.0

Player Version : | Flash Player 9

Initializes a new ColorMatrixFilter instance with the specified parameters.

Parameters

| `matrix:Array` (default = `null`)`` — An array of 20 items arranged as a 4 x 5 matrix.

Method Detail

clone | () | method

`override public function clone():BitmapFilter`

Language Version : | ActionScript 3.0

Player Version : | Flash Player 9

Returns a copy of this filter object.

Returns

| `BitmapFilter` — A new ColorMatrixFilter instance with all of the same properties as the original one.

Examples How to use examples
ColorMatrixFilterExample.as
The following example applies different color matrix filters to an image file. The filter constructor calls `buildChild()` four times to load and display four instances of the image. The first call to `buildChild()` takes `null` as an argument, applying no filter to the first instance. Each subsequent call to `buildChild()` takes as an argument a function that applies a different color matrix filter to each subsequent instance of the image.

The `buildChild()` function creates a new Loader object named `loader`. For each call to `buildChild()`, attach an event listener to the Loader object to listen for `complete` events, which are handled by the function passed to `buildChild()`.

The `applyRed()`, `applyGreen()`, and `applyBlue()` functions use different values for the `matrix` array to achieve different effects.

Note: For best results, use an image approximately 80 pixels in width. The name and location of the image file should match the value you pass to the `url` property. For example, the value passed to `url` in the example points to an image file named "Image.jpg" that is in the same directory as your SWF file.

    package {
        import flash.display.DisplayObject;
        import flash.display.Loader;
        import flash.display.Sprite;
        import flash.events.Event;
        import flash.events.IOErrorEvent;
        import flash.filters.ColorMatrixFilter;
        import flash.net.URLRequest;

        public class ColorMatrixFilterExample extends Sprite {
            private var size:uint  = 140;
            private var url:String = "Image.jpg";

            public function ColorMatrixFilterExample() {
                buildChild(null);
                buildChild(applyRed);
                buildChild(applyGreen);
                buildChild(applyBlue);
            }

            private function buildChild(loadHandler:Function):void {
                var loader:Loader = new Loader();
                loader.x = numChildren * size;
                loader.y = size;
                loader.contentLoaderInfo.addEventListener(IOErrorEvent.IO_ERROR, ioErrorHandler);
                if (loadHandler != null) {
                    loader.contentLoaderInfo.addEventListener(Event.COMPLETE, loadHandler);
                }

                var request:URLRequest = new URLRequest(url);
                loader.load(request);
                addChild(loader);
            }

            private function applyRed(event:Event):void {
                var child:DisplayObject = DisplayObject(event.target.loader);
                var matrix:Array = new Array();
                matrix = matrix.concat([1, 0, 0, 0, 0]); // red
                matrix = matrix.concat([0, 0, 0, 0, 0]); // green
                matrix = matrix.concat([0, 0, 0, 0, 0]); // blue
                matrix = matrix.concat([0, 0, 0, 1, 0]); // alpha

                applyFilter(child, matrix);
            }

            private function applyGreen(event:Event):void {
                var child:DisplayObject = DisplayObject(event.target.loader);
                var matrix:Array = new Array();
                matrix = matrix.concat([0, 0, 0, 0, 0]); // red
                matrix = matrix.concat([0, 1, 0, 0, 0]); // green
                matrix = matrix.concat([0, 0, 0, 0, 0]); // blue
                matrix = matrix.concat([0, 0, 0, 1, 0]); // alpha

                applyFilter(child, matrix);
            }

            private function applyBlue(event:Event):void {
                var child:DisplayObject = DisplayObject(event.target.loader);
                var matrix:Array = new Array();
                matrix = matrix.concat([0, 0, 0, 0, 0]); // red
                matrix = matrix.concat([0, 0, 0, 0, 0]); // green
                matrix = matrix.concat([0, 0, 1, 0, 0]); // blue
                matrix = matrix.concat([0, 0, 0, 1, 0]); // alpha

                applyFilter(child, matrix);
            }

            private function applyFilter(child:DisplayObject, matrix:Array):void {
                var filter:ColorMatrixFilter = new ColorMatrixFilter(matrix);
                var filters:Array = new Array();
                filters.push(filter);
                child.filters = filters;
            }

            private function ioErrorHandler(event:IOErrorEvent):void {
                trace("Unable to load image: " + url);
            }
        }
    }

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