Package arc.graphics

Class Mesh

java.lang.Object
arc.graphics.Mesh
All Implemented Interfaces:
Disposable
public class Mesh extends Object implements Disposable

A Mesh holds vertices composed of attributes specified by an array of VertexAttribute instances. 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 preferred 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.

  • Field Details

    • vertexSize

      public final int vertexSize
      The size of one vertex, in bytes.

    • attributes

      public final VertexAttribute[] attributes
      Do not modify.

    • vertices

      public final VertexData vertices

    • indices

      public final IndexData indices

  • Constructor Details

    • 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 useVertexArray, 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:
      useVertexArray - whether to use VBOs or VAOs. Note that the latter is not supported with OpenGL 3.0.
      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

  • Method Details

    • setVertices

      public Mesh setVertices(float[] vertices)
      Sets the vertices of this Mesh. The attributes are assumed to be given in float format.
      Parameters:
      vertices - the vertices.
      Returns:
      the mesh for invocation chaining.

    • setVertices

      public Mesh setVertices(float[] vertices, int offset, int count)
      Sets the vertices of this Mesh. The attributes are assumed to be given in float format.
      Parameters:
      vertices - the vertices.
      offset - the offset into the vertices array
      count - the number of floats to use
      Returns:
      the mesh for invocation chaining.

    • updateVertices

      public Mesh updateVertices(int targetOffset, float[] source)
      Update (a portion of) the vertices. Does not resize the backing buffer.
      Parameters:
      targetOffset - the offset in number of floats of the mesh part.
      source - the vertex data to update the mesh part with

    • updateVertices

      public Mesh updateVertices(int targetOffset, float[] source, int sourceOffset, int count)
      Update (a portion of) the vertices. Does not resize the backing buffer.
      Parameters:
      targetOffset - the offset in number of floats of the mesh part.
      source - the vertex data to update the mesh part with
      sourceOffset - the offset in number of floats within the source array
      count - the number of floats to update

    • setIndices

      public Mesh setIndices(short[] indices)
      Sets the indices of this Mesh
      Parameters:
      indices - the indices
      Returns:
      the mesh for invocation chaining.

    • setIndices

      public Mesh 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
      Returns:
      the mesh for invocation chaining.

    • 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

    • getIndices

      public void getIndices(int srcOffset, short[] indices, int destOffset)
      Copies the remaining indices from the Mesh to the short array. The short array must be large enough to hold destOffset + all the remaining indices.
      Parameters:
      srcOffset - the zero-based offset of the first index to fetch
      indices - the array to copy the indices to
      destOffset - the offset in the indices array to start copying

    • getIndices

      public void getIndices(int srcOffset, int count, short[] indices, int destOffset)
      Copies the indices from the Mesh to the short array. The short array must be large enough to hold destOffset + count indices.
      Parameters:
      srcOffset - the zero-based offset of the first index to fetch
      count - the total amount of indices to copy
      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 methods. Usually you want to use autobind. Manual binding is an expert functionality.
      Parameters:
      autoBind - whether to autobind meshes.

    • bind

      public void bind(Shader 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(Shader 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(Shader shader, int primitiveType)
      See Also:

    • render

      public void render(Shader shader, int primitiveType, int offset, int count)
      See Also:

    • render

      public void render(Shader shader, int primitiveType, int offset, int count, boolean autoBind)

      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 to the respective shader attributes. The binding is based on the alias defined for each VertexAttribute.

      This method must only be called after the Shader.bind() 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
      autoBind - overrides the autoBind member of this Mesh

    • dispose

      public void dispose()
      Frees all resources associated with this Mesh
      Specified by:
      dispose in interface Disposable

    • getVerticesBuffer

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

    • getIndicesBuffer

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