libgdx API

com.badlogic.gdx.graphics
Class Mesh

java.lang.Object
  extended by com.badlogic.gdx.graphics.Mesh
All Implemented Interfaces:
Disposable

public class Mesh
extends java.lang.Object
implements Disposable

A Mesh holds vertices composed of attributes specified by a VertexAttributes instance. The vertices are held either in VRAM in form of vertex buffer objects or in RAM in form of vertex arrays. The former variant is more performant and is prefered over vertex arrays if hardware supports it.

Meshes are automatically managed. If the OpenGL context is lost all vertex buffer objects get invalidated and must be reloaded when the context is recreated. This only happens on Android when a user switches to another application or receives an incoming call. A managed Mesh will be reloaded automagically so you don't have to do this manually.

A Mesh consists of vertices and optionally indices which specify which vertices define a triangle. Each vertex is composed of attributes such as position, normal, color or texture coordinate. Note that not all of this attributes must be given, except for position which is non-optional. Each attribute has an alias which is used when rendering a Mesh in OpenGL ES 2.0. The alias is used to bind a specific vertex attribute to a shader attribute. The shader source and the alias of the attribute must match exactly for this to work. For OpenGL ES 1.x rendering this aliases are irrelevant.

Meshes can be used with either OpenGL ES 1.x or OpenGL ES 2.0.

Author:
mzechner, Dave Clayton

Nested Class Summary
static class Mesh.VertexDataType
           
 
Field Summary
static boolean forceVBO
          used for benchmarking
 
Constructor Summary
Mesh(boolean isStatic, int maxVertices, int maxIndices, VertexAttribute... attributes)
          Creates a new Mesh with the given attributes.
Mesh(boolean isStatic, int maxVertices, int maxIndices, VertexAttributes attributes)
          Creates a new Mesh with the given attributes.
Mesh(Mesh.VertexDataType type, boolean isStatic, int maxVertices, int maxIndices, VertexAttribute... attributes)
          Creates a new Mesh with the given attributes.
 
Method Summary
 void bind()
          Binds the underlying VertexArray/VertexBufferObject and IndexBufferObject if indices were given.
 void bind(ShaderProgram shader)
          Binds the underlying VertexBufferObject and IndexBufferObject if indices where given.
 BoundingBox calculateBoundingBox()
          Calculates the BoundingBox of the vertices contained in this mesh.
 void calculateBoundingBox(BoundingBox bbox)
          Calculates the BoundingBox of the vertices contained in this mesh.
static void clearAllMeshes(Application app)
          Will clear the managed mesh cache.
 Mesh copy(boolean isStatic)
          Copies this mesh.
 Mesh copy(boolean isStatic, boolean removeDuplicates, int[] usage)
          Copies this mesh optionally removing duplicate vertices and/or reducing the amount of attributes.
static Mesh create(boolean isStatic, Mesh[] meshes)
          Create a new Mesh that is a combination of the supplied meshes.
static Mesh create(boolean isStatic, Mesh[] meshes, Matrix4[] transformations)
          Create a new Mesh that is a combination of the supplied meshes.
static Mesh create(boolean isStatic, Mesh base, Matrix4[] transformations)
          Create a new Mesh that is a combination of transformations of the supplied base mesh.
 void dispose()
          Frees all resources associated with this Mesh
 void getIndices(short[] indices)
          Copies the indices from the Mesh to the short array.
 void getIndices(short[] indices, int destOffset)
          Copies the indices from the Mesh to the short array.
 java.nio.ShortBuffer getIndicesBuffer()
           
