Package com.ardor3d.math

Class Vector3

java.lang.Object
com.ardor3d.math.Vector3
All Implemented Interfaces:
Poolable, ReadOnlyVector3, Savable, Externalizable, Serializable, Cloneable
public class Vector3 extends Object implements Cloneable, Savable, Externalizable, ReadOnlyVector3, Poolable
Vector3 represents a point or vector in a three dimensional system. This implementation stores its data in double-precision.
See Also:

  • Field Details

  • Constructor Details

    • Vector3

      public Vector3()
      Constructs a new vector set to (0, 0, 0).

    • Vector3

      public Vector3(ReadOnlyVector3 src)
      Constructs a new vector set to the (x, y, z) values of the given source vector.
      Parameters:
      src - the source vector

    • Vector3

      public Vector3(double x, double y, double z)
      Constructs a new vector set to (x, y, z).
      Parameters:
      x - the x value
      y - the y value
      z - the z value

  • Method Details

    • getX

      public double getX()
      Specified by:
      getX in interface ReadOnlyVector3

    • getY

      public double getY()
      Specified by:
      getY in interface ReadOnlyVector3

    • getZ

      public double getZ()
      Specified by:
      getZ in interface ReadOnlyVector3

    • getXf

      public float getXf()
      Specified by:
      getXf in interface ReadOnlyVector3
      Returns:
      x as a float, to decrease need for explicit casts.

    • getYf

      public float getYf()
      Specified by:
      getYf in interface ReadOnlyVector3
      Returns:
      y as a float, to decrease need for explicit casts.

    • getZf

      public float getZf()
      Specified by:
      getZf in interface ReadOnlyVector3
      Returns:
      z as a float, to decrease need for explicit casts.

    • getValue

      public double getValue(int index)
      Specified by:
      getValue in interface ReadOnlyVector3
      Parameters:
      index - the field index
      Returns:
      x value if index == 0, y value if index == 1 or z value if index == 2
      Throws:
      IllegalArgumentException - if index is not one of 0, 1, 2.

    • setValue

      public void setValue(int index, double value)
      Parameters:
      index - which field index in this vector to set.
      value - to set to one of x, y or z.
      Throws:
      IllegalArgumentException - if index is not one of 0, 1, 2.

    • toArray

      public double[] toArray(double[] store)
      Stores the double values of this vector in the given double array.
      Specified by:
      toArray in interface ReadOnlyVector3
      Parameters:
      store - if null, a new double[3] array is created.
      Returns:
      the double array
      Throws:
      ArrayIndexOutOfBoundsException - if store is not at least length 3.

    • toFloatArray

      public float[] toFloatArray(float[] store)
      Stores the double values of this vector in the given float array.
      Parameters:
      store - if null, a new float[3] array is created.
      Returns:
      the float array
      Throws:
      NullPointerException - if store is null.
      ArrayIndexOutOfBoundsException - if store is not at least length 3.

    • setX

      public void setX(double x)
      Sets the first component of this vector to the given double value.
      Parameters:
      x - the x value

    • setY

      public void setY(double y)
      Sets the second component of this vector to the given double value.
      Parameters:
      y - the y value

    • setZ

      public void setZ(double z)
      Sets the third component of this vector to the given double value.
      Parameters:
      z - the z value

    • set

      public Vector3 set(double x, double y, double z)
      Sets the value of this vector to (x, y, z)
      Parameters:
      x - the x value
      y - the y value
      z - the z value
      Returns:
      this vector for chaining

    • set

      public Vector3 set(ReadOnlyVector3 source)
      Sets the value of this vector to the (x, y, z) values of the provided source vector.
      Parameters:
      source - the source vector
      Returns:
      this vector for chaining
      Throws:
      NullPointerException - if source is null.

    • zero

      public Vector3 zero()
      Sets the value of this vector to (0, 0, 0)
      Returns:
      this vector for chaining

    • add

      public Vector3 add(double x, double y, double z, Vector3 store)
      Adds the given values to those of this vector and returns them in store * @param store the vector to store the result in for return. If null, a new vector object is created and returned. .
      Specified by:
      add in interface ReadOnlyVector3
      Parameters:
      x - the x value
      y - the y value
      z - the z value
      store - the vector to store the result in for return. If null, a new vector object is created and returned.
      Returns:
      (this.x + x, this.y + y, this.z + z)

    • addLocal

      public Vector3 addLocal(double x, double y, double z)
      Increments the values of this vector with the given x, y and z values.
      Parameters:
      x - the x value
      y - the y value
      z - the z value
      Returns:
      this vector for chaining

    • add

      public Vector3 add(ReadOnlyVector3 source, Vector3 store)
      Adds the values of the given source vector to those of this vector and returns them in store.
      Specified by:
      add in interface ReadOnlyVector3
      Parameters:
      source - the source vector
      store - the vector to store the result in for return. If null, a new vector object is created and returned.
      Returns:
      (this.x + source.x, this.y + source.y, this.z + source.z)
      Throws:
      NullPointerException - if source is null.

    • addLocal

      public Vector3 addLocal(ReadOnlyVector3 source)
      Increments the values of this vector with the x, y and z values of the given vector.
      Parameters:
      source - the source vector
      Returns:
      this vector for chaining
      Throws:
      NullPointerException - if source is null.

    • subtract

      public Vector3 subtract(double x, double y, double z, Vector3 store)
      Subtracts the given values from those of this vector and returns them in store.
      Specified by:
      subtract in interface ReadOnlyVector3
      Parameters:
      x - the x value
      y - the y value
      z - the z value
      store - the vector to store the result in for return. If null, a new vector object is created and returned.
      Returns:
      (this.x - x, this.y - y, this.z - z)

    • subtractLocal

      public Vector3 subtractLocal(double x, double y, double z)
      Decrements the values of this vector by the given x, y and z values.
      Parameters:
      x - the x value
      y - the y value
      z - the z value
      Returns:
      this vector for chaining

    • subtract

      public Vector3 subtract(ReadOnlyVector3 source, Vector3 store)
      Subtracts the values of the given source vector from those of this vector and returns them in store.
      Specified by:
      subtract in interface ReadOnlyVector3
      Parameters:
      source - the source vector
      store - the vector to store the result in for return. If null, a new vector object is created and returned.
      Returns:
      (this.x - source.x, this.y - source.y, this.z - source.z)
      Throws:
      NullPointerException - if source is null.

    • subtractLocal

      public Vector3 subtractLocal(ReadOnlyVector3 source)
      Decrements the values of this vector by the x, y and z values from the given source vector.
      Parameters:
      source - the source vector
      Returns:
      this vector for chaining
      Throws:
      NullPointerException - if source is null.

    • multiply

      public Vector3 multiply(double scalar, Vector3 store)
      Multiplies the values of this vector by the given scalar value and returns the result in store.
      Specified by:
      multiply in interface ReadOnlyVector3
      Parameters:
      scalar - the scalar value
      store - the vector to store the result in for return. If null, a new vector object is created and returned.
      Returns:
      a new vector (this.x * scalar, this.y * scalar, this.z * scalar)

    • multiplyLocal

      public Vector3 multiplyLocal(double scalar)
      Internally modifies the values of this vector by multiplying them each by the given scalar value.
      Parameters:
      scalar - the scalar value
      Returns:
      this vector for chaining

    • multiply

      public Vector3 multiply(ReadOnlyVector3 scale, Vector3 store)
      Multiplies the values of this vector by the given scale values and returns the result in store.
      Specified by:
      multiply in interface ReadOnlyVector3
      Parameters:
      scale - the scale value
      store - the vector to store the result in for return. If null, a new vector object is created and returned.
      Returns:
      a new vector (this.x * scale.x, this.y * scale.y, this.z * scale.z)

    • multiplyLocal

      public Vector3 multiplyLocal(ReadOnlyVector3 scale)
      Internally modifies the values of this vector by multiplying them each by the given scale values.
      Parameters:
      scale - the scale value
      Returns:
      this vector for chaining

    • multiply

      public Vector3 multiply(double x, double y, double z, Vector3 store)
      Multiplies the values of this vector by the given scale values and returns the result in store.
      Specified by:
      multiply in interface ReadOnlyVector3
      Parameters:
      x - the x value
      y - the y value
      z - the z value
      store - the vector to store the result in for return. If null, a new vector object is created and returned.
      Returns:
      a new vector (this.x * scale.x, this.y * scale.y, this.z * scale.z)

    • multiplyLocal

      public Vector3 multiplyLocal(double x, double y, double z)
      Internally modifies the values of this vector by multiplying them each by the given scale values.
      Parameters:
      x - the x value
      y - the y value
      z - the z value
      Returns:
      this vector for chaining

    • divide

      public Vector3 divide(double scalar, Vector3 store)
      Divides the values of this vector by the given scalar value and returns the result in store.
      Specified by:
      divide in interface ReadOnlyVector3
      Parameters:
      scalar - the scalar value
      store - the vector to store the result in for return. If null, a new vector object is created and returned.
      Returns:
      a new vector (this.x / scalar, this.y / scalar, this.z / scalar)

    • divideLocal

      public Vector3 divideLocal(double scalar)
      Internally modifies the values of this vector by dividing them each by the given scalar value.
      Parameters:
      scalar - the scalar value
      Returns:
      this vector for chaining
      Throws:
      ArithmeticException - if scalar is 0

    • divide

      public Vector3 divide(ReadOnlyVector3 scale, Vector3 store)
      Divides the values of this vector by the given scale values and returns the result in store.
      Specified by:
      divide in interface ReadOnlyVector3
      Parameters:
      scale - the scale value
      store - the vector to store the result in for return. If null, a new vector object is created and returned.
      Returns:
      a new vector (this.x / scale.x, this.y / scale.y, this.z / scale.z)

    • divideLocal

      public Vector3 divideLocal(ReadOnlyVector3 scale)
      Internally modifies the values of this vector by dividing them each by the given scale values.
      Parameters:
      scale - the scale value
      Returns:
      this vector for chaining

    • divide

      public Vector3 divide(double x, double y, double z, Vector3 store)
      Divides the values of this vector by the given scale values and returns the result in store.
      Specified by:
      divide in interface ReadOnlyVector3
      Parameters:
      x - the x value
      y - the y value
      z - the z value
      store - the vector to store the result in for return. If null, a new vector object is created and returned.
      Returns:
      a new vector (this.x / scale.x, this.y / scale.y, this.z / scale.z)

    • divideLocal

      public Vector3 divideLocal(double x, double y, double z)
      Internally modifies the values of this vector by dividing them each by the given scale values.
      Parameters:
      x - the x value
      y - the y value
      z - the z value
      Returns:
      this vector for chaining

    • scaleAddLocal

      public Vector3 scaleAddLocal(double scale, ReadOnlyVector3 add)
      Internally modifies this vector by multiplying its values with a given scale value, then adding a given "add" value.
      Parameters:
      scale - the value to multiply this vector by.
      add - the value to add to the result
      Returns:
      this vector for chaining

    • scaleAdd

      public Vector3 scaleAdd(double scale, ReadOnlyVector3 add, Vector3 store)
      Scales this vector by multiplying its values with a given scale value, then adding a given "add" value. The result is store in the given store parameter.
      Specified by:
      scaleAdd in interface ReadOnlyVector3
      Parameters:
      scale - the value to multiply by.
      add - the value to add
      store - the vector to store the result in for return. If null, a new vector object is created and returned.
      Returns:
      the store variable

    • negate

      public Vector3 negate(Vector3 store)
      Specified by:
      negate in interface ReadOnlyVector3
      Parameters:
      store - the vector to store the result in for return. If null, a new vector object is created and returned.
      Returns:
      same as multiply(-1, store)

    • negateLocal

      public Vector3 negateLocal()
      Returns:
      same as multiplyLocal(-1)

    • normalize

      public Vector3 normalize(Vector3 store)
      Creates a new unit length vector from this one by dividing by length. If the length is 0, (ie, if the vector is 0, 0, 0) then a new vector (0, 0, 0) is returned.
      Specified by:
      normalize in interface ReadOnlyVector3
      Parameters:
      store - the vector to store the result in for return. If null, a new vector object is created and returned.
      Returns:
      a new unit vector (or 0, 0, 0 if this unit is 0 length)

    • normalizeLocal

      public Vector3 normalizeLocal()
      Converts this vector into a unit vector by dividing it internally by its length. If the length is 0, (ie, if the vector is 0, 0, 0) then no action is taken.
      Returns:
      this vector for chaining

    • lerp

      public Vector3 lerp(ReadOnlyVector3 endVec, double scalar, Vector3 store)
      Performs a linear interpolation between this vector and the given end vector, using the given scalar as a percent. iow, if changeAmnt is closer to 0, the result will be closer to the current value of this vector and if it is closer to 1, the result will be closer to the end value. The result is returned as a new vector object.
      Specified by:
      lerp in interface ReadOnlyVector3
      Parameters:
      endVec - the end vector
      scalar - the scalar value
      store - the vector to store the result in for return. If null, a new vector object is created and returned.
      Returns:
      a new vector as described above.
      Throws:
      NullPointerException - if endVec is null.

    • lerpLocal

      public Vector3 lerpLocal(ReadOnlyVector3 endVec, double scalar)
      Performs a linear interpolation between this vector and the given end vector, using the given scalar as a percent. iow, if changeAmnt is closer to 0, the result will be closer to the current value of this vector and if it is closer to 1, the result will be closer to the end value. The result is stored back in this vector.
      Parameters:
      endVec - the end vector
      scalar - the scalar value
      Returns:
      this vector for chaining
      Throws:
      NullPointerException - if endVec is null.

    • lerp

      public static Vector3 lerp(ReadOnlyVector3 beginVec, ReadOnlyVector3 endVec, double scalar, Vector3 store)
      Performs a linear interpolation between the given begin and end vectors, using the given scalar as a percent. iow, if changeAmnt is closer to 0, the result will be closer to the begin value and if it is closer to 1, the result will be closer to the end value. The result is returned as a new vector object.
      Parameters:
      beginVec - the begin vector
      endVec - the end vector
      scalar - the scalar as a percent.
      store - the vector to store the result in for return. If null, a new vector object is created and returned. It IS safe for store to be the same as the begin or end vector.
      Returns:
      a new vector as described above.
      Throws:
      NullPointerException - if beginVec or endVec are null.

    • lerpLocal

      public Vector3 lerpLocal(ReadOnlyVector3 beginVec, ReadOnlyVector3 endVec, double scalar)
      Performs a linear interpolation between the given begin and end vectors, using the given scalar as a percent. iow, if scalar is closer to 0, the result will be closer to the begin value and if it is closer to 1, the result will be closer to the end value. The result is stored back in this vector.
      Parameters:
      beginVec - the begin vector
      endVec - the end vector
      scalar - the scalar as a percent.
      Returns:
      this vector for chaining
      Throws:
      NullPointerException - if beginVec or endVec are null.

    • length

      public double length()
      Specified by:
      length in interface ReadOnlyVector3
      Returns:
      the magnitude or distance between the origin (0, 0, 0) and the point described by this vector (x, y, z). Effectively the square root of the value returned by lengthSquared().

    • lengthSquared

      public double lengthSquared()
      Specified by:
      lengthSquared in interface ReadOnlyVector3
      Returns:
      the squared magnitude or squared distance between the origin (0, 0, 0) and the point described by this vector (x, y, z)

    • distanceSquared

      public double distanceSquared(double x, double y, double z)
      Specified by:
      distanceSquared in interface ReadOnlyVector3
      Parameters:
      x - the x value
      y - the y value
      z - the z value
      Returns:
      the squared distance between the point described by this vector and the given x, y, z point. When comparing the relative distance between two points it is usually sufficient to compare the squared distances, thus avoiding an expensive square root operation.

    • distanceSquared

      public double distanceSquared(ReadOnlyVector3 destination)
      Specified by:
      distanceSquared in interface ReadOnlyVector3
      Parameters:
      destination - the destination
      Returns:
      the squared distance between the point described by this vector and the given destination point. When comparing the relative distance between two points it is usually sufficient to compare the squared distances, thus avoiding an expensive square root operation.
      Throws:
      NullPointerException - if destination is null.

    • distance

      public double distance(double x, double y, double z)
      Specified by:
      distance in interface ReadOnlyVector3
      Parameters:
      x - the x value
      y - the y value
      z - the z value
      Returns:
      the distance between the point described by this vector and the given x, y, z point.

    • distance

      public double distance(ReadOnlyVector3 destination)
      Specified by:
      distance in interface ReadOnlyVector3
      Parameters:
      destination - the destination
      Returns:
      the distance between the point described by this vector and the given destination point.
      Throws:
      NullPointerException - if destination is null.

    • dot

      public double dot(double x, double y, double z)
      Specified by:
      dot in interface ReadOnlyVector3
      Parameters:
      x - the x value
      y - the y value
      z - the z value
      Returns:
      the dot product of this vector with the given x, y, z values.

    • dot

      public double dot(ReadOnlyVector3 vec)
      Specified by:
      dot in interface ReadOnlyVector3
      Parameters:
      vec - the vector
      Returns:
      the dot product of this vector with the x, y, z values of the given vector.
      Throws:
      NullPointerException - if vec is null.

    • cross

      public Vector3 cross(double x, double y, double z, Vector3 store)
      Specified by:
      cross in interface ReadOnlyVector3
      Parameters:
      x - the x value
      y - the y value
      z - the z value
      store - the vector to store the result in for return. If null, a new vector object is created and returned.
      Returns:
      the cross product of this vector with the given x, y, z values.

    • cross

      public Vector3 cross(ReadOnlyVector3 vec, Vector3 store)
      Specified by:
      cross in interface ReadOnlyVector3
      Parameters:
      vec - the vector
      store - the vector to store the result in for return. If null, a new vector object is created and returned.
      Returns:
      the cross product of this vector with the given vector's x, y, z values
      Throws:
      NullPointerException - if vec is null.

    • crossLocal

      public Vector3 crossLocal(double x, double y, double z)
      Parameters:
      x - the x value
      y - the y value
      z - the z value
      Returns:
      this vector, set to the cross product of this vector with the given x, y, z values.

    • crossLocal

      public Vector3 crossLocal(ReadOnlyVector3 vec)
      Parameters:
      vec - the vector
      Returns:
      this vector, set to the cross product of this vector with the given vector's x, y, z values
      Throws:
      NullPointerException - if vec is null.

    • smallestAngleBetween

      public double smallestAngleBetween(ReadOnlyVector3 otherVector)
      Specified by:
      smallestAngleBetween in interface ReadOnlyVector3
      Parameters:
      otherVector - a unit vector to find the angle against
      Returns:
      the minimum angle (in radians) between two vectors. It is assumed that both this vector and the given vector are unit vectors (normalized).
      Throws:
      NullPointerException - if otherVector is null.

    • isValid

      public static boolean isValid(ReadOnlyVector3 vector)
      Check a vector... if it is null or its doubles are NaN or infinite, return false. Else return true.
      Parameters:
      vector - the vector to check
      Returns:
      true or false as stated above.

    • isInfinite

      public static boolean isInfinite(ReadOnlyVector3 vector)
      Check if a vector is non-null and has infinite values.
      Parameters:
      vector - the vector to check
      Returns:
      true or false as stated above.

    • toString

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

    • hashCode

      public int hashCode()
      Overrides:
      hashCode in class Object
      Returns:
      returns a unique code for this vector object based on its values. If two vectors are numerically equal, they will return the same hash code value.

    • equals

      public boolean equals(Object o)
      Compares this object against the specified object
      Overrides:
      equals in class Object
      Parameters:
      o - the object to compare for equality
      Returns:
      true if this vector and the provided vector have the same x, y and z values.

    • clone

      public Vector3 clone()
      Specified by:
      clone in interface ReadOnlyVector3
      Overrides:
      clone in class Object

    • getClassTag

      public Class<? extends Vector3> 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 Vector3 fetchTempInstance()
      Returns:
      An instance of Vector3 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(Vector3 vec)
      Releases a Vector3 back to be used by a future call to fetchTempInstance. TAKE CARE: this Vector3 object should no longer have other classes referencing it or "Bad Things" will happen.
      Parameters:
      vec - the Vector3 to release.