Class Vector4

java.lang.Object
com.ardor3d.math.Vector4
All Implemented Interfaces:
Poolable, ReadOnlyVector4, Savable, Externalizable, Serializable, Cloneable

public class Vector4 extends Object implements Cloneable, Savable, Externalizable, ReadOnlyVector4, Poolable
Vector4 represents a point or vector in a four dimensional system. This implementation stores its data in double-precision.
See Also:
  • Field Details

    • ZERO

      public static final ReadOnlyVector4 ZERO
      0, 0, 0, 0
    • ONE

      public static final ReadOnlyVector4 ONE
      1, 1, 1, 1
    • NEG_ONE

      public static final ReadOnlyVector4 NEG_ONE
      -1, -1, -1, -1
    • UNIT_X

      public static final ReadOnlyVector4 UNIT_X
      1, 0, 0, 0
    • NEG_UNIT_X

      public static final ReadOnlyVector4 NEG_UNIT_X
      -1, 0, 0, 0
    • UNIT_Y

      public static final ReadOnlyVector4 UNIT_Y
      0, 1, 0, 0
    • NEG_UNIT_Y

      public static final ReadOnlyVector4 NEG_UNIT_Y
      0, -1, 0, 0
    • UNIT_Z

      public static final ReadOnlyVector4 UNIT_Z
      0, 0, 1, 0
    • NEG_UNIT_Z

      public static final ReadOnlyVector4 NEG_UNIT_Z
      0, 0, -1, 0
    • UNIT_W

      public static final ReadOnlyVector4 UNIT_W
      0, 0, 0, 1
    • NEG_UNIT_W

      public static final ReadOnlyVector4 NEG_UNIT_W
      0, 0, 0, -1
    • _x

      protected double _x
    • _y

      protected double _y
    • _z

      protected double _z
    • _w

      protected double _w
  • Constructor Details

    • Vector4

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

      public Vector4(ReadOnlyVector4 src)
      Constructs a new vector set to the (x, y, z, w) values of the given source vector.
      Parameters:
      src - the source vector
    • Vector4

      public Vector4(double x, double y, double z, double w)
      Constructs a new vector set to (x, y, z, w).
      Parameters:
      x - the x value
      y - the y value
      z - the z value
      w - the w value
  • Method Details

    • getX

      public double getX()
      Specified by:
      getX in interface ReadOnlyVector4
    • getY

      public double getY()
      Specified by:
      getY in interface ReadOnlyVector4
    • getZ

      public double getZ()
      Specified by:
      getZ in interface ReadOnlyVector4
    • getW

      public double getW()
      Specified by:
      getW in interface ReadOnlyVector4
    • getXf

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

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

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

      public float getWf()
      Specified by:
      getWf in interface ReadOnlyVector4
      Returns:
      w as a float, to decrease need for explicit casts.
    • getValue

      public double getValue(int index)
      Specified by:
      getValue in interface ReadOnlyVector4
      Parameters:
      index - the field index
      Returns:
      x value if index == 0, y value if index == 1, z value if index == 2 or w value if index == 3
      Throws:
      IllegalArgumentException - if index is not one of 0, 1, 2, 3.
    • 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, z or w.
      Throws:
      IllegalArgumentException - if index is not one of 0, 1, 2, 3. if this vector is read only
    • toArray

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

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

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

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

      public void setW(double w)
      Sets the fourth component of this vector to the given double value.
      Parameters:
      w - the w value to set
    • set

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

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

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

      public Vector4 add(double x, double y, double z, double w, Vector4 store)
      Adds the given values to those of this vector and returns them in store.
      Specified by:
      add in interface ReadOnlyVector4
      Parameters:
      x - the x value
      y - the y value
      z - the z value
      w - the w 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, this.w + w)
    • addLocal

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

      public Vector4 add(ReadOnlyVector4 source, Vector4 store)
      Adds the values of the given source vector to those of this vector and returns them in store.
      Specified by:
      add in interface ReadOnlyVector4
      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, this.w + source.w)
      Throws:
      NullPointerException - if source is null.
    • addLocal

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

      public Vector4 subtract(double x, double y, double z, double w, Vector4 store)
      Subtracts the given values from those of this vector and returns them in store.
      Specified by:
      subtract in interface ReadOnlyVector4
      Parameters:
      x - the x value
      y - the y value
      z - the z value
      w - the w 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, this.w - w)
    • subtractLocal

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

      public Vector4 subtract(ReadOnlyVector4 source, Vector4 store)
      Subtracts the values of the given source vector from those of this vector and returns them in store.
      Specified by:
      subtract in interface ReadOnlyVector4
      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, this.w - source.w)
      Throws:
      NullPointerException - if source is null.
    • subtractLocal

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

      public Vector4 multiply(double scalar, Vector4 store)
      Multiplies the values of this vector by the given scalar value and returns the result in store.
      Specified by:
      multiply in interface ReadOnlyVector4
      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, this.w * scalar)
    • multiplyLocal

      public Vector4 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 Vector4 multiply(ReadOnlyVector4 scale, Vector4 store)
      Multiplies the values of this vector by the given scalar value and returns the result in store.
      Specified by:
      multiply in interface ReadOnlyVector4
      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, this.w * scale.w)
    • multiplyLocal

      public Vector4 multiplyLocal(ReadOnlyVector4 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 Vector4 multiply(double x, double y, double z, double w, Vector4 store)
      Multiplies the values of this vector by the given scalar value and returns the result in store.
      Specified by:
      multiply in interface ReadOnlyVector4
      Parameters:
      x - the x value
      y - the y value
      z - the z value
      w - the w 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, this.w * scale.w)
    • multiplyLocal

      public Vector4 multiplyLocal(double x, double y, double z, double w)
      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
      w - the w value
      Returns:
      this vector for chaining
    • divide

      public Vector4 divide(double scalar, Vector4 store)
      Divides the values of this vector by the given scalar value and returns the result in store.
      Specified by:
      divide in interface ReadOnlyVector4
      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, this.w / scalar)
    • divideLocal

      public Vector4 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 Vector4 divide(ReadOnlyVector4 scale, Vector4 store)
      Divides the values of this vector by the given scale values and returns the result in store.
      Specified by:
      divide in interface ReadOnlyVector4
      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, this.w / scale.w)
    • divideLocal

      public Vector4 divideLocal(ReadOnlyVector4 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 Vector4 divide(double x, double y, double z, double w, Vector4 store)
      Divides the values of this vector by the given scale values and returns the result in store.
      Specified by:
      divide in interface ReadOnlyVector4
      Parameters:
      x - the x value
      y - the y value
      z - the z value
      w - the w 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, this.w / scale.w)
    • divideLocal

      public Vector4 divideLocal(double x, double y, double z, double w)
      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
      w - the w value
      Returns:
      this vector for chaining
    • scaleAddLocal

      public Vector4 scaleAddLocal(double scale, Vector4 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 Vector4 scaleAdd(double scale, ReadOnlyVector4 add, Vector4 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 ReadOnlyVector4
      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 Vector4 negate(Vector4 store)
      Specified by:
      negate in interface ReadOnlyVector4
      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 Vector4 negateLocal()
      Returns:
      same as multiplyLocal(-1)
    • normalize

      public Vector4 normalize(Vector4 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, 0) then a new vector (0, 0, 0, 0) is returned.
      Specified by:
      normalize in interface ReadOnlyVector4
      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, 0 if this unit is 0 length)
    • normalizeLocal

      public Vector4 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, 0) then no action is taken.
      Returns:
      this vector for chaining
    • lerp

      public Vector4 lerp(ReadOnlyVector4 endVec, double scalar, Vector4 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 ReadOnlyVector4
      Parameters:
      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.
      Returns:
      a new vector as described above.
      Throws:
      NullPointerException - if endVec is null.
    • lerpLocal

      public Vector4 lerpLocal(ReadOnlyVector4 endVec, double scalar)
      Performs a linear interpolation between this vector and the given end vector, using the given scalar as a percent. iow, if scalar 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 as a percent.
      Returns:
      this vector for chaining
      Throws:
      NullPointerException - if endVec is null.
    • lerp

      public static Vector4 lerp(ReadOnlyVector4 beginVec, ReadOnlyVector4 endVec, double scalar, Vector4 store)
      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 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.
      Returns:
      a new vector as described above.
      Throws:
      NullPointerException - if beginVec or endVec are null.
    • lerpLocal

      public Vector4 lerpLocal(ReadOnlyVector4 beginVec, ReadOnlyVector4 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 ReadOnlyVector4
      Returns:
      the magnitude or distance between the origin (0, 0, 0, 0) and the point described by this vector (x, y, z, w). Effectively the square root of the value returned by lengthSquared().
    • lengthSquared

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

      public double distanceSquared(double x, double y, double z, double w)
      Specified by:
      distanceSquared in interface ReadOnlyVector4
      Parameters:
      x - the x value
      y - the y value
      z - the z value
      w - the w value
      Returns:
      the squared distance between the point described by this vector and the given x, y, z, w 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(ReadOnlyVector4 destination)
      Specified by:
      distanceSquared in interface ReadOnlyVector4
      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, double w)
      Specified by:
      distance in interface ReadOnlyVector4
      Parameters:
      x - the x value
      y - the y value
      z - the z value
      w - the w value
      Returns:
      the distance between the point described by this vector and the given x, y, z, w point.
    • distance

      public double distance(ReadOnlyVector4 destination)
      Specified by:
      distance in interface ReadOnlyVector4
      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, double w)
      Specified by:
      dot in interface ReadOnlyVector4
      Parameters:
      x - the x value
      y - the y value
      z - the z value
      w - the w value
      Returns:
      the dot product of this vector with the given x, y, z, w values.
    • dot

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

      public static boolean isValid(ReadOnlyVector4 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.
    • 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, z and w values.
    • clone

      public Vector4 clone()
      Specified by:
      clone in interface ReadOnlyVector4
      Overrides:
      clone in class Object
    • getClassTag

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