static java.lang.String getManagedStatus()
           
 int getMaxIndices()
           
 int getMaxVertices()
           
 int getNumIndices()
           
 int getNumVertices()
           
 VertexAttribute getVertexAttribute(int usage)
          Returns the first VertexAttribute having the given VertexAttributes.Usage.
 VertexAttributes getVertexAttributes()
           
 int getVertexSize()
           
 void getVertices(float[] vertices)
          Copies the vertices from the Mesh to the float array.
 void getVertices(int srcOffset, float[] vertices)
          Copies the the remaining vertices from the Mesh to the float array.
 void getVertices(int srcOffset, int count, float[] vertices)
          Copies the specified vertices from the Mesh to the float array.
 void getVertices(int srcOffset, int count, float[] vertices, int destOffset)
          Copies the specified vertices from the Mesh to the float array.
 java.nio.FloatBuffer getVerticesBuffer()
           
static void invalidateAllMeshes(Application app)
          Invalidates all meshes so the next time they are rendered new VBO handles are generated.
 void render(int primitiveType)
           Renders the mesh using the given primitive type.
 void render(int primitiveType, int offset, int count)
           Renders the mesh using the given primitive type.
 void render(ShaderProgram shader, int primitiveType)
           Renders the mesh using the given primitive type.
 void render(ShaderProgram shader, int primitiveType, int offset, int count)
           Renders the mesh using the given primitive type.
 void scale(float scaleX, float scaleY, float scaleZ)
          Method to scale the positions in the mesh.
 void setAutoBind(boolean autoBind)
          Sets whether to bind the underlying VertexArray or VertexBufferObject automatically on a call to one of the render(int) methods or not.
 void setIndices(short[] indices)
          Sets the indices of this Mesh
 void setIndices(short[] indices, int offset, int count)
          Sets the indices of this Mesh.
 void setVertices(float[] vertices)
          Sets the vertices of this Mesh.
 void setVertices(float[] vertices, int offset, int count)
          Sets the vertices of this Mesh.
 void transform(Matrix4 matrix)
          Method to transform the positions in the mesh.
static void transform(Matrix4 matrix, float[] vertices, int vertexSize, int offset, int dimensions, int start, int count)
          Method to transform the positions in the float array.
protected  void transform(Matrix4 matrix, int start, int count)
           
 void unbind()
          Unbinds the underlying VertexArray/VertexBufferObject and IndexBufferObject is indices were given.
 void unbind(ShaderProgram shader)
          Unbinds the underlying VertexBufferObject and IndexBufferObject is indices were given.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

forceVBO

public static boolean forceVBO
used for benchmarking

Constructor Detail

Mesh

public Mesh(boolean isStatic,
            int maxVertices,
            int maxIndices,
            VertexAttribute... attributes)
Creates a new Mesh with the given attributes.

Parameters:
isStatic - whether this mesh is static or not. Allows for internal optimizations.
maxVertices - the maximum number of vertices this mesh can hold
maxIndices - the maximum number of indices this mesh can hold
attributes - the VertexAttributes. Each vertex attribute defines one property of a vertex such as position, normal or texture coordinate

Mesh

public Mesh(boolean isStatic,
            int maxVertices,
            int maxIndices,
            VertexAttributes attributes)
Creates a new Mesh with the given attributes.

Parameters:
isStatic - whether this mesh is static or not. Allows for internal optimizations.
maxVertices - the maximum number of vertices this mesh can hold
maxIndices - the maximum number of indices this mesh can hold
attributes - the VertexAttributes. Each vertex attribute defines one property of a vertex such as position, normal or texture coordinate

Mesh

public Mesh(Mesh.VertexDataType type,
            boolean isStatic,
            int maxVertices,
            int maxIndices,
            VertexAttribute... attributes)
Creates a new Mesh with the given attributes. This is an expert method with no error checking. Use at your own risk.

Parameters:
type - the Mesh.VertexDataType to be used, VBO or VA.
isStatic - whether this mesh is static or not. Allows for internal optimizations.
maxVertices - the maximum number of vertices this mesh can hold
maxIndices - the maximum number of indices this mesh can hold
attributes - the VertexAttributes. Each vertex attribute defines one property of a vertex such as position, normal or texture coordinate
Method Detail

create

public static Mesh create(boolean isStatic,
                          Mesh base,
                          Matrix4[] transformations)
