com.motorola.iden.micro3d
Class AffineTransform

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

public class AffineTransform

extends java.lang.Object

3D affine transformation class. This class handles the 3D affine transformation matrix. Element values are expressed as a fixed-point integer where 4096 is equal to 1.00. All values in the matrix must be in the range -32768 to 32767. Values that are smaller than -32768 will be automatically adjusted to -32768. Similarly, values greater than 32767 will be automatically adjusted to 32767.

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	M00 Specifies matrix element at row 1, column 1.
static int	M01 Specifies matrix element at row 1, column 2.
static int	M02 Specifies matrix element at row 1, column 3.
static int	M03 Specifies matrix element at row 1, column 4.
static int	M10 Specifies matrix element at row 2, column 1.
static int	M11 Specifies matrix element at row 2, column 2.
static int	M12 Specifies matrix element at row 2, column 3.
static int	M13 Specifies matrix element at row 2, column 4.
static int	M20 Specifies matrix element at row 3, column 1.
static int	M21 Specifies matrix element at row 3, column 2.
static int	M22 Specifies matrix element at row 3, column 3.
static int	M23 Specifies matrix element at row 3, column 4.
static int	MAX_VALUE The maximum value that can be used by the AffineTransform.
static int	MIN_VALUE The minimum value that can be used by the AffineTransform.

Constructor Summary

AffineTransform()
Constructs an AffineTransform with all of its elements set to 0.

AffineTransform(int[][] elements)
Constructs an AffineTransform with its elements set to the values in the specified two-dimensional array.

Method Summary

int	get(int fieldID) Gets the specified AffineTransform matrix element value.
static AffineTransform	getViewPointTransform(Vector3D position, Vector3D look, Vector3D up) Calculates a view point transformation matrix.
void	multiply(AffineTransform multiplier) Multiplies this AffineTransform object against another.
static AffineTransform	multiply(AffineTransform multiplicand, AffineTransform multiplier) Multiplies two AffineTransform objects against another.
static void	multiply(AffineTransform destination, AffineTransform multiplicand, AffineTransform multiplier) Multiplies two AffineTransform objects and stores the result of the operation in the specified destination.
void	normalize() Normalizes this AffineTransform.
void	rotateV(Vector3D axis, int angle) Rotates this transform about an arbitrary unit vector.
void	rotateX(int angle) Rotates this transform about the x-axis.
void	rotateY(int angle) Rotates this transform about the y-axis.
void	rotateZ(int angle) Rotates this transform about the z-axis.
void	set(int[][] elements) Sets the AffineTransform matrix elements with the integers in the specified two-dimensional array.
void	set(int fieldID, int value) Sets the specified AffineTransform matrix element with the specified value.
void	setIdentity() Converts this AffineTransform to an identity matrix.
Vector3D	transformPoint(Vector3D source) Returns a Vector3D transformed from a given point in this AffineTransform.

Methods inherited from class java.lang.Object

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

Field Detail

M00

public static final int M00

Specifies matrix element at row 1, column 1.

M01

public static final int M01

Specifies matrix element at row 1, column 2.

M02

public static final int M02

Specifies matrix element at row 1, column 3.

M03

public static final int M03

Specifies matrix element at row 1, column 4.

M10

public static final int M10

Specifies matrix element at row 2, column 1.

M11

public static final int M11

Specifies matrix element at row 2, column 2.

M12

public static final int M12

Specifies matrix element at row 2, column 3.

M13

public static final int M13

Specifies matrix element at row 2, column 4.

M20

public static final int M20

Specifies matrix element at row 3, column 1.

M21

public static final int M21

Specifies matrix element at row 3, column 2.

M22

public static final int M22

Specifies matrix element at row 3, column 3.

M23

public static final int M23

Specifies matrix element at row 3, column 4.

MIN_VALUE

public static final int MIN_VALUE

The minimum value that can be used by the AffineTransform.

MAX_VALUE

public static final int MAX_VALUE

The maximum value that can be used by the AffineTransform.

Constructor Detail

AffineTransform

public AffineTransform()

Constructs an AffineTransform with all of its elements set to 0.

AffineTransform

public AffineTransform(int[][] elements)
                throws java.lang.NullPointerException,
                       java.lang.IllegalArgumentException

Constructs an AffineTransform with its elements set to the values in the specified two-dimensional array. The outer array array must contain 3 elements. Each of those elements must contain an array of 4 elements.

The data in those arrays is set as follows. The value at index [0][0] represents the value described by the AffineTransform field M00. The value at index [0][3] represents the value described by the AffineTransform field M03.

All values in the array must be in the range -32768 to 32767. Values smaller than -32768 will be adjusted to -32768 ( AffineTransform.MIN_VALUE). Values larger than 32767 will be adjusted to 32767 (AffineTransform.MAX_VALUE).

Throws:

java.lang.IllegalArgumentException - if the specified array has invalid size.

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

See Also:

MIN_VALUE, MAX_VALUE, M00, M01, M02, M03, M10, M11, M12, M13, M20, M21, M22, M23

