Packagestarling.rendering
Classpublic class Painter
InheritancePainter Inheritance Object

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 middleman 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 also

RenderState


Public Properties
 PropertyDefined By
  backBufferHeight : int
[read-only] Returns the current height of the back buffer.
Painter
  backBufferScaleFactor : Number
[read-only] The number of pixels per point returned by the 'backBufferWidth/Height' properties.
Painter
  backBufferWidth : int
[read-only] Returns the current width of the back buffer.
Painter
  cacheEnabled : Boolean
Indicates if the render cache is enabled.
Painter
  context : Context3D
[read-only] The Context3D instance this painter renders into.
Painter
  contextValid : Boolean
[read-only] Indicates if the Context3D object is currently valid (i.e.
Painter
  drawCount : int
Indicates the number of stage3D draw calls.
Painter
  enableErrorChecking : Boolean
Indicates if Stage3D render methods will report errors.
Painter
  frameID : uint
Returns the index of the current frame if the render cache is enabled; otherwise, returns zero.
Painter
  pixelSize : Number
The size (in points) that represents one pixel in the back buffer.
Painter
  profile : String
[read-only] The Context3D profile of the current render context, or null if the context has not been created yet.
Painter
  shareContext : Boolean
Indicates if another Starling instance (or another Stage3D framework altogether) uses the same render context.
Painter
  sharedData : Dictionary
[read-only] A dictionary that can be used to save custom data related to the render context.
Painter
  stage3D : Stage3D
[read-only] The Stage3D instance this painter renders into.
Painter
  state : RenderState
[read-only] The current render state, containing some of the context settings, projection- and modelview-matrix, etc.
Painter
  stencilReferenceValue : uint
The current stencil reference value of the active render target.
Painter
Public Methods
 MethodDefined By
  
Painter(stage3D:Stage3D)
Creates a new Painter object.
Painter
  
batchMesh(mesh:Mesh, subset:MeshSubset = null):void
Adds a mesh to the current batch of unrendered meshes.
Painter
  
clear(rgb:uint = 0, alpha:Number = 0.0):void
Clears the render context with a certain color and alpha value.
Painter
  
configureBackBuffer(viewPort:Rectangle, contentScaleFactor:Number, antiAlias:int, enableDepthAndStencil:Boolean):void
Sets the viewport dimensions and other attributes of the rendering buffer.
Painter
  
deleteProgram(name:String):void
Deletes the program of a certain name.
Painter
  
dispose():void
Disposes all mesh batches, programs, and - if it is not being shared - the render context.
Painter
  
drawFromCache(startToken:BatchToken, endToken:BatchToken):void
Draws all meshes from the render cache between startToken and (but not including) endToken.
Painter
  
drawMask(mask:DisplayObject, maskee:DisplayObject = null):void
Draws a display object into the stencil buffer, incrementing the buffer on each used pixel.
Painter
  
eraseMask(mask:DisplayObject, maskee:DisplayObject = null):void
Draws a display object into the stencil buffer, decrementing the buffer on each used pixel.
Painter
  
Prevents the object from being drawn from the render cache in the next frame.
Painter
  
Completes all unfinished batches, cleanup procedures.
Painter
  
Finishes the current mesh batch and prepares the next one.
Painter
  
getProgram(name:String):Program
Returns the program registered under a certain name, or null if no program with this name has been registered.
Painter
  
hasProgram(name:String):Boolean
Indicates if a program is registered under a certain name.
Painter
  
nextFrame():void
Resets the current state, state stack, batch processor, stencil reference value, clipping rectangle, and draw count.
Painter
  
popState(token:BatchToken = null):void
Restores the render state that was last pushed to the stack.
Painter
  
Applies all relevant state settings to at the render context.
Painter
  
present():void
Resets the render target to the back buffer and displays its contents.
Painter
  
pushState(token:BatchToken = null):void
Pushes the current render state to a stack from which it can be restored later.
Painter
  
registerProgram(name:String, program:Program):void
Registers a program under a certain name.
Painter
  
requestContext3D(renderMode:String, profile:*):void
Requests a context3D object from the stage3D object.
Painter
  
setStateTo(transformationMatrix:Matrix, alphaFactor:Number = 1.0, blendMode:String = auto):void
Modifies the current state with a transformation matrix, alpha factor, and blend mode.
Painter
Property Detail
backBufferHeightproperty
backBufferHeight:int  [read-only]

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.


Implementation
    public function get backBufferHeight():int
backBufferScaleFactorproperty 
backBufferScaleFactor:Number  [read-only]

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


Implementation
    public function get backBufferScaleFactor():Number
backBufferWidthproperty 
backBufferWidth:int  [read-only]

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.


Implementation
    public function get backBufferWidth():int
cacheEnabledproperty 
cacheEnabled:Boolean

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.

The default value is true.


Implementation
    public function get cacheEnabled():Boolean
    public function set cacheEnabled(value:Boolean):void
contextproperty 
context:Context3D  [read-only]

The Context3D instance this painter renders into.


Implementation
    public function get context():Context3D
contextValidproperty 
contextValid:Boolean  [read-only]

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


Implementation
    public function get contextValid():Boolean
drawCountproperty 
drawCount:int

Indicates the number of stage3D draw calls.


Implementation
    public function get drawCount():int
    public function set drawCount(value:int):void
enableErrorCheckingproperty 
enableErrorChecking:Boolean

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

The default value is false.


Implementation
    public function get enableErrorChecking():Boolean
    public function set enableErrorChecking(value:Boolean):void
frameIDproperty 
frameID:uint

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.


Implementation
    public function get frameID():uint
    public function set frameID(value:uint):void
pixelSizeproperty 
pixelSize:Number

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


Implementation
    public function get pixelSize():Number
    public function set pixelSize(value:Number):void
profileproperty 
profile:String  [read-only]

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


Implementation
    public function get profile():String
shareContextproperty 
shareContext:Boolean

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

The default value is false.


Implementation
    public function get shareContext():Boolean
    public function set shareContext(value:Boolean):void
sharedDataproperty 
sharedData:Dictionary  [read-only]

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.


Implementation
    public function get sharedData():Dictionary
stage3Dproperty 
stage3D:Stage3D  [read-only]

The Stage3D instance this painter renders into.


Implementation
    public function get stage3D():Stage3D
stateproperty 
state:RenderState  [read-only]

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.


Implementation
    public function get state():RenderState
stencilReferenceValueproperty 
stencilReferenceValue:uint

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!


Implementation
    public function get stencilReferenceValue():uint
    public function set stencilReferenceValue(value:uint):void
Constructor Detail
Painter()Constructor
public function Painter(stage3D:Stage3D)

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
Method Detail
batchMesh()method
public function batchMesh(mesh:Mesh, subset:MeshSubset = null):void

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.

Parameters

mesh:Mesh — The mesh to batch.
 
subset:MeshSubset (default = null) — The range of vertices to be batched. If null, the complete mesh will be used.

clear()method 
public function clear(rgb:uint = 0, alpha:Number = 0.0):void

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

rgb:uint (default = 0)
 
alpha:Number (default = 0.0)

configureBackBuffer()method 
public function configureBackBuffer(viewPort:Rectangle, contentScaleFactor:Number, antiAlias:int, enableDepthAndStencil:Boolean):void

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:int — 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.

deleteProgram()method 
public function deleteProgram(name:String):void

Deletes the program of a certain name.

Parameters

name:String

dispose()method 
public function dispose():void

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

drawFromCache()method 
public function drawFromCache(startToken:BatchToken, endToken:BatchToken):void

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

drawMask()method 
public function drawMask(mask:DisplayObject, maskee:DisplayObject = null):void

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
 
maskee:DisplayObject (default = null)

eraseMask()method 
public function eraseMask(mask:DisplayObject, maskee:DisplayObject = null):void

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
 
maskee:DisplayObject (default = null)

excludeFromCache()method 
public function excludeFromCache(object:DisplayObject):void

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

finishFrame()method 
public function finishFrame():void

Completes all unfinished batches, cleanup procedures.

finishMeshBatch()method 
public function finishMeshBatch():void

Finishes the current mesh batch and prepares the next one.

getProgram()method 
public function getProgram(name:String):Program

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

Parameters

name:String

Returns
Program
hasProgram()method 
public function hasProgram(name:String):Boolean

Indicates if a program is registered under a certain name.

Parameters

name:String

Returns
Boolean
nextFrame()method 
public function nextFrame():void

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

popState()method 
public function popState(token:BatchToken = null):void

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

token:BatchToken (default = null)

prepareToDraw()method 
public function prepareToDraw():void

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().

present()method 
public function present():void

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

pushState()method 
public function pushState(token:BatchToken = null):void

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

token:BatchToken (default = null)

registerProgram()method 
public function registerProgram(name:String, program:Program):void

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

Parameters

name:String
 
program:Program

requestContext3D()method 
public function requestContext3D(renderMode:String, profile:*):void

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

Parameters

renderMode:String
 
profile:*

See also

setStateTo()method 
public function setStateTo(transformationMatrix:Matrix, alphaFactor:Number = 1.0, blendMode:String = auto):void

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

Parameters

transformationMatrix:Matrix — Used to transform the current modelviewMatrix.
 
alphaFactor:Number (default = 1.0) — Multiplied with the current alpha value.
 
blendMode:String (default = auto) — Replaces the current blend mode; except for "auto", which means the current value remains unchanged.