com.threerings.math
Class Transform3D

java.lang.Object
  com.threerings.math.Transform3D

All Implemented Interfaces:

Exportable, com.threerings.io.Streamable

public final class Transform3D
extends Object
implements Exportable, com.threerings.io.Streamable

Represents a 3D transformation in such a way as to accelerate operations such as composition and inversion by keeping track of the nature of the transform.

Nested Class Summary

Nested classes/interfaces inherited from interface com.threerings.io.Streamable

com.threerings.io.Streamable.Closure

Field Summary

static int	AFFINE An affine transformation represented by the upper three rows of a 4x4 matrix.
static int	GENERAL A general transformation represented by a 4x4 matrix.
static int	IDENTITY An identity transformation.
static int	RIGID A rigid transformation represented by a translation vector and a rotation quaternion.
static int	UNIFORM A transformation represented by translation, rotation, and a uniform scale value.

Constructor Summary

Transform3D()
Creates an identity transformation.

Transform3D(int type)
Creates an identity transformation of the specified type.

Transform3D(Matrix4f matrix)
Creates a transformation from the values in the supplied matrix.

Transform3D(Matrix4f matrix, boolean affine)
Creates a transformation from the values in the supplied matrix.

Transform3D(Transform2D transform)
Creates a transform from the supplied 2D transform.

Transform3D(Transform3D transform)
Copy constructor.

Transform3D(Vector3f translation, Quaternion rotation)
Creates a transformation from the values in the supplied objects.

Transform3D(Vector3f translation, Quaternion rotation, float scale)
Creates a transformation from the values in the supplied objects.

Transform3D(Vector3f translation, Quaternion rotation, Vector3f scale)
Creates a transformation from the values in the supplied objects.

Method Summary

float	approximateUniformScale() Extracts an approximation of the uniform scale from this transform.
Transform3D	compose(Transform3D other) Composes this transform with another.
Transform3D	compose(Transform3D other, Transform3D result) Composes this transform with another, storing the result in the object provided.
Transform3D	composeLocal(Transform3D other) Composes this transform in-place with another.
boolean	equals(Object other)
Quaternion	extractRotation() Extracts the rotation component of the transform.
Quaternion	extractRotation(Quaternion result) Extracts the rotation component of the transform and places it in the provided result quaternion.
Vector3f	extractScale() Extracts the scale component of the transform.
Vector3f	extractScale(Vector3f result) Extracts the scale component of the transform and places it in the provided result vector.
Vector3f	extractTranslation() Extracts the translation component of the transform.
Vector3f	extractTranslation(Vector3f result) Extracts the translation component of the transform and places it in the provided result vector.
Matrix4f	getMatrix() Returns a reference to the transformation matrix, which is only definitive when the type is AFFINE or GENERAL.
Quaternion	getRotation() Returns a reference to the rotation quaternion, which is only definitive when the type is RIGID or UNIFORM.
float	getScale() Returns the uniform scale, which is only definitive when the type is UNIFORM.
Vector3f	getTranslation() Returns a reference to the translation vector, which is only definitive when the type is RIGID or UNIFORM.
int	getType() Returns the type of this transformation.
int	hashCode()
Transform3D	invert() Inverts this transform.
Transform3D	invert(Transform3D result) Inverts this transform, storing the result in the provided object.
Transform3D	invertLocal() Inverts this transform in-place.
boolean	isMirrored() Checks whether the transform is mirrored.
Transform3D	lerp(Transform3D other, float t) Linearly interpolates between this and the specified other transform.
Transform3D	lerp(Transform3D other, float t, Transform3D result) Linearly interpolates between this and the specified other transform, placing the result in the transform provided.
Transform3D	lerpLocal(Transform3D other, float t) Linearly interpolates between this and the specified other transform, placing the result in this transform.
Transform3D	promote(int type) Promotes this transform to the specified type, which must be greater than or equal to its current type.
void	readFields(Importer in) Custom field read method.
Transform3D	set(Matrix4f matrix) Sets the transform using the supplied matrix.
Transform3D	set(Matrix4f matrix, boolean affine) Sets the transform using the supplied matrix.
Transform3D	set(Transform2D transform) Copies the values contained in another transform.
Transform3D	set(Transform3D transform) Copies the values contained in another transform.
Transform3D	set(Vector3f translation, Quaternion rotation) Sets the transform using the supplied values.
Transform3D	set(Vector3f translation, Quaternion rotation, float scale) Sets the transform using the supplied values.
Transform3D	set(Vector3f translation, Quaternion rotation, Vector3f scale) Sets the transform using the supplied values.
float	setScale(float scale) Sets the uniform scale.
Transform3D	setToIdentity() Sets the transform to the identity transform.
void	setType(int type) Sets the type of the transformation.
String	toString()
Vector3f	transformPoint(Vector3f pt) Transforms a point by this transform.
Vector3f	transformPoint(Vector3f pt, Vector3f result) Transforms a point by this transform and places the result in the object provided.
Vector3f	transformPointLocal(Vector3f pt) Transforms a point in-place by this transform.
float	transformPointZ(Vector3f pt) Transforms a point by this transform and returns the z coordinate of the result.
Vector3f	transformVector(Vector3f vec) Transforms a vector by this transform.
Vector3f	transformVector(Vector3f vec, Vector3f result) Transforms a vector by this transform and places the result in the object provided.
Vector3f	transformVectorLocal(Vector3f vec) Transforms a vector in-place by this transform.
Transform3D	update(int utype) Updates the transform fields corresponding to the specified type.
void	writeFields(Exporter out) Custom field write method.

