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

Package | starling.filters
Class | public class FragmentFilter
Inheritance | FragmentFilter Object
Subclasses | BlurFilter, ColorMatrixFilter, DisplacementMapFilter

The FragmentFilter class is the base class for all filter effects in Starling. All other filters of this package extend this class. You can attach them to any display object through the 'filter' property.

A fragment filter works in the following way:

1. The object that is filtered is rendered into a texture (in stage coordinates).
2. That texture is passed to the first filter pass.
3. Each pass processes the texture using a fragment shader (and optionally a vertex shader) to achieve a certain effect.
4. The output of each pass is used as the input for the next pass; if it's the final pass, it will be rendered directly to the back buffer.

All of this is set up by the abstract FragmentFilter class. Concrete subclasses just need to override the protected methods 'createPrograms', 'activate' and (optionally) 'deactivate' to create and execute its custom shader code. Each filter can be configured to either replace the original object, or be drawn below or above it. This can be done through the 'mode' property, which accepts one of the Strings defined in the 'FragmentFilterMode' class.

Beware that each filter should be used only on one object at a time. Otherwise, it will get slower and require more resources; and caching will lead to undefined results.

Public Properties

| Property | Defined By
--- | --- | ---
|  | isCached : Boolean [read-only] Indicates if the filter is cached (via the "cache" method). | FragmentFilter
|  | 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

| 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

| Method | Defined By
--- | --- | ---
|  | FragmentFilter(numPasses:int = 1, resolution:Number = 1.0) Creates a new Fragment filter with the specified number of passes and resolution. | FragmentFilter
|  | cache():void Caches the filter output into a texture. | FragmentFilter
|  | clearCache():void Clears the cached output of the filter. | FragmentFilter
|  | dispose():void Disposes the filter (programs, buffers, textures). | FragmentFilter
|  | 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

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

| 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

baseTextureID | property

`baseTextureID:int`

The ID (sampler) of the input texture (containing the output of the previous pass).

Implementation
`protected function get baseTextureID():int`
`protected function set baseTextureID(value:int):void`

isCached | property |

`isCached:Boolean` [read-only]

Indicates if the filter is cached (via the "cache" method).

Implementation
`public function get isCached():Boolean`

marginX | property |

`marginX:Number`

The x-margin will extend the size of the filter texture along the x-axis. Useful when the filter will "grow" the rendered object.

Implementation
`protected function get marginX():Number`
`protected function set marginX(value:Number):void`

marginY | property |

`marginY:Number`

The y-margin will extend the size of the filter texture along the y-axis. Useful when the filter will "grow" the rendered object.

Implementation
`protected function get marginY():Number`
`protected function set marginY(value:Number):void`

mode | property |

`mode:String`

The filter mode, which is one of the constants defined in the "FragmentFilterMode" class.

The default value is `"replace"`.

Implementation
`public function get mode():String`
`public function set mode(value:String):void`

mvpConstantID | property |

`mvpConstantID:int`

The ID of the first register of the modelview-projection constant (a 4x4 matrix).

Implementation
`protected function get mvpConstantID():int`
`protected function set mvpConstantID(value:int):void`

numPasses | property |

`numPasses:int`

The number of passes the filter is applied. The "activate" and "deactivate" methods will be called that often.

Implementation
`protected function get numPasses():int`
`protected function set numPasses(value:int):void`

offsetX | property |

`offsetX:Number`

Use the x-offset to move the filter output to the right or left.

Implementation
`public function get offsetX():Number`
`public function set offsetX(value:Number):void`

offsetY | property |

`offsetY:Number`

Use the y-offset to move the filter output to the top or bottom.

Implementation
`public function get offsetY():Number`
`public function set offsetY(value:Number):void`

resolution | property |

`resolution:Number`

The resolution of the filter texture. "1" means stage resolution, "0.5" half the stage resolution. A lower resolution saves memory and execution time (depending on the GPU), but results in a lower output quality. Values greater than 1 are allowed; such values might make sense for a cached filter when it is scaled up.

