Packagestarling.display
Classpublic class MeshBatch
InheritanceMeshBatch Inheritance Mesh Inheritance DisplayObject Inheritance EventDispatcher Inheritance Object

Combines a number of meshes to one display object and renders them efficiently.

The most basic tangible (non-container) display object in Starling is the Mesh. However, a mesh typically does not render itself; it just holds the data describing its geometry. Rendering is orchestrated by the "MeshBatch" class. As its name suggests, it acts as a batch for an arbitrary number of Mesh instances; add meshes to a batch and they are all rendered together, in one draw call.

You can only batch meshes that share similar properties, e.g. they need to have the same texture and the same blend mode. The first object you add to a batch will decide this state; call canAddMesh to find out if a new mesh shares that state. To reset the current state, you can call clear; this will also remove all geometry that has been added thus far.

Starling will use MeshBatch instances (or compatible objects) for all rendering. However, you can also instantiate MeshBatch instances yourself and add them to the display tree. That makes sense for an object containing a large number of meshes; that way, that object can be created once and then rendered very efficiently, without having to copy its vertices and indices between buffers and GPU memory.

See also

Mesh
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 this object will be added to the painter's batch on rendering, or if it will draw itself right away.
MeshBatch
 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
 Inheritedcolor : uint
Changes the color of all vertices to the same value.
Mesh
 InheriteddefaultStyle : Class
[static] The default style used for meshes if no specific style is provided.
Mesh
 InheriteddefaultStyleFactory : Function
[static] A factory method that is used to create the 'MeshStyle' for a mesh if no specific style is provided.
Mesh
 Inheritedfilter : FragmentFilter
The filter that is attached to the display object.
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
 InheritedmaskInverted : Boolean
Indicates if the masked region of this object is set to be inverted.
DisplayObject
 Inheritedname : String
The name of the display object (default: null).
DisplayObject
  numIndices : int
The total number of indices in the mesh.
MeshBatch
 InheritednumTriangles : int
[read-only] The total number of triangles in this mesh.
Mesh
  numVertices : int
The total number of vertices in the mesh.
MeshBatch
 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
 InheritedpixelSnapping : Boolean
Controls whether or not the instance snaps to the nearest pixel.
Mesh
 InheritedrequiresRedraw : Boolean
[read-only] Indicates if the object needs to be redrawn in the upcoming frame, i.e.
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
 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
 Inheritedstage : Stage
[read-only] The stage the display object is connected to, or null if it is not connected to the stage.
DisplayObject
 Inheritedstyle : MeshStyle
The style that is used to render the mesh.
Mesh
 Inheritedtexture : Texture
The texture that is mapped to the mesh (or null, if there is none).
Mesh
 InheritedtextureRepeat : Boolean
Indicates if pixels at the edges will be repeated or clamped.
Mesh
 InheritedtextureSmoothing : String
The smoothing filter that is used for the texture.
Mesh
 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
 InheritedvertexFormat : VertexDataFormat
[read-only] The format used to store the vertices.
Mesh
 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
 InheritedindexData : IndexData
[read-only] The index data describing how the vertices are interconnected.
Mesh
 InheritedvertexData : VertexData
[read-only] The vertex data describing all vertices of the mesh.
Mesh
Public Methods
 MethodDefined By
  
Creates a new, empty MeshBatch instance.
MeshBatch
 Inherited
addEventListener(type:String, listener:Function):void
[override] Registers an event listener at a certain object.
DisplayObject
  
addMesh(mesh:Mesh, matrix:Matrix = null, alpha:Number = 1.0, subset:MeshSubset = null, ignoreTransformations:Boolean = false):void
Adds a mesh to the batch by appending its vertices and indices.
MeshBatch
  
addMeshAt(mesh:Mesh, indexID:int = -1, vertexID:int = -1, matrix:Matrix = null, alpha:Number = 1.0, subset:MeshSubset = null, ignoreTransformations:Boolean = false):void
Adds a mesh to the batch by copying its vertices and indices to the given positions.
MeshBatch
 Inherited
alignPivot(horizontalAlign:String = center, verticalAlign:String = center):void
Moves the pivot point to a certain position within the local coordinate system of the object.
DisplayObject
  
canAddMesh(mesh:Mesh, numVertices:int = -1):Boolean
Indicates if the given mesh instance fits to the current state of the batch.
MeshBatch
  
clear():void
Removes all geometry.
MeshBatch
 Inherited
[static] Creates a new instance of the current default MeshStyle.
Mesh
 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 all resources of the display object.
MeshBatch
 Inherited
drawToBitmapData(out:BitmapData = null, color:uint = 0x0, alpha:Number = 0.0):BitmapData
Draws the object into a BitmapData object.
DisplayObject
 Inherited
