A class that orchestrates rendering of all Starling display objects.

A Starling instance contains exactly one 'Painter' instance that should be used for all rendering purposes. Each frame, it is passed to the render methods of all rendered display objects. To access it outside a render method, call `Starling.painter`.

The painter is responsible for drawing all display objects to the screen. At its core, it is a wrapper for many Context3D methods, but that's not all: it also provides a convenient state mechanism, supports masking and acts as __iddleman between display objects and renderers.

The State Stack

The most important concept of the Painter class is the state stack. A RenderState stores a combination of settings that are currently used for rendering, e.g. the current projection- and modelview-matrices and context-related settings. It can be accessed and manipulated via the `state` property. Use the methods `pushState` and `popState` to store a specific state and restore it later. That makes it easy to write rendering code that doesn't have any side effects.

    						painter.pushState(); // save a copy of the current state on the stack
    						painter.state.renderTarget = renderTexture;
    						painter.state.transformModelviewMatrix(object.transformationMatrix);
    						painter.state.alpha = 0.5;
    						painter.prepareToDraw(); // apply all state settings at the render context
    						drawSomething(); // insert Stage3D rendering code here
    					painter.popState(); // restores previous state

@see RenderState

### Hierarchy

- Painter

## Index

### Constructors

- constructor

### Properties

- backBufferHeight
- backBufferScaleFactor
- backBufferWidth
- cacheEnabled
- context
- contextValid
- drawCount
- enableErrorChecking
- frameID
- pixelSize
- profile
- programs
- shareContext
- sharedData
- stage3D
- state
- stencilReferenceValue
- DEFAULT_STENCIL_VALUE

### Methods

- batchMesh
- clear
- configureBackBuffer
- deleteProgram
- dispose
- drawFromCache
- drawMask
- enableBatchTrimming
- eraseMask
- excludeFromCache
- fillToken
- finishFrame
- finishMeshBatch
- getProgram
- get_backBufferHeight
- get_backBufferScaleFactor
- get_backBufferWidth
- get_cacheEnabled
- get_context
- get_contextValid
- get_drawCount
- get_enableErrorChecking
- get_frameID
- get_pixelSize
- get_profile
- get_programs
- get_shareContext
- get_sharedData
- get_stage3D
- get_state
- get_stencilReferenceValue
- hasProgram
- nextFrame
- popState
- prepareToDraw
- present
- pushState
- refreshBackBufferSize
- registerProgram
- requestContext3D
- restoreState
- setStateTo
- set_cacheEnabled
- set_drawCount
- set_enableErrorChecking
- set_frameID
- set_pixelSize
- set_shareContext
- set_stencilReferenceValue
- setupContextDefaults

## Constructors

### constructor

- new Painter(stage3D: Stage3D, sharedContext?: null | boolean): Painter

- - Defined in lib/starling/rendering/Painter.d.ts:63

  Creates a new Painter object. Normally, it's not necessary to create any custom painters; instead, use the global painter found on the Starling instance.

  #### Parameters

  - ##### stage3D: Stage3D

  - ##### Optional sharedContext: null | boolean

  #### Returns Painter

## Properties

### backBufferHeight

backBufferHeight: number

- Defined in lib/starling/rendering/Painter.d.ts:352

Returns the current height of the back buffer. In most cases, this value is in pixels; however, if the app is running on an HiDPI display with an activated 'supportHighResolutions' setting, you have to multiply with 'backBufferPixelsPerPoint' for the actual pixel count. Alternatively, use the Context3D-property with the same name: it will return the exact pixel values.

### backBufferScaleFactor

backBufferScaleFactor: number

- Defined in lib/starling/rendering/Painter.d.ts:358

The number of pixels per point returned by the 'backBufferWidth/Height' properties. Except for desktop HiDPI displays with an activated 'supportHighResolutions' setting, this will always return '1'.

### backBufferWidth

backBufferWidth: number

- Defined in lib/starling/rendering/Painter.d.ts:344

Returns the current width of the back buffer. In most cases, this value is in pixels; however, if the app is running on an HiDPI display with an activated 'supportHighResolutions' setting, you have to multiply with 'backBufferPixelsPerPoint' for the actual pixel count. Alternatively, use the Context3D-property with the same name: it will return the exact pixel values.

### cacheEnabled

cacheEnabled: boolean

- Defined in lib/starling/rendering/Painter.d.ts:292

Indicates if the render cache is enabled. Normally, this should be left at the default; however, some custom rendering logic might require to change this property temporarily. Also note that the cache is automatically reactivated each frame, right before the render process.

