Packagestarling.core
Classpublic class RenderSupport
InheritanceRenderSupport Inheritance Object

A class that contains helper methods simplifying Stage3D rendering. A RenderSupport instance is passed to any "render" method of display objects. It allows manipulation of the current transformation matrix (similar to the matrix manipulation methods of OpenGL 1.x) and other helper methods.



Public Properties
 PropertyDefined By
  blendMode : String
The blend mode to be used on rendering.
RenderSupport
  drawCount : int
[read-only] Indicates the number of stage3D draw calls.
RenderSupport
  modelViewMatrix : Matrix
[read-only] Returns the current modelview matrix.
RenderSupport
  mvpMatrix : Matrix
[read-only] Calculates the product of modelview and projection matrix.
RenderSupport
  mvpMatrix3D : Matrix3D
[read-only] Calculates the product of modelview and projection matrix and stores it in a 3D matrix.
RenderSupport
  projectionMatrix : Matrix
Returns the current projection matrix.
RenderSupport
  projectionMatrix3D : Matrix3D
Returns the current 3D projection matrix.
RenderSupport
  renderTarget : Texture
The texture that is currently being rendered into, or 'null' to render into the back buffer.
RenderSupport
  stencilReferenceValue : uint
The current stencil reference value, which is per default the depth of the current stencil mask stack.
RenderSupport
Public Methods
 MethodDefined By
  
Creates a new RenderSupport object with an empty matrix stack.
RenderSupport
  
applyBlendMode(premultipliedAlpha:Boolean):void
Activates the current blend mode on the active rendering context.
RenderSupport
  
Updates the context3D scissor rectangle using the current clipping rectangle.
RenderSupport
  
assembleAgal(vertexShader:String, fragmentShader:String, resultProgram:Program3D = null):Program3D
[static] Assembles fragment- and vertex-shaders, passed as Strings, to a Program3D.
RenderSupport
  
batchQuad(quad:Quad, parentAlpha:Number, texture:Texture = null, smoothing:String = null):void
Adds a quad to the current batch of unrendered quads.
RenderSupport
  
batchQuadBatch(quadBatch:QuadBatch, parentAlpha:Number):void
Adds a batch of quads to the current batch of unrendered quads.
RenderSupport
  
clear(rgb:uint = 0, alpha:Number = 0.0):void
Clears the render context with a certain color and alpha value.
RenderSupport
  
clear(rgb:uint = 0, alpha:Number = 0.0):void
[static] Clears the render context with a certain color and alpha value.
RenderSupport
  
dispose():void
Disposes all quad batches.
RenderSupport
  
Renders the current quad batch and resets it.
RenderSupport
  
getTextureLookupFlags(format:String, mipMapping:Boolean, repeat:Boolean = false, smoothing:String = bilinear):String
[static] Returns the flags that are required for AGAL texture lookup, including the '<' and '>' delimiters.
RenderSupport
  
Changes the modelview matrix to the identity matrix.
RenderSupport
  
nextFrame():void
Resets matrix stack, blend mode, quad batch index, and draw count.
RenderSupport
  
Restores the clipping rectangle that was last pushed to the stack.
RenderSupport
  
popMask():void
Redraws the most recently pushed mask into the stencil buffer, decrementing the buffer on each used pixel.
RenderSupport
  
popMatrix():void
Restores the modelview matrix that was last pushed to the stack.
RenderSupport
  
Restores the 3D modelview matrix that was last pushed to the stack.
RenderSupport
  
prependMatrix(matrix:Matrix):void
Prepends a matrix to the modelview matrix by multiplying it with another matrix.
RenderSupport
  
pushClipRect(rectangle:Rectangle, intersectWithCurrent:Boolean = true):Rectangle
The clipping rectangle can be used to limit rendering in the current render target to a certain area.
RenderSupport
  
Draws a display object into the stencil buffer, incrementing the buffer on each used pixel.
RenderSupport
  
