Package com.ardor3d.math

Class Transform

java.lang.Object
com.ardor3d.math.Transform
All Implemented Interfaces:
Poolable, ReadOnlyTransform, Savable, Externalizable, Serializable, Cloneable
Direct Known Subclasses:
ValidatingTransform
public class Transform extends Object implements Cloneable, Savable, Externalizable, ReadOnlyTransform, Poolable
Transform models a transformation in 3d space as: Y = M*X+T, with M being a Matrix3 and T is a Vector3. Generally M will be a rotation only matrix in which case it is represented by the matrix and scale fields as R*S, where S is a positive scale vector. For non-uniform scales and reflections, use setMatrix, which will consider M as being a general 3x3 matrix and disregard anything set in scale.
See Also:

  • Field Details

    • ALLOWED_DEVIANCE

      public static final double ALLOWED_DEVIANCE
      Used with equals method to determine if two Transforms are close enough to be considered equal.
      See Also:

    • IDENTITY

      public static final ReadOnlyTransform IDENTITY
      Identity transform.

    • _matrix

      protected final Matrix3 _matrix

    • _translation

      protected final Vector3 _translation

    • _scale

      protected final Vector3 _scale

    • _identity

      protected boolean _identity
      true if this transform is guaranteed to be the identity matrix.

    • _rotationMatrix

      protected boolean _rotationMatrix
      true if the matrix portion of this transform is only rotation.

    • _uniformScale

      protected boolean _uniformScale
      true if scale is used and scale is guaranteed to be uniform.

  • Constructor Details

    • Transform

      public Transform()
      Constructs a new Transform object.

    • Transform

      public Transform(ReadOnlyTransform source)
      Constructs a new Transform object from the information stored in the given source Transform.
      Parameters:
      source - the source transform
      Throws:
      NullPointerException - if source is null.

    • Transform

      protected Transform(ReadOnlyMatrix3 matrix, ReadOnlyVector3 scale, ReadOnlyVector3 translation, boolean identity, boolean rotationMatrix, boolean uniformScale)
      Internal only constructor, generally used for making an immutable transform.
      Parameters:
      matrix - the matrix
      scale - the scale value
      translation - the translation
      identity - true if it's the identity transform
      rotationMatrix - true if it's a rotation matrix
      uniformScale - true if it's the scale is uniform
      Throws:
      NullPointerException - if a param is null.

  • Method Details

    • getMatrix

      public ReadOnlyMatrix3 getMatrix()
      Specified by:
      getMatrix in interface ReadOnlyTransform

    • getTranslation

      public ReadOnlyVector3 getTranslation()
      Specified by:
      getTranslation in interface ReadOnlyTransform

    • getScale

      public ReadOnlyVector3 getScale()
      Specified by:
      getScale in interface ReadOnlyTransform

    • isIdentity

      public boolean isIdentity()
      Specified by:
      isIdentity in interface ReadOnlyTransform
      Returns:
      true if this transform is guaranteed to be the identity matrix.

    • isRotationMatrix

      public boolean isRotationMatrix()
      Specified by:
      isRotationMatrix in interface ReadOnlyTransform
      Returns:
      true if the matrix portion of this transform is only rotation.

    • isUniformScale

      public boolean isUniformScale()
      Specified by:
      isUniformScale in interface ReadOnlyTransform
      Returns:
      true if scale is used and scale is guaranteed to be uniform.

    • setIdentity

      public Transform setIdentity()
      Resets this transform to identity and resets all flags.
      Returns:
      this Transform for chaining.

    • setRotation

      public Transform setRotation(ReadOnlyMatrix3 rotation)
      Sets the matrix portion of this transform to the given value. NB: Calling this with a matrix that is not purely rotational (orthonormal) will result in a Transform whose scale comes from its matrix. Further attempts to set scale directly will throw an error.
      Parameters:
      rotation - our new matrix.
      Returns:
      this transform for chaining.
      Throws:
      NullPointerException - if rotation is null.
      See Also:

    • setRotation

      public Transform setRotation(ReadOnlyQuaternion rotation)
      Sets the matrix portion of this transform to the rotational value of the given Quaternion. Calling this allows scale to be set and used.
      Parameters:
      rotation - the rotation quaternion
      Returns:
      this transform for chaining.
      Throws:
      NullPointerException - if rotation is null.

    • setTranslation

      public Transform setTranslation(ReadOnlyVector3 translation)
      Sets the translation portion of this transform to the given value.
      Parameters:
      translation - the translation vector
      Returns:
      this transform for chaining.
      Throws:
      NullPointerException - if translation is null.

    • setTranslation

      public Transform setTranslation(double x, double y, double z)
      Sets the translation portion of this transform to the given values.
      Parameters:
      x - the x value
      y - the y value
      z - the z value
      Returns:
      this transform for chaining.

    • setScale

      public Transform setScale(ReadOnlyVector3 scale)
      Sets the scale portion of this transform to the given value.
      Parameters:
      scale - the scale value
      Returns:
      this transform for chaining.
      Throws:
      NullPointerException - if scale is null.
      TransformException - if this transform has a generic 3x3 matrix set.
      IllegalArgumentException - if scale is (0,0,0)

    • setScale

      public Transform setScale(double x, double y, double z)
      Sets the scale portion of this transform to the given values.
      Parameters:
      x - the x value
      y - the y value
      z - the z value
      Returns:
      this transform for chaining.
      Throws:
      NullPointerException - if scale is null.
      TransformException - if this transform has a generic 3x3 matrix set.
      IllegalArgumentException - if scale is (0,0,0)

    • setScale

      public Transform setScale(double uniformScale)
      Sets the scale portion of this transform to the given value as a vector (u, u, u)
      Parameters:
      uniformScale - the uniform scale
      Returns:
      this transform for chaining.
      Throws:
      TransformException - if this transform has a generic 3x3 matrix set.
      IllegalArgumentException - if uniformScale is 0

    • set

      public Transform set(ReadOnlyTransform source)
      Copies the given transform values into this transform object.
      Parameters:
      source - the source transform
      Returns:
      this transform for chaining.
      Throws:
      NullPointerException - if source is null.

    • translate

      public Transform translate(double x, double y, double z)
      Locally adds to the translation of this transform.
      Parameters:
      x - the x value
      y - the y value
      z - the z value
      Returns:
      this transform for chaining.

    • translate

      public Transform translate(ReadOnlyVector3 vec)
      Locally adds to the translation of this transform.
      Parameters:
      vec - the vector
      Returns:
      this transform for chaining.

    • applyForward

      public Vector3 applyForward(Vector3 point)
      Locally applies this transform to the given point: P' = M*P+T
      Specified by:
      applyForward in interface ReadOnlyTransform
      Parameters:
      point - the point
      Returns:
      the transformed point.
      Throws:
      NullPointerException - if point is null.

    • applyForward

      public Vector3 applyForward(ReadOnlyVector3 point, Vector3 store)
      Applies this transform to the given point and returns the result in the given store vector: P' = M*P+T
      Specified by:
      applyForward in interface ReadOnlyTransform
      Parameters:
      point - the point
      store - the vector to store our result in. if null, a new vector will be created.
      Returns:
      the transformed point.
      Throws:
      NullPointerException - if point is null.

    • applyInverse

      public Vector3 applyInverse(Vector3 point)
      Locally applies the inverse of this transform to the given point: P' = M^{-1}*(P-T)
      Specified by:
      applyInverse in interface ReadOnlyTransform
      Parameters:
      point - the point
      Returns:
      the transformed point.
      Throws:
      NullPointerException - if point is null.

    • applyInverse

      public Vector3 applyInverse(ReadOnlyVector3 point, Vector3 store)
      Applies the inverse of this transform to the given point and returns the result in the given store vector: P' = M^{-1}*(P-T)
      Specified by:
      applyInverse in interface ReadOnlyTransform
      Parameters:
      point - the point
      store - the vector to store our result in. if null, a new vector will be created.
      Returns:
      the transformed point.
      Throws:
      NullPointerException - if point is null.

    • applyForwardVector

      public Vector3 applyForwardVector(Vector3 vector)
      Locally applies this transform to the given vector: V' = M*V
      Specified by:
      applyForwardVector in interface ReadOnlyTransform
      Parameters:
      vector - the vector
      Returns:
      the transformed vector.
      Throws:
      NullPointerException - if vector is null.

    • applyForwardVector

      public Vector3 applyForwardVector(ReadOnlyVector3 vector, Vector3 store)
      Applies this transform to the given vector and returns the result in the given store vector: V' = M*V
      Specified by:
      applyForwardVector in interface ReadOnlyTransform
      Parameters:
      vector - the vector
      store - the vector to store our result in. if null, a new vector will be created.
      Returns:
      the transformed vector.
      Throws:
      NullPointerException - if vector is null.

    • applyInverseVector

      public Vector3 applyInverseVector(Vector3 vector)
      Locally applies the inverse of this transform to the given vector: V' = M^{-1}*V
      Specified by:
      applyInverseVector in interface ReadOnlyTransform
      Parameters:
      vector - the vector
      Returns:
      the transformed vector.
      Throws:
      NullPointerException - if vector is null.

    • applyInverseVector

      public Vector3 applyInverseVector(ReadOnlyVector3 vector, Vector3 store)
      Applies the inverse of this transform to the given vector and returns the result in the given store vector: V' = M^{-1}*V
      Specified by:
      applyInverseVector in interface ReadOnlyTransform
      Parameters:
      vector - the vector
      store - the vector to store our result in. if null, a new vector will be created.
      Returns:
      the transformed vector.
      Throws:
      NullPointerException - if vector is null.

    • multiply

      public Transform multiply(ReadOnlyTransform transformBy, Transform store)
      Calculates the product of this transform with the given "transformBy" transform (P = this * T) and stores this in store.
      Specified by:
      multiply in interface ReadOnlyTransform
      Parameters:
      transformBy - the second transform involved in the multiplication
      store - the transform to store the result in for return. If null, a new transform object is created and returned. It is NOT safe for store to be the same object as transformBy or "this".
      Returns:
      the product
      Throws:
      NullPointerException - if transformBy is null.

    • updateFlags

      protected void updateFlags(boolean rotationMatrixGuaranteed)
      Updates _rotationMatrix, _uniformScale and _identity based on the current contents of this Transform.
      Parameters:
      rotationMatrixGuaranteed - true if we know for sure that the _matrix component is rotational.

    • invert

      public Transform invert(Transform store)
      Calculates the inverse of this transform.
      Specified by:
      invert in interface ReadOnlyTransform
      Parameters:
      store - the transform to store the result in for return. If null, a new transform object is created and returned. It IS safe for store to be the same object as "this".
      Returns:
      the inverted transform

    • getHomogeneousMatrix

      public Matrix4 getHomogeneousMatrix(Matrix4 store)
      Specified by:
      getHomogeneousMatrix in interface ReadOnlyTransform
      Parameters:
      store - the matrix to store the result in for return. If null, a new matrix object is created and returned.
      Returns:
      this transform represented as a 4x4 matrix: 
       R R R Tx
 R R R Ty
 R R R Tz
 0 0 0 1

    • getGLApplyMatrix

      public void getGLApplyMatrix(DoubleBuffer store)
      Description copied from interface: ReadOnlyTransform
      Populates an nio double buffer with data from this transform to use as a model view matrix in OpenGL. This is done as efficiently as possible, not touching positions 3, 7, 11 and 15.
      Specified by:
      getGLApplyMatrix in interface ReadOnlyTransform
      Parameters:
      store - double buffer to store in. Assumes a size of 16 and that position 3, 7 and 11 are already set as 0.0 and 15 is already 1.0.

    • getGLApplyMatrix

      public void getGLApplyMatrix(FloatBuffer store)
      Description copied from interface: ReadOnlyTransform
      Populates an nio float buffer with data from this transform to use as a model view matrix in OpenGL. This is done as efficiently as possible, not touching positions 3, 7, 11 and 15.
      Specified by:
      getGLApplyMatrix in interface ReadOnlyTransform
      Parameters:
      store - float buffer to store in. Assumes a size of 16 and that position 3, 7 and 11 are already set as 0.0f and 15 is already 1.0f.

    • fromHomogeneousMatrix

      public Transform fromHomogeneousMatrix(ReadOnlyMatrix4 matrix)
      Reads in a 4x4 matrix as a 3x3 matrix and translation.
      Parameters:
      matrix - the homogeneous matrix
      Returns:
      this matrix for chaining.
      Throws:
      NullPointerException - if matrix is null.

    • isValid

      public static boolean isValid(ReadOnlyTransform transform)
      Check a transform... if it is null or one of its members are invalid, return false. Else return true.
      Parameters:
      transform - the transform to check
      Returns:
      true or false as stated above.

    • toString

      public String toString()
      Overrides:
      toString in class Object
      Returns:
      the string representation of this triangle.

    • hashCode

      public int hashCode()
      Overrides:
      hashCode in class Object
      Returns:
      returns a unique code for this transform object based on its values.

    • equals

      public boolean equals(Object o)
      Overrides:
      equals in class Object
      Parameters:
      o - the object to compare for equality
      Returns:
      true if this transform and the provided transform have the same values.

    • strictEquals

      public boolean strictEquals(Object o)
      Specified by:
      strictEquals in interface ReadOnlyTransform
      Parameters:
      o - the object to compare for equality
      Returns:
      true if this transform and the provided transform have the exact same double values.

    • clone

      public Transform clone()
      Specified by:
      clone in interface ReadOnlyTransform
      Overrides:
      clone in class Object

    • getClassTag

      public Class<? extends Transform> getClassTag()
      Specified by:
      getClassTag in interface Savable

    • write

      public void write(OutputCapsule capsule) throws IOException
      Specified by:
      write in interface Savable
      Throws:
      IOException

    • read

      public void read(InputCapsule capsule) throws IOException
      Specified by:
      read in interface Savable
      Throws:
      IOException

    • readExternal

      public void readExternal(ObjectInput in) throws IOException, ClassNotFoundException
      Used with serialization. Not to be called manually.
      Specified by:
      readExternal in interface Externalizable
      Parameters:
      in - ObjectInput
      Throws:
      IOException - if something wrong occurs while reading
      ClassNotFoundException - if a class is not found

    • writeExternal

      public void writeExternal(ObjectOutput out) throws IOException
      Used with serialization. Not to be called manually.
      Specified by:
      writeExternal in interface Externalizable
      Parameters:
      out - ObjectOutput
      Throws:
      IOException - if something wrong occurs while writing

    • fetchTempInstance

      public static final Transform fetchTempInstance()
      Returns:
      An instance of Transform that is intended for temporary use in calculations and so forth. Multiple calls to the method should return instances of this class that are not currently in use.

    • releaseTempInstance

      public static final void releaseTempInstance(Transform trans)
      Releases a Transform back to be used by a future call to fetchTempInstance. TAKE CARE: this Transform object should no longer have other classes referencing it or "Bad Things" will happen.
      Parameters:
      trans - the Transform to release.