| Package | starling.display |
| Class | public class MeshBatch |
| Inheritance | MeshBatch  Mesh DisplayObject EventDispatcher Object |
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
| 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 this object will be added to the painter's batch on rendering,
or if it will draw itself right away. | MeshBatch | ||
| 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 | |
| color : uint Changes the color of all vertices to the same value. | Mesh | |
| defaultStyle : Class [static] The default style used for meshes if no specific style is provided. | Mesh | |
| defaultStyleFactory : Function [static] A factory method that is used to create the 'MeshStyle' for a mesh if no specific
style is provided. | Mesh | |
| filter : FragmentFilter The filter that is attached to the display object. | 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 | |
| maskInverted : Boolean Indicates if the masked region of this object is set to be inverted. | DisplayObject | |
| name : String The name of the display object (default: null). | DisplayObject | |
| numIndices : int The total number of indices in the mesh. | MeshBatch | ||
| numTriangles : int [read-only] The total number of triangles in this mesh. | Mesh | |
| numVertices : int The total number of vertices in the mesh. | MeshBatch | ||
| 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 | |
| pixelSnapping : Boolean Controls whether or not the instance snaps to the nearest pixel. | Mesh | |
| requiresRedraw : Boolean [read-only] Indicates if the object needs to be redrawn in the upcoming frame, i.e. | 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 | |
| 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 | |
| stage : Stage [read-only] The stage the display object is connected to, or null if it is not connected
to the stage. | DisplayObject | |
| style : MeshStyle The style that is used to render the mesh. | Mesh | |
| texture : Texture The texture that is mapped to the mesh (or null, if there is none). | Mesh | |
| textureRepeat : Boolean Indicates if pixels at the edges will be repeated or clamped. | Mesh | |
| textureSmoothing : String The smoothing filter that is used for the texture. | Mesh | |
| 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 | |
| vertexFormat : VertexDataFormat [read-only] The format used to store the vertices. | Mesh | |
| 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, empty MeshBatch instance. | MeshBatch | ||
| 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 | ||
| 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 | ||
| [static] Creates a new instance of the current default MeshStyle. | Mesh | |
| 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 all resources of the display object. | MeshBatch | ||
| drawToBitmapData(out:BitmapData = null, color:uint = 0x0, alpha:Number = 0.0):BitmapData Draws the object into a BitmapData object. | DisplayObject | |
| [static] Creates a mesh from the specified polygon. | Mesh | |
| getBounds(targetSpace:DisplayObject, out:Rectangle = null):Rectangle [override] Returns a rectangle that completely encloses the object as it appears in another
coordinate system. | Mesh | |
| getTexCoords(vertexID:int, out:Point = null):Point Returns the texture coordinates of the vertex at the specified index. | Mesh | |
| getTransformationMatrix(targetSpace:DisplayObject, out:Matrix = null):Matrix Creates a matrix that represents the transformation from the local coordinate system
to another. | DisplayObject | |
| getTransformationMatrix3D(targetSpace:DisplayObject, out:Matrix3D = null):Matrix3D Creates a matrix that represents the transformation from the local coordinate system
to another. | DisplayObject | |
| getVertexAlpha(vertexID:int):Number Returns the alpha value of the vertex at the specified index. | Mesh | |
| getVertexColor(vertexID:int):uint Returns the RGB color of the vertex at the specified index. | Mesh | |
| getVertexPosition(vertexID:int, out:Point = null):Point The position of the vertex at the specified index, in the mesh's local coordinate
system. | Mesh | |
| globalToLocal(globalPoint:Point, out:Point = null):Point Transforms a point from global (stage) coordinates to the local coordinate system. | DisplayObject | |
| globalToLocal3D(globalPoint:Point, out:Vector3D = null):Vector3D Transforms a point from global (stage) coordinates to the 3D local coordinate system. | DisplayObject | |
| 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 | |
| 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 | |
| hitTestMask(localPoint:Point):Boolean Checks if a certain point is inside the display object's mask. | DisplayObject | |
| local3DToGlobal(localPoint:Vector3D, out:Point = null):Point Transforms a 3D point from the local coordinate system to global (stage) coordinates. | DisplayObject | |
| localToGlobal(localPoint:Point, out:Point = null):Point Transforms a point from the local coordinate system to global (stage) coordinates. | DisplayObject | |
| 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 | |
[override] If the batchable property is enabled, this method will add the batch
to the painter's current batch. | MeshBatch | ||
setIndexDataChanged():void [override] This method must be called whenever the mesh's index data was changed. | MeshBatch | ||
| setRequiresRedraw():void Forces the object to be redrawn in the next frame. | DisplayObject | |
[override] Sets the style that is used to render the mesh. | MeshBatch | ||
| setTexCoords(vertexID:int, u:Number, v:Number):void Sets the texture coordinates of the vertex at the specified index to the given values. | Mesh | |
| setVertexAlpha(vertexID:int, alpha:Number):void Sets the alpha value of the vertex at the specified index to a certain value. | Mesh | |
| setVertexColor(vertexID:int, color:uint):void Sets the RGB color of the vertex at the specified index to a certain value. | Mesh | |
setVertexDataChanged():void [override] This method must be called whenever the mesh's vertex data was changed. | MeshBatch | ||
| setVertexPosition(vertexID:int, x:Number, y:Number):void | Mesh | |
| Constant | Defined By | ||
|---|---|---|---|
| MAX_NUM_VERTICES : int = 65535 [static] The maximum number of vertices that fit into one MeshBatch. | MeshBatch | ||
| batchable | property |
Hide Inherited Public Properties
Show Inherited Public Propertiesbatchable:BooleanIndicates 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.
public function get batchable():Boolean public function set batchable(value:Boolean):void| numIndices | property |
numIndices:intThe 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!
public function get numIndices():int public function set numIndices(value:int):void| numVertices | property |
numVertices:intThe 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!
public function get numVertices():int public function set numVertices(value:int):void| MeshBatch | () | Constructor |
public function MeshBatch()Creates a new, empty MeshBatch instance.
| addMesh | () | method |
public function addMesh(mesh:Mesh, matrix:Matrix = null, alpha:Number = 1.0, subset:MeshSubset = null, ignoreTransformations:Boolean = false):voidAdds 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)mesh.transformationMatrix
will be used instead (except if the last parameter is enabled).
| |
alpha:Number (default = 1.0) | |
subset:MeshSubset (default = null)null for
the complete mesh.
| |
ignoreTransformations:Boolean (default = false)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):voidAdds 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) | |
vertexID:int (default = -1) | |
matrix:Matrix (default = null)mesh.transformationMatrix
will be used instead (except if the last parameter is enabled).
| |
alpha:Number (default = 1.0) | |
subset:MeshSubset (default = null)null for
the complete mesh.
| |
ignoreTransformations:Boolean (default = false)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)-1, mesh.numVertices will be used
|
Boolean |
| clear | () | method |
public function clear():voidRemoves all geometry.
| dispose | () | method |
override public function dispose():voidDisposes 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():voidThis 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)null, the default
style will be created.
| |
mergeWithPredecessor:Boolean (default = true) |
| setVertexDataChanged | () | method |
override public function setVertexDataChanged():voidThis 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.
| MAX_NUM_VERTICES | Constant |
public static const MAX_NUM_VERTICES:int = 65535The maximum number of vertices that fit into one MeshBatch.