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
 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
 Inheritedfilter : FragmentFilter
The filter or filter group that is attached to the display object.
DisplayObject
 InheritedhasVisibleArea : Boolean
[read-only] Indicates if an object occupies any visible area.
DisplayObject
 Inheritedheight : Number
The height of the object in pixels.
DisplayObject
 Inheritedname : String
The name of the display object (default: null).
DisplayObject
  numQuads : int
[read-only]
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
 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
 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]
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]
QuadBatch
  tinted : Boolean
[read-only]
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
 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
Public Methods
 MethodDefined By
  
Creates a new QuadBatch instance with empty batch data.
QuadBatch
 Inherited
addEventListener(type:String, listener:Function):void
Registers an event listener at a certain object.
EventDispatcher
  
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
QuadBatch
  
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
Dispatches an event to all objects that have registered listeners for its type.
EventDispatcher
 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
 Inherited
getTransformationMatrix(targetSpace:DisplayObject, resultMatrix:Matrix = null):Matrix
Creates a matrix that represents the transformation from the local coordinate system to another.
DisplayObject
 Inherited
globalToLocal(globalPoint:Point, resultPoint:Point = null):Point
Transforms a point from global (stage) coordinates to the 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
  
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
localToGlobal(localPoint:Point, resultPoint:Point = null):Point
Transforms a point from the local coordinate system to global (stage) coordinates.
DisplayObject
 Inherited
removeEventListener(type:String, listener:Function):void
Removes an event listener from the object.
EventDispatcher
 Inherited
removeEventListeners(type:String = null):void
Removes all event listeners with a certain type, or all of them if type is null.
EventDispatcher
 Inherited
removeFromParent(dispose:Boolean = false):void
Removes the object from its parent, if it has one.
DisplayObject
  
render(support:RenderSupport, parentAlpha:Number):void
[override] Renders the display object with the help of a support object.
QuadBatch
  
renderCustom(mvpMatrix:Matrix, 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
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 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
Property Detail
numQuadsproperty
numQuads:int  [read-only]


Implementation
    public function get numQuads():int
smoothingproperty 
smoothing:String  [read-only]


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


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


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

Creates a new QuadBatch instance with empty batch data.

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 'isStageChange' 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

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
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 8192 quads).

Parameters

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

Returns
Boolean
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:Matrix, 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:Matrix
 
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.