Packagestarling.display
Classpublic class QuadBatch
InheritanceQuadBatch Inheritance DisplayObject Inheritance EventDispatcher Inheritance Object

Optimizes rendering of a number of quads with an identical state.

The majority of all rendered objects in Starling are quads. In fact, all the default leaf nodes of Starling are quads (the Image and Quad classes). The rendering of those quads can be accelerated by a big factor if all quads with an identical state are sent to the GPU in just one call. That's what the QuadBatch class can do.

The 'flatten' method of the Sprite class uses this class internally to optimize its rendering performance. In most situations, it is recommended to stick with flattened sprites, because they are easier to use. Sometimes, however, it makes sense to use the QuadBatch class directly: e.g. you can add one quad multiple times to a quad batch, whereas you can only add it once to a sprite. Furthermore, this class does not dispatch ADDED or ADDED_TO_STAGE events when a quad is added, which makes it more lightweight.

One QuadBatch object is bound to a specific render state. The first object you add to a batch will decide on the QuadBatch's state, that is: its texture, its settings for smoothing and blending, and if it's tinted (colored vertices and/or transparency). When you reset the batch, it will accept a new state on the next added quad.

The class extends DisplayObject, but you can use it even without adding it to the display tree. Just call the 'renderCustom' method from within another render method, and pass appropriate values for transformation matrix, alpha and blend mode.

See also

Sprite


Public Properties
 PropertyDefined By
 Inheritedalpha : Number
The opacity of the object.
DisplayObject
 Inheritedbase : DisplayObject
[read-only] The topmost object in the display tree the object is part of.
DisplayObject
  batchable : Boolean
Indicates if the batch itself should be batched on rendering.
QuadBatch
 InheritedblendMode : String
The blend mode determines how the object is blended with the objects underneath.
DisplayObject
 Inheritedbounds : Rectangle
[read-only] The bounds of the object relative to the local coordinates of the parent.
DisplayObject
  capacity : int
Indicates the number of quads for which space is allocated (vertex- and index-buffers).
QuadBatch
 Inheritedfilter : FragmentFilter
The filter that is attached to the display object.
DisplayObject
  forceTinted : Boolean
If enabled, the QuadBatch will always be rendered with a tinting-enabled fragment shader and the method 'isStateChange' won't take tinting into account.
QuadBatch
 InheritedhasVisibleArea : Boolean
[read-only] Indicates if an object occupies any visible area.
DisplayObject
 Inheritedheight : Number
The height of the object in pixels.
DisplayObject
 Inheritedis3D : Boolean
[read-only] Indicates if this object or any of its parents is a 'Sprite3D' object.
DisplayObject
 Inheritedmask : DisplayObject
The display object that acts as a mask for the current object.
DisplayObject
 Inheritedname : String
The name of the display object (default: null).
DisplayObject
  numQuads : int
[read-only] Returns the number of quads that have been added to the batch.
QuadBatch
  ownsTexture : Boolean
If enabled, the texture (if there is one) will be disposed when the QuadBatch is.
QuadBatch
 Inheritedparent : DisplayObjectContainer
[read-only] The display object container that contains this display object.
DisplayObject
 InheritedpivotX : Number
The x coordinate of the object's origin in its own coordinate space (default: 0).
DisplayObject
 InheritedpivotY : Number
The y coordinate of the object's origin in its own coordinate space (default: 0).
DisplayObject
  premultipliedAlpha : Boolean
[read-only] Indicates if the rgb values are stored premultiplied with the alpha value.
QuadBatch
 Inheritedroot : DisplayObject