fromPolygon(polygon:Polygon, style:MeshStyle = null):Mesh
[static] Creates a mesh from the specified polygon.
Mesh
 Inherited
getBounds(targetSpace:DisplayObject, out:Rectangle = null):Rectangle
[override] Returns a rectangle that completely encloses the object as it appears in another coordinate system.
Mesh
 Inherited
getTexCoords(vertexID:int, out:Point = null):Point
Returns the texture coordinates of the vertex at the specified index.
Mesh
 Inherited
getTransformationMatrix(targetSpace:DisplayObject, out:Matrix = null):Matrix
Creates a matrix that represents the transformation from the local coordinate system to another.
DisplayObject
 Inherited
getTransformationMatrix3D(targetSpace:DisplayObject, out:Matrix3D = null):Matrix3D
Creates a matrix that represents the transformation from the local coordinate system to another.
DisplayObject
 Inherited
getVertexAlpha(vertexID:int):Number
Returns the alpha value of the vertex at the specified index.
Mesh
 Inherited
getVertexColor(vertexID:int):uint
Returns the RGB color of the vertex at the specified index.
Mesh
 Inherited
getVertexPosition(vertexID:int, out:Point = null):Point
The position of the vertex at the specified index, in the mesh's local coordinate system.
Mesh
 Inherited
globalToLocal(globalPoint:Point, out:Point = null):Point
Transforms a point from global (stage) coordinates to the local coordinate system.
DisplayObject
 Inherited
globalToLocal3D(globalPoint:Point, out:Vector3D = null):Vector3D
Transforms a point from global (stage) coordinates to the 3D local coordinate system.
DisplayObject
 Inherited
hasEventListener(type:String, listener:Function = null):Boolean
If called with one argument, figures out if there are any listeners registered for the given event type.
EventDispatcher
 Inherited
hitTest(localPoint:Point):DisplayObject
[override] Returns the object that is found topmost beneath a point in local coordinates, or nil if the test fails.
Mesh
 Inherited
hitTestMask(localPoint:Point):Boolean
Checks if a certain point is inside the display object's mask.
DisplayObject
 Inherited
local3DToGlobal(localPoint:Vector3D, out:Point = null):Point
Transforms a 3D point from the local coordinate system to global (stage) coordinates.
DisplayObject
 Inherited
localToGlobal(localPoint:Point, out:Point = null):Point
Transforms a point from the local coordinate system to global (stage) coordinates.
DisplayObject
 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(painter:Painter):void
[override] If the batchable property is enabled, this method will add the batch to the painter's current batch.
MeshBatch
  
[override] This method must be called whenever the mesh's index data was changed.
MeshBatch
 Inherited
Forces the object to be redrawn in the next frame.
DisplayObject
  
setStyle(meshStyle:MeshStyle = null, mergeWithPredecessor:Boolean = true):void
[override] Sets the style that is used to render the mesh.
MeshBatch
 Inherited
setTexCoords(vertexID:int, u:Number, v:Number):void
Sets the texture coordinates of the vertex at the specified index to the given values.
Mesh
 Inherited
setVertexAlpha(vertexID:int, alpha:Number):void
Sets the alpha value of the vertex at the specified index to a certain value.
Mesh
 Inherited
setVertexColor(vertexID:int, color:uint):void
Sets the RGB color of the vertex at the specified index to a certain value.
Mesh
  
[override] This method must be called whenever the mesh's vertex data was changed.
MeshBatch
 Inherited
setVertexPosition(vertexID:int, x:Number, y:Number):void
Mesh
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_VERTICES : int = 65535
[static] The maximum number of vertices that fit into one MeshBatch.
MeshBatch
Property Detail
batchableproperty
batchable:Boolean

Indicates if this object will be added to the painter's batch on rendering, or if it will draw itself right away.

Only batchable meshes can profit from the render cache; but batching large meshes may take up a lot of CPU time. Activate this property only if the batch contains just a handful of vertices (say, 20 quads).

The default value is false.


Implementation
    public function get batchable():Boolean
    public function set batchable(value:Boolean):void
numIndicesproperty 
numIndices:int

The total number of indices in the mesh. If you change this to a smaller value, the surplus will be deleted. Always make sure that the number of indices is a multiple of three!


Implementation
    public function get numIndices():int
    public function set numIndices(value:int):void
numVerticesproperty 
numVertices:int

The total number of vertices in the mesh. If you change this to a smaller value, the surplus will be deleted. Make sure that no indices reference those deleted vertices!


Implementation
    public function get numVertices():int
    public function set numVertices(value:int):void
