Packagestarling.filters
Classpublic class FragmentFilter
InheritanceFragmentFilter Inheritance EventDispatcher Inheritance Object
Subclasses BlurFilter, ColorMatrixFilter, CompositeFilter, DisplacementMapFilter, DropShadowFilter, FilterChain, GlowFilter

The FragmentFilter class is the base class for all filter effects in Starling. All filters must 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 to be filtered is rendered into a texture.
  2. That texture is passed to the process method.
  3. This method processes the texture using a FilterEffect subclass that processes the input via fragment and vertex shaders to achieve a certain effect.
  4. If the filter requires several passes, the process method may execute the effect several times, or even make use of other filters in the process.
  5. In the end, a quad with the output texture is added to the batch renderer. In the next frame, if the object hasn't changed, the filter is drawn directly from the render cache.
  6. Alternatively, the last pass may be drawn directly to the back buffer. That saves one draw call, but means that the object may not be drawn from the render cache in the next frame. Starling makes an educated guess if that makes sense, but you can also force it to do so via the alwaysDrawToBackBuffer property.

All of this is set up by the basic FragmentFilter class. Concrete subclasses just need to override the protected method createEffect and (optionally) process. Multi-pass filters must also override numPasses.

Typically, any properties on the filter are just forwarded to an effect instance, which is then used automatically by process to render the filter pass. For a simple example on how to write a single-pass filter, look at the implementation of the ColorMatrixFilter; for a composite filter (i.e. a filter that combines several others), look at the GlowFilter.

Beware that a filter instance may only be used on one object at a time!

Animated filters

The process method of a filter is only called when it's necessary, i.e. when the filter properties or the target display object changes. This means that you cannot rely on the method to be called on a regular basis, as needed when creating an animated filter class. Instead, you can do so by listening for an ENTER_FRAME-event. It is dispatched on the filter once every frame, as long as the filter is assigned to a display object that is connected to the stage.

Caching

Per default, whenever the target display object is changed in any way (i.e. the render cache fails), the filter is reprocessed. However, you can manually cache the filter output via the method of the same name: this will let the filter redraw the current output texture, even if the target object changes later on. That's especially useful if you add a filter to an object that changes only rarely, e.g. a TextField or an Image. Keep in mind, though, that you have to call cache() again in order for any changes to show up.

See also

starling.rendering.FilterEffect


Public Properties
 PropertyDefined By
  alwaysDrawToBackBuffer : Boolean
Indicates if the last filter pass is always drawn directly to the back buffer.
FragmentFilter
  antiAliasing : int
The anti-aliasing level.
FragmentFilter
  isCached : Boolean
[read-only] Indicates if the filter is cached (via the cache method).
FragmentFilter
  numPasses : int
[read-only] Indicates the number of rendering passes required for this filter.
FragmentFilter
  padding : Padding
Padding can extend the size of the filter texture in all directions.
FragmentFilter
  resolution : Number
The resolution of the filter texture.
FragmentFilter
  textureFormat : String
The format of the filter texture.
FragmentFilter
  textureSmoothing : String
The smoothing mode of the filter texture.
FragmentFilter
Protected Properties
 PropertyDefined By
  effect : FilterEffect
[read-only] The effect instance returning the FilterEffect created via createEffect.
FragmentFilter
  indexData : IndexData
[read-only] The IndexData used to process the effect.
FragmentFilter
  maintainResolutionAcrossPasses : Boolean
Indicates if the filter requires all passes to be processed with the exact same resolution.
FragmentFilter
  vertexData : VertexData
[read-only] The VertexData used to process the effect.
FragmentFilter
Public Methods
 MethodDefined By
  
Creates a new instance.
FragmentFilter
 Inherited
addEventListener(type:String, listener:Function):void
Registers an event listener at a certain object.
EventDispatcher
  
cache():void
Caches the filter output into a texture.
FragmentFilter
  
clearCache():void
Clears the cached output of the filter.
FragmentFilter
 Inherited
dispatchEvent(event:Event):void
Dispatches an event to all objects that have registered listeners for its type.
EventDispatcher
 Inherited
dispatchEventWith(type:String, bubbles:Boolean = false, data:Object = null):void
Dispatches an event with the given parameters to all objects that have registered listeners for the given type.
EventDispatcher
  
dispose():void
Disposes all resources that have been created by the filter.
FragmentFilter
 Inherited
hasEventListener(type:String, listener:Function = null):Boolean
If called with one argument, figures out if there are any listeners registered for the given event type.
EventDispatcher
  
process(painter:Painter, helper:IFilterHelper, input0:Texture = null, input1:Texture = null, input2:Texture = null, input3:Texture = null):Texture
Does the actual filter processing.
FragmentFilter
 Inherited
removeEventListener(type:String, listener:Function):void
Removes an event listener from the object.
EventDispatcher
 Inherited
removeEventListeners(type:String = null):void
Removes all event listeners with a certain type, or all of them if type is null.
EventDispatcher
  
render(painter:Painter):void
Renders the filtered target object.
FragmentFilter
Protected Methods
 MethodDefined By
  
Creates the effect that does the actual, low-level rendering.
FragmentFilter
  
Called when assigning a target display object.
FragmentFilter
  
Call this method when any of the filter's properties changes.
FragmentFilter
Events
 Event Summary Defined By
  Dispatched when the settings change in a way that requires a redraw.FragmentFilter
  Dispatched every frame on filters assigned to display objects connected to the stage.FragmentFilter
Property Detail
alwaysDrawToBackBufferproperty
alwaysDrawToBackBuffer:Boolean

Indicates if the last filter pass is always drawn directly to the back buffer.

