com.motorola.iden.micro3d
Class Layout3D

java.lang.Object
  |
  +--com.motorola.iden.micro3d.Layout3D

public class Layout3D

extends java.lang.Object

Layout3D class is used to specify how an Object3D is rendered on the screen. An Object3D without a Layout3D will not be rendered.

Coordinate Systems

Micro3D engine uses the following coordinate systems:

• Model coordinate system - used for describing the model (figure) data. The model coordinates are hidden inside the figure.
• View coordinate system - used for describing the camera's view. This is a right-handed coordinate system and the following values are supported:
  
  • X: right direction [-32768, 32767]
  
  
  • Y: down direction [-32768, 32767]
  
  
  • Z: forward direction [-32768, 32767]
  
  
• Screen coordinate system - used for screen display. This is a right-handed coordinate system and the following values are supported:
  
  • X: right direction [-2048, 2047]
  
  
  • Y: down direction [-2048, 2047]
  
  
  • Z: forward direction [-32768, 32767]
  
  

Model points are transformed in the following order before they are finally drawn onto the display:
model coordinates => view coordinates => screen coordinates
The view transformation matrix is used to convert the view coordinate system into the screen coordinate system. The Micro3D API provides two modes for creating and manipulating the view transformation matrix: automatic and manual.

Automatic

In the automatic mode the view transformation matrix is automatically created when the object is rendered. The view transformation matrix is created based on the parameters assigned to this Layout3D object.

The first step in creating the view transformation matrix is setting up the view point. This can be accomplished in two ways:

• Create the viewpoint transformation matrix automatically by specifying the view position, view direction, and view up direction. The viewpoint is set with the method setViewpoint(), where view location, view direction, and view up direction are specfied with Vector3D objects.
• Create the viewpoint transformation matrix and assign it to this Layout3D object with the setViewpointTransform() method.

Regardless of which way is used to create the viewpoint transformation matrix, the current viewpoint transformation matrix can be obtained with the getViewpointTransform() method.

The second step in creating the view transformation matrix is to specify the orientation of the 3d object. This again can be accomplished in two ways:

• Set the orientation by specifying rotation around X,Y,and Z axis. The rotation is specified by using rotateX(), rotateY(), and rotateZ() methods. The rotation is specified in degrees where 4096 is equal to 360 degrees. The initial values for all three angles are 0 degrees.
• Set the orientation by specifying rotation around an arbitrary axis. The rotation is specified using the rotateV() method and providing a rotation axis defined by Vector3D, and rotation angle in degrees (where 4096 is equal to 360 degrees).

It is important to note that invoking any of the rotation methods does not actually manipulate the view transformation matrix at that time. All the calculations are performed when the objects are rendered to the screen. As a result, when the Layout3D is in automatic mode, invoking the method getViewTransform() will not return the view transformation matrix. In addition, the rotation methods are not cumulative. For example, calling rotateX(30) then rotateX(60) and then rendering the object will not result in a 90 degree rotation. Instead only the last value is used, so the object will be rotated 60 degrees around the X axis.

Manual

In the manual mode, the developer has a complete control over the view transformation matrix. The view transformation matrix is created by manipulating the AffineTransform object. Once the desired view transformation matrix has been created, it can be assigned to the Layout3D object by using the setViewTransform() method. When the Layout3D is in manual mode, the viewpoint transformation matrix is not used. Therefore, using the method setViewpointTransform() will not have any effect on the rendering.

Layout3D

When a Layout3D is instantiated, it is created with a default viewpoint and rotation angles for X, Y, and Z axis (0 degrees). The Layout3D will remain in the automatic mode as long as only rotateX(), rotateY(), and rotateZ() methods are used to specify rotation. If the method rotateV() is used, the Layout3D remains in automatic mode, but from this point on the X, Y, and Z angle values are ignored and only the arbitrary axis angle is used. However, as soon as either of the rotateX(), rotateY(), or rotateZ() methods is used, the Layout3D will use the existing X, Y, and Z values to create the view transformation matrix.
Once the method setViewTransform() is used the Layout3d will switch to manual mode. From that point on, the existing viewpoint and axis rotation angles will be ignored, and only the specified view transformation matrix will be used. The Layout3D will switch to automatic mode, as soon as rotateX(), rotateY(), rotateZ(), or rotateV() is used.
It is recommended to use the automatic mode. In most cases the automatic mode will be faster than setting up the same view transformation matrix manually. This is due to the fact the in the automatic mode all the transformation calculations are done at once right before rendering, while in the manual mode the transformation matrix must be created by invoking individual methods. The manual mode should only be used if there is an explicit need to manually modify the view transformation matrix.

