Packagestarling.rendering
Classpublic class RenderState
InheritanceRenderState Inheritance Object

The RenderState stores a combination of settings that are currently used for rendering. This includes modelview and transformation matrices as well as context3D related settings.

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.

Matrix Magic

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

Painter
starling.display.Sprite3D


Public Properties
 PropertyDefined 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
  depthMask : Boolean
Enables or disables depth buffer writes.
RenderState
  depthTest : String
Sets type of comparison used for depth testing.
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
Public Methods
 MethodDefined 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
  
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
Property Detail
alphaproperty
alpha:Number

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


Implementation
    public function get alpha():Number
    public function set alpha(value:Number):void
blendModeproperty 
blendMode:String

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


Implementation
    public function get blendMode():String
    public function set blendMode(value:String):void

See also

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


Implementation
    public function get clipRect():Rectangle
    public function set clipRect(value:Rectangle):void
cullingproperty 
culling:String

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


Implementation
    public function get culling():String
    public function set culling(value:String):void
depthMaskproperty 
depthMask:Boolean

Enables or disables depth buffer writes.

The default value is false.


Implementation
    public function get depthMask():Boolean
    public function set depthMask(value:Boolean):void
depthTestproperty 
depthTest:String

Sets type of comparison used for depth testing.

The default value is Context3DCompareMode.ALWAYS.


Implementation
    public function get depthTest():String
    public function set depthTest(value:String):void
is3Dproperty 
is3D:Boolean  [read-only]

Indicates if there have been any 3D transformations. Returns true if the 3D modelview matrix contains a value.


Implementation
    public function get is3D():Boolean
modelviewMatrixproperty 
modelviewMatrix:Matrix

Returns the current 2D modelview matrix. CAUTION: Use with care! Each call returns the same instance.

The default value is identity matrix.


Implementation
    public function get modelviewMatrix():Matrix
    public function set modelviewMatrix(value:Matrix):void
modelviewMatrix3Dproperty 
modelviewMatrix3D:Matrix3D

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


Implementation
    public function get modelviewMatrix3D():Matrix3D
    public function set modelviewMatrix3D(value:Matrix3D):void
mvpMatrix3Dproperty 
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.


Implementation
    public function get mvpMatrix3D():Matrix3D
onDrawRequiredproperty 
onDrawRequired:Function


Implementation
    public function get onDrawRequired():Function
    public function set onDrawRequired(value:Function):void
projectionMatrix3Dproperty 
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.


Implementation
    public function get projectionMatrix3D():Matrix3D
    public function set projectionMatrix3D(value:Matrix3D):void
renderTargetproperty 
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.


Implementation
    public function get renderTarget():Texture
    public function set renderTarget(value:Texture):void
renderTargetAntiAliasproperty 
renderTargetAntiAlias:int  [read-only]

The anti-alias setting used when setting the current render target via setRenderTarget.


Implementation
    public function get renderTargetAntiAlias():int
renderTargetSupportsDepthAndStencilproperty 
renderTargetSupportsDepthAndStencil:Boolean  [read-only]

Indicates if the render target (set via setRenderTarget) has its depth and stencil buffers enabled.


Implementation
    public function get renderTargetSupportsDepthAndStencil():Boolean
Constructor Detail
RenderState()Constructor
public function RenderState()

Creates a new render state with the default settings.

Method Detail
copyFrom()method
public function copyFrom(renderState:RenderState):void

Duplicates all properties of another instance on the current instance.

Parameters

renderState:RenderState

reset()method 
public function reset():void

Resets the RenderState to the default settings. (Check each property documentation for its default value.)

setModelviewMatricesToIdentity()method 
public function setModelviewMatricesToIdentity():void

Changes 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):void

Creates 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):void

Changes the the current render target.

Parameters

target:Texture — Either a texture or null to render into the back buffer.
 
enableDepthAndStencil:Boolean (default = true) — Indicates if depth and stencil testing will be available. This parameter affects only texture targets.
 
antiAlias:int (default = 0) — The anti-aliasing quality (range: 0 - 4). 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):void

Prepends the given matrix to the 2D modelview matrix.

Parameters

matrix:Matrix

transformModelviewMatrix3D()method 
public function transformModelviewMatrix3D(matrix:Matrix3D):void

Prepends 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