Creates a new effect.
The internally used index buffer used on rendering.
The current size of the index buffer (in number of indices).
The MVP (modelview-projection) matrix transforms vertices into clipspace.
The 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.
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
.
Returns the base name for the program. @default the fully qualified class name
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.
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.
@default 0
The internally used vertex buffer used on rendering.
The current size of the vertex buffer (in blocks of 32 bits).
The data format that this effect requires from the VertexData that it renders:
"position:number2"
The vertex format expected by uploadVertexData
:
"position:number2"
Purges the index- and vertex-buffers.
Purges one or both of the vertex- and index-buffers.
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.
Uploads the given index data to the internal index buffer. If the buffer is too small, a new one is created automatically.
@param indexData The IndexData instance to upload.
@param bufferUsage 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.
Uploads the given vertex data to the internal vertex buffer. If the buffer is too small, a new one is created automatically.
@param vertexData The VertexData instance to upload.
@param bufferUsage 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.
Generated using TypeDoc
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
andFragmentFilter
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!
Note that the
VertexData
being uploaded has to be created with the same format as the one returned by the effect'svertexFormat
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
orMeshEffect
, 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():number
(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 theVertexData
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 aftercontext.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
andMeshEffect
classes to see how to approach sub-classing.@see FilterEffect @see MeshEffect @see starling.styles.MeshStyle @see starling.filters.FragmentFilter @see starling.utils.RenderUtil