Projection Types

Micro3D engine supports two types of projection:

• Parallel projection - the view volume is a rectangular parallelepiped determined by the rendering size and the view direction. An object's distance from the viewpoint does not affect its size.
• Perspective projection - the view volume is a truncated pyramid with a rectangular base determined by the view's field of view and the screen rectangle. An object's distance from the viewpoint does affect the object size. Objects that are too near, too far, or are in the opposite direction from the viewpoint are not rendered.
  In the view volume, the plane closest to the viewpoint is called the near clipping plane and the plane farthest to the viewpoint is called the far clipping plane. The angle representing the visibility range is called the field of view.

When using 3D data, it is necessary to properly set the model size, scale, and projection at each step. Incorrect choice of settings may result in the model being too big, too small, or sticking out of the screen and thus not viewable. The projection types and the projection parameters are set with setProjection() method. The following projection modes are supported:

• Parallel projection by specifying the scale - this mode is specified with the PARALLEL_SCALE constant. The parameters are specified with an integer array containing two elements: the width ratio of the screen transformation, and the height ratio of the screen transformation (in that order). Value of 4096 represents unit scaling. (4096 = 1.0). The model is enlarged for larger numbers and reduced for smaller numbers. The distance between the viewpoint and the model is not taken into consideration.
• Parallel projection by specifying the width of the projection plane - this mode is specified with the PARALLEL_WIDTH constant. The parameters are specified with an integer array containing one element: the projection plane's width. The unit size of the width is the view coordinate system unit size * 4096. Because the projection plane is projected onto the screen, if the projection plane is expanded (the width is increased), the object's display size will be reduced. The projection plane's height will automatically be set so that the screen's aspect ration is maintained. The distance between the viewpoint and the model is not taken into consideration.
• Parallel projection by specifying the width and height of the projection plane - this mode is specified with the PARALLEL_WIDTH_HEIGHT constant. The parameters are specified with an integer array containing two elements: the width of the projection plane and the height of the projection plane (in that order). The unit size for the width and height is the view coordinate system unit size * 4096. Because the projection plane is projected onto the screen, if the projection plane is expanded (the width is increased), the object's display size will be reduced. The distance between the viewpoint and the model is not taken into consideration.
• Perspective projection by specifying the field of view - this mode is specified with the PERSPECTIVE_FOV constant. The parameters are specified with an integer array containing three elements: the distance between the camera and the near clipping plane, the distance between the camera and the far clipping plane, and the field of view (in that order). The valid value range for the distance between the camera and the near clipping plane is [1, 32767]. The valid value range for the distance between the camera and the far clipping plane is [2, 32767]. For the view angle the valid range is [1, 2047], where 4096 is equal to 360 degrees.
  If the field of view is decreased, the projection plance is reduced and as a result the display will show an enlarged object. Since the view volume is set by specifying the distance to the near and far clipping plane, the space in front of the near clipping plane and the space behind the far clipping plane will not be displayed even if they are within the field of view.
• Perspective projection by specifying the near clipping plane's width - this mode is specified with the PERSPECTIVE_WIDTH constant. The parameters are specified with an integer array containing three elements: the distance between the camera and the near clipping plane, the distance between the camera and the far clipping plane, and the width of the near clipping plane's projection plane (in that order). The valid value range for the distance between the camera and the near clipping plane is [1, 32767]. The valid value range for the distance between the camera and the far clipping plane is [2, 32767]. The unit size of the width is the view coordinate system unit size * 4096 (this value should be greater than 0). The far clipping plane's height will be automatically adjusted to the same ration as the aspect ration of the screen.
  If the specified width is reduced, the projection plane is reduced and as a result the display will show an enlarged object. Since the view volume is set by specifying the distance to the near and far clipping plane, the space in front of the near clipping plane and the space behind the far clipping plane will not be displayed even if they are within the field of view.
• Perspective projection by specifying the near clipping plane's width and height - this mode is specified with the PERSPECTIVE_WIDTH_HEIGHT constant. The parameters are specified with an integer array containing four elements: the distance between the camera and the near clipping plane, the distance between the camera and the far clipping plane, the width of the near clipping plane's projection plane, and the height of the near clipping's plane projection plane (in that order). The valid value range for the distance between the camera and the near clipping plane is [1, 32767]. The valid value range for the distance between the camera and the far clipping plane is [2, 32767]. The unit size of the width and the height is the view coordinate system unit size * 4096 (this value should be greater than 0).
  If the specified width and height are reduced, the projection plane is reduced and as a result the display will show an enlarged object. Since the view volume is set by specifying the distance to the near and far clipping plane, the space in front of the near clipping plane and the space behind the far clipping plane will not be displayed even if they are within the field of view.

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.

