com.motorola.iden.micro3d
Class Figure

java.lang.Object
  |
  +--com.motorola.iden.micro3d.Object3D
        |
        +--com.motorola.iden.micro3d.Figure

public class Figure

extends Object3D

Figure contains and manages model data. The Micro3D engine supports .mbac data files that are used to store polygon-based model data.

MOTOROLA and the Stylized M Logo are registered trademarks of Motorola, Inc. Reg. U.S. Pat. & Tm. Off.
© COPYRIGHT 2003-2004 MOTOROLA, Inc. All Rights Reserved.

Method Summary

static Figure	createFigure(byte[] data, int offset, int length) Creates a Figure which is decoded from the data stored in the specified byte array at the specified offset and length.
static Figure	createFigure(java.lang.String name) Creates a Figure from the data obtained from the named resource.
int	getActionIndex() Returns the index of the action this Figure is using for animation.
ActionTable	getActionTable() Returns the ActionTable this Figure is using or null if no ActionTable has been set associated with this Figure.
int	getFrameIndex() Returns the frame index value this Figure is using for animation.
int	getNumberOfPatterns() Returns the number of external appearance states for a Figure.
int	getPattern() Returns the pattern index this Figure is set to.
void	setActionTable(ActionTable actionTable) Sets the ActionTable for this Figure to use.
void	setPattern(int pattern) Modifies the appearance of the figure by setting the pattern used during rendering.
void	setPosture(int actionIndex, int frameIndex) Sets the posture for the Figure.

Methods inherited from class com.motorola.iden.micro3d.Object3D

getLayout, getSphereTexture, getTexture, setLayout, setSphereTexture, setTexture

Methods inherited from class java.lang.Object

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

Method Detail

createFigure

public static Figure createFigure(byte[] data,
                                  int offset,
                                  int length)
                           throws java.lang.NullPointerException,
                                  java.lang.IllegalArgumentException,
                                  java.lang.ArrayIndexOutOfBoundsException,
                                  java.io.IOException

Creates a Figure which is decoded from the data stored in the specified byte array at the specified offset and length. The data must be in the format supported by the implementation (.mbac).

The offset and length parameters specify a range of data within the data byte array. The offset parameter specifies the offset into the array of the first data byte to be used. It must therefore lie within the range [0..(data.length-1)]. The length parameter specifies the number of data bytes to be used. It must be a positive integer and it must not cause the range to extend beyond the end of the array. That is, it must be true that offset + length <= data.length.

This method is intended for use when loading figure data from a variety of sources, such as from persistent storage or from the network.

Parameters:

data - the array of figure data in .mbac format.

offset - the offset of the start of the data in the array.

length - the length of the data in the array.

Returns:

the created figure.

Throws:

java.lang.ArrayIndexOutOfBoundsException - if offset and length specify an invalid range.

java.lang.IllegalArgumentException - if the array does not contain valid figure data.

java.io.IOException - if the data contained cannot be decoded.

java.lang.NullPointerException - if the data array is null.

createFigure

public static Figure createFigure(java.lang.String name)
                           throws java.io.IOException,
                                  java.lang.NullPointerException

Creates a Figure from the data obtained from the named resource. The specified parameter must name a valid resource file containing the .mbac data.

Parameters:

name - the name of the resource containing the animation data in the supported .mbac format.

Returns:

the created figure.

Throws:

java.io.IOException - if the resource does not exist, the data cannot be loaded, or the figure data cannot be decoded.

java.lang.NullPointerException - if the resource name is null.

getActionTable

public ActionTable getActionTable()

Returns the ActionTable this Figure is using or null if no ActionTable has been set associated with this Figure.

Returns:

the ActionTable used for this Figure or null if no ActionTable is associated with this Figure.

setActionTable

public void setActionTable(ActionTable actionTable)

Sets the ActionTable for this Figure to use. If the ActionTable is null the Figure will have its action and frame indices set to 0.

Parameters:

actionTable - the ActionTable to use with this Figure.

getActionIndex

public int getActionIndex()

Returns the index of the action this Figure is using for animation. This method returns 0 if no ActionTable is associated with this Figure.

Returns:

an index to an action within the ActionTable; returns 0 is no ActionTable is associated with this Figure.

getFrameIndex

public int getFrameIndex()

Returns the frame index value this Figure is using for animation. If no ActionTable is set it returns the default value of 0.

Returns:

an index to a frame of action within the ActionTable.

setPosture

public void setPosture(int actionIndex,
                       int frameIndex)
                throws java.lang.IllegalArgumentException

Sets the posture for the Figure.

The posture is obtained from the ActionTable associated with this Figure and the specified frame and action indices. The actionIndex value specified must be equal to or greater than 0 and less than the number of actions returned by getNumberOfActions() for the ActionTable associated with this Figure. The frameIndex value should be at least 0 and less than the number of frames returned by getNumberOfFrames(int) for the ActionTable associated with this Figure and the index value actionIndex. If the frameIndex value is less than 0 it will be adjusted to 0. If the frameIndex value is grater than the maximum number or frames it will be adjusted to the maximum frame number.

Parameters:

actionIndex - the index to the desired action within the ActionTable.

frameIndex - the index of the frame for the action specified.

Throws:

java.lang.IllegalArgumentException - if an invalid action index is specified or if there is no action table associated with the figure.

getNumberOfPatterns

public int getNumberOfPatterns()

Returns the number of external appearance states for a Figure.

Returns:

the number of external appearance states for the Figure.

getPattern

public int getPattern()

Returns the pattern index this Figure is set to.

Returns:

the pattern index this Figure is set to.

setPattern

public void setPattern(int pattern)

Modifies the appearance of the figure by setting the pattern used during rendering. Each figure is capable of holding multiple external appearances (vertex positions).

Each figure can have up to 33 external appearances. This includes the state without any pattern specified (the common set state). Each of these external appearances is seen as a bit in a 32-bit integer and it is set through the parameter. For example, a figure has five external states as described below:

• Pattern 0: the face (the common set)
• Pattern 1: closed eyes
• Pattern 2: open eyes
• Pattern 3: closed mouth
• Pattern 4: open mouth

figure.setPattern(0) is a face without eyes or a mouth.
figure.setPattern(1<<0) is a face with eyes closed.
figure.setPattern(1<<1) is a face with eyes open.
figure.setPattern(1<<2) is a face with a closed mouth.
figure.setPattern(1<<3) is a face with an open mouth.
figure.setPattern((1<<0) | (1<<3)) is a face with closed eyes and an open mouth.

Note: For
figure.setPattern((1<<0) | (1<<1)) a face with both closed and open eyes will be rendered.

Parameters:

pattern - the pattern index to set the Figure to.