| Package | starling.filters |
| Class | public class FragmentFilter |
| Inheritance | FragmentFilter  Object |
| Subclasses | BlurFilter, ColorMatrixFilter, DisplacementMapFilter |
A fragment filter works in the following way:
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.
| 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 | ||
| 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 | ||
| 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 | ||
Applies the filter on a certain display object, rendering the output into the current
render target. | FragmentFilter | ||
| Method | Defined By | ||
|---|---|---|---|
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 | ||
| 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 | ||
| baseTextureID | property |
baseTextureID:intThe ID (sampler) of the input texture (containing the output of the previous pass).
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).
public function get isCached():Boolean| marginX | property |
marginX:NumberThe x-margin will extend the size of the filter texture along the x-axis. Useful when the filter will "grow" the rendered object.
protected function get marginX():Number protected function set marginX(value:Number):void| marginY | property |
marginY:NumberThe y-margin will extend the size of the filter texture along the y-axis. Useful when the filter will "grow" the rendered object.
protected function get marginY():Number protected function set marginY(value:Number):void| mode | property |
mode:StringThe filter mode, which is one of the constants defined in the "FragmentFilterMode" class.
The default value is "replace".
public function get mode():String public function set mode(value:String):void| mvpConstantID | property |
mvpConstantID:intThe ID of the first register of the modelview-projection constant (a 4x4 matrix).
protected function get mvpConstantID():int protected function set mvpConstantID(value:int):void| numPasses | property |
numPasses:intThe number of passes the filter is applied. The "activate" and "deactivate" methods will be called that often.
protected function get numPasses():int protected function set numPasses(value:int):void| offsetX | property |
offsetX:NumberUse the x-offset to move the filter output to the right or left.
public function get offsetX():Number public function set offsetX(value:Number):void| offsetY | property |
offsetY:NumberUse the y-offset to move the filter output to the top or bottom.
public function get offsetY():Number public function set offsetY(value:Number):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 (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.
public function get resolution():Number public function set resolution(value:Number):void| texCoordsAtID | property |
texCoordsAtID:intThe ID of the vertex buffer attribute that stores the texture coordinates.
protected function get texCoordsAtID():int protected function set texCoordsAtID(value:int):void| vertexPosAtID | property |
vertexPosAtID:intThe ID of the vertex buffer attribute that stores the vertex position.
protected function get vertexPosAtID():int protected function set vertexPosAtID(value:int):void| 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.
ParametersnumPasses:int (default = 1) | |
resolution:Number (default = 1.0) |
| activate | () | method |
protected function activate(pass:int, context:Context3D, texture:Texture):voidSubclasses 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):Program3DAssembles 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) |
Program3D |
| cache | () | method |
public function cache():voidCaches 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():voidClears the cached output of the filter. After calling this method, the filter will be executed once per frame again.
| createPrograms | () | method |
protected function createPrograms():voidSubclasses 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):voidThis 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():voidDisposes the filter (programs, buffers, textures).
| render | () | method |
public function render(object:DisplayObject, support:RenderSupport, parentAlpha:Number):voidApplies 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 |
| PMA | Constant |
protected const PMA:Boolean = trueAll 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:StringThe standard vertex shader code. It will be used automatically if you don't create a custom vertex shader yourself.