Method Detail

get

public int get(int fieldID)

Gets the specified AffineTransform matrix element value.

The fieldID parameter should be one of the field values specified in the AffineTransform class.

Parameters:

fieldID - the ID of the matrix element value to return.

Returns:

the value of the specified matrix element.

Throws:

java.lang.IllegalArgumentException - if the field ID is not valid.

See Also:

M00, M01, M02, M03, M10, M11, M12, M13, M20, M21, M22, M23

set

public void set(int fieldID,
                int value)
         throws java.lang.IllegalArgumentException

Sets the specified AffineTransform matrix element with the specified value.

The fieldID parameter should be one of the field values specified in the AffineTransform class.

The specified value must be in the range -32768 to 32767. Values smaller than -32768 will be adjusted to -32768 ( AffineTransform.MIN_VALUE). Values larger than 32767 will be adjusted to 32767 (AffineTransform.MAX_VALUE).

Parameters:

fieldID - the ID of the matrix element being set.

value - the value to set that element to.

Throws:

java.lang.IllegalArgumentException - if the field ID is not valid.

See Also:

MIN_VALUE, MAX_VALUE, M00, M01, M02, M03, M10, M11, M12, M13, M20, M21, M22, M23

set

public void set(int[][] elements)
         throws java.lang.NullPointerException,
                java.lang.IllegalArgumentException

Sets the AffineTransform matrix elements with the integers in the specified two-dimensional array. The outer array array must contain 3 elements. Each of those elements must contain an array of 4 elements.

All values in the array must be in the range -32768 to 32767. Values smaller than -32768 will be adjusted to -32768 ( AffineTransform.MIN_VALUE). Values larger than 32767 will be adjusted to 32767 (AffineTransform.MAX_VALUE).

Throws:

java.lang.IllegalArgumentException - if the specified array has invalid size.

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

See Also:

MIN_VALUE, MAX_VALUE

getViewPointTransform

public static AffineTransform getViewPointTransform(Vector3D position,
                                                    Vector3D look,
                                                    Vector3D up)
                                             throws java.lang.NullPointerException,
                                                    java.lang.IllegalArgumentException

Calculates a view point transformation matrix.

The viewpoint transformation matrix is created from the view position vector, the view direction vector, and the view up direction vector. The specified look and up vectors cannot be zero vectors nor be parallel to each other.

Parameters:

position - a Vector3D containing the viewpoint position.

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.

rotateX

public void rotateX(int angle)

Rotates this transform about the x-axis.

For greater precision, a value of 4096 is equivalent to 360 degrees.

Parameters:

angle - the angle of rotation.

rotateY

public void rotateY(int angle)

Rotates this transform about the y-axis.

For greater precision, a value of 4096 is equivalent to 360 degrees.

Parameters:

angle - the angle of rotation.

rotateZ

public void rotateZ(int angle)

Rotates this transform about the z-axis.

For greater precision, a value of 4096 is equivalent to 360 degrees.

Parameters:

angle - the angle of rotation.

rotateV

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

Rotates this transform about an arbitrary unit vector.

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 this method will produce incorrect results.

Parameters:

axis - the unit vector for the rotation.

angle - the angle of rotation.

Throws:

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

transformPoint

public Vector3D transformPoint(Vector3D source)
                        throws java.lang.NullPointerException

Returns a Vector3D transformed from a given point in this AffineTransform.

Parameters:

source - the Vector3D containing the point to transform.

Returns:

a new Vector3D specifying the transformed point.

Throws:

java.lang.NullPointerException - if the source point is null.

multiply

public void multiply(AffineTransform multiplier)
              throws java.lang.NullPointerException

Multiplies this AffineTransform object against another.

The result is stored within the AffineTransform the method was called on.

Parameters:

multiplier - the AffineTransform to multiply this AffineTransform with.

Throws:

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

multiply

public static AffineTransform multiply(AffineTransform multiplicand,
                                       AffineTransform multiplier)
                                throws java.lang.NullPointerException

Multiplies two AffineTransform objects against another.

The result is returned in a new AffineTransform instance.

Parameters:

multiplicand - the AffineTransform serving as the multiplicand.

multiplier - the AffineTransform serving as the multiplier.

Returns:

an AffineTransform containing the result.

Throws:

java.lang.NullPointerException - if either the multiplicand or the multiplier is null.

multiply

public static void multiply(AffineTransform destination,
                            AffineTransform multiplicand,
                            AffineTransform multiplier)
                     throws java.lang.NullPointerException

Multiplies two AffineTransform objects and stores the result of the operation in the specified destination.

Parameters:

destination - the AffineTransform that should hold the result.

multiplicand - the AffineTransform serving as the multiplicand.

multiplier - the AffineTransform serving as the multiplier.

Throws:

java.lang.NullPointerException - if any of the specified parameters is null.

normalize

public void normalize()

Normalizes this AffineTransform. If this is a zero matrix this method does nothing. A zero matrix is a matrix with all elements equal to zero.

setIdentity

public void setIdentity()

Converts this AffineTransform to an identity matrix.