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.
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.
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'.
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.
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
The Context3D instance this painter renders into.
Indicates if the Context3D object is currently valid (i.e. it hasn't been lost or disposed).
Indicates the number of stage3D draw calls.
Indicates if Stage3D render methods will report errors. Activate only when needed, as this has a negative impact on performance. @default false
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.
The size (in points) that represents one pixel in the back buffer.
The Context3D profile of the current render context, or null
if the context has not been created yet.
Indicates if another Starling instance (or another Stage3D framework altogether) uses the same render context. @default false
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.
The Stage3D instance this painter renders into.
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.
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!
The value with which the stencil buffer will be cleared, and the default reference value used for stencil tests.
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.
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'.
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.
the position and size of the area that should be rendered into, in pixels.
only relevant for Desktop (!) HiDPI screens. If you want to support high resolutions, pass the 'contentScaleFactor' of the Flash stage; otherwise, '1.0'.
from 0 (none) to 16 (very high quality).
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.
if enabled, zooming a website will adapt the size of the back buffer.
Deletes the program of a certain name.
Disposes all mesh batches, programs, and - if it is not being shared - the render context.
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.
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.
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.
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.
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.
Updates all properties of the given token so that it describes the current position within the render cache.
Completes all unfinished batches, cleanup procedures.
Finishes the current mesh batch and prepares the next one.
Returns the program registered under a certain name, or null if no program with this name has been registered.
Indicates if a program is registered under a certain name.
Resets the current state, state stack, batch processor, stencil reference value, clipping rectangle, and draw count. Furthermore, depth testing is disabled.
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.
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()
.
Resets the render target to the back buffer and displays its contents.
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.
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).
Registers a program under a certain name. If the name was already used, the previous program is overwritten.
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
Restores the render state that was last pushed to the stack, but does NOT remove it from the stack.
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.
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.
Generated using TypeDoc
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 methodspushState
andpopState
to store a specific state and restore it later. That makes it easy to write rendering code that doesn't have any side effects.@see RenderState