Package com.jme3.math

Class Transform

java.lang.Object
com.jme3.math.Transform
All Implemented Interfaces:
Savable, Serializable, Cloneable
public final class Transform extends Object implements Savable, Cloneable, Serializable
A 3-D coordinate transform composed of translation, rotation, and scaling. The order of application is: scale, then rotate, then translate.

Started July 16, 2004

See Also:

  • Field Details

    • IDENTITY

      public static final Transform IDENTITY
      Shared instance of the identity transform. Do not modify!

  • Constructor Details

    • Transform

      public Transform(Vector3f translation, Quaternion rot)
      Instantiates a coordinate transform without scaling.
      Parameters:
      translation - the desired translation (not null, unaffected)
      rot - the desired rotation (not null, unaffected)

    • Transform

      public Transform(Vector3f translation, Quaternion rot, Vector3f scale)
      Instantiates a coordinate transform with scaling.
      Parameters:
      translation - the desired translation (not null, unaffected)
      rot - the desired rotation (not null, unaffected)
      scale - the desired scaling (not null, unaffected)

    • Transform

      public Transform(Vector3f translation)
      Instantiates a translation-only transform.
      Parameters:
      translation - the desired translation (not null, unaffected)

    • Transform

      public Transform(Quaternion rot)
      Instantiates a rotation-only transform.
      Parameters:
      rot - the desired rotation (not null, unaffected)

    • Transform

      public Transform()
      Instantiates an identity transform: no translation, no rotation, and no scaling.

  • Method Details

    • setRotation

      public Transform setRotation(Quaternion rot)
      Sets the rotation component to the argument.
      Parameters:
      rot - the desired rotation value (not null, unaffected)
      Returns:
      the (modified) current instance (for chaining)

    • setTranslation

      public Transform setTranslation(Vector3f trans)
      Sets the translation component to the argument.
      Parameters:
      trans - the desired offsets (not null, unaffected)
      Returns:
      the (modified) current instance (for chaining)

    • getTranslation

      public Vector3f getTranslation()
      Returns the translation component.
      Returns:
      the pre-existing instance (not null)

    • setScale

      public Transform setScale(Vector3f scale)
      Sets the scaling component to the argument.
      Parameters:
      scale - the desired scale factors (not null, unaffected)
      Returns:
      the (modified) current instance (for chaining)

    • setScale

      public Transform setScale(float scale)
      Sets the scaling component to the argument. This yields uniform scaling.
      Parameters:
      scale - the desired scale factor for all local axes
      Returns:
      the (modified) current instance (for chaining)

    • getScale

      public Vector3f getScale()
      Returns the scaling component.
      Returns:
      the pre-existing instance (not null)

    • getTranslation

      public Vector3f getTranslation(Vector3f trans)
      Copies the translation component to the argument. If the argument is null, a new Vector3f is created to hold the value. Either way, the current instance is unaffected, unless the argument is its scaling component.
      Parameters:
      trans - storage for the result (modified if not null)
      Returns:
      the translation offsets (either trans or a new Vector3f)

    • getRotation

      public Quaternion getRotation(Quaternion quat)
      Copies the rotation component to the argument. If the argument is null, a new Quaternion is created to hold the value. Either way, the current instance is unaffected.
      Parameters:
      quat - storage for the result (modified if not null)
      Returns:
      the rotation value (either quat or a new Quaternion)

    • getRotation

      public Quaternion getRotation()
      Returns the rotation component.
      Returns:
      the pre-existing instance (not null)

    • getScale

      public Vector3f getScale(Vector3f scale)
      Copies the scaling component to the argument. If the argument is null, a new Vector3f is created to hold the value. Either way, the current instance is unaffected, unless the argument is its translation component.
      Parameters:
      scale - storage for the result (modified if not null)
      Returns:
      the scale factors (either scale or a new Vector3f)

    • interpolateTransforms

      public void interpolateTransforms(Transform t1, Transform t2, float delta)
      Interpolates quickly between the specified transforms, using Quaternion.nlerp(com.jme3.math.Quaternion, float) and Vector3f.interpolateLocal(com.jme3.math.Vector3f, com.jme3.math.Vector3f, float).
      Parameters:
      t1 - the desired value when delta=0 (not null, unaffected unless it's this)
      t2 - the desired value when delta=1 (not null, unaffected unless it's this)
      delta - the fractional change amount

    • combineWithParent

      public Transform combineWithParent(Transform parent)
      Combines with the argument and returns the (modified) current instance. This method is used to combine Node and Spatial transforms.
      Parameters:
      parent - the parent transform (not null, parent.rot.norm() approximately equal to 1, unaffected unless it's this)
      Returns:
      the (modified) current instance (for chaining)

    • setTranslation

      public Transform setTranslation(float x, float y, float z)
      Sets the translation component to the specified values.
      Parameters:
      x - the desired X offset
      y - the desired Y offset
      z - the desired Z offset
      Returns:
      the (modified) current instance (for chaining)

    • setScale

      public Transform setScale(float x, float y, float z)
      Sets the scaling component to the specified values.
      Parameters:
      x - the desired X scale factor
      y - the desired Y scale factor
      z - the desired Z scale factor
      Returns:
      the (modified) current instance (for chaining)

    • transformVector

      public Vector3f transformVector(Vector3f in, Vector3f store)
      Transforms the specified coordinates and returns the result in store. If the store is null, a new Vector3f is created to hold the value. Either way, the current instance is unaffected, unless store is its translation or scaling.

      The transform's quaternion is assumed to be normalized. No error checking is performed; the caller should ensure that rot.norm() is approximately equal to 1.

      Parameters:
      in - the coordinates to transform (not null, unaffected)
      store - storage for the result (modified if not null)
      Returns:
      the transformed coordinates (either store or a new Vector3f)

    • transformInverseVector

      public Vector3f transformInverseVector(Vector3f in, Vector3f store)
      Applies the inverse transform to the specified coordinates and returns the result in store. If the store is null, a new Vector3f is created to hold the value. Either way, the current instance is unaffected, unless store is its translation or scaling.

      The transform's quaternion is assumed to be normalized. No error checking is performed; the caller should ensure that rot.norm() is approximately equal to 1.

      Parameters:
      in - the coordinates to transform (not null, unaffected unless it's store)
      store - storage for the result (modified if not null)
      Returns:
      the transformed coordinates (either store or a new Vector3f)

    • toTransformMatrix

      public Matrix4f toTransformMatrix()
      Creates an equivalent transform matrix. The current instance is unaffected.
      Returns:
      a new Matrix4f

    • toTransformMatrix

      public Matrix4f toTransformMatrix(Matrix4f store)
      Converts to an equivalent transform matrix. The current instance is unaffected.
      Parameters:
      store - storage for the result (modified if not null)
      Returns:
      a transform matrix (either store or a new Matrix4f)

    • fromTransformMatrix

      public void fromTransformMatrix(Matrix4f mat)
      Sets the current instance from a transform matrix. Any reflection or shear in the matrix is lost -- in other words, it may not be possible to recreate the original matrix from the result.

      After this method is invoked, all components of scale will be non-negative, even if mat includes reflection.

      Parameters:
      mat - the input matrix (not null, unaffected)

    • invert

      public Transform invert()
      Returns the inverse. The current instance is unaffected.

      Assumes (but does not verify) that the scale factors are all positive. If any component of scale is negative or zero, the result is undefined.

      Returns:
      a new Transform

    • loadIdentity

      public void loadIdentity()
      Sets the current instance to the identity transform: translation=(0,0,0) scaling=(1,1,1) rotation=(0,0,0,1).

    • isIdentity

      public boolean isIdentity()
      Tests for exact identity. The current instance is unaffected.
      Returns:
      true if equal to IDENTITY, otherwise false

    • hashCode

      public int hashCode()
      Returns a hash code. If two transforms have identical values, they will have the same hash code. The current instance is unaffected.
      Overrides:
      hashCode in class Object
      Returns:
      a 32-bit value for use in hashing

    • equals

      public boolean equals(Object obj)
      Tests for exact equality with the argument, distinguishing -0 from 0. If obj is null, false is returned. Either way, the current instance is unaffected.
      Overrides:
      equals in class Object
      Parameters:
      obj - the object to compare (may be null, unaffected)
      Returns:
      true if this and obj have identical values, otherwise false

    • toString

      public String toString()
      Returns a string representation of the transform, which is unaffected. For example, the identity transform is represented by: 
       Transform[ 0.0, 0.0, 0.0]
 [ 0.0, 0.0, 0.0, 1.0]
 [ 1.0 , 1.0, 1.0]
      Overrides:
      toString in class Object
      Returns:
      the string representation (not null, not empty)

    • set

      public Transform set(Transform transform)
      Copies all 3 components from the argument.
      Parameters:
      transform - The Transform to copy (not null, unaffected)
      Returns:
      the (modified) current instance (for chaining)

    • write

      public void write(JmeExporter e) throws IOException
      Serializes to the argument, for example when saving to a J3O file. The current instance is unaffected.
      Specified by:
      write in interface Savable
      Parameters:
      e - (not null)
      Throws:
      IOException - from the exporter

    • read

      public void read(JmeImporter importer) throws IOException
      De-serializes from the argument, for example when loading from a J3O file.
      Specified by:
      read in interface Savable
      Parameters:
      importer - (not null)
      Throws:
      IOException - from the importer

    • clone

      public Transform clone()
      Creates a copy. The current instance is unaffected.
      Overrides:
      clone in class Object
      Returns:
      a new instance, equivalent to the current one