Package com.ardor3d.math

Class Vector2

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

  • Field Details

  • Constructor Details

    • Vector2

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

    • Vector2

      public Vector2(ReadOnlyVector2 src)
      Constructs a new vector set to the (x, y) values of the given source vector.
      Parameters:
      src - the vector to copy from

    • Vector2

      public Vector2(double x, double y)
      Constructs a new vector set to (x, y).
      Parameters:
      x - the abscissa
      y - the ordinate

  • Method Details

    • getX

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

    • getY

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

    • getXf

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

    • getYf

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

    • getValue

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

    • 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 or y.
      Throws:
      IllegalArgumentException - if index is not one of 0, 1.

    • toArray

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

    • setX

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

    • setY

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

    • set

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

    • set

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

    • zero

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

    • add

      public Vector2 add(double x, double y, Vector2 store)
      Adds the given values to those of this vector and returns them in store
      Specified by:
      add in interface ReadOnlyVector2
      Parameters:
      x - the x value to add
      y - the y value to add
      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)

    • addLocal

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

    • add

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

    • addLocal

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

    • subtract

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

    • subtractLocal

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

    • subtract

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

    • subtractLocal

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

    • multiply

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

    • multiplyLocal

      public Vector2 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 Vector2 multiply(ReadOnlyVector2 scale, Vector2 store)
      Multiplies the values of this vector by the given scale values and returns the result in store.
      Specified by:
      multiply in interface ReadOnlyVector2
      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)

    • multiplyLocal

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

    • multiply

      public Vector2 multiply(double x, double y, Vector2 store)
      Multiplies the values of this vector by the given scale values and returns the result in store.
      Specified by:
      multiply in interface ReadOnlyVector2
      Parameters:
      x - the x value to multiply
      y - the y value to multiply
      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)

    • multiplyLocal

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

    • divide

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

    • divideLocal

      public Vector2 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 Vector2 divide(ReadOnlyVector2 scale, Vector2 store)
      Divides the values of this vector by the given scale values and returns the result in store.
      Specified by:
      divide in interface ReadOnlyVector2
      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)

    • divideLocal

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

    • divide

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

    • divideLocal

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

    • scaleAddLocal

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

    • normalize

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

    • normalizeLocal

      public Vector2 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) then no action is taken.
      Returns:
      this vector for chaining

    • rotateAroundOrigin

      public Vector2 rotateAroundOrigin(double angle, boolean clockwise, Vector2 store)
      Creates a new vector representing this vector rotated around 0,0 by a specified angle in a given direction.
      Specified by:
      rotateAroundOrigin in interface ReadOnlyVector2
      Parameters:
      angle - in radians
      clockwise - true to rotate in a clockwise direction
      store - the vector to store the result in for return. If null, a new vector object is created and returned.
      Returns:
      the new rotated vector

    • rotateAroundOriginLocal

      public Vector2 rotateAroundOriginLocal(double angle, boolean clockwise)
      Internally rotates this vector around 0,0 by a specified angle in a given direction.
      Parameters:
      angle - in radians
      clockwise - true to rotate in a clockwise direction
      Returns:
      this vector for chaining

    • lerp

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

    • lerpLocal

      public Vector2 lerpLocal(ReadOnlyVector2 beginVec, ReadOnlyVector2 endVec, double scalar)
      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 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 ReadOnlyVector2
      Returns:
      the magnitude of this vector, or the distance between the origin (0, 0) and the point described by (x, y). Basically sqrt(x^2 + y^2)

    • lengthSquared

      public double lengthSquared()
      Specified by:
      lengthSquared in interface ReadOnlyVector2
      Returns:
      the squared magnitude of this vector. (x^2 + y^2)

    • distanceSquared

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

    • distance

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

    • dot

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

    • getPolarAngle

      public double getPolarAngle()
      Specified by:
      getPolarAngle in interface ReadOnlyVector2
      Returns:
      the angle - in radians [-pi, pi) - represented by this Vector2 as expressed by a conversion from rectangular coordinates (x, y) to polar coordinates (r, theta ).

    • angleBetween

      public double angleBetween(ReadOnlyVector2 otherVector)
      Specified by:
      angleBetween in interface ReadOnlyVector2
      Parameters:
      otherVector - the "destination" unit vector
      Returns:
      the angle (in radians) required to rotate a ray represented by this vector to lie co-linear to a ray described by the given vector. It is assumed that both this vector and the given vector are unit vectors (normalized).
      Throws:
      NullPointerException - if otherVector is null.

    • smallestAngleBetween

      public double smallestAngleBetween(ReadOnlyVector2 otherVector)
      Specified by:
      smallestAngleBetween in interface ReadOnlyVector2
      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(ReadOnlyVector2 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 and y values.

    • clone

      public Vector2 clone()
      Specified by:
      clone in interface ReadOnlyVector2
      Overrides:
      clone in class Object

    • getClassTag

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