GODPAPER | All Packages | All Classes | Index | Frames No Frames |
QuadBatch

Package | starling.display
Class | public class QuadBatch
Inheritance | QuadBatch DisplayObject EventDispatcher 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
Hide Inherited Public Properties
Show Inherited Public Properties

| 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
|  | hasVisibleArea : Boolean [read-only] Indicates if an object occupies any visible area. | DisplayObject
|  | height : Number The height of the object in pixels. | 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
|  | 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
|  | 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
|  | 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

Protected Properties

| Property | Defined By
--- | --- | ---
|  | mVertexData : VertexData The raw vertex data of the quad. | QuadBatch

Public Methods
Hide Inherited Public Methods
Show Inherited Public Methods

| Method | Defined By
--- | --- | ---
|  | QuadBatch() Creates a new QuadBatch instance with empty batch data. | QuadBatch
|  | addEventListener(type:String, listener:Function):void [override] | 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
|  | clone():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
|  | dispatchEvent(event:Event):void Dispatches an event to all objects that have registered listeners for its type. | EventDispatcher
|  | 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
|  | 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
|  | 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
|  | 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
|  | localToGlobal(localPoint:Point, resultPoint:Point = null):Point Transforms a point from the local coordinate system to global (stage) coordinates. | DisplayObject
|  | removeEventListener(type:String, listener:Function):void [override] | DisplayObject
|  | removeEventListeners(type:String = null):void [override] | 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: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
|  | 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

| Method | Defined By
--- | --- | ---
|  | onVertexDataChanged():void Call this method after manually changing the contents of 'mVertexData'. | QuadBatch

Events
Hide Inherited Events
Show Inherited Events

| Event | Summary | Defined By
--- | --- | --- | ---
|  | added | Dispatched when an object is added to a parent. | DisplayObject
|  | addedToStage | Dispatched when an object is connected to the stage (directly or indirectly). | DisplayObject
|  | enterFrame | Dispatched once every frame on every object that is connected to the stage. | DisplayObject
|  | keyDown | Dispatched when a key on the keyboard is pressed. | DisplayObject
|  | keyUp | Dispatched when a key on the keyboard is released. | DisplayObject
|  | removed | Dispatched when an object is removed from its parent. | DisplayObject
|  | removedFromStage | Dispatched when an object is removed from the stage and won't be rendered any longer. | DisplayObject
|  | touch | Dispatched when an object is touched. | DisplayObject

Public Constants

| Constant | Defined By
--- | --- | ---
|  | MAX_NUM_QUADS : int = 8192 [static] The maximum number of quads that can be displayed by one QuadBatch. | QuadBatch

Property Detail

batchable | property

`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`

capacity | property |

`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`

mVertexData | property |

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

numQuads | property |

`numQuads:int` [read-only]

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

Implementation
`public function get numQuads():int`

premultipliedAlpha | property |

`premultipliedAlpha:Boolean` [read-only]

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

Implementation
`public function get premultipliedAlpha():Boolean`

smoothing | property |

`smoothing:String` [read-only]

The TextureSmoothing used for rendering.

Implementation
`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.

Implementation
`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.

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 '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 8192 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'.

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.

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_QUADS | Constant

`public static const MAX_NUM_QUADS:int = 8192`

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

Thu Jan 16 2014, 01:11 PM +08:00