Packagestarling.rendering
Classpublic class Effect
InheritanceEffect Inheritance Object
Subclasses FilterEffect

An effect encapsulates all steps of a Stage3D draw operation. It configures the render context and sets up shader programs as well as index- and vertex-buffers, thus providing the basic mechanisms of all low-level rendering.

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:

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

FilterEffect
MeshEffect
starling.styles.MeshStyle
starling.filters.FragmentFilter
starling.utils.RenderUtil


Public Properties
 PropertyDefined 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
Protected Properties
 PropertyDefined 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
Public Methods
 MethodDefined By
  
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
Protected Methods
 MethodDefined 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
Public Constants
 ConstantDefined By
  VERTEX_FORMAT : VertexDataFormat
[static] The vertex format expected by uploadVertexData: "position:float2"
Effect
Property Detail
indexBufferproperty
indexBuffer:IndexBuffer3D  [read-only]

The internally used index buffer used on rendering.


Implementation
    protected function get indexBuffer():IndexBuffer3D
indexBufferSizeproperty 
indexBufferSize:int  [read-only]

The current size of the index buffer (in number of indices).


Implementation
    protected function get indexBufferSize():int
mvpMatrix3Dproperty 
mvpMatrix3D:Matrix3D

The MVP (modelview-projection) matrix transforms vertices into clipspace.


Implementation
    public function get mvpMatrix3D():Matrix3D
    public function set mvpMatrix3D(value:Matrix3D):void
onRestoreproperty 
onRestore:Function

The 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.


Implementation
    public function get onRestore():Function
    public function set onRestore(value:Function):void
programproperty 
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.


Implementation
    protected function get program():Program
programBaseNameproperty 
programBaseName:String

Returns the base name for the program.

The default value is the fully qualified class name.


Implementation
    protected function get programBaseName():String
    protected function set programBaseName(value:String):void
programNameproperty 
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.


Implementation
    protected function get programName():String
programVariantNameproperty 
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.


Implementation
    protected function get programVariantName():uint
vertexBufferproperty 
vertexBuffer:VertexBuffer3D  [read-only]

The internally used vertex buffer used on rendering.


Implementation
    protected function get vertexBuffer():VertexBuffer3D
vertexBufferSizeproperty 
vertexBufferSize:int  [read-only]

The current size of the vertex buffer (in blocks of 32 bits).


Implementation
    protected function get vertexBufferSize():int
vertexFormatproperty 
vertexFormat:VertexDataFormat  [read-only]

The data format that this effect requires from the VertexData that it renders: "position:float2"


Implementation
    public function get vertexFormat():VertexDataFormat
Constructor Detail
Effect()Constructor
public function Effect()

Creates a new effect.

Method Detail
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:

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.

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

Purges the index- and vertex-buffers.

purgeBuffers()method 
public function purgeBuffers(vertexBuffer:Boolean = true, indexBuffer:Boolean = true):void

Purges 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):void

Uploads 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) — The expected buffer usage. Use one of the constants defined in 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):void

Uploads 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) — The expected buffer usage. Use one of the constants defined in Context3DBufferUsage. Only used when the method call causes the creation of a new vertex buffer.

Constant Detail
VERTEX_FORMATConstant
public static const VERTEX_FORMAT:VertexDataFormat

The vertex format expected by uploadVertexData: "position:float2"