Packagestarling.filters
Classpublic class FragmentFilter
InheritanceFragmentFilter Inheritance 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
 PropertyDefined 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
 PropertyDefined 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
 MethodDefined 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
 MethodDefined 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
  
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
 ConstantDefined 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
baseTextureIDproperty
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
isCachedproperty 
isCached:Boolean  [read-only]

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


Implementation
    public function get isCached():Boolean
marginXproperty 
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
marginYproperty 
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
modeproperty 
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
mvpConstantIDproperty 
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
numPassesproperty 
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
offsetXproperty 
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
offsetYproperty 
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
resolutionproperty 
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
texCoordsAtIDproperty 
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
vertexPosAtIDproperty 
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:

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
PMAConstant
protected const PMA:Boolean = true

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

STD_FRAGMENT_SHADERConstant 
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_SHADERConstant 
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.