@default true

### context

context: Context3D

- Defined in lib/starling/rendering/Painter.d.ts:312

The Context3D instance this painter renders into.

### contextValid

contextValid: boolean

- Defined in lib/starling/rendering/Painter.d.ts:363

Indicates if the Context3D object is currently valid (i.e. it hasn't been lost or disposed).

### drawCount

drawCount: number

- Defined in lib/starling/rendering/Painter.d.ts:272

Indicates the number of stage3D draw calls.

### enableErrorChecking

enableErrorChecking: boolean

- Defined in lib/starling/rendering/Painter.d.ts:335

Indicates if Stage3D render methods will report errors. Activate only when needed, as this has a negative impact on performance. @default false

### frameID

frameID: number

- Defined in lib/starling/rendering/Painter.d.ts:318

Returns the index of the current frame if the render cache is enabled; otherwise, returns zero. To get the frameID regardless of the render cache, call `Starling.frameID` instead.

### pixelSize

pixelSize: number

- Defined in lib/starling/rendering/Painter.d.ts:323

The size (in points) that represents one pixel in the back buffer.

### profile

profile: string

- Defined in lib/starling/rendering/Painter.d.ts:368

The Context3D profile of the current render context, or `null` if the context has not been created yet.

### Protected programs

programs: Map<string, Program>

- Defined in lib/starling/rendering/Painter.d.ts:378

### shareContext

shareContext: boolean

- Defined in lib/starling/rendering/Painter.d.ts:329

Indicates if another Starling instance (or another Stage3D framework altogether) uses the same render context. @default false

### sharedData

sharedData: Map<string, any>

- Defined in lib/starling/rendering/Painter.d.ts:375

A dictionary that can be used to save custom data related to the render context. If you need to share data that is bound to the render context (e.g. textures), use this dictionary instead of creating a static class variable. That way, the data will be available for all Starling instances that use this stage3D / context.

### stage3D

stage3D: Stage3D

- Defined in lib/starling/rendering/Painter.d.ts:308

The Stage3D instance this painter renders into.

### state

state: RenderState

- Defined in lib/starling/rendering/Painter.d.ts:304

The current render state, containing some of the context settings, projection- and modelview-matrix, etc. Always returns the same instance, even after calls to "pushState" and "popState".

When you change the current RenderState, and this change is not compatible with the current render batch, the batch will be concluded right away. Thus, watch out for changes of blend mode, clipping rectangle, render target or culling.

### stencilReferenceValue

stencilReferenceValue: number

- Defined in lib/starling/rendering/Painter.d.ts:281

The current stencil reference value of the active render target. This value is typically incremented when drawing a mask and decrementing when erasing it. The painter keeps track of one stencil reference value per render target. Only change this value if you know what you're doing!

### Static DEFAULT_STENCIL_VALUE

DEFAULT_STENCIL_VALUE: number

- Defined in lib/starling/rendering/Painter.d.ts:63

The value with which the stencil buffer will be cleared, and the default reference value used for stencil tests.

## Methods

### batchMesh

- batchMesh(mesh: Mesh, subset?: MeshSubset): void

- - Defined in lib/starling/rendering/Painter.d.ts:205

  Adds a mesh to the current batch of unrendered meshes. If the current batch is not compatible with the mesh, all previous meshes are rendered at once and the batch is cleared.

  @param mesh The mesh to batch. @param subset The range of vertices to be batched. If `null`, the complete mesh will be used.

  #### Parameters

  - ##### mesh: Mesh

  - ##### Optional subset: MeshSubset

  #### Returns void

### clear

- clear(rgb?: number, alpha?: number): void

- - Defined in lib/starling/rendering/Painter.d.ts:257

  Clears the render context with a certain color and alpha value. Since this also clears the stencil buffer, the stencil reference value is also reset to '0'.

  #### Parameters

  - ##### Optional rgb: number

  - ##### Optional alpha: number

  #### Returns void

### configureBackBuffer

- configureBackBuffer(viewPort: Rectangle, contentScaleFactor: number, antiAlias: number, enableDepthAndStencil: boolean, supportBrowserZoom?: boolean): void

- - Defined in lib/starling/rendering/Painter.d.ts:107

  Sets the viewport dimensions and other attributes of the rendering buffer. Starling will call this method internally, so most apps won't need to mess with this.

  Beware: if `shareContext` is enabled, the method will only update the painter's context-related information (like the size of the back buffer), but won't make any actual changes to the context.

  #### Parameters

  - ##### viewPort: Rectangle

    the position and size of the area that should be rendered into, in pixels.

  - ##### contentScaleFactor: number

    only relevant for Desktop (!) HiDPI screens. If you want to support high resolutions, pass the 'contentScaleFactor' of the Flash stage; otherwise, '1.0'.

  - ##### antiAlias: number

    from 0 (none) to 16 (very high quality).

  - ##### enableDepthAndStencil: boolean

    indicates whether the depth and stencil buffers should be enabled. Note that on AIR, you also have to enable this setting in the app-xml (application descriptor); otherwise, this setting will be silently ignored.

  - ##### Optional supportBrowserZoom: boolean

    if enabled, zooming a website will adapt the size of the back buffer.

  #### Returns void

### deleteProgram

- deleteProgram(name: string): void

- - Defined in lib/starling/rendering/Painter.d.ts:118

  Deletes the program of a certain name.

  #### Parameters

  - ##### name: string

  #### Returns void

### dispose

- dispose(): void

- - Defined in lib/starling/rendering/Painter.d.ts:73

  Disposes all mesh batches, programs, and - if it is not being shared - the render context.

  #### Returns void

### drawFromCache

- drawFromCache(startToken: BatchToken, endToken: BatchToken): void

- - Defined in lib/starling/rendering/Painter.d.ts:235

  Draws all meshes from the render cache between `startToken` and (but not including) `endToken`. The render cache contains all meshes rendered in the previous frame.

  #### Parameters

  - ##### startToken: BatchToken

  - ##### endToken: BatchToken

  #### Returns void

### drawMask

- drawMask(mask: DisplayObject, maskee?: DisplayObject): void

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

  Draws a display object into the stencil buffer, incrementing the buffer on each used pixel. The stencil reference value is incremented as well; thus, any subsequent stencil tests outside of this area will fail.

  If 'mask' is part of the display list, it will be drawn at its conventional stage coordinates. Otherwise, it will be drawn with the current modelview matrix.

  As an optimization, this method might update the clipping rectangle of the render state instead of utilizing the stencil buffer. This is possible when the mask object is of type `starling.display.Quad` and is aligned parallel to the stage axes.

  Note that masking breaks the render cache; the masked object must be redrawn anew in the next frame. If you pass `maskee`, the method will automatically call `excludeFromCache(maskee)` for you.

  #### Parameters

  - ##### mask: DisplayObject

  - ##### Optional maskee: DisplayObject

  #### Returns void

### enableBatchTrimming

- enableBatchTrimming(enabled?: boolean, interval?: number): void

- - Defined in lib/starling/rendering/Painter.d.ts:219

  Indicate how often the internally used batches are being trimmed to save memory.

  While rendering, the internally used MeshBatches are used in a different way in each frame. To save memory, they should be trimmed every once in a while. This method defines how often that happens, if at all. (Default: enabled = true, interval = 250)

  @param enabled If trimming happens at all. Only disable temporarily! @param interval The number of frames between each trim operation.

  #### Parameters

  - ##### Optional enabled: boolean

  - ##### Optional interval: number

  #### Returns void

### eraseMask

- eraseMask(mask: DisplayObject, maskee?: DisplayObject): void

- - Defined in lib/starling/rendering/Painter.d.ts:193

  Draws a display object into the stencil buffer, decrementing the buffer on each used pixel. This effectively erases the object from the stencil buffer, restoring the previous state. The stencil reference value will be decremented.

  Note: if the mask object meets the requirements of using the clipping rectangle, it will be assumed that this erase operation undoes the clipping rectangle change caused by the corresponding `drawMask()` call.

  #### Parameters

  - ##### mask: DisplayObject

  - ##### Optional maskee: DisplayObject

  #### Returns void

### excludeFromCache

- excludeFromCache(object: DisplayObject): void

- - Defined in lib/starling/rendering/Painter.d.ts:245

  Prevents the object from being drawn from the render cache in the next frame. Different to `setRequiresRedraw()`, this does not indicate that the object has changed in any way, but just that it doesn't support being drawn from cache.

  Note that when a container is excluded from the render cache, its children will still be cached! This just means that batching is interrupted at this object when the display tree is traversed.

  #### Parameters

  - ##### object: DisplayObject

  #### Returns void

### fillToken

- fillToken(token: BatchToken): void

- - Defined in lib/starling/rendering/Painter.d.ts:163

  Updates all properties of the given token so that it describes the current position within the render cache.

  #### Parameters

  - ##### token: BatchToken

  #### Returns void

### finishFrame

- finishFrame(): void

- - Defined in lib/starling/rendering/Painter.d.ts:222

  Completes all unfinished batches, cleanup procedures.

  #### Returns void

### finishMeshBatch

- finishMeshBatch(): void

- - Defined in lib/starling/rendering/Painter.d.ts:208

  Finishes the current mesh batch and prepares the next one.

  #### Returns void

### getProgram

- getProgram(name: string): Program

- - Defined in lib/starling/rendering/Painter.d.ts:122

  Returns the program registered under a certain name, or null if no program with this name has been registered.

  #### Parameters

  - ##### name: string

  #### Returns Program

### Protected get_backBufferHeight

- get_backBufferHeight(): number

- - Defined in lib/starling/rendering/Painter.d.ts:353

  #### Returns number

### Protected get_backBufferScaleFactor

- get_backBufferScaleFactor(): number

- - Defined in lib/starling/rendering/Painter.d.ts:359

  #### Returns number

### Protected get_backBufferWidth

- get_backBufferWidth(): number

- - Defined in lib/starling/rendering/Painter.d.ts:345

  #### Returns number

### Protected get_cacheEnabled

- get_cacheEnabled(): boolean

- - Defined in lib/starling/rendering/Painter.d.ts:293

  #### Returns boolean

### Protected get_context

- get_context(): Context3D

- - Defined in lib/starling/rendering/Painter.d.ts:313

  #### Returns Context3D

### Protected get_contextValid

- get_contextValid(): boolean

- - Defined in lib/starling/rendering/Painter.d.ts:364

  #### Returns boolean

### Protected get_drawCount

- get_drawCount(): number

- - Defined in lib/starling/rendering/Painter.d.ts:273

  #### Returns number

### Protected get_enableErrorChecking

- get_enableErrorChecking(): boolean

- - Defined in lib/starling/rendering/Painter.d.ts:336

  #### Returns boolean

### Protected get_frameID

- get_frameID(): number

- - Defined in lib/starling/rendering/Painter.d.ts:320

  #### Returns number

### Protected get_pixelSize

- get_pixelSize(): number

- - Defined in lib/starling/rendering/Painter.d.ts:324

  #### Returns number

### Protected get_profile

- get_profile(): string

- - Defined in lib/starling/rendering/Painter.d.ts:369

  #### Returns string

### Protected get_programs

- get_programs(): Map<string, Program>

- - Defined in lib/starling/rendering/Painter.d.ts:379

  #### Returns Map<string, Program>

### Protected get_shareContext

- get_shareContext(): boolean

- - Defined in lib/starling/rendering/Painter.d.ts:330

  #### Returns boolean

### Protected get_sharedData

- get_sharedData(): Map<string, any>

- - Defined in lib/starling/rendering/Painter.d.ts:376

  #### Returns Map<string, any>

### Protected get_stage3D

- get_stage3D(): Stage3D

- - Defined in lib/starling/rendering/Painter.d.ts:309

  #### Returns Stage3D

### Protected get_state

- get_state(): RenderState

- - Defined in lib/starling/rendering/Painter.d.ts:305

  #### Returns RenderState

### Protected get_stencilReferenceValue

- get_stencilReferenceValue(): number

- - Defined in lib/starling/rendering/Painter.d.ts:282

  #### Returns number

### hasProgram

- hasProgram(name: string): boolean

- - Defined in lib/starling/rendering/Painter.d.ts:125

  Indicates if a program is registered under a certain name.

  #### Parameters

  - ##### name: string

  #### Returns boolean

### nextFrame

- nextFrame(): void

- - Defined in lib/starling/rendering/Painter.d.ts:230

  Resets the current state, state stack, batch processor, stencil reference value, clipping rectangle, and draw count. Furthermore, depth testing is disabled.

  #### Returns void

### popState

- popState(token?: BatchToken): void

- - Defined in lib/starling/rendering/Painter.d.ts:155

  Restores the render state that was last pushed to the stack. If this changes blend mode, clipping rectangle, render target or culling, the current batch will be drawn right away.

  If you pass a BatchToken, it will be updated to point to the current location within the render cache. That way, you can later reference this location to render a subset of the cache.

  #### Parameters

  - ##### Optional token: BatchToken

  #### Returns void

### prepareToDraw

- prepareToDraw(): void

- - Defined in lib/starling/rendering/Painter.d.ts:253

  Applies all relevant state settings to at the render context. This includes blend mode, render target and clipping rectangle. Always call this method before `context.drawTriangles()`.

  #### Returns void

### present

- present(): void

- - Defined in lib/starling/rendering/Painter.d.ts:260

  Resets the render target to the back buffer and displays its contents.

  #### Returns void

### pushState

- pushState(token?: BatchToken): void

- - Defined in lib/starling/rendering/Painter.d.ts:135

  Pushes the current render state to a stack from which it can be restored later.

  If you pass a BatchToken, it will be updated to point to the current location within the render cache. That way, you can later reference this location to render a subset of the cache.

  #### Parameters

  - ##### Optional token: BatchToken

  #### Returns void

### refreshBackBufferSize

- refreshBackBufferSize(scaleFactor: number): void

- - Defined in lib/starling/rendering/Painter.d.ts:267

  Refreshes the values of "backBufferWidth" and "backBufferHeight" from the current context dimensions and stores the given "backBufferScaleFactor". This method is called by Starling when the browser zoom factor changes (in case "supportBrowserZoom" is enabled).

  #### Parameters

  - ##### scaleFactor: number

  #### Returns void

### registerProgram

- registerProgram(name: string, program: Program): void

- - Defined in lib/starling/rendering/Painter.d.ts:115

  Registers a program under a certain name. If the name was already used, the previous program is overwritten.

  #### Parameters

  - ##### name: string

  - ##### program: Program

  #### Returns void

### requestContext3D

- requestContext3D(renderMode: string, profile: any): void

- - Defined in lib/starling/rendering/Painter.d.ts:85

  Requests a context3D object from the stage3D object. This is called by Starling internally during the initialization process. You normally don't need to call this method yourself. (For a detailed description of the parameters, look at the documentation of the method with the same name in the "RenderUtil" class.)

  @see starling.utils.RenderUtil

  #### Parameters

  - ##### renderMode: string

  - ##### profile: any

  #### Returns void

### restoreState

- restoreState(): void

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

  Restores the render state that was last pushed to the stack, but does NOT remove it from the stack.

  #### Returns void

### setStateTo

- setStateTo(transformationMatrix: Matrix, alphaFactor?: number, blendMode?: string): void

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

  Modifies the current state with a transformation matrix, alpha factor, and blend mode.

  @param transformationMatrix Used to transform the current `modelviewMatrix`. @param alphaFactor Multiplied with the current alpha value. @param blendMode Replaces the current blend mode; except for "auto", which means the current value remains unchanged.

  #### Parameters

  - ##### transformationMatrix: Matrix

  - ##### Optional alphaFactor: number

  - ##### Optional blendMode: string

  #### Returns void

### Protected set_cacheEnabled

- set_cacheEnabled(value: boolean): boolean

- - Defined in lib/starling/rendering/Painter.d.ts:294

  #### Parameters

  - ##### value: boolean

  #### Returns boolean

### Protected set_drawCount

- set_drawCount(value: number): number

- - Defined in lib/starling/rendering/Painter.d.ts:274

  #### Parameters

  - ##### value: number

  #### Returns number

### Protected set_enableErrorChecking

- set_enableErrorChecking(value: boolean): boolean

- - Defined in lib/starling/rendering/Painter.d.ts:337

  #### Parameters

  - ##### value: boolean

  #### Returns boolean

### Protected set_frameID

- set_frameID(value: number): number

- - Defined in lib/starling/rendering/Painter.d.ts:319

  #### Parameters

  - ##### value: number

  #### Returns number

### Protected set_pixelSize

- set_pixelSize(value: number): number

- - Defined in lib/starling/rendering/Painter.d.ts:325

  #### Parameters

  - ##### value: number

  #### Returns number

### Protected set_shareContext

- set_shareContext(value: boolean): boolean

- - Defined in lib/starling/rendering/Painter.d.ts:331

  #### Parameters

  - ##### value: boolean

  #### Returns boolean

### Protected set_stencilReferenceValue

- set_stencilReferenceValue(value: number): number

- - Defined in lib/starling/rendering/Painter.d.ts:283

  #### Parameters

  - ##### value: number

  #### Returns number

### setupContextDefaults

- setupContextDefaults(): void

- - Defined in lib/starling/rendering/Painter.d.ts:226

  Makes sure that the default context settings Starling relies on will be refreshed before the next 'draw' operation. This includes blend mode, culling, and depth test.

  #### Returns void

Generated using TypeDoc