Package | starling.display |
Class | public class QuadBatch |
Inheritance | QuadBatch ![]() ![]() ![]() |
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 | |
![]() | 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 | |
![]() | filter : FragmentFilter The filter or filter group 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] | 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 | |
![]() | 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] | 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] | QuadBatch | ||
tinted : Boolean [read-only] | 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 |
Method | Defined By | ||
---|---|---|---|
Creates a new QuadBatch instance with empty batch data. | QuadBatch | ||
![]() | 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 | ||
[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 | ||
![]() | getTransformationMatrix(targetSpace:DisplayObject, resultMatrix:Matrix = null):Matrix Creates a matrix that represents the transformation from the local coordinate system
to another. | DisplayObject | |
![]() | 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 Removes an event listener from the object. | EventDispatcher | |
![]() | removeEventListeners(type:String = null):void Removes all event listeners with a certain type, or all of them if type is null. | EventDispatcher | |
![]() | 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 |
numQuads | property |
numQuads:int
[read-only] public function get numQuads():int
smoothing | property |
smoothing:String
[read-only] public function get smoothing():String
texture | property |
tinted | property |
tinted:Boolean
[read-only] public function get tinted():Boolean
QuadBatch | () | Constructor |
public function QuadBatch()
Creates a new QuadBatch instance with empty batch data.
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 |
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 )
|
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 )
|
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.