Field Summary

static int	PARALLEL_SCALE Identifier for parallel projection specified by setting the scale of the view-to-screen transformation.
static int	PARALLEL_WIDTH Identifier for parallel projection specified by setting the projection plane's width.
static int	PARALLEL_WIDTH_HEIGHT Identifier for parallel projection specified by setting the projection plane's width and height.
static int	PERSPECTIVE_FOV Identifier for perspective projection specified by field of view parameters.
static int	PERSPECTIVE_WIDTH Identifier for perspective projection specified by the width of the near clipping plane's projection plane.
static int	PERSPECTIVE_WIDTH_HEIGHT Identifier for perspective projection specified by width and height of the near clipping plane's projection plane.

Constructor Summary

Layout3D()
Creates a Layout3D for use with rendering Figure and Primitive objects.

Method Summary

Light	getLight() Returns the Light used with this Layout3D.
int[]	getProjectionParameters() Returns a copy of the projection parameters set for this Layout3D.
int	getProjectionType() Returns the projection type set for this Layout3D.
int	getToonHighColor() Returns the high color value used for toon shading.
int	getToonLowColor() Returns the low color value used for toon shading.
int	getToonThreshold() Returns the threshold value used for toon shading.
AffineTransform	getViewPointTransform() Returns the affine transform serving as the view point transformation matrix for this Layout3D.
AffineTransform	getViewTransform() Returns the AffineTransform used as the view transformation for this Layout3D.
boolean	isSemiTransparent() Checks whether or not semi-transparent rendering is enabled for this Layout3D.
boolean	isToonShaded() Checks whether toon shading is enabled for this Layout3D.
void	rotateV(Vector3D axis, int angle) Rotates the view transformation matrix about an arbitrary unit vector.
void	rotateX(int angle) Rotates the view transformation matrix about the X axis.
void	rotateY(int angle) Rotates the view transformation matrix about the Y axis.
void	rotateZ(int angle) Rotates the view transformation matrix about the Z axis.
void	setLight(Light light) Sets a Light to be used for this Layout3D.
void	setProjection(int type, int[] parameters) Sets the projection used by this Layout3D.
void	setSemiTransparent(boolean transparent) Enables or disables semi-transparency for this Layout3D.
void	setToonShading(boolean toon) Enables or disables toon shading for this Layout3D.
void	setToonShading(int threshold, int highColor, int lowColor) Sets the toon shading parameters to the specified values and enables toon shading.
void	setViewPoint(Vector3D position, Vector3D look, Vector3D up) Creates an affine transform from the provided vectors that will serve as the view point transformation matrix used when determining the view transformation for this Layout3D.
void	setViewPointTransform(AffineTransform viewPointTransform) Sets the affine transform that will serve as the view point transformation matrix used when determining the view transformation for this Layout3D.
void	setViewTransform(AffineTransform viewTransform) Sets an AffineTransform to be used as the view transformation for this Layout3D.

Methods inherited from class java.lang.Object

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

Field Detail

PERSPECTIVE_FOV

public static final int PERSPECTIVE_FOV

Identifier for perspective projection specified by field of view parameters.

When setting projection parameters the required array length is 3.

PERSPECTIVE_WIDTH

public static final int PERSPECTIVE_WIDTH

Identifier for perspective projection specified by the width of the near clipping plane's projection plane.

When setting projection parameters the required array length is 3.

PERSPECTIVE_WIDTH_HEIGHT

public static final int PERSPECTIVE_WIDTH_HEIGHT

Identifier for perspective projection specified by width and height of the near clipping plane's projection plane.

When setting projection parameters the required array length is 4.

PARALLEL_SCALE

public static final int PARALLEL_SCALE

Identifier for parallel projection specified by setting the scale of the view-to-screen transformation.

When setting projection parameters the required array length is 2.

PARALLEL_WIDTH

public static final int PARALLEL_WIDTH

Identifier for parallel projection specified by setting the projection plane's width.

When setting projection parameters the required array length is 1.

PARALLEL_WIDTH_HEIGHT

public static final int PARALLEL_WIDTH_HEIGHT

Identifier for parallel projection specified by setting the projection plane's width and height.

When setting projection parameters the required array length is 2.

Constructor Detail

Layout3D

public Layout3D()

Creates a Layout3D for use with rendering Figure and Primitive objects. The Layout3D will contain default settings for rendering as follows:

• a view point with (0, 0, 0), (0, 0, 1), and (0, 1, 0) as the position, look, and up vectors, respectively
• a 0 value for x, y, and z rotation angles
• parallel projection set by scale values of 4096
• a null light source
• semi-transparent effects disabled
• toon shading disabled