Create a new Mesh that is a combination of transformations of the supplied base mesh. Not all primitive types, like line strip and triangle strip, can be combined.

Parameters:
isStatic - whether this mesh is static or not. Allows for internal optimizations.
transformations - the transformations to apply to the meshes
Returns:
the combined mesh

create

public static Mesh create(boolean isStatic,
                          Mesh[] meshes)
Create a new Mesh that is a combination of the supplied meshes. The meshes must have the same VertexAttributes signature. Not all primitive types, like line strip and triangle strip, can be combined.

Parameters:
isStatic - whether this mesh is static or not. Allows for internal optimizations.
meshes - the meshes to combine
Returns:
the combined mesh

create

public static Mesh create(boolean isStatic,
                          Mesh[] meshes,
                          Matrix4[] transformations)
Create a new Mesh that is a combination of the supplied meshes. The meshes must have the same VertexAttributes signature. If transformations is supplied, it must have the same length as meshes. Not all primitive types, like line strip and triangle strip, can be combined.

Parameters:
isStatic - whether this mesh is static or not. Allows for internal optimizations.
meshes - the meshes to combine
transformations - the transformations to apply to the meshes
Returns:
the combined mesh

setVertices

public void setVertices(float[] vertices)
Sets the vertices of this Mesh. The attributes are assumed to be given in float format. If this mesh is configured to use fixed point an IllegalArgumentException will be thrown.

Parameters:
vertices - the vertices.

setVertices

public void setVertices(float[] vertices,
                        int offset,
                        int count)
Sets the vertices of this Mesh. The attributes are assumed to be given in float format. If this mesh is configured to use fixed point an IllegalArgumentException will be thrown.

Parameters:
vertices - the vertices.
offset - the offset into the vertices array
count - the number of floats to use

getVertices

public void getVertices(float[] vertices)
Copies the vertices from the Mesh to the float array. The float array must be large enough to hold all the Mesh's vertices.

Parameters:
vertices - the array to copy the vertices to

getVertices

public void getVertices(int srcOffset,
                        float[] vertices)
Copies the the remaining vertices from the Mesh to the float array. The float array must be large enough to hold the remaining vertices.

Parameters:
srcOffset - the offset (in number of floats) of the vertices in the mesh to copy
vertices - the array to copy the vertices to

getVertices

public void getVertices(int srcOffset,
                        int count,
                        float[] vertices)
Copies the specified vertices from the Mesh to the float array. The float array must be large enough to hold count vertices.

Parameters:
srcOffset - the offset (in number of floats) of the vertices in the mesh to copy
count - the amount of floats to copy
vertices - the array to copy the vertices to

getVertices

public void getVertices(int srcOffset,
                        int count,
                        float[] vertices,
                        int destOffset)
Copies the specified vertices from the Mesh to the float array. The float array must be large enough to hold destOffset+count vertices.

Parameters:
srcOffset - the offset (in number of floats) of the vertices in the mesh to copy
count - the amount of floats to copy
vertices - the array to copy the vertices to
destOffset - the offset (in floats) in the vertices array to start copying

setIndices

public void setIndices(short[] indices)
Sets the indices of this Mesh

Parameters:
indices - the indices

setIndices

public void setIndices(short[] indices,
                       int offset,
                       int count)
Sets the indices of this Mesh.

Parameters:
indices - the indices
offset - the offset into the indices array
count - the number of indices to copy

getIndices

public void getIndices(short[] indices)
Copies the indices from the Mesh to the short array. The short array must be large enough to hold all the Mesh's indices.

Parameters:
indices - the array to copy the indices to

getIndices

public void getIndices(short[] indices,
                       int destOffset)
Copies the indices from the Mesh to the short array. The short array must be large enough to hold destOffset + all the Mesh's indices.

Parameters:
indices - the array to copy the indices to
destOffset - the offset in the indices array to start copying

getNumIndices

