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:int
The 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: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.
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.
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"
.
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).
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.
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.
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.
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
.
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.
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.
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):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 )
|
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 |
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.