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

- Effect
  - FilterEffect

## Index

### Constructors

- constructor

### Properties

- indexBuffer
- indexBufferSize
- mvpMatrix3D
- onRestore
- program
- programBaseName
- programName
- programVariantName
- vertexBuffer
- vertexBufferSize
- vertexFormat
- VERTEX_FORMAT

### Methods

- dispose
- get_indexBuffer
- get_indexBufferSize
- get_mvpMatrix3D
- get_onRestore
- get_program
- get_programBaseName
- get_programName
- get_programVariantName
- get_vertexBuffer
- get_vertexBufferSize
- get_vertexFormat
- purgeBuffers
- render
- set_mvpMatrix3D
- set_onRestore
- set_programBaseName
- uploadIndexData
- uploadVertexData

## Constructors

### constructor

- new Effect(): Effect

- - Defined in lib/starling/rendering/Effect.d.ts:90

  Creates a new effect.

  #### Returns Effect

## Properties

### Protected indexBuffer

indexBuffer: IndexBuffer3D

- Defined in lib/starling/rendering/Effect.d.ts:182

The internally used index buffer used on rendering.

### Protected indexBufferSize

indexBufferSize: number

- Defined in lib/starling/rendering/Effect.d.ts:186

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

### mvpMatrix3D

mvpMatrix3D: Matrix3D

- Defined in lib/starling/rendering/Effect.d.ts:177

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

### onRestore

onRestore: function

- Defined in lib/starling/rendering/Effect.d.ts:167

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

- Defined in lib/starling/rendering/Effect.d.ts:159

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

- Defined in lib/starling/rendering/Effect.d.ts:142

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

### programName

programName: string

- Defined in lib/starling/rendering/Effect.d.ts:153

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

- Defined in lib/starling/rendering/Effect.d.ts:136

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

- Defined in lib/starling/rendering/Effect.d.ts:190

The internally used vertex buffer used on rendering.

### Protected vertexBufferSize

vertexBufferSize: number

- Defined in lib/starling/rendering/Effect.d.ts:194

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

### vertexFormat

vertexFormat: VertexDataFormat

- Defined in lib/starling/rendering/Effect.d.ts:173

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

### Static VERTEX_FORMAT

VERTEX_FORMAT: VertexDataFormat

- Defined in lib/starling/rendering/Effect.d.ts:90

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

## Methods

### dispose

- dispose(): void

- - Defined in lib/starling/rendering/Effect.d.ts:96

  Purges the index- and vertex-buffers.

  #### Returns void

### Protected get_indexBuffer

- get_indexBuffer(): IndexBuffer3D

- - Defined in lib/starling/rendering/Effect.d.ts:183

  #### Returns IndexBuffer3D

### Protected get_indexBufferSize

- get_indexBufferSize(): number

- - Defined in lib/starling/rendering/Effect.d.ts:187

  #### Returns number

### Protected get_mvpMatrix3D

- get_mvpMatrix3D(): Matrix3D

- - Defined in lib/starling/rendering/Effect.d.ts:178

  #### Returns Matrix3D

### Protected get_onRestore

- get_onRestore(): function

- - Defined in lib/starling/rendering/Effect.d.ts:168

  #### Returns function

  - - (Effect: any): void

    - #### Parameters

      - ##### Effect: any

      #### Returns void

### Protected get_program

- get_program(): Program

- - Defined in lib/starling/rendering/Effect.d.ts:160

  #### Returns Program

### Protected get_programBaseName

- get_programBaseName(): string

- - Defined in lib/starling/rendering/Effect.d.ts:143

  #### Returns string

### Protected get_programName

- get_programName(): string

- - Defined in lib/starling/rendering/Effect.d.ts:154

  #### Returns string

### Protected get_programVariantName

- get_programVariantName(): number

- - Defined in lib/starling/rendering/Effect.d.ts:137

  #### Returns number

### Protected get_vertexBuffer

- get_vertexBuffer(): VertexBuffer3D

- - Defined in lib/starling/rendering/Effect.d.ts:191

  #### Returns VertexBuffer3D

### Protected get_vertexBufferSize

- get_vertexBufferSize(): number

- - Defined in lib/starling/rendering/Effect.d.ts:195

  #### Returns number

### Protected get_vertexFormat

- get_vertexFormat(): VertexDataFormat

- - Defined in lib/starling/rendering/Effect.d.ts:174

  #### Returns VertexDataFormat

### purgeBuffers

- purgeBuffers(vertexBuffer?: boolean, indexBuffer?: boolean): void

- - Defined in lib/starling/rendering/Effect.d.ts:99

  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

- - Defined in lib/starling/rendering/Effect.d.ts:128

  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

- - Defined in lib/starling/rendering/Effect.d.ts:179

  #### Parameters

  - ##### value: Matrix3D

  #### Returns Matrix3D

### Protected set_onRestore

- set_onRestore(value: function): function

- - Defined in lib/starling/rendering/Effect.d.ts:169

  #### 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

- - Defined in lib/starling/rendering/Effect.d.ts:144

  #### Parameters

  - ##### value: string

  #### Returns string

### uploadIndexData

- uploadIndexData(indexData: IndexData, bufferUsage?: string): void

- - Defined in lib/starling/rendering/Effect.d.ts:109

  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

- - Defined in lib/starling/rendering/Effect.d.ts:120

  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