| Package | starling.rendering |
| Class | public class Effect |
| Inheritance | Effect  Object |
| Subclasses | FilterEffect |
Using the Effect class
Effects are mostly used by the MeshStyle and FragmentFilter
classes. When you extend those classes, you'll be required to provide a custom effect.
Setting it up for rendering is done by the base class, though, so you rarely have to
initiate the rendering yourself. Nevertheless, it's good to know how an effect is doing
its work.
Using an effect always follows steps shown in the example below. You create the effect, configure it, upload vertex data and then: draw!
// create effect
var effect:MeshEffect = new MeshEffect();
// configure effect
effect.mvpMatrix3D = painter.state.mvpMatrix3D;
effect.texture = getHeroTexture();
effect.color = 0xf0f0f0;
// upload vertex data
effect.uploadIndexData(indexData);
effect.uploadVertexData(vertexData);
// draw!
effect.render(0, numTriangles);Note that the VertexData being uploaded has to be created with the same
format as the one returned by the effect's vertexFormat property.
Extending the Effect class
The base Effect-class can only render white triangles, which is not much
use in itself. However, it is designed to be extended; subclasses can easily implement any
kinds of shaders.
Normally, you won't extend this class directly, but either FilterEffect
or MeshEffect, depending on your needs (i.e. if you want to create a new
fragment filter or a new mesh style). Whichever base class you're extending, you should
override the following methods:
createProgram():Program — must create the actual program containing
vertex- and fragment-shaders. A program will be created only once for each render
context; this is taken care of by the base class.get programVariantName():uint (optional) — override this if your
effect requires different programs, depending on its settings. The recommended
way to do this is via a bit-mask that uniquely encodes the current settings.get vertexFormat():String (optional) — must return the
VertexData format that this effect requires for its vertices. If
the effect does not require any special attributes, you can leave this out.beforeDraw(context:Context3D):void — Set up your context by
configuring program constants and buffer attributes.afterDraw(context:Context3D):void — Will be called directly after
context.drawTriangles(). Clean up any context configuration here.Furthermore, you need to add properties that manage the data you require on rendering,
e.g. the texture(s) that should be used, program constants, etc. I recommend looking at
the implementations of Starling's FilterEffect and MeshEffect
classes to see how to approach sub-classing.
See also
| Property | Defined By | ||
|---|---|---|---|
| mvpMatrix3D : Matrix3D The MVP (modelview-projection) matrix transforms vertices into clipspace. | Effect | ||
| onRestore : Function The function that you provide here will be called after a context loss. | Effect | ||
| vertexFormat : VertexDataFormat [read-only] The data format that this effect requires from the VertexData that it renders:
"position:float2" | Effect | ||
| Property | Defined By | ||
|---|---|---|---|
| indexBuffer : IndexBuffer3D [read-only] The internally used index buffer used on rendering. | Effect | ||
| indexBufferSize : int [read-only] The current size of the index buffer (in number of indices). | Effect | ||
| program : Program [read-only] Returns the current program, either by creating a new one (via
createProgram) or by getting it from the Painter. | Effect | ||
| programBaseName : String Returns the base name for the program. | Effect | ||
| programName : String [read-only] Returns the full name of the program, which is used to register it at the current
Painter. | Effect | ||
| programVariantName : uint [read-only] Override this method if the effect requires a different program depending on the
current settings. | Effect | ||
| vertexBuffer : VertexBuffer3D [read-only] The internally used vertex buffer used on rendering. | Effect | ||
| vertexBufferSize : int [read-only] The current size of the vertex buffer (in blocks of 32 bits). | Effect | ||
| Method | Defined By | ||
|---|---|---|---|
Effect() Creates a new effect. | Effect | ||
dispose():void Purges the index- and vertex-buffers. | Effect | ||
purgeBuffers(vertexBuffer:Boolean = true, indexBuffer:Boolean = true):void Purges one or both of the vertex- and index-buffers. | Effect | ||
render(firstIndex:int = 0, numTriangles:int = -1):void Draws the triangles described by the index- and vertex-buffers, or a range of them. | Effect | ||
uploadIndexData(indexData:IndexData, bufferUsage:String = staticDraw):void Uploads the given index data to the internal index buffer. | Effect | ||
uploadVertexData(vertexData:VertexData, bufferUsage:String = staticDraw):void Uploads the given vertex data to the internal vertex buffer. | Effect | ||
| Method | Defined By | ||
|---|---|---|---|
afterDraw(context:Context3D):void This method is called by render, directly after
context.drawTriangles. | Effect | ||
beforeDraw(context:Context3D):void This method is called by render, directly before
context.drawTriangles. | Effect | ||
Creates the program (a combination of vertex- and fragment-shader) used to render
the effect with the current settings. | Effect | ||
| Constant | Defined By | ||
|---|---|---|---|
| VERTEX_FORMAT : VertexDataFormat [static] The vertex format expected by uploadVertexData:
"position:float2" | Effect | ||
| indexBuffer | property |
indexBuffer:IndexBuffer3D [read-only] The internally used index buffer used on rendering.
protected function get indexBuffer():IndexBuffer3D| indexBufferSize | property |
indexBufferSize:int [read-only] The current size of the index buffer (in number of indices).
protected function get indexBufferSize():int| mvpMatrix3D | property |
mvpMatrix3D:Matrix3DThe MVP (modelview-projection) matrix transforms vertices into clipspace.
public function get mvpMatrix3D():Matrix3D public function set mvpMatrix3D(value:Matrix3D):void| onRestore | property |
onRestore:FunctionThe function that you provide here will be called after a context loss. Call both "upload..." methods from within the callback to restore any vertex or index buffers. The callback will be executed with the effect as its sole parameter.
public function get onRestore():Function public function set onRestore(value:Function):void| program | property |
program:Program [read-only] Returns the current program, either by creating a new one (via
createProgram) or by getting it from the Painter.
Do not override this method! Instead, implement createProgram.
protected function get program():Program| programBaseName | property |
programBaseName:StringReturns the base name for the program.
The default value is the fully qualified class name.
protected function get programBaseName():String protected function set programBaseName(value:String):void| programName | property |
programName:String [read-only] Returns the full name of the program, which is used to register it at the current
Painter.
The default implementation efficiently combines the program's base and variant
names (e.g. LightEffect#42). It shouldn't be necessary to override
this method.
protected function get programName():String| programVariantName | property |
programVariantName:uint [read-only] Override this method if the effect requires a different program depending on the current settings. Ideally, you do this by creating a bit mask encoding all the options. This method is called often, so do not allocate any temporary objects when overriding.
The default value is 0.
protected function get programVariantName():uint| vertexBuffer | property |
vertexBuffer:VertexBuffer3D [read-only] The internally used vertex buffer used on rendering.
protected function get vertexBuffer():VertexBuffer3D| vertexBufferSize | property |
vertexBufferSize:int [read-only] The current size of the vertex buffer (in blocks of 32 bits).
protected function get vertexBufferSize():int| vertexFormat | property |
vertexFormat:VertexDataFormat [read-only] The data format that this effect requires from the VertexData that it renders:
"position:float2"
public function get vertexFormat():VertexDataFormat| Effect | () | Constructor |
public function Effect()Creates a new effect.
| afterDraw | () | method |
protected function afterDraw(context:Context3D):void This method is called by render, directly after
context.drawTriangles. Resets vertex buffer attributes.
Parameters
context:Context3D |
| beforeDraw | () | method |
protected function beforeDraw(context:Context3D):void This method is called by render, directly before
context.drawTriangles. It activates the program and sets up
the context with the following constants and attributes:
vc0-vc3 — MVP matrixva0 — vertex position (xy)Parameters
context:Context3D |
| createProgram | () | method |
protected function createProgram():Program Creates the program (a combination of vertex- and fragment-shader) used to render
the effect with the current settings. Override this method in a subclass to create
your shaders. This method will only be called once; the program is automatically stored
in the Painter and re-used by all instances of this effect.
The basic implementation always outputs pure white.
ReturnsProgram |
| dispose | () | method |
public function dispose():voidPurges the index- and vertex-buffers.
| purgeBuffers | () | method |
public function purgeBuffers(vertexBuffer:Boolean = true, indexBuffer:Boolean = true):voidPurges one or both of the vertex- and index-buffers.
Parameters
vertexBuffer:Boolean (default = true) | |
indexBuffer:Boolean (default = true) |
| render | () | method |
public function render(firstIndex:int = 0, numTriangles:int = -1):void Draws the triangles described by the index- and vertex-buffers, or a range of them.
This calls beforeDraw, context.drawTriangles, and
afterDraw, in this order.
Parameters
firstIndex:int (default = 0) | |
numTriangles:int (default = -1) |
| uploadIndexData | () | method |
public function uploadIndexData(indexData:IndexData, bufferUsage:String = staticDraw):voidUploads the given index data to the internal index buffer. If the buffer is too small, a new one is created automatically.
Parameters
indexData:IndexData — The IndexData instance to upload.
| |
bufferUsage:String (default = staticDraw)Context3DBufferUsage. Only used when the method call
causes the creation of a new index buffer.
|
| uploadVertexData | () | method |
public function uploadVertexData(vertexData:VertexData, bufferUsage:String = staticDraw):voidUploads the given vertex data to the internal vertex buffer. If the buffer is too small, a new one is created automatically.
Parameters
vertexData:VertexData — The VertexData instance to upload.
| |
bufferUsage:String (default = staticDraw)Context3DBufferUsage. Only used when the method call
causes the creation of a new vertex buffer.
|
| VERTEX_FORMAT | Constant |
public static const VERTEX_FORMAT:VertexDataFormat The vertex format expected by uploadVertexData:
"position:float2"