Methods inherited from class java.lang.Object

getClass, notify, notifyAll, wait, wait, wait

Field Detail

IDENTITY

public static final int IDENTITY

An identity transformation.

See Also:

Constant Field Values

RIGID

public static final int RIGID

A rigid transformation represented by a translation vector and a rotation quaternion.

See Also:

Constant Field Values

UNIFORM

public static final int UNIFORM

A transformation represented by translation, rotation, and a uniform scale value.

See Also:

Constant Field Values

AFFINE

public static final int AFFINE

An affine transformation represented by the upper three rows of a 4x4 matrix.

See Also:

Constant Field Values

GENERAL

public static final int GENERAL

A general transformation represented by a 4x4 matrix.

See Also:

Constant Field Values

Constructor Detail

Transform3D

public Transform3D()

Creates an identity transformation.

Transform3D

public Transform3D(int type)

Creates an identity transformation of the specified type.

Transform3D

public Transform3D(Vector3f translation,
                   Quaternion rotation)

Creates a transformation from the values in the supplied objects.

Transform3D

public Transform3D(Vector3f translation,
                   Quaternion rotation,
                   float scale)

Creates a transformation from the values in the supplied objects.

Transform3D

public Transform3D(Vector3f translation,
                   Quaternion rotation,
                   Vector3f scale)

Creates a transformation from the values in the supplied objects.

Transform3D

public Transform3D(Matrix4f matrix)

Creates a transformation from the values in the supplied matrix.

Transform3D

public Transform3D(Matrix4f matrix,
                   boolean affine)

Creates a transformation from the values in the supplied matrix.

Parameters:

affine - whether or not the provided matrix is known to be affine.

Transform3D

public Transform3D(Transform2D transform)

Creates a transform from the supplied 2D transform.

Transform3D

public Transform3D(Transform3D transform)

Copy constructor.

Method Detail

getType

public int getType()

Returns the type of this transformation.

setType

public void setType(int type)

Sets the type of the transformation. This doesn't actually change any of the values, but it does initialize the fields required for the type if they are null. To promote to a more general transform type, see promote(int).

getTranslation

public Vector3f getTranslation()

Returns a reference to the translation vector, which is only definitive when the type is RIGID or UNIFORM.

getRotation

public Quaternion getRotation()

Returns a reference to the rotation quaternion, which is only definitive when the type is RIGID or UNIFORM.

getScale

public float getScale()

Returns the uniform scale, which is only definitive when the type is UNIFORM.

setScale

public float setScale(float scale)

Sets the uniform scale.

Returns:

the scale value set, for chaining.

getMatrix

public Matrix4f getMatrix()

Returns a reference to the transformation matrix, which is only definitive when the type is AFFINE or GENERAL.

invertLocal

public Transform3D invertLocal()

Inverts this transform in-place.

Returns:

a reference to this transform, for chaining.

invert

public Transform3D invert()

Inverts this transform.

Returns:

a new transform containing the result.

invert

public Transform3D invert(Transform3D result)

Inverts this transform, storing the result in the provided object.

Returns:

a reference to the result transform, for chaining.

composeLocal

public Transform3D composeLocal(Transform3D other)

Composes this transform in-place with another.

Returns:

a reference to this transform, for chaining.

compose

public Transform3D compose(Transform3D other)

Composes this transform with another.

Returns:

a new transform containing the result.

compose

public Transform3D compose(Transform3D other,
                           Transform3D result)

Composes this transform with another, storing the result in the object provided.

lerpLocal

public Transform3D lerpLocal(Transform3D other,
                             float t)

Linearly interpolates between this and the specified other transform, placing the result in this transform.

Returns:

a reference to this transform, for chaining.

lerp

public Transform3D lerp(Transform3D other,
                        float t)

Linearly interpolates between this and the specified other transform.

