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.
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.
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.
*/ public function pushState(token:BatchToken=null):Void { _stateStackPos++; if (_stateStackLength < _stateStackPos + 1) _stateStack[_stateStackLength++] = new RenderState(); if (token != null) _batchProcessor.fillToken(token); _stateStack[_stateStackPos].copyFrom(_state); } /** Modifies the current state with a transformation matrix, alpha factor, and blend mode. * * @param transformationMatrix Used to transform the currentmodelviewMatrix.
* @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.
*/
public function setStateTo(transformationMatrix:Matrix, alphaFactor:Float=1.0,
blendMode:String="auto"):Void
{
if (transformationMatrix != null) MatrixUtil.prependMatrix(_state._modelviewMatrix, transformationMatrix);
if (alphaFactor != 1.0) _state._alpha *= alphaFactor;
if (blendMode != BlendMode.AUTO) _state.blendMode = blendMode;
}
/** 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.
*/ public function popState(token:BatchToken=null):Void { if (_stateStackPos < 0) throw new IllegalOperationError("Cannot pop empty state stack"); _state.copyFrom(_stateStack[_stateStackPos]); // -> might cause 'finishMeshBatch' _stateStackPos--; if (token != null) _batchProcessor.fillToken(token); } /** Restores the render state that was last pushed to the stack, but does NOT remove * it from the stack. */ public function restoreState():Void { if (_stateStackPos < 0) throw new IllegalOperationError("Cannot restore from empty state stack"); _state.copyFrom(_stateStack[_stateStackPos]); // -> might cause 'finishMeshBatch' } /** Updates all properties of the given token so that it describes the current position * within the render cache. */ public function fillToken(token:BatchToken):Void { if (token != null) _batchProcessor.fillToken(token); } // masks /** 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.
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.
null, the complete
* mesh will be used.
*/
public function batchMesh(mesh:Mesh, subset:MeshSubset=null):Void
{
_batchProcessor.addMesh(mesh, _state, subset);
}
/** Finishes the current mesh batch and prepares the next one. */
public function finishMeshBatch():Void
{
_batchProcessor.finishBatch();
}
/** 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. */ public function enableBatchTrimming(enabled:Bool=true, interval:Int=250):Void { _batchTrimInterval = enabled ? interval : 0; } /** Completes all unfinished batches, cleanup procedures. */ public function finishFrame():Void { if (_batchTrimInterval > 0) { var baseInterval:Int = _batchTrimInterval | 0x1; // odd number -> alternating processors var specInterval:Int = Std.int(_batchTrimInterval * 1.5); if (_frameID % baseInterval == 0) _batchProcessorCurr.trim(); if (_frameID % specInterval == 0) _batchProcessorSpec.trim(); } _batchProcessor.finishFrame(); _batchProcessor = _batchProcessorSpec; // no cache between frames processCacheExclusions(); } private function processCacheExclusions():Void { var i:Int, length:Int = _batchCacheExclusions.length; for (i in 0...length) _batchCacheExclusions[i].excludeFromCache(); _batchCacheExclusions.length = 0; } /** 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. */ public function setupContextDefaults():Void { _actualBlendMode = null; _actualCulling = null; _actualDepthMask = false; _actualDepthTest = null; } /** Resets the current state, state stack, batch processor, stencil reference value, * clipping rectangle, and draw count. Furthermore, depth testing is disabled. */ public function nextFrame():Void { // update batch processors _batchProcessor = swapBatchProcessors(); _batchProcessor.clear(); _batchProcessorSpec.clear(); setupContextDefaults(); // reset everything else stencilReferenceValue = DEFAULT_STENCIL_VALUE; _clipRectStack.length = 0; _drawCount = 0; _stateStackPos = -1; _state.reset(); } private function swapBatchProcessors():BatchProcessor { var tmp:BatchProcessor = _batchProcessorPrev; _batchProcessorPrev = _batchProcessorCurr; return _batchProcessorCurr = tmp; } /** Draws all meshes from the render cache betweenstartToken and
* (but not including) endToken. The render cache contains all meshes
* rendered in the previous frame. */
public function drawFromCache(startToken:BatchToken, endToken:BatchToken):Void
{
var meshBatch:MeshBatch;
var subset:MeshSubset = sMeshSubset;
if (!startToken.equals(endToken))
{
if (!_batchProcessorPrev.frameFinished) {
trace("Encountered invalid batch processor → skipping draw operation.");
return;
}
pushState();
for (i in startToken.batchID...(endToken.batchID + 1))
{
meshBatch = _batchProcessorPrev.getBatchAt(i);
subset.setTo(); // resets subset
if (i == startToken.batchID)
{
subset.vertexID = startToken.vertexID;
subset.indexID = startToken.indexID;
subset.numVertices = meshBatch.numVertices - subset.vertexID;
subset.numIndices = meshBatch.numIndices - subset.indexID;
}
if (i == endToken.batchID)
{
subset.numVertices = endToken.vertexID - subset.vertexID;
subset.numIndices = endToken.indexID - subset.indexID;
}
if (subset.numVertices != 0)
{
_state.alpha = 1.0;
_state.blendMode = meshBatch.blendMode;
_batchProcessor.addMesh(meshBatch, _state, subset, true);
}
}
popState();
}
}
/** 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.
*/ public function excludeFromCache(object:DisplayObject):Void { if (object != null) _batchCacheExclusions[_batchCacheExclusions.length] = object; } private function drawBatch(meshBatch:MeshBatch):Void { pushState(); state.blendMode = meshBatch.blendMode; state.modelviewMatrix.identity(); state.alpha = 1.0; meshBatch.render(this); popState(); } // helper methods /** 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().
*/
public function prepareToDraw():Void
{
applyBlendMode();
applyRenderTarget();
applyClipRect();
applyCulling();
applyDepthTest();
}
/** 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'. */
public function clear(rgb:UInt=0, alpha:Float=0.0):Void
{
applyRenderTarget();
stencilReferenceValue = DEFAULT_STENCIL_VALUE;
RenderUtil.clear(rgb, alpha, 1.0, DEFAULT_STENCIL_VALUE);
}
/** Resets the render target to the back buffer and displays its contents. */
public function present():Void
{
_state.renderTarget = null;
_actualRenderTarget = null;
_context.present();
}
private function applyBlendMode():Void
{
var blendMode:String = _state.blendMode;
if (blendMode != _actualBlendMode)
{
BlendMode.get(_state.blendMode).activate();
_actualBlendMode = blendMode;
}
}
private function applyCulling():Void
{
var culling:String = _state.culling;
if (culling != _actualCulling)
{
_context.setCulling(culling);
_actualCulling = culling;
}
}
private function applyDepthTest():Void
{
var depthMask:Bool = _state.depthMask;
var depthTest:String = _state.depthTest;
if (depthMask != _actualDepthMask || depthTest != _actualDepthTest)
{
_context.setDepthTest(depthMask, depthTest);
_actualDepthMask = depthMask;
_actualDepthTest = depthTest;
}
}
private function applyRenderTarget():Void
{
var target:TextureBase = _state.renderTargetBase;
var options:UInt = _state.renderTargetOptions;
if (target != _actualRenderTarget || options != _actualRenderTargetOptions)
{
if (target != null)
{
var antiAlias:Int = _state.renderTargetAntiAlias;
var depthAndStencil:Bool = _state.renderTargetSupportsDepthAndStencil;
_context.setRenderToTexture(target, depthAndStencil, antiAlias);
}
else
_context.setRenderToBackBuffer();
_context.setStencilReferenceValue(stencilReferenceValue);
_actualRenderTargetOptions = options;
_actualRenderTarget = target;
}
}
private function applyClipRect():Void
{
var clipRect:Rectangle = _state.clipRect;
if (clipRect != null)
{
var width:Int, height:Int;
var projMatrix:Matrix3D = _state.projectionMatrix3D;
var renderTarget:Texture = _state.renderTarget;
if (renderTarget != null)
{
width = Std.int(renderTarget.root.nativeWidth);
height = Std.int(renderTarget.root.nativeHeight);
}
else
{
width = _backBufferWidth;
height = _backBufferHeight;
}
// convert to pixel coordinates (matrix transformation ends up in range [-1, 1])
MatrixUtil.transformCoords3D(projMatrix, clipRect.x, clipRect.y, 0.0, sPoint3D);
sPoint3D.project(); // eliminate w-coordinate
sClipRect.x = (sPoint3D.x * 0.5 + 0.5) * width;
sClipRect.y = (0.5 - sPoint3D.y * 0.5) * height;
MatrixUtil.transformCoords3D(projMatrix, clipRect.right, clipRect.bottom, 0.0, sPoint3D);
sPoint3D.project(); // eliminate w-coordinate
sClipRect.right = (sPoint3D.x * 0.5 + 0.5) * width;
sClipRect.bottom = (0.5 - sPoint3D.y * 0.5) * height;
sBufferRect.setTo(0, 0, width, height);
RectangleUtil.intersect(sClipRect, sBufferRect, sScissorRect);
// an empty rectangle is not allowed, so we set it to the smallest possible size
if (sScissorRect.width < 1 || sScissorRect.height < 1)
sScissorRect.setTo(0, 0, 1, 1);
_context.setScissorRectangle(sScissorRect);
}
else
{
_context.setScissorRectangle(null);
}
}
/** 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).
*/
public function refreshBackBufferSize(scaleFactor:Float):Void
{
_backBufferWidth = _context.backBufferWidth;
_backBufferHeight = _context.backBufferHeight;
_backBufferScaleFactor = scaleFactor;
}
// properties
/** Indicates the number of stage3D draw calls. */
public var drawCount(get, set):Int;
private function get_drawCount():Int { return _drawCount; }
private function set_drawCount(value:Int):Int { return _drawCount = value; }
/** 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!
*/
public var stencilReferenceValue(get, set):UInt;
private function get_stencilReferenceValue():UInt
{
var key:Dynamic = _state.renderTarget != null ? _state.renderTargetBase : this;
if (_stencilReferenceValues.exists(key)) return _stencilReferenceValues.get(key);
else return DEFAULT_STENCIL_VALUE;
}
private function set_stencilReferenceValue(value:UInt):UInt
{
var key:Dynamic = _state.renderTarget != null ? _state.renderTargetBase : this;
_stencilReferenceValues.set(key, value);
if (contextValid)
_context.setStencilReferenceValue(value);
return value;
}
/** 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
*/
public var cacheEnabled(get, set):Bool;
private function get_cacheEnabled():Bool { return _batchProcessor == _batchProcessorCurr; }
private function set_cacheEnabled(value:Bool):Bool
{
if (value != cacheEnabled)
{
finishMeshBatch();
if (value) _batchProcessor = _batchProcessorCurr;
else _batchProcessor = _batchProcessorSpec;
}
return value;
}
/** 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 var state(get, never):RenderState; private function get_state():RenderState { return _state; } /** The Stage3D instance this painter renders into. */ public var stage3D(get, never):Stage3D; private function get_stage3D():Stage3D { return _stage3D; } /** The Context3D instance this painter renders into. */ public var context(get, never):Context3D; private function get_context():Context3D { return _context; } /** 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 var frameID(get, set):UInt;
private function set_frameID(value:UInt):UInt { return _frameID = value; }
private function get_frameID():UInt
{
return _batchProcessor == _batchProcessorCurr ? _frameID : 0;
}
/** The size (in points) that represents one pixel in the back buffer. */
public var pixelSize(get, set):Float;
private function get_pixelSize():Float { return _pixelSize; }
private function set_pixelSize(value:Float):Float { return _pixelSize = value; }
/** Indicates if another Starling instance (or another Stage3D framework altogether)
* uses the same render context. @default false */
public var shareContext(get, set):Bool;
private function get_shareContext():Bool { return _shareContext; }
private function set_shareContext(value:Bool):Bool { return _shareContext = value; }
/** Indicates if Stage3D render methods will report errors. Activate only when needed,
* as this has a negative impact on performance. @default false */
public var enableErrorChecking(get, set):Bool;
private function get_enableErrorChecking():Bool { return _enableErrorChecking; }
private function set_enableErrorChecking(value:Bool):Bool
{
_enableErrorChecking = value;
if (_context != null) _context.enableErrorChecking = value;
if (value) trace("[Starling] Warning: 'enableErrorChecking' has a " +
"negative impact on performance. Never activate for release builds!");
return value;
}
/** 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 'backBufferScaleFactor'
* for the actual pixel count. Alternatively, use the Context3D-property with the
* same name: it will return the exact pixel values. */
public var backBufferWidth(get, never):Int;
private function get_backBufferWidth():Int { return _backBufferWidth; }
/** 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 'backBufferScaleFactor'
* for the actual pixel count. Alternatively, use the Context3D-property with the
* same name: it will return the exact pixel values. */
public var backBufferHeight(get, never):Int;
private function get_backBufferHeight():Int { return _backBufferHeight; }
/** 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 var backBufferScaleFactor(get, never):Float;
private function get_backBufferScaleFactor():Float { return _backBufferScaleFactor; }
/** Indicates if the Context3D object is currently valid (i.e. it hasn't been lost or
* disposed). */
public var contextValid(get, never):Bool;
private function get_contextValid():Bool
{
if (_context != null)
{
var driverInfo:String = _context.driverInfo;
return driverInfo != null && driverInfo != "" && driverInfo != "Disposed";
}
else return false;
}
/** The Context3D profile of the current render context, or null
* if the context has not been created yet. */
public var profile(get, never):String;
private function get_profile():String
{
if (_context != null) return _context.profile;
else return null;
}
/** 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 var sharedData(get, never):Map