| Package | starling.rendering |
| Class | public class Painter |
| Inheritance | Painter  Object |
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 StackThe 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 stateSee also
| Property | Defined 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 | ||
| Method | Defined By | ||
|---|---|---|---|
Painter(stage3D:Stage3D) Creates a new Painter object. | Painter | ||
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, supportBrowserZoom:Boolean = false):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 | ||
Draws all meshes from the render cache between startToken and
(but not including) endToken. | Painter | ||
Draws a display object into the stencil buffer only; increments or decrements the
entry value corresponding to the pixel of the shape in the stencil buffer, for the
normal or inverted mask modes, respectively. | Painter | ||
enableBatchTrimming(enabled:Boolean = true, interval:int = 250):void Indicate how often the internally used batches are being trimmed to save memory. | Painter | ||
Draws a display object into the stencil buffer only; increments or decrements the
entry value corresponding to the pixel of the shape in the stencil buffer, for the
inverted or normal mask modes, respectively. | Painter | ||
excludeFromCache(object:DisplayObject):void Prevents the object from being drawn from the render cache in the next frame. | Painter | ||
fillToken(token:BatchToken):void Updates all properties of the given token so that it describes the current position
within the render cache. | Painter | ||
finishFrame():void Completes all unfinished batches, cleanup procedures. | Painter | ||
finishMeshBatch():void 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 | ||
prepareToDraw():void 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 | ||
refreshBackBufferSize(scaleFactor:Number):void Refreshes the values of "backBufferWidth" and "backBufferHeight" from the current
context dimensions and stores the given "backBufferScaleFactor". | 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 | ||
restoreState():void Restores the render state that was last pushed to the stack, but does NOT remove
it from the stack. | 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 | ||
setupContextDefaults():void Makes sure that the default context settings Starling relies on will be refreshed
before the next 'draw' operation. | Painter | ||
| Constant | Defined By | ||
|---|---|---|---|
| DEFAULT_STENCIL_VALUE : uint = 127 [static] The value with which the stencil buffer will be cleared,
and the default reference value used for stencil tests. | Painter | ||
| backBufferHeight | property |
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.
public function get backBufferHeight():int| backBufferScaleFactor | property |
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'.
public function get backBufferScaleFactor():Number| backBufferWidth | property |
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.
public function get backBufferWidth():int| cacheEnabled | property |
cacheEnabled:BooleanIndicates 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.
public function get cacheEnabled():Boolean public function set cacheEnabled(value:Boolean):void| context | property |
context:Context3D [read-only] The Context3D instance this painter renders into.
public function get context():Context3D| contextValid | property |
contextValid:Boolean [read-only] Indicates if the Context3D object is currently valid (i.e. it hasn't been lost or disposed).
public function get contextValid():Boolean| drawCount | property |
drawCount:intIndicates the number of stage3D draw calls.
public function get drawCount():int public function set drawCount(value:int):void| enableErrorChecking | property |
enableErrorChecking:BooleanIndicates if Stage3D render methods will report errors. Activate only when needed, as this has a negative impact on performance.
The default value is false.
public function get enableErrorChecking():Boolean public function set enableErrorChecking(value:Boolean):void| frameID | property |
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.
public function get frameID():uint public function set frameID(value:uint):void| pixelSize | property |
pixelSize:NumberThe size (in points) that represents one pixel in the back buffer.
public function get pixelSize():Number public function set pixelSize(value:Number):void| profile | property |
profile:String [read-only] The Context3D profile of the current render context, or null
if the context has not been created yet.
public function get profile():String| shareContext | property |
shareContext:BooleanIndicates if another Starling instance (or another Stage3D framework altogether) uses the same render context.
The default value is false.
public function get shareContext():Boolean public function set shareContext(value:Boolean):void| sharedData | property |
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.
public function get sharedData():Dictionary| stage3D | property |
stage3D:Stage3D [read-only] The Stage3D instance this painter renders into.
public function get stage3D():Stage3D| state | property |
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.
public function get state():RenderState| stencilReferenceValue | property |
stencilReferenceValue:uintThe 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!
public function get stencilReferenceValue():uint public function set stencilReferenceValue(value:uint):void| 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.
Parametersstage3D:Stage3D |
| batchMesh | () | method |
public function batchMesh(mesh:Mesh, subset:MeshSubset = null):voidAdds 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)null, the complete
mesh will be used.
|
| clear | () | method |
public function clear(rgb:uint = 0, alpha:Number = 0.0):voidClears 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 its default value.
Parameters
rgb:uint (default = 0) | |
alpha:Number (default = 0.0) |
| configureBackBuffer | () | method |
public function configureBackBuffer(viewPort:Rectangle, contentScaleFactor:Number, antiAlias:int, enableDepthAndStencil:Boolean, supportBrowserZoom:Boolean = false):voidSets 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.
| |
supportBrowserZoom:Boolean (default = false) |
| deleteProgram | () | method |
public function deleteProgram(name:String):voidDeletes the program of a certain name.
Parameters
name:String |
| dispose | () | method |
public function dispose():voidDisposes 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):voidDraws a display object into the stencil buffer only; increments or decrements the entry value corresponding to the pixel of the shape in the stencil buffer, for the normal or inverted mask modes, respectively. Effectively, the stencil buffer modification is to mark only the appropriate pixel coordinates where the 'maskee' object is to be rendered. The stencil reference value will be incremented in the normal mask mode only.
If the '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) |
| enableBatchTrimming | () | method |
public function enableBatchTrimming(enabled:Boolean = true, interval:int = 250):voidIndicate 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)
Parameters
enabled:Boolean (default = true) | |
interval:int (default = 250) |
| eraseMask | () | method |
public function eraseMask(mask:DisplayObject, maskee:DisplayObject = null):voidDraws a display object into the stencil buffer only; increments or decrements the entry value corresponding to the pixel of the shape in the stencil buffer, for the inverted or normal mask modes, respectively. Effectively, The stencil buffer modification is to erase the object shape from the stencil buffer, restoring the previous state. The stencil reference value will be decremented in the normal mask mode only.
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 |
| fillToken | () | method |
public function fillToken(token:BatchToken):voidUpdates all properties of the given token so that it describes the current position within the render cache.
Parameters
token:BatchToken |
| finishFrame | () | method |
public function finishFrame():voidCompletes all unfinished batches, cleanup procedures.
| finishMeshBatch | () | method |
public function finishMeshBatch():voidFinishes the current mesh batch and prepares the next one.
| getProgram | () | method |
public function getProgram(name:String):ProgramReturns the program registered under a certain name, or null if no program with this name has been registered.
Parameters
name:String |
Program |
| hasProgram | () | method |
public function hasProgram(name:String):BooleanIndicates if a program is registered under a certain name.
Parameters
name:String |
Boolean |
| nextFrame | () | method |
public function nextFrame():voidResets 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):voidRestores 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():voidResets the render target to the back buffer and displays its contents.
| pushState | () | method |
public function pushState(token:BatchToken = null):voidPushes 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) |
| refreshBackBufferSize | () | method |
public function refreshBackBufferSize(scaleFactor:Number):voidRefreshes 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 |
| registerProgram | () | method |
public function registerProgram(name:String, program:Program):voidRegisters 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:*):voidRequests 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
| restoreState | () | method |
public function restoreState():voidRestores the render state that was last pushed to the stack, but does NOT remove it from the stack.
| setStateTo | () | method |
public function setStateTo(transformationMatrix:Matrix, alphaFactor:Number = 1.0, blendMode:String = auto):voidModifies 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) | |
blendMode:String (default = auto) |
| setupContextDefaults | () | method |
public function setupContextDefaults():voidMakes 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.
| DEFAULT_STENCIL_VALUE | Constant |
public static const DEFAULT_STENCIL_VALUE:uint = 127The value with which the stencil buffer will be cleared, and the default reference value used for stencil tests.