Returns:

a new transform containing the result.

lerp

public Transform3D lerp(Transform3D other,
                        float t,
                        Transform3D result)

Linearly interpolates between this and the specified other transform, placing the result in the transform provided.

Returns:

a reference to the result transform, for chaining.

set

public Transform3D set(Transform3D transform)

Copies the values contained in another transform.

Returns:

a reference to this transform, for chaining.

set

public Transform3D set(Transform2D transform)

Copies the values contained in another transform.

Returns:

a reference to this transform, for chaining.

setToIdentity

public Transform3D setToIdentity()

Sets the transform to the identity transform.

Returns:

a reference to this transform, for chaining.

set

public Transform3D set(Vector3f translation,
                       Quaternion rotation)

Sets the transform using the supplied values.

Returns:

a reference to this transform, for chaining.

set

public Transform3D set(Vector3f translation,
                       Quaternion rotation,
                       float scale)

Sets the transform using the supplied values.

Returns:

a reference to this transform, for chaining.

set

public Transform3D set(Vector3f translation,
                       Quaternion rotation,
                       Vector3f scale)

Sets the transform using the supplied values.

Returns:

a reference to this transform, for chaining.

set

public Transform3D set(Matrix4f matrix)

Sets the transform using the supplied matrix.

Returns:

a reference to this transform, for chaining.

set

public Transform3D set(Matrix4f matrix,
                       boolean affine)

Sets the transform using the supplied matrix.

Parameters:

affine - whether or not the provided matrix is affine.

Returns:

a reference to this transform, for chaining.

promote

public Transform3D promote(int type)

Promotes this transform to the specified type, which must be greater than or equal to its current type.

Returns:

a reference to this transform, for chaining.

update

public Transform3D update(int utype)

Updates the transform fields corresponding to the specified type. For example, if this matrix is IDENTITY and type is RIGID, then the translation and rotation fields are set to zero and the identity quaternion, respectively.

Parameters:

utype - the desired type, which must be greater than or equal to the type of this transform.

Returns:

a reference to this transform, for chaining.

transformPointLocal

public Vector3f transformPointLocal(Vector3f pt)

Transforms a point in-place by this transform.

Returns:

a reference to the point, for chaining.

transformPoint

public Vector3f transformPoint(Vector3f pt)

Transforms a point by this transform.

Returns:

a new vector containing the result.

transformPoint

public Vector3f transformPoint(Vector3f pt,
                               Vector3f result)

Transforms a point by this transform and places the result in the object provided.

Returns:

a reference to the result object, for chaining.

transformPointZ

public float transformPointZ(Vector3f pt)

Transforms a point by this transform and returns the z coordinate of the result.

transformVectorLocal

public Vector3f transformVectorLocal(Vector3f vec)

Transforms a vector in-place by this transform.

Returns:

a reference to the transformed vector, for chaining.

transformVector

public Vector3f transformVector(Vector3f vec)

Transforms a vector by this transform.

Returns:

a new vector containing the result.

transformVector

public Vector3f transformVector(Vector3f vec,
                                Vector3f result)

Transforms a vector by this transform and places the result in the object provided.

Returns:

a reference to the result vector, for chaining.

extractTranslation

public Vector3f extractTranslation()

Extracts the translation component of the transform.

Returns:

a new vector containing the result.

extractTranslation

public Vector3f extractTranslation(Vector3f result)

Extracts the translation component of the transform and places it in the provided result vector.

Returns:

a reference to the result vector, for chaining.

extractRotation

public Quaternion extractRotation()

Extracts the rotation component of the transform.

Returns:

a new quaternion containing the result.

extractRotation

public Quaternion extractRotation(Quaternion result)

Extracts the rotation component of the transform and places it in the provided result quaternion.

Returns:

a reference to the result quaternion, for chaining.

extractScale

public Vector3f extractScale()

Extracts the scale component of the transform.

Returns:

a new vector containing the result.

extractScale

public Vector3f extractScale(Vector3f result)

Extracts the scale component of the transform and places it in the provided result vector.

Returns:

a reference to the result vector, for chaining.

approximateUniformScale

public float approximateUniformScale()

Extracts an approximation of the uniform scale from this transform.

isMirrored

public boolean isMirrored()

Checks whether the transform is mirrored.

writeFields

public void writeFields(Exporter out)
                 throws IOException

Custom field write method.

Throws:

IOException

readFields

public void readFields(Importer in)
                throws IOException

Custom field read method.

Throws:

IOException

toString

public String toString()

Overrides:

toString in class Object

hashCode

public int hashCode()

Overrides:

hashCode in class Object

equals

public boolean equals(Object other)

Overrides:

equals in class Object