| Package | starling.rendering |
| Class | public class RenderState |
| Inheritance | RenderState  Object |
Starling's Painter instance stores a reference to the current RenderState. Via a stack mechanism, you can always save a specific state and restore it later. That makes it easy to write rendering code that doesn't have any side effects.
Beware that any context-related settings are not applied on the context
right away, but only after calling painter.prepareToDraw().
However, the Painter recognizes changes to those settings and will finish the current
batch right away if necessary.
On rendering, Starling traverses the display tree, constantly moving from one coordinate system to the next. Each display object stores its vertex coordinates in its local coordinate system; on rendering, they must be moved to a global, 2D coordinate space (the so-called "clip-space"). To handle these calculations, the RenderState contains a set of matrices.
By multiplying vertex coordinates with the modelviewMatrix, you'll get the
coordinates in "screen-space", or in other words: in stage coordinates. (Optionally,
there's also a 3D version of this matrix. It comes into play when you're working with
Sprite3D containers.)
By feeding the result of the previous transformation into the
projectionMatrix, you'll end up with so-called "clipping coordinates",
which are in the range [-1, 1] (just as needed by the graphics pipeline).
If you've got vertices in the 3D space, this matrix will also execute a perspective
projection.
Finally, there's the mvpMatrix, which is short for
"modelviewProjectionMatrix". This is simply a combination of modelview- and
projectionMatrix, combining the effects of both. Pass this matrix
to the vertex shader and all your vertices will automatically end up at the right
position.
See also
| Property | Defined By | ||
|---|---|---|---|
| alpha : Number The current, cumulated alpha value. | RenderState | ||
| blendMode : String The blend mode to be used on rendering. | RenderState | ||
| clipRect : Rectangle The clipping rectangle can be used to limit rendering in the current render target to
a certain area. | RenderState | ||
| culling : String Sets the triangle culling mode. | RenderState | ||
| is3D : Boolean [read-only] Indicates if there have been any 3D transformations. | RenderState | ||
| modelviewMatrix : Matrix Returns the current 2D modelview matrix. | RenderState | ||
| modelviewMatrix3D : Matrix3D Returns the current 3D modelview matrix, if there have been 3D transformations. | RenderState | ||
| mvpMatrix3D : Matrix3D [read-only] Calculates the product of modelview and projection matrix and stores it in a 3D matrix. | RenderState | ||
| onDrawRequired : Function | RenderState | ||
| projectionMatrix3D : Matrix3D Returns the current projection matrix. | RenderState | ||
| renderTarget : Texture The texture that is currently being rendered into, or null
to render into the back buffer. | RenderState | ||
| renderTargetAntiAlias : int [read-only] The anti-alias setting used when setting the current render target
via setRenderTarget. | RenderState | ||
| renderTargetSupportsDepthAndStencil : Boolean [read-only] Indicates if the render target (set via setRenderTarget)
has its depth and stencil buffers enabled. | RenderState | ||
| Method | Defined By | ||
|---|---|---|---|
Creates a new render state with the default settings. | RenderState | ||
copyFrom(renderState:RenderState):void Duplicates all properties of another instance on the current instance. | RenderState | ||
reset():void Resets the RenderState to the default settings. | RenderState | ||
Changes the modelview matrices (2D and, if available, 3D) to identity matrices. | RenderState | ||
setProjectionMatrix(x:Number, y:Number, width:Number, height:Number, stageWidth:Number = 0, stageHeight:Number = 0, cameraPos:Vector3D = null):void Creates a perspective projection matrix suitable for 2D and 3D rendering. | RenderState | ||
setProjectionMatrixChanged():void This method needs to be called whenever projectionMatrix3D was changed
other than via setProjectionMatrix. | RenderState | ||
setRenderTarget(target:Texture, enableDepthAndStencil:Boolean = true, antiAlias:int = 0):void Changes the the current render target. | RenderState | ||
transformModelviewMatrix(matrix:Matrix):void Prepends the given matrix to the 2D modelview matrix. | RenderState | ||
transformModelviewMatrix3D(matrix:Matrix3D):void Prepends the given matrix to the 3D modelview matrix. | RenderState | ||
| alpha | property |
alpha:NumberThe current, cumulated alpha value. Beware that, in a standard 'render' method, this already includes the current object! The value is the product of current object's alpha value and all its parents.
The default value is 1.0.
public function get alpha():Number public function set alpha(value:Number):void| blendMode | property |
blendMode:StringThe blend mode to be used on rendering. A value of "auto" is ignored, since it means that the mode should remain unchanged.
The default value is BlendMode.NORMAL.
public function get blendMode():String public function set blendMode(value:String):voidSee also
| clipRect | property |
clipRect:Rectangle The clipping rectangle can be used to limit rendering in the current render target to
a certain area. This method expects the rectangle in stage coordinates. To prevent
any clipping, assign null.
The default value is null.
public function get clipRect():Rectangle public function set clipRect(value:Rectangle):void| culling | property |
culling:StringSets the triangle culling mode. Allows to exclude triangles from rendering based on their orientation relative to the view plane.
The default value is Context3DTriangleFace.NONE.
public function get culling():String public function set culling(value:String):void| is3D | property |
is3D:Boolean [read-only] Indicates if there have been any 3D transformations.
Returns true if the 3D modelview matrix contains a value.
public function get is3D():Boolean| modelviewMatrix | property |
modelviewMatrix:MatrixReturns the current 2D modelview matrix. CAUTION: Use with care! Each call returns the same instance.
The default value is identity matrix.
public function get modelviewMatrix():Matrix public function set modelviewMatrix(value:Matrix):void| modelviewMatrix3D | property |
modelviewMatrix3D:Matrix3DReturns the current 3D modelview matrix, if there have been 3D transformations. CAUTION: Use with care! Each call returns the same instance.
The default value is null.
public function get modelviewMatrix3D():Matrix3D public function set modelviewMatrix3D(value:Matrix3D):void| mvpMatrix3D | property |
mvpMatrix3D:Matrix3D [read-only] Calculates the product of modelview and projection matrix and stores it in a 3D matrix. CAUTION: Use with care! Each call returns the same instance.
public function get mvpMatrix3D():Matrix3D| onDrawRequired | property |
onDrawRequired:Function public function get onDrawRequired():Function public function set onDrawRequired(value:Function):void| projectionMatrix3D | property |
projectionMatrix3D:Matrix3D Returns the current projection matrix. You can use the method 'setProjectionMatrix3D'
to set it up in an intuitive way.
CAUTION: Use with care! Each call returns the same instance. If you modify the matrix
in place, you have to call setProjectionMatrixChanged.
The default value is identity matrix.
public function get projectionMatrix3D():Matrix3D public function set projectionMatrix3D(value:Matrix3D):void| renderTarget | property |
renderTarget:Texture The texture that is currently being rendered into, or null
to render into the back buffer. On assignment, calls setRenderTarget
with its default parameters.
public function get renderTarget():Texture public function set renderTarget(value:Texture):void| renderTargetAntiAlias | property |
renderTargetAntiAlias:int [read-only] The anti-alias setting used when setting the current render target
via setRenderTarget.
public function get renderTargetAntiAlias():int| renderTargetSupportsDepthAndStencil | property |
renderTargetSupportsDepthAndStencil:Boolean [read-only] Indicates if the render target (set via setRenderTarget)
has its depth and stencil buffers enabled.
public function get renderTargetSupportsDepthAndStencil():Boolean| RenderState | () | Constructor |
public function RenderState()Creates a new render state with the default settings.
| copyFrom | () | method |
public function copyFrom(renderState:RenderState):voidDuplicates all properties of another instance on the current instance.
Parameters
renderState:RenderState |
| reset | () | method |
public function reset():voidResets the RenderState to the default settings. (Check each property documentation for its default value.)
| setModelviewMatricesToIdentity | () | method |
public function setModelviewMatricesToIdentity():voidChanges the modelview matrices (2D and, if available, 3D) to identity matrices. An object transformed an identity matrix performs no transformation.
| setProjectionMatrix | () | method |
public function setProjectionMatrix(x:Number, y:Number, width:Number, height:Number, stageWidth:Number = 0, stageHeight:Number = 0, cameraPos:Vector3D = null):voidCreates a perspective projection matrix suitable for 2D and 3D rendering.
The first 4 parameters define which area of the stage you want to view (the camera will 'zoom' to exactly this region). The final 3 parameters determine the perspective in which you're looking at the stage.
The stage is always on the rectangle that is spawned up between x- and y-axis (with the given size). All objects that are exactly on that rectangle (z equals zero) will be rendered in their true size, without any distortion.
If you pass only the first 4 parameters, the camera will be set up above the center of the stage, with a field of view of 1.0 rad.
Parameters
x:Number | |
y:Number | |
width:Number | |
height:Number | |
stageWidth:Number (default = 0) | |
stageHeight:Number (default = 0) | |
cameraPos:Vector3D (default = null) |
| setProjectionMatrixChanged | () | method |
public function setProjectionMatrixChanged():void This method needs to be called whenever projectionMatrix3D was changed
other than via setProjectionMatrix.
| setRenderTarget | () | method |
public function setRenderTarget(target:Texture, enableDepthAndStencil:Boolean = true, antiAlias:int = 0):voidChanges the the current render target.
Parameters
target:Texture — Either a texture or null to render into the back buffer.
| |
enableDepthAndStencil:Boolean (default = true) | |
antiAlias:int (default = 0)0 - 16).
This parameter affects only texture targets. Note that at the time
of this writing, AIR supports anti-aliasing only on Desktop.
|
| transformModelviewMatrix | () | method |
public function transformModelviewMatrix(matrix:Matrix):voidPrepends the given matrix to the 2D modelview matrix.
Parameters
matrix:Matrix |
| transformModelviewMatrix3D | () | method |
public function transformModelviewMatrix3D(matrix:Matrix3D):voidPrepends the given matrix to the 3D modelview matrix. The current contents of the 2D modelview matrix is stored in the 3D modelview matrix before doing so; the 2D modelview matrix is then reset to the identity matrix.
Parameters
matrix:Matrix3D |