Constructor Detail
MeshBatch()Constructor
public function MeshBatch()

Creates a new, empty MeshBatch instance.

Method Detail
addMesh()method
public function addMesh(mesh:Mesh, matrix:Matrix = null, alpha:Number = 1.0, subset:MeshSubset = null, ignoreTransformations:Boolean = false):void

Adds a mesh to the batch by appending its vertices and indices.

Note that the first time you add a mesh to the batch, the batch will duplicate its MeshStyle. All subsequently added meshes will then be converted to that same style.

Parameters

mesh:Mesh — the mesh to add to the batch.
 
matrix:Matrix (default = null) — transform all vertex positions with a certain matrix. If this parameter is omitted, mesh.transformationMatrix will be used instead (except if the last parameter is enabled).
 
alpha:Number (default = 1.0) — will be multiplied with each vertex' alpha value.
 
subset:MeshSubset (default = null) — the subset of the mesh you want to add, or null for the complete mesh.
 
ignoreTransformations:Boolean (default = false) — when enabled, the mesh's vertices will be added without transforming them in any way (no matter the value of the matrix parameter).

addMeshAt()method 
public function addMeshAt(mesh:Mesh, indexID:int = -1, vertexID:int = -1, matrix:Matrix = null, alpha:Number = 1.0, subset:MeshSubset = null, ignoreTransformations:Boolean = false):void

Adds a mesh to the batch by copying its vertices and indices to the given positions. Beware that you need to check for yourself if those positions make sense; for example, you need to make sure that they are aligned within the 3-indices groups making up the mesh's triangles.

It's easiest to only add objects with an identical setup, e.g. only quads. For the latter, indices are aligned in groups of 6 (one quad requires six indices), and the vertices in groups of 4 (one vertex for every corner).

Note that the first time you add a mesh to the batch, the batch will duplicate its MeshStyle. All subsequently added meshes will then be converted to that same style.

Parameters

mesh:Mesh — the mesh to add to the batch.
 
indexID:int (default = -1) — the position at which the mesh's indices should be added to the batch. If negative, they will be added at the very end.
 
vertexID:int (default = -1) — the position at which the mesh's vertices should be added to the batch. If negative, they will be added at the very end.
 
matrix:Matrix (default = null) — transform all vertex positions with a certain matrix. If this parameter is omitted, mesh.transformationMatrix will be used instead (except if the last parameter is enabled).
 
alpha:Number (default = 1.0) — will be multiplied with each vertex' alpha value.
 
subset:MeshSubset (default = null) — the subset of the mesh you want to add, or null for the complete mesh.
 
ignoreTransformations:Boolean (default = false) — when enabled, the mesh's vertices will be added without transforming them in any way (no matter the value of the matrix parameter).

canAddMesh()method 
public function canAddMesh(mesh:Mesh, numVertices:int = -1):Boolean

Indicates if the given mesh instance fits to the current state of the batch. Will always return true for the first added mesh; later calls will check if the style matches and if the maximum number of vertices is not exceeded.

Parameters

mesh:Mesh — the mesh to add to the batch.
 
numVertices:int (default = -1) — if -1, mesh.numVertices will be used

Returns
Boolean
clear()method 
public function clear():void

Removes all geometry.

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

Disposes all resources of the display object. GPU buffers are released, event listeners are removed, filters and masks are disposed.

render()method 
override public function render(painter:Painter):void

If the batchable property is enabled, this method will add the batch to the painter's current batch. Otherwise, this will actually do the drawing.

Parameters

painter:Painter

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

This method must be called whenever the mesh's index data was changed. Makes sure that the index buffer is synchronized before rendering, and forces a redraw.

setStyle()method 
override public function setStyle(meshStyle:MeshStyle = null, mergeWithPredecessor:Boolean = true):void

Sets the style that is used to render the mesh. Styles (which are always subclasses of MeshStyle) provide a means to completely modify the way a mesh is rendered. For example, they may add support for color transformations or normal mapping.

When assigning a new style, the vertex format will be changed to fit it. Do not use the same style instance on multiple objects! Instead, make use of style.clone() to assign an identical style to multiple meshes.

Parameters

meshStyle:MeshStyle (default = null) — the style to assign. If null, the default style will be created.
 
mergeWithPredecessor:Boolean (default = true) — if enabled, all attributes of the previous style will be be copied to the new one, if possible.

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

This method must be called whenever the mesh's vertex data was changed. Makes sure that the vertex buffer is synchronized before rendering, and forces a redraw.

Constant Detail
MAX_NUM_VERTICESConstant
public static const MAX_NUM_VERTICES:int = 65535

The maximum number of vertices that fit into one MeshBatch.