public int getNumIndices()
Returns:
the number of defined indices

getNumVertices

public int getNumVertices()
Returns:
the number of defined vertices

getMaxVertices

public int getMaxVertices()
Returns:
the maximum number of vertices this mesh can hold

getMaxIndices

public int getMaxIndices()
Returns:
the maximum number of indices this mesh can hold

getVertexSize

public int getVertexSize()
Returns:
the size of a single vertex in bytes

setAutoBind

public void setAutoBind(boolean autoBind)
Sets whether to bind the underlying VertexArray or VertexBufferObject automatically on a call to one of the render(int) methods or not. Usually you want to use autobind. Manual binding is an expert functionality. There is a driver bug on the MSM720xa chips that will fuck up memory if you manipulate the vertices and indices of a Mesh multiple times while it is bound. Keep this in mind.

Parameters:
autoBind - whether to autobind meshes.

bind

public void bind()
Binds the underlying VertexArray/VertexBufferObject and IndexBufferObject if indices were given. Use this with OpenGL ES 1.x and when auto-bind is disabled.


unbind

public void unbind()
Unbinds the underlying VertexArray/VertexBufferObject and IndexBufferObject is indices were given. Use this with OpenGL ES 1.x and when auto-bind is disabled.


bind

public void bind(ShaderProgram shader)
Binds the underlying VertexBufferObject and IndexBufferObject if indices where given. Use this with OpenGL ES 2.0 and when auto-bind is disabled.

Parameters:
shader - the shader (does not bind the shader)

unbind

public void unbind(ShaderProgram shader)
Unbinds the underlying VertexBufferObject and IndexBufferObject is indices were given. Use this with OpenGL ES 1.x and when auto-bind is disabled.

Parameters:
shader - the shader (does not unbind the shader)

render

public void render(int primitiveType)

Renders the mesh using the given primitive type. If indices are set for this mesh then getNumIndices() / #vertices per primitive primitives are rendered. If no indices are set then getNumVertices() / #vertices per primitive are rendered.

This method is intended for use with OpenGL ES 1.x and will throw an IllegalStateException when OpenGL ES 2.0 is used.

Parameters:
primitiveType - the primitive type

render

public void render(int primitiveType,
                   int offset,
                   int count)

Renders the mesh using the given primitive type. offset specifies the offset into vertex buffer and is ignored for the index buffer. Count specifies the number of vertices or indices to use thus count / #vertices per primitive primitives are rendered.

This method is intended for use with OpenGL ES 1.x and will throw an IllegalStateException when OpenGL ES 2.0 is used.

Parameters:
primitiveType - the primitive type
offset - the offset into the vertex buffer, ignored for indexed rendering
count - number of vertices or indices to use

render

public void render(ShaderProgram shader,
                   int primitiveType)

Renders the mesh using the given primitive type. If indices are set for this mesh then getNumIndices() / #vertices per primitive primitives are rendered. If no indices are set then getNumVertices() / #vertices per primitive are rendered.

This method will automatically bind each vertex attribute as specified at construction time via VertexAttributes to the respective shader attributes. The binding is based on the alias defined for each VertexAttribute.

This method must only be called after the ShaderProgram.begin() method has been called!

This method is intended for use with OpenGL ES 2.0 and will throw an IllegalStateException when OpenGL ES 1.x is used.

Parameters:
primitiveType - the primitive type

render

public void render(ShaderProgram shader,
                   int primitiveType,
                   int offset,
                   int count)

Renders the mesh using the given primitive type. offset specifies the offset into either the vertex buffer or the index buffer depending on whether indices are defined. count specifies the number of vertices or indices to use thus count / #vertices per primitive primitives are rendered.

This method will automatically bind each vertex attribute as specified at construction time via VertexAttributes to the respective shader attributes. The binding is based on the alias defined for each VertexAttribute.

This method must only be called after the ShaderProgram.begin() method has been called!