pushMatrix():void
Pushes the current modelview matrix to a stack from which it can be restored later.
RenderSupport
  
Pushes the current 3D modelview matrix to a stack from which it can be restored later.
RenderSupport
  
raiseDrawCount(value:uint = 1):void
Raises the draw count by a specific value.
RenderSupport
  
Empties the matrix stack, resets the modelview matrix to the identity matrix.
RenderSupport
  
rotateMatrix(angle:Number):void
Prepends a rotation (angle in radians) to the modelview matrix.
RenderSupport
  
scaleMatrix(sx:Number, sy:Number):void
Prepends an incremental scale change to the modelview matrix.
RenderSupport
  
setBlendFactors(premultipliedAlpha:Boolean, blendMode:String = normal):void
[static] Sets up the blending factors that correspond with a certain blend mode.
RenderSupport
  
setDefaultBlendFactors(premultipliedAlpha:Boolean):void
[static] Deprecated.
RenderSupport
  
setOrthographicProjection(x:Number, y:Number, width:Number, height:Number):void
Deprecated: Please Use setProjectionMatrix
Sets up the projection matrix for ortographic 2D rendering.
RenderSupport
  
setProjectionMatrix(x:Number, y:Number, width:Number, height:Number, stageWidth:Number = 0, stageHeight:Number = 0, cameraPos:Vector3D = null):void
Sets up the projection matrices for 2D and 3D rendering.
RenderSupport
  
setRenderTarget(target:Texture, antiAliasing:int = 0):void
Changes the the current render target.
RenderSupport
  
Prepends translation, scale and rotation of an object to the modelview matrix.
RenderSupport
  
Prepends translation, scale and rotation of an object to the 3D modelview matrix.
RenderSupport
  
transformMatrixForObject(matrix:Matrix, object:DisplayObject):void
[static] Prepends translation, scale and rotation of an object to a custom matrix.
RenderSupport
  
translateMatrix(dx:Number, dy:Number):void
Prepends a translation to the modelview matrix.
RenderSupport
Property Detail
blendModeproperty
blendMode:String

The blend mode to be used on rendering. To apply the factor, you have to manually call 'applyBlendMode' (because the actual blend factors depend on the PMA mode).


Implementation
    public function get blendMode():String
    public function set blendMode(value:String):void
drawCountproperty 
drawCount:int  [read-only]

Indicates the number of stage3D draw calls.


Implementation
    public function get drawCount():int
modelViewMatrixproperty 
modelViewMatrix:Matrix  [read-only]

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


Implementation
    public function get modelViewMatrix():Matrix
mvpMatrixproperty 
mvpMatrix:Matrix  [read-only]

Calculates the product of modelview and projection matrix. CAUTION: Use with care! Each call returns the same instance.


Implementation
    public function get mvpMatrix():Matrix
mvpMatrix3Dproperty 
mvpMatrix3D:Matrix3D  [read-only]

Calculates the product of modelview and projection matrix and stores it in a 3D matrix. Different to 'mvpMatrix', this also takes 3D transformations into account. CAUTION: Use with care! Each call returns the same instance.


Implementation
    public function get mvpMatrix3D():Matrix3D
projectionMatrixproperty 
projectionMatrix:Matrix

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


Implementation
    public function get projectionMatrix():Matrix
    public function set projectionMatrix(value:Matrix):void
projectionMatrix3Dproperty 
projectionMatrix3D:Matrix3D

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


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. If you set a new target, it is immediately activated.


Implementation
    public function get renderTarget():Texture
    public function set renderTarget(value:Texture):void
stencilReferenceValueproperty 
stencilReferenceValue:uint

The current stencil reference value, which is per default the depth of the current stencil mask stack. Only change this value if you know what you're doing.


Implementation
    public function get stencilReferenceValue():uint
    public function set stencilReferenceValue(value:uint):void
Constructor Detail
RenderSupport()Constructor
public function RenderSupport()

