javax.microedition.m3g
Class Mesh

java.lang.Object
  javax.microedition.m3g.Object3D
      javax.microedition.m3g.Transformable
          javax.microedition.m3g.Node
              javax.microedition.m3g.Mesh

Direct Known Subclasses:

MorphingMesh, SkinnedMesh

public class Mesh

extends Node

A scene graph node that represents a 3D object defined as a polygonal surface.

This class represents a conventional rigid body mesh, while the derived classes MorphingMesh and SkinnedMesh extend it with capabilities to transform vertices independently of each other. The structure of a basic Mesh is shown in the figure below.

A Mesh is composed of one or more submeshes and their associated Appearances. A submesh is an array of triangle strips defined by an IndexBuffer object. The triangle strips are formed by indexing the vertex coordinates and other vertex attributes in an associated VertexBuffer. All submeshes in a Mesh share the same VertexBuffer. However, in the case of a MorphingMesh, a weighted linear combination of multiple VertexBuffers is used in place of a single VertexBuffer.

Submeshes within a Mesh are rendered in the order of ascending Appearance layers, and such that opaque submeshes are rendered before transparent submeshes on the same layer. See the setLayer method in Appearance for more discussion on layered rendering.

Rendering and picking of a submesh is disabled if its Appearance is null.

Deferred exceptions

An exception is thrown if the VertexBuffer or any of the IndexBuffers are in an invalid state when rendering or picking; see the respective class descriptions for more information. Note that it would be useless to check for these exception cases at construction time, because the application may freely change the contents of a VertexBuffer or an Appearance at any time. However, null IndexBuffers and VertexBuffers are blocked at the constructor, as usual, because the application is not able to change them afterwards.

See Also:

Binary format, VertexBuffer, IndexBuffer

Field Summary

Fields inherited from class javax.microedition.m3g.Node

NONE, ORIGIN, X_AXIS, Y_AXIS, Z_AXIS

Constructor Summary

Mesh(VertexBuffer vertices, IndexBuffer[] submeshes, Appearance[] appearances)
Constructs a new Mesh with the given VertexBuffer and submeshes.

Mesh(VertexBuffer vertices, IndexBuffer submesh, Appearance appearance)
Constructs a new Mesh consisting of only one submesh.

Method Summary

Appearance	getAppearance(int index) Gets the current Appearance of the specified submesh.
IndexBuffer	getIndexBuffer(int index) Retrieves the submesh at the given index.
int	getSubmeshCount() Gets the number of submeshes in this Mesh.
VertexBuffer	getVertexBuffer() Gets the vertex buffer of this Mesh.
void	setAppearance(int index, Appearance appearance) Sets the Appearance for the specified submesh.

Methods inherited from class javax.microedition.m3g.Node

align, getAlignmentReference, getAlignmentTarget, getAlphaFactor, getParent, getScope, getTransformTo, isPickingEnabled, isRenderingEnabled, setAlignment, setAlphaFactor, setPickingEnable, setRenderingEnable, setScope

Methods inherited from class javax.microedition.m3g.Transformable

getCompositeTransform, getOrientation, getScale, getTransform, getTranslation, postRotate, preRotate, scale, setOrientation, setScale, setTransform, setTranslation, translate

Methods inherited from class javax.microedition.m3g.Object3D

addAnimationTrack, animate, duplicate, find, getAnimationTrack, getAnimationTrackCount, getReferences, getUserID, getUserObject, removeAnimationTrack, setUserID, setUserObject

Constructor Detail

Mesh

public Mesh(VertexBuffer vertices,
            IndexBuffer submesh,
            Appearance appearance)

Constructs a new Mesh consisting of only one submesh. Rendering and picking of the Mesh is initially disabled if the Appearance is set to null.

Parameters:

vertices - a VertexBuffer to use for this mesh

submesh - an IndexBuffer defining the triangle strips to draw

appearance - an Appearance to use for this mesh, or null

Throws:

java.lang.NullPointerException - if vertices is null

java.lang.NullPointerException - if submesh is null

Mesh

public Mesh(VertexBuffer vertices,
            IndexBuffer[] submeshes,
            Appearance[] appearances)

Constructs a new Mesh with the given VertexBuffer and submeshes. The number of submeshes is set equal to the length of the submeshes array. The appearances array is parallel to that, and must have at least as many elements. A null Appearance disables rendering and picking of the corresponding submesh. If the array itself is null, all appearances are initialized to null.

Parameters:

vertices - a VertexBuffer to use for all submeshes in this mesh

submeshes - an IndexBuffer array defining the submeshes to draw

appearances - an Appearance array parallel to submeshes, or null

Throws:

java.lang.NullPointerException - if vertices is null

java.lang.NullPointerException - if submeshes is null

java.lang.NullPointerException - if any element in submeshes is null

java.lang.IllegalArgumentException - if submeshes is empty

java.lang.IllegalArgumentException - if (appearances != null) && (appearances.length < submeshes.length)

Method Detail

setAppearance

public void setAppearance(int index,
                          Appearance appearance)

Sets the Appearance for the specified submesh.

Parameters:

index - index of the submesh to set the Appearance of

appearance - Appearance to set for the submesh at index, or null to disable the submesh

Throws:

java.lang.IndexOutOfBoundsException - if (index < 0) || (index >= getSubmeshCount)

See Also:

getAppearance

getAppearance

public Appearance getAppearance(int index)

Gets the current Appearance of the specified submesh.

Parameters:

index - index of the submesh to get the Appearance of

Returns:

current Appearance of the submesh at index

Throws:

java.lang.IndexOutOfBoundsException - if (index < 0) || (index >= getSubmeshCount)

See Also:

setAppearance

getIndexBuffer

public IndexBuffer getIndexBuffer(int index)

Retrieves the submesh at the given index.

Parameters:

index - index of the submesh to get

Returns:

current IndexBuffer at index

Throws:

java.lang.IndexOutOfBoundsException - if (index < 0) || (index >= getSubmeshCount)

getVertexBuffer

public VertexBuffer getVertexBuffer()

Gets the vertex buffer of this Mesh. This is always the original VertexBuffer that was supplied at construction. The VertexBuffer is never written to by the implementation. Specifically, the results of morphing (MorphingMesh) and skinning (SkinnedMesh) are not written to the VertexBuffer, nor are they exposed to the application by any other means.

In the case of a MorphingMesh, this VertexBuffer represents the base mesh. The morph target VertexBuffers can be retrieved with the getMorphTarget method in MorphingMesh.

Returns:

the (base) VertexBuffer of this Mesh

getSubmeshCount

public int getSubmeshCount()

Gets the number of submeshes in this Mesh. This is always at least 1.

Returns:

the number of submeshes in this Mesh