javax.microedition.m3d
Class MorphingMesh

java.lang.Object
  |
  +--javax.microedition.m3d.Object3D
        |
        +--javax.microedition.m3d.Node
              |
              +--javax.microedition.m3d.Mesh
                    |
                    +--javax.microedition.m3d.MorphingMesh

public class MorphingMesh

extends Mesh

A vertex morphing mesh. MorphingMesh is equivalent to an ordinary Mesh, except that the vertices that are rendered are computed as a weighted linear combination of a base VertexBuffer and a number of morph target VertexBuffers. All morph targets must have the same subset of vertex attributes of the base mesh: the same type of arrays, the same number of vertices in the arrays, the same number of components per vertex, and the same component size. Attributes that are not morphed are taken as-is from the base mesh.

The structure of a MorphingMesh object is shown in the figure below.

Vertex morphing

Denoting the base mesh with B, the morph targets with T_i, and the weights corresponding to the morph targets with w_i, the resultant mesh R is computed as follows:

R = B + sum[ (Ti - B) × wi ]

The scale and bias of vertex positions and texture coordinates in morph targets are ignored. The scale and bias of the resultant mesh are taken from the base mesh as such, without any interpolation. Correct interpolation between (integer) values that are in different (floating point) scales would require the values to be first multiplied with the scale factor, and only then interpolated. This involves several floating point operations per value, which would make morphing of anything but the most trivial meshes prohibitively expensive on current mobile hardware. Note that interpolating the scale terms separately from the values would yield results that lie outside the convex hull of the interpolants, which is not a desirable effect.

Deferred exceptions

Any special cases and exceptions that are defined for Mesh also apply for MorphingMesh. An extra exception case is introduced due to the requirement that morph targets must be "subsets" of the base mesh, and that they must all have the same set of vertex attributes with the same dimensions, as specified above. This requirement cannot be enforced until when the morphing is actually done, that is, when rendering or picking.

See Also:

Binary format

Field Summary

Fields inherited from class javax.microedition.m3d.Node

NONE, ORIGIN, X_AXIS, Y_AXIS, Z_AXIS

Fields inherited from class javax.microedition.m3d.Object3D

userObject

Constructor Summary

MorphingMesh(VertexBuffer base, VertexBuffer[] targets, IndexBuffer[] triangles, Appearance[] appearances)
Constructs a new MorphingMesh with specified base mesh, morph targets, and submeshes.

MorphingMesh(VertexBuffer base, VertexBuffer[] targets, IndexBuffer triangles, Appearance appearance)
Constructs a new MorphingMesh with specified base mesh and morph targets.

Method Summary

VertexBuffer	getMorphTarget(int index) Returns the morph target VertexBuffer at the given index.
int	getMorphTargetCount() Returns the number of morph targets in this MorphingMesh.
void	getWeights(float[] weights) Gets the current morph target weights for this mesh.
void	setWeights(float[] weights) Sets the weights for all morph targets in this mesh.

Methods inherited from class javax.microedition.m3d.Mesh

getAppearance, getIndexBuffer, getSubmeshCount, getVertexBuffer, setAppearance

Methods inherited from class javax.microedition.m3d.Node

getAlphaFactor, getOrientation, getParent, getScale, getScopeID, getTransform, getTransformTo, getTranslation, isEnabled, setAlignment, setAlphaFactor, setEnable, setOrientation, setScale, setScopeID, setTransform, setTranslation

Methods inherited from class javax.microedition.m3d.Object3D

addAnimationTrack, animate, clone, find, getAnimationTrack, getAnimationTrackCount, getReferences, getUserID, removeAnimationTrack, setUserID

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

MorphingMesh

public MorphingMesh(VertexBuffer base,
                    VertexBuffer[] targets,
                    IndexBuffer triangles,
                    Appearance appearance)

Constructs a new MorphingMesh with specified base mesh and morph targets. The morph target weights are initially set to zero, meaning that the resultant mesh is equal to the base mesh.

The constructed MorphingMesh has only one submesh that is common to the base mesh and all morph targets. In other words, triangle connectivity and appearance cannot be morphed.

Parameters:

base - a VertexBuffer representing the base mesh

targets - a VertexBuffer array representing the morph targets

triangles - an IndexBuffer defining the triangle strips to draw

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

MorphingMesh

public MorphingMesh(VertexBuffer base,
                    VertexBuffer[] targets,
                    IndexBuffer[] triangles,
                    Appearance[] appearances)

Constructs a new MorphingMesh with specified base mesh, morph targets, and submeshes. The morph target weights are initially set to zero, meaning that the resultant mesh is equal to the base mesh.

The number of submeshes is set equal to the length of triangles. The appearances array is parallel to that, and must have at least as many elements. Alternatively, it may be null, in which case all the Appearances are initialized to null.

The submeshes are common to the base mesh and all morph targets. In other words, triangle connectivity and appearance cannot be morphed.

Parameters:

base - a VertexBuffer representing the base mesh

targets - a VertexBuffer array representing the morph targets

triangles - an IndexBuffer array defining the triangle strips to draw

appearances - an Appearance array parallel to triangles; a null element disables rendering of that submesh, and a null array initializes all appearances to null

Throws:

java.lang.IllegalArgumentException - if targets is empty

java.lang.IllegalArgumentException - if triangles is empty

java.lang.IllegalArgumentException - if appearances.length < triangles.length

Method Detail

getMorphTarget

public VertexBuffer getMorphTarget(int index)

Returns the morph target VertexBuffer at the given index.

Parameters:

index - the index of the morph target to get

Returns:

the VertexBuffer object at index

Throws:

java.lang.IndexOutOfBoundsException - if index is negative or greater than or equal to the number of morph targets in this MorphingMesh

getMorphTargetCount

public int getMorphTargetCount()

Returns the number of morph targets in this MorphingMesh.

Returns:

the number of morph targets

setWeights

public void setWeights(float[] weights)

Sets the weights for all morph targets in this mesh. The weights can have any values, but in the typical case they are set between [0, 1] such that their sum equals 1.0. Implementations are likely to use an optimized morphing routine for this and some other common cases, and a slower generic routine for everything else. Therefore, using weights with magnitudes larger than the typical 1 or 2 might result in a significant performance penalty.

Parameters:

weights - weight factors for all morph targets

Throws:

java.lang.IllegalArgumentException - if weights.length < getMorphTargetCount

See Also:

getWeights

getWeights

public void getWeights(float[] weights)

Gets the current morph target weights for this mesh.

Parameters:

weights - array to be populated with the morph target weights

Throws:

java.lang.IllegalArgumentException - if weights.length < getMorphTargetCount

See Also:

setWeights