Creates a new RenderSupport object with an empty matrix stack.

Method Detail
applyBlendMode()method
public function applyBlendMode(premultipliedAlpha:Boolean):void

Activates the current blend mode on the active rendering context.

Parameters

premultipliedAlpha:Boolean

applyClipRect()method 
public function applyClipRect():void

Updates the context3D scissor rectangle using the current clipping rectangle. This method is called automatically when either the render target, the projection matrix, or the clipping rectangle changes.

assembleAgal()method 
public static function assembleAgal(vertexShader:String, fragmentShader:String, resultProgram:Program3D = null):Program3D

Assembles fragment- and vertex-shaders, passed as Strings, to a Program3D. If you pass a 'resultProgram', it will be uploaded to that program; otherwise, a new program will be created on the current Stage3D context.

Parameters

vertexShader:String
 
fragmentShader:String
 
resultProgram:Program3D (default = null)

Returns
Program3D
batchQuad()method 
public function batchQuad(quad:Quad, parentAlpha:Number, texture:Texture = null, smoothing:String = null):void

Adds a quad to the current batch of unrendered quads. If there is a state change, all previous quads are rendered at once, and the batch is reset.

Parameters

quad:Quad
 
parentAlpha:Number
 
texture:Texture (default = null)
 
smoothing:String (default = null)

batchQuadBatch()method 
public function batchQuadBatch(quadBatch:QuadBatch, parentAlpha:Number):void

Adds a batch of quads to the current batch of unrendered quads. If there is a state change, all previous quads are rendered at once.

Note that copying the contents of the QuadBatch to the current "cumulative" batch takes some time. If the batch consists of more than just a few quads, you may be better off calling the "render(Custom)" method on the batch instead. Otherwise, the additional CPU effort will be more expensive than what you save by avoiding the draw call. (Rule of thumb: no more than 16-20 quads.)

Parameters

quadBatch:QuadBatch
 
parentAlpha:Number

clear()method 
public function clear(rgb:uint = 0, alpha:Number = 0.0):void

Clears the render context with a certain color and alpha value.

Parameters

rgb:uint (default = 0)
 
alpha:Number (default = 0.0)

clear()method 
public static function clear(rgb:uint = 0, alpha:Number = 0.0):void

Clears the render context with a certain color and alpha value.

Parameters

rgb:uint (default = 0)
 
alpha:Number (default = 0.0)

dispose()method 
public function dispose():void

Disposes all quad batches.

finishQuadBatch()method 
public function finishQuadBatch():void

Renders the current quad batch and resets it.

getTextureLookupFlags()method 
public static function getTextureLookupFlags(format:String, mipMapping:Boolean, repeat:Boolean = false, smoothing:String = bilinear):String

Returns the flags that are required for AGAL texture lookup, including the '<' and '>' delimiters.

Parameters

format:String
 
mipMapping:Boolean
 
repeat:Boolean (default = false)
 
smoothing:String (default = bilinear)

Returns
String
loadIdentity()method 
public function loadIdentity():void

Changes the modelview matrix to the identity matrix.

nextFrame()method 
public function nextFrame():void

Resets matrix stack, blend mode, quad batch index, and draw count.

popClipRect()method 
public function popClipRect():void

Restores the clipping rectangle that was last pushed to the stack.

popMask()method 
public function popMask():void

Redraws the most recently pushed mask into the stencil buffer, decrementing the buffer on each used pixel. This effectively removes the object from the stencil buffer, restoring the previous state. The stencil reference value will be decremented.

popMatrix()method 
public function popMatrix():void

Restores the modelview matrix that was last pushed to the stack.

popMatrix3D()method 
public function popMatrix3D():void

Restores the 3D modelview matrix that was last pushed to the stack.

prependMatrix()method 
public function prependMatrix(matrix:Matrix):void

Prepends a matrix to the modelview matrix by multiplying it with another matrix.

Parameters

matrix:Matrix

