| Package | starling.filters |
| Class | public class FragmentFilter |
| Inheritance | FragmentFilter  EventDispatcher Object |
| Subclasses | BlurFilter, ColorMatrixFilter, CompositeFilter, DisplacementMapFilter, DropShadowFilter, FilterChain, GlowFilter |
filter property.
A fragment filter works in the following way:
process method.FilterEffect subclass
that processes the input via fragment and vertex shaders to achieve a certain
effect.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
| Property | Defined 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 | ||
| Property | Defined 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 | ||
| Method | Defined By | ||
|---|---|---|---|
Creates a new instance. | FragmentFilter | ||
 | 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 | ||
| dispatchEvent(event:Event):void Dispatches an event to all objects that have registered listeners for its type. | EventDispatcher | |
| 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 | ||
| 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 | ||
| removeEventListener(type:String, listener:Function):void Removes an event listener from the object. | EventDispatcher | |
| removeEventListeners(type:String = null):void Removes all event listeners with a certain type, or all of them if type is null. | EventDispatcher | |
Renders the filtered target object. | FragmentFilter | ||
| Method | Defined By | ||
|---|---|---|---|
Creates the effect that does the actual, low-level rendering. | FragmentFilter | ||
onTargetAssigned(target:DisplayObject):void Called when assigning a target display object. | FragmentFilter | ||
setRequiresRedraw():void Call this method when any of the filter's properties changes. | FragmentFilter | ||
| 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 | |||
| alwaysDrawToBackBuffer | property |
Hide Inherited Public Methods
Show Inherited Public MethodsalwaysDrawToBackBuffer:BooleanIndicates 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.
public function get alwaysDrawToBackBuffer():Boolean public function set alwaysDrawToBackBuffer(value:Boolean):void| antiAliasing | property |
antiAliasing:intThe 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.
public function get antiAliasing():int public function set antiAliasing(value:int):void| effect | property |
effect:FilterEffect [read-only] The effect instance returning the FilterEffect created via createEffect.
protected function get effect():FilterEffect| indexData | property |
indexData:IndexData [read-only] The IndexData used to process the effect. Per default, references a quad (two triangles) of four vertices.
protected function get indexData():IndexData| isCached | property |
isCached:Boolean [read-only] Indicates if the filter is cached (via the cache method).
public function get isCached():Boolean| maintainResolutionAcrossPasses | property |
maintainResolutionAcrossPasses:BooleanIndicates 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.
protected function get maintainResolutionAcrossPasses():Boolean protected function set maintainResolutionAcrossPasses(value:Boolean):void| numPasses | property |
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.
public function get numPasses():int| padding | property |
padding:PaddingPadding 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.
public function get padding():Padding public function set padding(value:Padding):void| resolution | property |
resolution:NumberThe 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.
public function get resolution():Number public function set resolution(value:Number):void| textureFormat | property |
textureFormat:StringThe format of the filter texture.
The default value is BGRA.
public function get textureFormat():String public function set textureFormat(value:String):void| textureSmoothing | property |
textureSmoothing:StringThe smoothing mode of the filter texture.
The default value is bilinear.
public function get textureSmoothing():String public function set textureSmoothing(value:String):void| vertexData | property |
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.
protected function get vertexData():VertexData| FragmentFilter | () | Constructor |
public function FragmentFilter()Creates a new instance. The base class' implementation just draws the unmodified input texture.
| cache | () | method |
public function cache():voidCaches 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():voidClears the cached output of the filter. After calling this method, the filter will be processed once per frame again.
| createEffect | () | method |
protected function createEffect():FilterEffectCreates 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).
ReturnsFilterEffect |
| dispose | () | method |
public function dispose():voidDisposes all resources that have been created by the filter.
| onTargetAssigned | () | method |
protected function onTargetAssigned(target:DisplayObject):voidCalled 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) |
Texture |
| render | () | method |
public function render(painter:Painter):voidRenders 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():voidCall this method when any of the filter's properties changes. This will make sure the filter is redrawn in the next frame.
| change | Event |
starling.events.EventDispatched when the settings change in a way that requires a redraw.
| enterFrame | Event |
starling.events.EnterFrameEventDispatched every frame on filters assigned to display objects connected to the stage.