Options
All
  • Public
  • Public/Protected
  • All
Menu

Class Effect

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 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():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 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 FilterEffect @see MeshEffect @see starling.styles.MeshStyle @see starling.filters.FragmentFilter @see starling.utils.RenderUtil

Hierarchy

Index

Constructors

constructor

Properties

Protected indexBuffer

indexBuffer: IndexBuffer3D

The internally used index buffer used on rendering.

Protected indexBufferSize

indexBufferSize: number

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

mvpMatrix3D

mvpMatrix3D: Matrix3D

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

onRestore

onRestore: function

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.

Type declaration

    • (Effect: any): void
    • Parameters

      • Effect: any

      Returns void

Protected program

program: Program

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.

programBaseName

programBaseName: string

Returns the base name for the program. @default the fully qualified class name

programName

programName: string

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.

programVariantName

programVariantName: number

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

Protected vertexBuffer

vertexBuffer: VertexBuffer3D

The internally used vertex buffer used on rendering.

Protected vertexBufferSize

vertexBufferSize: number

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

vertexFormat

vertexFormat: VertexDataFormat

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

Static VERTEX_FORMAT

VERTEX_FORMAT: VertexDataFormat

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

Methods

dispose

  • dispose(): void

Protected get_indexBuffer

  • get_indexBuffer(): IndexBuffer3D

Protected get_indexBufferSize

  • get_indexBufferSize(): number

Protected get_mvpMatrix3D

  • get_mvpMatrix3D(): Matrix3D

Protected get_onRestore

  • get_onRestore(): function

Protected get_program

Protected get_programBaseName

  • get_programBaseName(): string

Protected get_programName

  • get_programName(): string

Protected get_programVariantName

  • get_programVariantName(): number

Protected get_vertexBuffer

  • get_vertexBuffer(): VertexBuffer3D

Protected get_vertexBufferSize

  • get_vertexBufferSize(): number

Protected get_vertexFormat

purgeBuffers

  • purgeBuffers(vertexBuffer?: boolean, indexBuffer?: boolean): void
  • Purges one or both of the vertex- and index-buffers.

    Parameters

    • Optional vertexBuffer: boolean
    • Optional indexBuffer: boolean

    Returns void

render

  • render(firstIndex?: number, numTriangles?: number): 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

    • Optional firstIndex: number
    • Optional numTriangles: number

    Returns void

Protected set_mvpMatrix3D

  • set_mvpMatrix3D(value: Matrix3D): Matrix3D

Protected set_onRestore

  • set_onRestore(value: function): function
  • Parameters

    • value: function
        • (Effect: any): void
        • Parameters

          • Effect: any

          Returns void

    Returns function

      • (Effect: any): void
      • Parameters

        • Effect: any

        Returns void

Protected set_programBaseName

  • set_programBaseName(value: string): string

uploadIndexData

  • uploadIndexData(indexData: IndexData, bufferUsage?: string): void
  • 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.

    Parameters

    • indexData: IndexData
    • Optional bufferUsage: string

    Returns void

uploadVertexData

  • uploadVertexData(vertexData: VertexData, bufferUsage?: string): void
  • 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.

    Parameters

    • vertexData: VertexData
    • Optional bufferUsage: string

    Returns void

Generated using TypeDoc