pushClipRect()method 
public function pushClipRect(rectangle:Rectangle, intersectWithCurrent:Boolean = true):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. Internally, it uses the 'scissorRectangle' of stage3D, which works with pixel coordinates. Per default, any pushed rectangle is intersected with the previous rectangle; the method returns that intersection.

Parameters

rectangle:Rectangle
 
intersectWithCurrent:Boolean (default = true)

Returns
Rectangle
pushMask()method 
public function pushMask(mask:DisplayObject):void

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.

Parameters

mask:DisplayObject

pushMatrix()method 
public function pushMatrix():void

Pushes the current modelview matrix to a stack from which it can be restored later.

pushMatrix3D()method 
public function pushMatrix3D():void

Pushes the current 3D modelview matrix to a stack from which it can be restored later.

raiseDrawCount()method 
public function raiseDrawCount(value:uint = 1):void

Raises the draw count by a specific value. Call this method in custom render methods to keep the statistics display in sync.

Parameters

value:uint (default = 1)

resetMatrix()method 
public function resetMatrix():void

Empties the matrix stack, resets the modelview matrix to the identity matrix.

rotateMatrix()method 
public function rotateMatrix(angle:Number):void

Prepends a rotation (angle in radians) to the modelview matrix.

Parameters

angle:Number

scaleMatrix()method 
public function scaleMatrix(sx:Number, sy:Number):void

Prepends an incremental scale change to the modelview matrix.

Parameters

sx:Number
 
sy:Number

setBlendFactors()method 
public static function setBlendFactors(premultipliedAlpha:Boolean, blendMode:String = normal):void

Sets up the blending factors that correspond with a certain blend mode.

Parameters

premultipliedAlpha:Boolean
 
blendMode:String (default = normal)

setDefaultBlendFactors()method 
public static function setDefaultBlendFactors(premultipliedAlpha:Boolean):void

Deprecated. Call 'setBlendFactors' instead.

Parameters

premultipliedAlpha:Boolean

setOrthographicProjection()method 
public function setOrthographicProjection(x:Number, y:Number, width:Number, height:Number):void
Deprecated: Please Use setProjectionMatrix

Sets up the projection matrix for ortographic 2D rendering.

Parameters

x:Number
 
y:Number
 
width:Number
 
height:Number

setProjectionMatrix()method 
public function setProjectionMatrix(x:Number, y:Number, width:Number, height:Number, stageWidth:Number = 0, stageHeight:Number = 0, cameraPos:Vector3D = null):void

Sets up the projection matrices 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 perspective in which you're looking at the stage is determined by the final 3 parameters.

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.

Parameters

x:Number
 
y:Number
 
width:Number
 
height:Number
 
stageWidth:Number (default = 0)
 
stageHeight:Number (default = 0)
 
cameraPos:Vector3D (default = null)

setRenderTarget()method 
public function setRenderTarget(target:Texture, antiAliasing:int = 0):void

Changes the the current render target.

Parameters

target:Texture — Either a texture or 'null' to render into the back buffer.
 
antiAliasing:int (default = 0) — Only supported for textures, beginning with AIR 13, and only on Desktop. Values range from 0 (no antialiasing) to 4 (best quality).

transformMatrix()method 
public function transformMatrix(object:DisplayObject):void

Prepends translation, scale and rotation of an object to the modelview matrix.

Parameters

object:DisplayObject

transformMatrix3D()method 
public function transformMatrix3D(object:DisplayObject):void

Prepends translation, scale and rotation of an object 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

object:DisplayObject

transformMatrixForObject()method 
public static function transformMatrixForObject(matrix:Matrix, object:DisplayObject):void

Prepends translation, scale and rotation of an object to a custom matrix.

Parameters

matrix:Matrix
 
object:DisplayObject

translateMatrix()method 
public function translateMatrix(dx:Number, dy:Number):void

Prepends a translation to the modelview matrix.

Parameters

dx:Number
 
dy:Number