The default value is `1`.

Implementation
`public function get resolution():Number`
`public function set resolution(value:Number):void`

texCoordsAtID | property |

`texCoordsAtID:int`

The ID of the vertex buffer attribute that stores the texture coordinates.

Implementation
`protected function get texCoordsAtID():int`
`protected function set texCoordsAtID(value:int):void`

vertexPosAtID | property |

`vertexPosAtID:int`

The ID of the vertex buffer attribute that stores the vertex position.

Implementation
`protected function get vertexPosAtID():int`
`protected function set vertexPosAtID(value:int):void`
Constructor Detail

FragmentFilter | () | Constructor

`public function FragmentFilter(numPasses:int = 1, resolution:Number = 1.0)`

Creates a new Fragment filter with the specified number of passes and resolution. This constructor may only be called by the constructor of a subclass.

Parameters

| `numPasses:int` (default = `1`)``
| `resolution:Number` (default = `1.0`)``

Method Detail

activate | () | method

`protected function activate(pass:int, context:Context3D, texture:Texture):void`

Subclasses must override this method and use it to activate their fragment- and to vertext-programs. The 'activate' call directly precedes the call to 'context.drawTriangles'. Set up the context the way your filter needs it. The following constants and attributes are set automatically:

- vertex constants 0-3: mvpMatrix (3D)
- vertex attribute 0: vertex position (FLOAT_2)
- vertex attribute 1: texture coordinates (FLOAT_2)
- texture 0: input texture

Parameters

| `pass:int` — the current render pass, starting with '0'. Multipass filters can provide different logic for each pass.
| `context:Context3D` — the current context3D (the same as in Starling.context, passed just for convenience)
| `texture:Texture` — the input texture, which is already bound to sampler 0.

assembleAgal | () | method |

`protected function assembleAgal(fragmentShader:String = null, vertexShader:String = null):Program3D`

Assembles fragment- and vertex-shaders, passed as Strings, to a Program3D. If any argument is null, it is replaced by the class constants STD_FRAGMENT_SHADER or STD_VERTEX_SHADER, respectively.

Parameters

| `fragmentShader:String` (default = `null`)``
| `vertexShader:String` (default = `null`)``

Returns

| `Program3D`

cache | () | method |

`public function cache():void`

Caches the filter output into a texture. An uncached filter is rendered in every frame; a cached filter only once. However, if the filtered object or the filter settings change, it has to be updated manually; to do that, call "cache" again.

clearCache | () | method |

`public function clearCache():void`

Clears the cached output of the filter. After calling this method, the filter will be executed once per frame again.

createPrograms | () | method |

`protected function createPrograms():void`

Subclasses must override this method and use it to create their fragment- and vertex-programs.

deactivate | () | method |

`protected function deactivate(pass:int, context:Context3D, texture:Texture):void`

This method is called directly after 'context.drawTriangles'. If you need to clean up any resources, you can do so in this method.

Parameters

| `pass:int`
| `context:Context3D`
| `texture:Texture`

dispose | () | method |

`public function dispose():void`

Disposes the filter (programs, buffers, textures).

render | () | method |

`public function render(object:DisplayObject, support:RenderSupport, parentAlpha:Number):void`

Applies the filter on a certain display object, rendering the output into the current render target. This method is called automatically by Starling's rendering system for the object the filter is attached to.

Parameters

| `object:DisplayObject`
| `support:RenderSupport`
| `parentAlpha:Number`

Constant Detail

PMA | Constant

`protected const PMA:Boolean = true`

All filter processing is expected to be done with premultiplied alpha.

STD_FRAGMENT_SHADER | Constant |

`protected const STD_FRAGMENT_SHADER:String = tex oc, v0, fs0 <2d, clamp, linear, mipnone>`

The standard fragment shader code. It just forwards the texture color to the output.

STD_VERTEX_SHADER | Constant |

`protected const STD_VERTEX_SHADER:String`

The standard vertex shader code. It will be used automatically if you don't create a custom vertex shader yourself.

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