GODPAPER | All Packages | All Classes | Index | Frames No Frames |
ColorMatrixFilter

Package | starling.filters
Class | public class ColorMatrixFilter
Inheritance | ColorMatrixFilter FragmentFilter Object

The ColorMatrixFilter class lets you apply a 4x5 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.

The class contains several convenience methods for frequently used color adjustments. All those methods change the current matrix, which means you can easily combine them in one filter:

          // create an inverted filter with 50% saturation and 180° hue rotation
          var filter:ColorMatrixFilter = new ColorMatrixFilter();
          filter.invert();
          filter.adjustSaturation(-0.5);
          filter.adjustHue(1.0);

If you want to gradually animate one of the predefined color adjustments, either reset the matrix after each step, or use an identical adjustment value for each step; the changes will add up.

Public Properties
Hide Inherited Public Properties
Show Inherited Public Properties

| Property | Defined By
--- | --- | ---
|  | isCached : Boolean [read-only] Indicates if the filter is cached (via the "cache" method). | FragmentFilter
|  | matrix : Vector.<Number> A vector of 20 items arranged as a 4x5 matrix. | ColorMatrixFilter
|  | mode : String The filter mode, which is one of the constants defined in the "FragmentFilterMode" class. | FragmentFilter
|  | offsetX : Number Use the x-offset to move the filter output to the right or left. | FragmentFilter
|  | offsetY : Number Use the y-offset to move the filter output to the top or bottom. | FragmentFilter
|  | resolution : Number The resolution of the filter texture. | FragmentFilter

Protected Properties
Hide Inherited Protected Properties
Show Inherited Protected Properties

| Property | Defined By
--- | --- | ---
|  | baseTextureID : int The ID (sampler) of the input texture (containing the output of the previous pass). | FragmentFilter
|  | marginX : Number The x-margin will extend the size of the filter texture along the x-axis. | FragmentFilter
|  | marginY : Number The y-margin will extend the size of the filter texture along the y-axis. | FragmentFilter
|  | mvpConstantID : int The ID of the first register of the modelview-projection constant (a 4x4 matrix). | FragmentFilter
|  | numPasses : int The number of passes the filter is applied. | FragmentFilter
|  | texCoordsAtID : int The ID of the vertex buffer attribute that stores the texture coordinates. | FragmentFilter
|  | vertexPosAtID : int The ID of the vertex buffer attribute that stores the vertex position. | FragmentFilter

Public Methods
Hide Inherited Public Methods
Show Inherited Public Methods

| Method | Defined By
--- | --- | ---
|  | ColorMatrixFilter(matrix:Vector.<Number> = null) Creates a new ColorMatrixFilter instance with the specified matrix. | ColorMatrixFilter
|  | adjustBrightness(value:Number):void Changes the brightness. | ColorMatrixFilter
|  | adjustContrast(value:Number):void Changes the contrast. | ColorMatrixFilter
|  | adjustHue(value:Number):void Changes the hue of the image. | ColorMatrixFilter
|  | adjustSaturation(sat:Number):void Changes the saturation. | ColorMatrixFilter
|  | cache():void Caches the filter output into a texture. | FragmentFilter
|  | clearCache():void Clears the cached output of the filter. | FragmentFilter
|  | concat(matrix:Vector.<Number>):void Concatenates the current matrix with another one. | ColorMatrixFilter
|  | dispose():void [override] Disposes the filter (programs, buffers, textures). | ColorMatrixFilter
|  | invert():void Inverts the colors of the filtered objects. | ColorMatrixFilter
|  | render(object:DisplayObject, support:RenderSupport, parentAlpha:Number):void Applies the filter on a certain display object, rendering the output into the current render target. | FragmentFilter
|  | reset():void Changes the filter matrix back to the identity matrix. | ColorMatrixFilter

Protected Methods
Show Inherited Protected Methods
Show Inherited Protected Methods

| Method | Defined By
--- | --- | ---
|  | activate(pass:int, context:Context3D, texture:Texture):void Subclasses must override this method and use it to activate their fragment- and to vertext-programs. | FragmentFilter
|  | assembleAgal(fragmentShader:String = null, vertexShader:String = null):Program3D Assembles fragment- and vertex-shaders, passed as Strings, to a Program3D. | FragmentFilter
|  | createPrograms():void Subclasses must override this method and use it to create their fragment- and vertex-programs. | FragmentFilter
|  | deactivate(pass:int, context:Context3D, texture:Texture):void This method is called directly after 'context.drawTriangles'. | FragmentFilter

Protected Constants
Hide Inherited Protected Constants
Show Inherited Protected Constants

| Constant | Defined By
--- | --- | ---
|  | PMA : Boolean = true All filter processing is expected to be done with premultiplied alpha. | FragmentFilter
|  | STD_FRAGMENT_SHADER : String = tex oc, v0, fs0 <2d, clamp, linear, mipnone> The standard fragment shader code. | FragmentFilter
|  | STD_VERTEX_SHADER : String The standard vertex shader code. | FragmentFilter

Property Detail

matrix | property

`matrix:Vector.<Number>`

A vector of 20 items arranged as a 4x5 matrix.

Implementation
`public function get matrix():Vector.<Number>`
`public function set matrix(value:Vector.<Number>):void`
Constructor Detail

ColorMatrixFilter | () | Constructor

`public function ColorMatrixFilter(matrix:Vector.<Number> = null)`

Creates a new ColorMatrixFilter instance with the specified matrix.

Parameters

| `matrix:Vector.<Number>` (default = `null`)`` — a vector of 20 items arranged as a 4x5 matrix.

Method Detail

adjustBrightness | () | method

`public function adjustBrightness(value:Number):void`

Changes the brightness. Typical values are in the range (-1, 1). Values above zero will make the image brighter, values below zero will make it darker.

Parameters

| `value:Number`

adjustContrast | () | method |

`public function adjustContrast(value:Number):void`

Changes the contrast. Typical values are in the range (-1, 1). Values above zero will raise, values below zero will reduce the contrast.

Parameters

| `value:Number`

adjustHue | () | method |

`public function adjustHue(value:Number):void`

Changes the hue of the image. Typical values are in the range (-1, 1).

Parameters

| `value:Number`

adjustSaturation | () | method |

`public function adjustSaturation(sat:Number):void`

Changes the saturation. Typical values are in the range (-1, 1). Values above zero will raise, values below zero will reduce the saturation. '-1' will produce a grayscale image.

Parameters

| `sat:Number`

concat | () | method |

`public function concat(matrix:Vector.<Number>):void`

Concatenates the current matrix with another one.

Parameters

| `matrix:Vector.<Number>`

dispose | () | method |

`override public function dispose():void`

Disposes the filter (programs, buffers, textures).

invert | () | method |

`public function invert():void`

Inverts the colors of the filtered objects.

reset | () | method |

`public function reset():void`

Changes the filter matrix back to the identity matrix.

Thu Jan 16 2014, 01:11 PM +08:00