This method is intended for use with OpenGL ES 2.0 and will throw an IllegalStateException when OpenGL ES 1.x is used.

Parameters:
shader - the shader to be used
primitiveType - the primitive type
offset - the offset into the vertex or index buffer
count - number of vertices or indices to use

dispose

public void dispose()
Frees all resources associated with this Mesh

Specified by:
dispose in interface Disposable

getVertexAttribute

public VertexAttribute getVertexAttribute(int usage)
Returns the first VertexAttribute having the given VertexAttributes.Usage.

Parameters:
usage - the Usage.
Returns:
the VertexAttribute or null if no attribute with that usage was found.

getVertexAttributes

public VertexAttributes getVertexAttributes()
Returns:
the vertex attributes of this Mesh

getVerticesBuffer

public java.nio.FloatBuffer getVerticesBuffer()
Returns:
the backing FloatBuffer holding the vertices. Does not have to be a direct buffer on Android!

calculateBoundingBox

public BoundingBox calculateBoundingBox()
Calculates the BoundingBox of the vertices contained in this mesh. In case no vertices are defined yet a GdxRuntimeException is thrown. This method creates a new BoundingBox instance.

Returns:
the bounding box.

calculateBoundingBox

public void calculateBoundingBox(BoundingBox bbox)
Calculates the BoundingBox of the vertices contained in this mesh. In case no vertices are defined yet a GdxRuntimeException is thrown.

Parameters:
bbox - the bounding box to store the result in.

getIndicesBuffer

public java.nio.ShortBuffer getIndicesBuffer()
Returns:
the backing shortbuffer holding the indices. Does not have to be a direct buffer on Android!

invalidateAllMeshes

public static void invalidateAllMeshes(Application app)
Invalidates all meshes so the next time they are rendered new VBO handles are generated.

Parameters:
app -

clearAllMeshes

public static void clearAllMeshes(Application app)
Will clear the managed mesh cache. I wouldn't use this if i was you :)


getManagedStatus

public static java.lang.String getManagedStatus()

scale

public void scale(float scaleX,
                  float scaleY,
                  float scaleZ)
Method to scale the positions in the mesh. Normals will be kept as is. This is a potentially slow operation, use with care. It will also create a temporary float[] which will be garbage collected.

Parameters:
scaleX - scale on x
scaleY - scale on y
scaleZ - scale on z

transform

public void transform(Matrix4 matrix)
Method to transform the positions in the mesh. Normals will be kept as is. This is a potentially slow operation, use with care. It will also create a temporary float[] which will be garbage collected.

Parameters:
matrix - the transformation matrix

transform

protected void transform(Matrix4 matrix,
                         int start,
                         int count)

transform

public static void transform(Matrix4 matrix,
                             float[] vertices,
                             int vertexSize,
                             int offset,
                             int dimensions,
                             int start,
                             int count)
Method to transform the positions in the float array. Normals will be kept as is. This is a potentially slow operation, use with care.

Parameters:
matrix - the transformation matrix
vertices - the float array
vertexSize - the number of floats in each vertex
offset - the offset within a vertex to the position
dimensions - the size of the position
start - the vertex to start with
count - the amount of vertices to transform

copy

public Mesh copy(boolean isStatic,
                 boolean removeDuplicates,
                 int[] usage)
Copies this mesh optionally removing duplicate vertices and/or reducing the amount of attributes.

Parameters:
isStatic - whether the new mesh is static or not. Allows for internal optimizations.
removeDuplicates - whether to remove duplicate vertices if possible. Only the vertices specified by usage are checked.
usage - which attributes (if available) to copy
Returns:
the copy of this mesh

copy

public Mesh copy(boolean isStatic)
Copies this mesh.

Parameters:
isStatic - whether the new mesh is static or not. Allows for internal optimizations.
Returns:
the copy of this mesh

libgdx API

Copyright 2010 Mario Zechner (contact@badlogicgames.com), Nathan Sweet (admin@esotericsoftware.com)