Per default, the filter tries to automatically render in a smart way: objects that are currently moving are rendered to the back buffer, objects that are static are rendered into a texture first, which allows the filter to be drawn directly from the render cache in the next frame (in case the object remains static).

However, this fails when filters are added to an object that does not support the render cache, or to a container with such a child (e.g. a Sprite3D object or a masked display object). In such a case, enable this property for maximum performance.

The default value is false.


Implementation
    public function get alwaysDrawToBackBuffer():Boolean
    public function set alwaysDrawToBackBuffer(value:Boolean):void
antiAliasingproperty 
antiAliasing:int

The anti-aliasing level. This is only used for rendering the target object into a texture, not for the filter passes. 0 - none, 4 - maximum.

The default value is 0.


Implementation
    public function get antiAliasing():int
    public function set antiAliasing(value:int):void
effectproperty 
effect:FilterEffect  [read-only]

The effect instance returning the FilterEffect created via createEffect.


Implementation
    protected function get effect():FilterEffect
indexDataproperty 
indexData:IndexData  [read-only]

The IndexData used to process the effect. Per default, references a quad (two triangles) of four vertices.


Implementation
    protected function get indexData():IndexData
isCachedproperty 
isCached:Boolean  [read-only]

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


Implementation
    public function get isCached():Boolean
maintainResolutionAcrossPassesproperty 
maintainResolutionAcrossPasses:Boolean

Indicates if the filter requires all passes to be processed with the exact same resolution.

Some filters must use the same resolution for input and output; e.g. the blur filter is very sensitive to changes of pixel / texel sizes. When the filter is used as part of a filter chain, or if its last pass is drawn directly to the back buffer, such a filter produces artifacts. In that case, the filter author must set this property to true.

The default value is false.


Implementation
    protected function get maintainResolutionAcrossPasses():Boolean
    protected function set maintainResolutionAcrossPasses(value:Boolean):void
numPassesproperty 
numPasses:int  [read-only]

Indicates the number of rendering passes required for this filter. Subclasses must override this method if the number of passes is not 1.


Implementation
    public function get numPasses():int
paddingproperty 
padding:Padding

Padding can extend the size of the filter texture in all directions. That's useful when the filter "grows" the bounds of the object in any direction.


Implementation
    public function get padding():Padding
    public function set padding(value:Padding):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, 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
textureFormatproperty 
textureFormat:String

The format of the filter texture.

The default value is BGRA.


Implementation
    public function get textureFormat():String
    public function set textureFormat(value:String):void
textureSmoothingproperty 
textureSmoothing:String

The smoothing mode of the filter texture.

The default value is bilinear.


Implementation
    public function get textureSmoothing():String
    public function set textureSmoothing(value:String):void
vertexDataproperty 
vertexData:VertexData  [read-only]

The VertexData used to process the effect. Per default, uses the format provided by the effect, and contains four vertices enclosing the target object.


Implementation
    protected function get vertexData():VertexData
Constructor Detail
FragmentFilter()Constructor
public function FragmentFilter()

Creates a new instance. The base class' implementation just draws the unmodified input texture.

Method Detail
cache()method
public function cache():void

Caches the filter output into a texture.

An uncached filter is rendered every frame (except if it can be rendered from the global render cache, which happens if the target object does not change its appearance or location relative to the stage). A cached filter is only rendered once; the output stays unchanged until you call cache again or change the filter settings.

Beware: you cannot cache filters on 3D objects; if the object the filter is attached to is a Sprite3D or has a Sprite3D as (grand-) parent, the request will be silently ignored. However, you can cache a 2D object that has 3D children!

clearCache()method 
public function clearCache():void

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

createEffect()method 
protected function createEffect():FilterEffect

Creates the effect that does the actual, low-level rendering. Must be overridden by all subclasses that do any rendering on their own (instead of just forwarding processing to other filters).

Returns
FilterEffect
dispose()method 
public function dispose():void

Disposes all resources that have been created by the filter.

onTargetAssigned()method 
protected function onTargetAssigned(target:DisplayObject):void

Called when assigning a target display object. Override to plug in class-specific logic.

Parameters

target:DisplayObject

process()method 
public function process(painter:Painter, helper:IFilterHelper, input0:Texture = null, input1:Texture = null, input2:Texture = null, input3:Texture = null):Texture

Does the actual filter processing. This method will be called with up to four input textures and must return a new texture (acquired from the helper) that contains the filtered output. To to do this, it configures the FilterEffect (provided via createEffect) and calls its render method.

In a standard filter, only input0 will contain a texture; that's the object the filter was applied to, rendered into an appropriately sized texture. However, filters may also accept multiple textures; that's useful when you need to combine the output of several filters into one. For example, the DropShadowFilter uses a BlurFilter to create the shadow and then feeds both input and shadow texture into a CompositeFilter.

Never create or dispose any textures manually within this method; instead, get new textures from the provided helper object, and pass them to the helper when you do not need them any longer. Ownership of both input textures and returned texture lies at the caller; only temporary textures should be put into the helper.

Parameters

painter:Painter
 
helper:IFilterHelper
 
input0:Texture (default = null)
 
input1:Texture (default = null)
 
input2:Texture (default = null)
 
input3:Texture (default = null)

Returns
Texture
render()method 
public function render(painter:Painter):void

Renders the filtered target object. Most users will never have to call this manually; it's executed automatically in the rendering process of the filtered display object.

Parameters

painter:Painter

setRequiresRedraw()method 
protected function setRequiresRedraw():void

Call this method when any of the filter's properties changes. This will make sure the filter is redrawn in the next frame.

Event Detail
change Event
Event Object Type: starling.events.Event

Dispatched when the settings change in a way that requires a redraw.

enterFrame Event  
Event Object Type: starling.events.EnterFrameEvent

Dispatched every frame on filters assigned to display objects connected to the stage.