[read-only] The root object the display object is connected to (i.e.
DisplayObject
 Inheritedrotation : Number
The rotation of the object in radians.
DisplayObject
 Inheritedscale : Number
Sets both 'scaleX' and 'scaleY' to the same value.
DisplayObject
 InheritedscaleX : Number
The horizontal scale factor.
DisplayObject
 InheritedscaleY : Number
The vertical scale factor.
DisplayObject
 InheritedskewX : Number
The horizontal skew angle in radians.
DisplayObject
 InheritedskewY : Number
The vertical skew angle in radians.
DisplayObject
  smoothing : String
[read-only] The TextureSmoothing used for rendering.
QuadBatch
 Inheritedstage : Stage
[read-only] The stage the display object is connected to, or null if it is not connected to the stage.
DisplayObject
  texture : Texture
[read-only] The texture that is used for rendering, or null for pure quads.
QuadBatch
  tinted : Boolean
[read-only] Indicates if any vertices have a non-white color or are not fully opaque.
QuadBatch
 Inheritedtouchable : Boolean
Indicates if this object (and its children) will receive touch events.
DisplayObject
 InheritedtransformationMatrix : Matrix
The transformation matrix of the object relative to its parent.
DisplayObject
 InheritedtransformationMatrix3D : Matrix3D
[read-only] The 3D transformation matrix of the object relative to its parent.
DisplayObject
 InheriteduseHandCursor : Boolean
Indicates if the mouse cursor should transform into a hand while it's over the sprite.
DisplayObject
 Inheritedvisible : Boolean
The visibility of the object.
DisplayObject
 Inheritedwidth : Number
The width of the object in pixels.
DisplayObject
 Inheritedx : Number
The x coordinate of the object relative to the local coordinates of the parent.
DisplayObject
 Inheritedy : Number
The y coordinate of the object relative to the local coordinates of the parent.
DisplayObject
Protected Properties
 PropertyDefined By
  mVertexData : VertexData
The raw vertex data of the quad.
QuadBatch
Public Methods
 MethodDefined By
  
QuadBatch(optimizeForProfile:Boolean = false)
Creates a new QuadBatch instance with empty batch data.
QuadBatch
 Inherited
addEventListener(type:String, listener:Function):void
[override] Registers an event listener at a certain object.
DisplayObject
  
addImage(image:Image, parentAlpha:Number = 1.0, modelViewMatrix:Matrix = null, blendMode:String = null):void
Adds an image to the batch.
QuadBatch
  
addQuad(quad:Quad, parentAlpha:Number = 1.0, texture:Texture = null, smoothing:String = null, modelViewMatrix:Matrix = null, blendMode:String = null):void
Adds a quad to the batch.
QuadBatch
  
addQuadBatch(quadBatch:QuadBatch, parentAlpha:Number = 1.0, modelViewMatrix:Matrix = null, blendMode:String = null):void
Adds another QuadBatch to this batch.
QuadBatch
 Inherited
alignPivot(hAlign:String = center, vAlign:String = center):void
Moves the pivot point to a certain position within the local coordinate system of the object.
DisplayObject
  
Creates a duplicate of the QuadBatch object.
QuadBatch
  
compile(object:DisplayObject, quadBatches:Vector.<QuadBatch>):void
[static] Analyses an object that is made up exclusively of quads (or other containers) and creates a vector of QuadBatch objects representing it.
QuadBatch
 Inherited
dispatchEvent(event:Event):void
[override]
DisplayObject
 Inherited
dispatchEventWith(type:String, bubbles:Boolean = false, data:Object = null):void
Dispatches an event with the given parameters to all objects that have registered listeners for the given type.
EventDispatcher
  
dispose():void
[override] Disposes vertex- and index-buffer.
QuadBatch
  
getBounds(targetSpace:DisplayObject, resultRect:Rectangle = null):Rectangle
[override] Returns a rectangle that completely encloses the object as it appears in another coordinate system.
QuadBatch
  
getQuadAlpha(quadID:int):Number
Returns the alpha value of the first vertex of a specific quad.
QuadBatch
  
getQuadBounds(quadID:int, transformationMatrix:Matrix = null, resultRect:Rectangle = null):Rectangle
Calculates the bounds of a specific quad, optionally transformed by a matrix.
QuadBatch
  
getQuadColor(quadID:int):uint
Returns the color of the first vertex of a specific quad.
QuadBatch
 Inherited
getTransformationMatrix(targetSpace:DisplayObject, resultMatrix:Matrix = null):Matrix
Creates a matrix that represents the transformation from the local coordinate system to another.
DisplayObject
 Inherited
getTransformationMatrix3D(targetSpace:DisplayObject, resultMatrix:Matrix3D = null):Matrix3D
Creates a matrix that represents the transformation from the local coordinate system to another.
DisplayObject
  
getVertexAlpha(quadID:int, vertexID:int):Number
Returns the alpha value of one vertex of a specific quad.
QuadBatch
  
getVertexColor(quadID:int, vertexID:int):uint
Returns the color of one vertex of a specific quad.
QuadBatch
 Inherited
globalToLocal(globalPoint:Point, resultPoint:Point = null):Point
Transforms a point from global (stage) coordinates to the local coordinate system.
DisplayObject
 Inherited
globalToLocal3D(globalPoint:Point, resultPoint:Vector3D = null):Vector3D
Transforms a point from global (stage) coordinates to the 3D local coordinate system.
DisplayObject
 Inherited
hasEventListener(type:String):Boolean
Returns if there are listeners registered for a certain event type.
EventDispatcher
 Inherited
hitTest(localPoint:Point, forTouch:Boolean = false):DisplayObject
Returns the object that is found topmost beneath a point in local coordinates, or nil if the test fails.
DisplayObject
 Inherited
hitTestMask(localPoint:Point):Boolean
Checks if a certain point is inside the display object's mask.
DisplayObject
  
isStateChange(tinted:Boolean, parentAlpha:Number, texture:Texture, smoothing:String, blendMode:String, numQuads:int = 1):Boolean
Indicates if specific quads can be added to the batch without causing a state change.
QuadBatch
 Inherited
local3DToGlobal(localPoint:Vector3D, resultPoint:Point = null):Point
Transforms a 3D point from the local coordinate system to global (stage) coordinates.
DisplayObject
 Inherited
localToGlobal(localPoint:Point, resultPoint:Point = null):Point
Transforms a point from the local coordinate system to global (stage) coordinates.
DisplayObject
  
optimize(quadBatches:Vector.<QuadBatch>):void
[static] Naively optimizes a list of batches by merging all that have an identical state.
QuadBatch
 Inherited
removeEventListener(type:String, listener:Function):void
[override] Removes an event listener from the object.
DisplayObject
 Inherited
removeEventListeners(type:String = null):void
[override] Removes all event listeners with a certain type, or all of them if type is null.
DisplayObject
 Inherited
removeFromParent(dispose:Boolean = false):void
Removes the object from its parent, if it has one, and optionally disposes it.
DisplayObject
  
render(support:RenderSupport, parentAlpha:Number):void
[override] Renders the display object with the help of a support object.
QuadBatch
  
renderCustom(mvpMatrix:Matrix3D, parentAlpha:Number = 1.0, blendMode:String = null):void
Renders the current batch with custom settings for model-view-projection matrix, alpha and blend mode.
QuadBatch
  
reset():void
Resets the batch.
QuadBatch
  
setQuad(quadID:Number, quad:Quad):void
Replaces a quad or image at a certain index with another one.
QuadBatch
  
setQuadAlpha(quadID:int, alpha:Number):void
Updates the alpha value of a specific quad.
QuadBatch
  
setQuadColor(quadID:int, color:uint):void
Updates the color of a specific quad.
QuadBatch
  
setVertexAlpha(quadID:int, vertexID:int, alpha:Number):void
Updates the alpha value of one vertex of a specific quad.
QuadBatch
  
setVertexColor(quadID:int, vertexID:int, color:uint):void
Updates the color of one vertex of a specific quad.
QuadBatch
  
transformQuad(quadID:int, matrix:Matrix):void
Transforms the vertices of a certain quad by the given matrix.
QuadBatch
Protected Methods
 MethodDefined By
  
Call this method after manually changing the contents of 'mVertexData'.
QuadBatch
Events
 Event Summary Defined By
 InheritedDispatched when an object is added to a parent.DisplayObject
 InheritedDispatched when an object is connected to the stage (directly or indirectly).DisplayObject
 InheritedDispatched once every frame on every object that is connected to the stage.DisplayObject
 InheritedDispatched when a key on the keyboard is pressed.DisplayObject
 InheritedDispatched when a key on the keyboard is released.DisplayObject
 InheritedDispatched when an object is removed from its parent.DisplayObject
 InheritedDispatched when an object is removed from the stage and won't be rendered any longer.DisplayObject
 InheritedDispatched when an object is touched.DisplayObject
Public Constants
 ConstantDefined By
  MAX_NUM_QUADS : int = 16383
[static] The maximum number of quads that can be displayed by one QuadBatch.
QuadBatch
Property Detail
batchableproperty
batchable:Boolean

Indicates if the batch itself should be batched on rendering. This makes sense only if it contains only a small number of quads (we recommend no more than 16). Otherwise, the CPU costs will exceed any gains you get from avoiding the additional draw call.

The default value is false.


Implementation
    public function get batchable():Boolean
    public function set batchable(value:Boolean):void
capacityproperty 
capacity:int

Indicates the number of quads for which space is allocated (vertex- and index-buffers). If you add more quads than what fits into the current capacity, the QuadBatch is expanded automatically. However, if you know beforehand how many vertices you need, you can manually set the right capacity with this method.


Implementation
    public function get capacity():int
    public function set capacity(value:int):void
forceTintedproperty 
forceTinted:Boolean

If enabled, the QuadBatch will always be rendered with a tinting-enabled fragment shader and the method 'isStateChange' won't take tinting into account. This means fewer state changes, but also a slightly more complex fragment shader for non-tinted quads. On modern hardware, that's not a problem, and you'll avoid unnecessary state changes. However, on old devices like the iPad 1, you should be careful with this setting.

The default value is false.


Implementation
    public function get forceTinted():Boolean
    public function set forceTinted(value:Boolean):void
mVertexDataproperty 
protected var mVertexData:VertexData

The raw vertex data of the quad. After modifying its contents, call 'onVertexDataChanged' to upload the changes to the vertex buffers. Don't change the size of this object manually; instead, use the 'capacity' property of the QuadBatch.

numQuadsproperty 
numQuads:int  [read-only]

Returns the number of quads that have been added to the batch.


Implementation
    public function get numQuads():int
ownsTextureproperty 
ownsTexture:Boolean

If enabled, the texture (if there is one) will be disposed when the QuadBatch is.


Implementation
    public function get ownsTexture():Boolean
    public function set ownsTexture(value:Boolean):void
premultipliedAlphaproperty 
premultipliedAlpha:Boolean  [read-only]

Indicates if the rgb values are stored premultiplied with the alpha value.


Implementation
    public function get premultipliedAlpha():Boolean
smoothingproperty 
smoothing:String  [read-only]

The TextureSmoothing used for rendering.


Implementation
    public function get smoothing():String
textureproperty 
texture:Texture  [read-only]

The texture that is used for rendering, or null for pure quads. Note that this is the texture instance of the first added quad; subsequently added quads may use a different instance, as long as the base texture is the same.


Implementation
    public function get texture():Texture
tintedproperty 
tinted:Boolean  [read-only]

Indicates if any vertices have a non-white color or are not fully opaque.


Implementation
    public function get tinted():Boolean
Constructor Detail
QuadBatch()Constructor
public function QuadBatch(optimizeForProfile:Boolean = false)

Creates a new QuadBatch instance with empty batch data.

Parameters
optimizeForProfile:Boolean (default = false) — if enabled, the 'forceTinted' property will be automatically activated in 'baselineExtended' and better profiles.
Method Detail
addImage()method
public function addImage(image:Image, parentAlpha:Number = 1.0, modelViewMatrix:Matrix = null, blendMode:String = null):void

Adds an image to the batch. This method internally calls 'addQuad' with the correct parameters for 'texture' and 'smoothing'.

Parameters

image:Image
 
parentAlpha:Number (default = 1.0)
 
modelViewMatrix:Matrix (default = null)
 
blendMode:String (default = null)

addQuad()method 
public function addQuad(quad:Quad, parentAlpha:Number = 1.0, texture:Texture = null, smoothing:String = null, modelViewMatrix:Matrix = null, blendMode:String = null):void

Adds a quad to the batch. The first quad determines the state of the batch, i.e. the values for texture, smoothing and blendmode. When you add additional quads, make sure they share that state (e.g. with the 'isStateChange' method), or reset the batch.

Parameters

quad:Quad
 
parentAlpha:Number (default = 1.0)
 
texture:Texture (default = null)
 
smoothing:String (default = null)
 
modelViewMatrix:Matrix (default = null)
 
blendMode:String (default = null)

addQuadBatch()method 
public function addQuadBatch(quadBatch:QuadBatch, parentAlpha:Number = 1.0, modelViewMatrix:Matrix = null, blendMode:String = null):void

Adds another QuadBatch to this batch. Just like the 'addQuad' method, you have to make sure that you only add batches with an equal state.

Parameters

quadBatch:QuadBatch
 
parentAlpha:Number (default = 1.0)
 
modelViewMatrix:Matrix (default = null)
 
blendMode:String (default = null)

clone()method 
public function clone():QuadBatch

Creates a duplicate of the QuadBatch object.

Returns
QuadBatch
compile()method 
public static function compile(object:DisplayObject, quadBatches:Vector.<QuadBatch>):void

Analyses an object that is made up exclusively of quads (or other containers) and creates a vector of QuadBatch objects representing it. This can be used to render the container very efficiently. The 'flatten'-method of the Sprite class uses this method internally.

Parameters

object:DisplayObject
 
quadBatches:Vector.<QuadBatch>

dispose()method 
override public function dispose():void

Disposes vertex- and index-buffer.

getBounds()method 
override public function getBounds(targetSpace:DisplayObject, resultRect:Rectangle = null):Rectangle

Returns a rectangle that completely encloses the object as it appears in another coordinate system. If you pass a 'resultRectangle', the result will be stored in this rectangle instead of creating a new object.

Parameters

targetSpace:DisplayObject
 
resultRect:Rectangle (default = null)

Returns
Rectangle
getQuadAlpha()method 
public function getQuadAlpha(quadID:int):Number

Returns the alpha value of the first vertex of a specific quad.

Parameters

quadID:int

Returns
Number
getQuadBounds()method 
public function getQuadBounds(quadID:int, transformationMatrix:Matrix = null, resultRect:Rectangle = null):Rectangle

Calculates the bounds of a specific quad, optionally transformed by a matrix. If you pass a 'resultRect', the result will be stored in this rectangle instead of creating a new object.

Parameters

quadID:int
 
transformationMatrix:Matrix (default = null)
 
resultRect:Rectangle (default = null)

Returns
Rectangle
getQuadColor()method 
public function getQuadColor(quadID:int):uint

Returns the color of the first vertex of a specific quad.

Parameters

quadID:int

Returns
uint
getVertexAlpha()method 
public function getVertexAlpha(quadID:int, vertexID:int):Number

Returns the alpha value of one vertex of a specific quad.

Parameters

quadID:int
 
vertexID:int

Returns
Number
getVertexColor()method 
public function getVertexColor(quadID:int, vertexID:int):uint

Returns the color of one vertex of a specific quad.

Parameters

quadID:int
 
vertexID:int

Returns
uint
isStateChange()method 
public function isStateChange(tinted:Boolean, parentAlpha:Number, texture:Texture, smoothing:String, blendMode:String, numQuads:int = 1):Boolean

Indicates if specific quads can be added to the batch without causing a state change. A state change occurs if the quad uses a different base texture, has a different 'tinted', 'smoothing', 'repeat' or 'blendMode' setting, or if the batch is full (one batch can contain up to 16383 quads).

Parameters

tinted:Boolean
 
parentAlpha:Number
 
texture:Texture
 
smoothing:String
 
blendMode:String
 
numQuads:int (default = 1)

Returns
Boolean
onVertexDataChanged()method 
protected function onVertexDataChanged():void

Call this method after manually changing the contents of 'mVertexData'.

optimize()method 
public static function optimize(quadBatches:Vector.<QuadBatch>):void

Naively optimizes a list of batches by merging all that have an identical state. Naturally, this will change the z-order of some of the batches, so this method is useful only for specific use-cases.

Parameters

quadBatches:Vector.<QuadBatch>

render()method 
override public function render(support:RenderSupport, parentAlpha:Number):void

Renders the display object with the help of a support object. Never call this method directly, except from within another render method.

Parameters

support:RenderSupport — Provides utility functions for rendering.
 
parentAlpha:Number — The accumulated alpha value from the object's parent up to the stage.

renderCustom()method 
public function renderCustom(mvpMatrix:Matrix3D, parentAlpha:Number = 1.0, blendMode:String = null):void

Renders the current batch with custom settings for model-view-projection matrix, alpha and blend mode. This makes it possible to render batches that are not part of the display list.

Parameters

mvpMatrix:Matrix3D
 
parentAlpha:Number (default = 1.0)
 
blendMode:String (default = null)

reset()method 
public function reset():void

Resets the batch. The vertex- and index-buffers remain their size, so that they can be reused quickly.

setQuad()method 
public function setQuad(quadID:Number, quad:Quad):void

Replaces a quad or image at a certain index with another one.

Parameters

quadID:Number
 
quad:Quad

setQuadAlpha()method 
public function setQuadAlpha(quadID:int, alpha:Number):void

Updates the alpha value of a specific quad.

Parameters

quadID:int
 
alpha:Number

setQuadColor()method 
public function setQuadColor(quadID:int, color:uint):void

Updates the color of a specific quad.

Parameters

quadID:int
 
color:uint

setVertexAlpha()method 
public function setVertexAlpha(quadID:int, vertexID:int, alpha:Number):void

Updates the alpha value of one vertex of a specific quad.

Parameters

quadID:int
 
vertexID:int
 
alpha:Number

setVertexColor()method 
public function setVertexColor(quadID:int, vertexID:int, color:uint):void

Updates the color of one vertex of a specific quad.

Parameters

quadID:int
 
vertexID:int
 
color:uint

transformQuad()method 
public function transformQuad(quadID:int, matrix:Matrix):void

Transforms the vertices of a certain quad by the given matrix.

Parameters

quadID:int
 
matrix:Matrix

Constant Detail
MAX_NUM_QUADSConstant
public static const MAX_NUM_QUADS:int = 16383

The maximum number of quads that can be displayed by one QuadBatch.