Method Detail

rotateX

public void rotateX(int angle)

Rotates the view transformation matrix about the X axis. This method also re-establishes automatic handling of the view transformation.

For greater precision, a value of 4096 is equivalent to 360 degrees. The rotation is not cumulative; the specified parameter overwrites any existing value.

Parameters:

angle - the angle of rotation.

See Also:

setViewTransform(AffineTransform)

rotateY

public void rotateY(int angle)

Rotates the view transformation matrix about the Y axis. This method also re-establishes automatic handling of the view transformation.

For greater precision, a value of 4096 is equivalent to 360 degrees. The rotation is not cumulative; the specified parameter overwrites any existing value.

Parameters:

angle - the angle of rotation.

See Also:

setViewTransform(AffineTransform)

rotateZ

public void rotateZ(int angle)

Rotates the view transformation matrix about the Z axis. This method also re-establishes automatic handling of the view transformation.

For greater precision, a value of 4096 is equivalent to 360 degrees. The rotation is not cumulative; the specified parameter overwrites any existing value.

Parameters:

angle - the angle of rotation.

See Also:

setViewTransform(AffineTransform)

rotateV

public void rotateV(Vector3D axis,
                    int angle)
             throws java.lang.NullPointerException

Rotates the view transformation matrix about an arbitrary unit vector. This method also re-establishes automatic handling of the view transformation.

For greater precision, a value of 4096 is equivalent to 360 degrees. The specified axis must be a unit vector (vector of length 4096). If a non-unit vector is specified the image might not render correctly. The rotation is not cumulative; the specified parameter overwrites any existing value.

Parameters:

axis - the unit vector for the rotation.

angle - the angle of rotation.

Throws:

java.lang.NullPointerException - if the axis is null.

See Also:

setViewTransform(AffineTransform)

getViewTransform

public AffineTransform getViewTransform()

Returns the AffineTransform used as the view transformation for this Layout3D. If the view transformation matrix for this layout has not been set with setViewTransform method null will be returned.

Returns:

the AffineTransform used as the view transformation for this Layout3D or null.

setViewTransform

public void setViewTransform(AffineTransform viewTransform)
                      throws java.lang.NullPointerException

Sets an AffineTransform to be used as the view transformation for this Layout3D. The view transformation cannot be set to null.

If the view transform is set then this Layout3D no longer maintains automatic control of the view transformation unless a subsequent call to one of the rotation methods in this class is called.

Parameters:

transform - the AffineTransform that will serve as the view transformation.

Throws:

java.lang.NullPointerException - if the transform is null.

See Also:

rotateX(int), rotateY(int), rotateZ(int), rotateV(Vector3D, int)

getViewPointTransform

public AffineTransform getViewPointTransform()

Returns the affine transform serving as the view point transformation matrix for this Layout3D. The view point transformation matrix returned may not be used if this Layout3D is not maintaining automatic control of the view transformation.

Returns:

the affine transform serving as the view point transformation matrix.

See Also:

setViewTransform(AffineTransform), rotateX(int), rotateY(int), rotateZ(int), rotateV(Vector3D, int)

setViewPointTransform

public void setViewPointTransform(AffineTransform viewPointTransform)
                           throws java.lang.NullPointerException

Sets the affine transform that will serve as the view point transformation matrix used when determining the view transformation for this Layout3D. If this Layout3D is not maintaining automatic control of the view transformation then the view point transformation matrix is not used.

Parameters:

viewPointTransform - the affine transform that will serve as the view point transformation matrix.

Throws:

java.lang.NullPointerException - if the specified view point transform is null.

See Also:

setViewTransform(AffineTransform), rotateX(int), rotateY(int), rotateZ(int), rotateV(Vector3D, int)

setViewPoint

public void setViewPoint(Vector3D position,
                         Vector3D look,
                         Vector3D up)
                  throws java.lang.NullPointerException,
                         java.lang.IllegalArgumentException

Creates an affine transform from the provided vectors that will serve as the view point transformation matrix used when determining the view transformation for this Layout3D. If this Layout3D is not maintaining automatic control of the view transformation then the view point transformation matrix is not used.

Parameters:

position - a Vector3D containing the viewpoint coordinates.

look - a Vector3D containing the view direction vector from the viewpoint.

up - a Vector3D containing the up direction vector from the viewpoint.

Throws:

java.lang.NullPointerException - if any of the vectors are null.

java.lang.IllegalArgumentException - if look or up are zero vectors or are parallel to each other.

See Also:

setViewTransform(AffineTransform), rotateX(int), rotateY(int), rotateZ(int), rotateV(Vector3D, int)

getProjectionType

public int getProjectionType()

Returns the projection type set for this Layout3D.

Returns:

an identifier for the projection type set for this Layout3D.

See Also:

PERSPECTIVE_FOV, PERSPECTIVE_WIDTH, PERSPECTIVE_WIDTH_HEIGHT, PARALLEL_SCALE, PARALLEL_WIDTH, PARALLEL_WIDTH_HEIGHT

getProjectionParameters

public int[] getProjectionParameters()

Returns a copy of the projection parameters set for this Layout3D.

Returns:

an int array containing the projection parameters used with this Layout3D.

setProjection

public void setProjection(int type,
                          int[] parameters)
                   throws java.lang.IllegalArgumentException

Sets the projection used by this Layout3D. The projection type should be specified by using one of the constant values defined by this class. The minimum array length for the parameters array is determined by the projection type specified. The array passed in is copied for storage. See the class description for details on how to specify a projection and its parameters. If the specified parameter array contains more elements than needed for that particular projection type, the additional elements will be ignored.

Parameters:

type - the projection type being specified.

parameters - the parameters for the specified projection type.

Throws:

java.lang.IllegalArgumentException - if the projection type is invalid or if the array parameters are incompatible with the projection type.

See Also:

PERSPECTIVE_FOV, PERSPECTIVE_WIDTH, PERSPECTIVE_WIDTH_HEIGHT, PARALLEL_SCALE, PARALLEL_WIDTH, PARALLEL_WIDTH_HEIGHT

getLight

public Light getLight()

Returns the Light used with this Layout3D. This method returns null if no Light object has been associated with this Layout.

Returns:

the Light used with this Layout3D or null if no Light object has been assigned to this Layout.

setLight

public void setLight(Light light)

Sets a Light to be used for this Layout3D. The Light can be set to null disabling lighting effects with this Layout3D and forcing flat shading during rendering.

Parameters:

light - the Light to be used for this Layout3D.

isSemiTransparent

public boolean isSemiTransparent()

Checks whether or not semi-transparent rendering is enabled for this Layout3D.

Returns:

true if semi-transparent rendering is enabled, false otherwise.

setSemiTransparent

public void setSemiTransparent(boolean transparent)

Enables or disables semi-transparency for this Layout3D. In order for semi-transparency effects to be rendered, the figure or the primitive must be created with support for transparency. For figures this means that the blending attributes must be assigned to each polygon during data creation. For primitives, the blending attributes must be assigned using the setBlendingType(int type) method. If a figure or a primitive does not support transparency this setting will not have any affect on the rendering.

Parameters:

transparent - true to enable semi-transparent rendering, false to disable it.

See Also:

Primitive.setBlendingType(int type)

isToonShaded

public boolean isToonShaded()

Checks whether toon shading is enabled for this Layout3D.

Returns:

true if toon shading is enabled, false otherwise.

getToonThreshold

public int getToonThreshold()

Returns the threshold value used for toon shading.

Returns:

the threshold level used for toon shading.

getToonHighColor

public int getToonHighColor()

Returns the high color value used for toon shading. See Graphics for information on specifying RGB values.

Returns:

the high color level used for toon shading.

See Also:

Graphics

getToonLowColor

public int getToonLowColor()

Returns the low color value used for toon shading. See Graphics for information on specifying RGB values.

Returns:

the low color level used for toon shading.

See Also:

Graphics

setToonShading

public void setToonShading(int threshold,
                           int highColor,
                           int lowColor)
                    throws java.lang.IllegalArgumentException

Sets the toon shading parameters to the specified values and enables toon shading. The threshold parameter is the dividing threshold with 256 level of gradiation. The valid values are from 0 to 255, where 255=1.0. The lowColor and highColor parameters define the colors for the two color regions and are specified as RGB values. In order for toon shading to take effect, a Light must be assigned to this Layout3D. See Graphics for information on specifying RGB values.

Parameters:

threshold - the threshold level for toon shading.

highColor - the color to be used when the color is higher than the threshold.

lowColor - the color to be used when the color is lower than the threshold.

Throws:

java.lang.IllegalArgumentException - if an invalid threshold value is used.

See Also:

Graphics

setToonShading

public void setToonShading(boolean toon)

Enables or disables toon shading for this Layout3D. If toon shading parameters have not been set a separate call to setToonShading(int, int, int) should be made. In order for toon shading to take effect, a Light must be assigned to this Layout3D.

Parameters:

toon - true to enable toon shading, false to disable it.

See Also:

setToonShading(int, int, int)