| Package | starling.display |
| Class | public class QuadBatch |
| Inheritance | QuadBatch  DisplayObject EventDispatcher Object |
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
| Property | Defined By | ||
|---|---|---|---|
 | alpha : Number The opacity of the object. | DisplayObject | |
| base : 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 | ||
| blendMode : String The blend mode determines how the object is blended with the objects underneath. | DisplayObject | |
| bounds : 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 | ||
| filter : 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 | ||
| hasVisibleArea : Boolean [read-only] Indicates if an object occupies any visible area. | DisplayObject | |
| height : Number The height of the object in pixels. | DisplayObject | |
| is3D : Boolean [read-only] Indicates if this object or any of its parents is a 'Sprite3D' object. | DisplayObject | |
| mask : DisplayObject The display object that acts as a mask for the current object. | DisplayObject | |
| name : 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 | ||
| parent : DisplayObjectContainer [read-only] The display object container that contains this display object. | DisplayObject | |
| pivotX : Number The x coordinate of the object's origin in its own coordinate space (default: 0). | DisplayObject | |
| pivotY : 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 | ||
| root : DisplayObject [read-only] The root object the display object is connected to (i.e. | DisplayObject | |
| rotation : Number The rotation of the object in radians. | DisplayObject | |
| scale : Number Sets both 'scaleX' and 'scaleY' to the same value. | DisplayObject | |
| scaleX : Number The horizontal scale factor. | DisplayObject | |
| scaleY : Number The vertical scale factor. | DisplayObject | |
| skewX : Number The horizontal skew angle in radians. | DisplayObject | |
| skewY : Number The vertical skew angle in radians. | DisplayObject | |
| smoothing : String [read-only] The TextureSmoothing used for rendering. | QuadBatch | ||
| stage : 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 | ||
| touchable : Boolean Indicates if this object (and its children) will receive touch events. | DisplayObject | |
| transformationMatrix : Matrix The transformation matrix of the object relative to its parent. | DisplayObject | |
| transformationMatrix3D : Matrix3D [read-only] The 3D transformation matrix of the object relative to its parent. | DisplayObject | |
| useHandCursor : Boolean Indicates if the mouse cursor should transform into a hand while it's over the sprite. | DisplayObject | |
| visible : Boolean The visibility of the object. | DisplayObject | |
| width : Number The width of the object in pixels. | DisplayObject | |
| x : Number The x coordinate of the object relative to the local coordinates of the parent. | DisplayObject | |
| y : Number The y coordinate of the object relative to the local coordinates of the parent. | DisplayObject | |
| Property | Defined By | ||
|---|---|---|---|
| mVertexData : VertexData The raw vertex data of the quad. | QuadBatch | ||
| Method | Defined By | ||
|---|---|---|---|
QuadBatch(optimizeForProfile:Boolean = false) Creates a new QuadBatch instance with empty batch data. | QuadBatch | ||
| 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 | ||
| 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 | ||
[static] Analyses an object that is made up exclusively of quads (or other containers)
and creates a vector of QuadBatch objects representing it. | QuadBatch | ||
| dispatchEvent(event:Event):void [override] | DisplayObject | |
| 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 | ||
| getTransformationMatrix(targetSpace:DisplayObject, resultMatrix:Matrix = null):Matrix Creates a matrix that represents the transformation from the local coordinate system
to another. | DisplayObject | |
| 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 | ||
| globalToLocal(globalPoint:Point, resultPoint:Point = null):Point Transforms a point from global (stage) coordinates to the local coordinate system. | DisplayObject | |
| globalToLocal3D(globalPoint:Point, resultPoint:Vector3D = null):Vector3D Transforms a point from global (stage) coordinates to the 3D local coordinate system. | DisplayObject | |
| hasEventListener(type:String):Boolean Returns if there are listeners registered for a certain event type. | EventDispatcher | |
| 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 | |
| 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 | ||
| local3DToGlobal(localPoint:Vector3D, resultPoint:Point = null):Point Transforms a 3D point from the local coordinate system to global (stage) coordinates. | DisplayObject | |
| localToGlobal(localPoint:Point, resultPoint:Point = null):Point Transforms a point from the local coordinate system to global (stage) coordinates. | DisplayObject | |
[static] Naively optimizes a list of batches by merging all that have an identical state. | QuadBatch | ||
| removeEventListener(type:String, listener:Function):void [override] Removes an event listener from the object. | DisplayObject | |
| removeEventListeners(type:String = null):void [override] Removes all event listeners with a certain type, or all of them if type is null. | DisplayObject | |
| 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 | ||
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 | ||
| Method | Defined By | ||
|---|---|---|---|
onVertexDataChanged():void Call this method after manually changing the contents of 'mVertexData'. | QuadBatch | ||
| Constant | Defined By | ||
|---|---|---|---|
| MAX_NUM_QUADS : int = 16383 [static] The maximum number of quads that can be displayed by one QuadBatch. | QuadBatch | ||
| batchable | property |
Hide Inherited Public Properties
Show Inherited Public Propertiesbatchable:BooleanIndicates 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.
public function get batchable():Boolean public function set batchable(value:Boolean):void| capacity | property |
capacity:intIndicates 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.
public function get capacity():int public function set capacity(value:int):void| forceTinted | property |
forceTinted:BooleanIf 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.
public function get forceTinted():Boolean public function set forceTinted(value:Boolean):void| mVertexData | property |
protected var mVertexData:VertexDataThe 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.
| numQuads | property |
numQuads:int [read-only] Returns the number of quads that have been added to the batch.
public function get numQuads():int| ownsTexture | property |
ownsTexture:BooleanIf enabled, the texture (if there is one) will be disposed when the QuadBatch is.
public function get ownsTexture():Boolean public function set ownsTexture(value:Boolean):void| premultipliedAlpha | property |
premultipliedAlpha:Boolean [read-only] Indicates if the rgb values are stored premultiplied with the alpha value.
public function get premultipliedAlpha():Boolean| smoothing | property |
smoothing:String [read-only] The TextureSmoothing used for rendering.
public function get smoothing():String| texture | property |
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.
public function get texture():Texture| tinted | property |
tinted:Boolean [read-only] Indicates if any vertices have a non-white color or are not fully opaque.
public function get tinted():Boolean| QuadBatch | () | Constructor |
public function QuadBatch(optimizeForProfile:Boolean = false)Creates a new QuadBatch instance with empty batch data.
ParametersoptimizeForProfile:Boolean (default = false) |
| addImage | () | method |
public function addImage(image:Image, parentAlpha:Number = 1.0, modelViewMatrix:Matrix = null, blendMode:String = null):voidAdds 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):voidAdds 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):voidAdds 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 |
| compile | () | method |
public static function compile(object:DisplayObject, quadBatches:Vector.<QuadBatch>):voidAnalyses 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():voidDisposes vertex- and index-buffer.
| getBounds | () | method |
override public function getBounds(targetSpace:DisplayObject, resultRect:Rectangle = null):RectangleReturns 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) |
Rectangle |
| getQuadAlpha | () | method |
public function getQuadAlpha(quadID:int):NumberReturns the alpha value of the first vertex of a specific quad.
Parameters
quadID:int |
Number |
| getQuadBounds | () | method |
public function getQuadBounds(quadID:int, transformationMatrix:Matrix = null, resultRect:Rectangle = null):RectangleCalculates 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) |
Rectangle |
| getQuadColor | () | method |
public function getQuadColor(quadID:int):uintReturns the color of the first vertex of a specific quad.
Parameters
quadID:int |
uint |
| getVertexAlpha | () | method |
public function getVertexAlpha(quadID:int, vertexID:int):NumberReturns the alpha value of one vertex of a specific quad.
Parameters
quadID:int | |
vertexID:int |
Number |
| getVertexColor | () | method |
public function getVertexColor(quadID:int, vertexID:int):uintReturns the color of one vertex of a specific quad.
Parameters
quadID:int | |
vertexID:int |
uint |
| isStateChange | () | method |
public function isStateChange(tinted:Boolean, parentAlpha:Number, texture:Texture, smoothing:String, blendMode:String, numQuads:int = 1):BooleanIndicates 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) |
Boolean |
| onVertexDataChanged | () | method |
protected function onVertexDataChanged():voidCall this method after manually changing the contents of 'mVertexData'.
| optimize | () | method |
public static function optimize(quadBatches:Vector.<QuadBatch>):voidNaively 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):voidRenders 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):voidRenders 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():voidResets 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):voidReplaces 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):voidUpdates the alpha value of a specific quad.
Parameters
quadID:int | |
alpha:Number |
| setQuadColor | () | method |
public function setQuadColor(quadID:int, color:uint):voidUpdates the color of a specific quad.
Parameters
quadID:int | |
color:uint |
| setVertexAlpha | () | method |
public function setVertexAlpha(quadID:int, vertexID:int, alpha:Number):voidUpdates 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):voidUpdates 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):voidTransforms the vertices of a certain quad by the given matrix.
Parameters
quadID:int | |
matrix:Matrix |
| MAX_NUM_QUADS | Constant |
public static const MAX_NUM_QUADS:int = 16383The maximum number of quads that can be displayed by one QuadBatch.