Package com.jme3.math

Class Vector2f

java.lang.Object
com.jme3.math.Vector2f
All Implemented Interfaces:
Savable, Serializable, Cloneable
public final class Vector2f extends Object implements Savable, Cloneable, Serializable
A vector composed of 2 single-precision components, used to represent locations, offsets, directions, and rotations in 2-dimensional space.

Methods with names ending in "Local" modify the current instance. They are used to avoid creating garbage.

See Also:

  • Field Summary

    Fields
    Modifier and Type
    Field
    Description
    static final Vector2f
    UNIT_XY
    Shared instance of the all-ones vector (1,1).
    float
    x
    The first (X) component.
    float
    y
    The 2nd (Y) component.
    static final Vector2f
    ZERO
    Shared instance of the all-zero vector (0,0).

  • Constructor Summary

    Constructors
    Constructor
    Description
    Vector2f()
    Instantiates an all-zero vector (0,0).
    Vector2f(float x, float y)
    Instantiates a vector with specified components.
    Vector2f(Vector2f vector2f)
    Instantiates a copy of the argument.

  • Method Summary

    Modifier and Type
    Method
    Description
    Vector2f
    add(Vector2f vec)
    Adds the argument and returns the sum as a new instance.
    Vector2f
    add(Vector2f vec, Vector2f result)
    Adds a specified vector and returns the sum in a 3rd vector.
    Vector2f
    addLocal(float addX, float addY)
    Adds specified amounts to the vector's components and returns the (modified) current instance.
    Vector2f
    addLocal(Vector2f vec)
    Adds the argument and returns the (modified) current instance.
    float
    angleBetween(Vector2f otherVector)
    Returns the signed angle between the current instance and the argument.
    Vector2f
    clone()
    Creates a copy.
    Vector3f
    cross(Vector2f v)
    Calculates a cross product with the argument and returns the product as a new instance.
    float
    determinant(Vector2f v)
    Returns the Z component of the cross product with the argument.
    float
    distance(Vector2f v)
    Returns the distance between the current instance and the argument.
    float
    distanceSquared(float otherX, float otherY)
    Returns the square of the distance between the current instance and a vector with the specified components.
    float
    distanceSquared(Vector2f v)
    Returns the square of the distance between the current instance and the argument.
    Vector2f
    divide(float scalar)
    Divides by the scalar argument and returns the quotient as a new instance.
    Vector2f
    divide(float x, float y)
    Divides component-wise by the specified components and returns the quotient as a new instance.
    Vector2f
    divideLocal(float scalar)
    Divides the vector by the scalar argument and returns the (modified) current instance.
    Vector2f
    divideLocal(float x, float y)
    Divides component-wise by the specified components returns the (modified) current instance.
    float
    dot(Vector2f vec)
    Returns the dot (or inner) product with the argument.
    boolean
    equals(Object o)
    Tests for exact equality with the argument, distinguishing -0 from 0.
    float
    getAngle()
    Returns the angle of the vector in polar coordinates.
    float
    getX()
    Returns the X component.
    float
    getY()
    Returns the Y component.
    int
    hashCode()
    Returns a hash code.
    Vector2f
    interpolateLocal(Vector2f finalVec, float changeAmount)
    Interpolates linearly between the current instance and the specified vector, returning the (modified) current instance.
    Vector2f
    interpolateLocal(Vector2f beginVec, Vector2f finalVec, float changeAmount)
    Interpolates linearly between the specified beginning and final vectors, returning the (modified) current instance.
    boolean
    isSimilar(Vector2f other, float epsilon)
    Tests for approximate equality with the specified vector, using the specified tolerance.
    static boolean
    isValidVector(Vector2f vector)
    Tests whether the argument is a valid vector, returning false if it's null or if any component is NaN or infinite.
    float
    length()
    Returns the length (or magnitude).
    float
    lengthSquared()
    Returns the square of the length.
    Vector2f
    mult(float scalar)
    Multiplies with the scalar argument and returns the product as a new instance.
    Vector2f
    mult(float x, float y)
    Multiplies component-wise by the specified components and returns the product as a new instance.
    Vector2f
    mult(float scalar, Vector2f product)
    Multiplies with the specified scalar and stores the product in the specified vector.
    Vector2f
    multLocal(float scalar)
    Multiplies by the scalar argument and returns the (modified) current instance.
    Vector2f
    multLocal(float x, float y)
    Multiplies component-wise by the specified components and returns the (modified) current instance.
    Vector2f
    multLocal(Vector2f vec)
    Multiplies component-wise by the argument and returns the (modified) current instance.
    Vector2f
    negate()
    Returns the negative of the vector.
    Vector2f
    negateLocal()
    Negates both components and returns the (modified) current instance.
    Vector2f
    normalize()
    Normalizes the vector to length=1 and returns the result as a new instance.
    Vector2f
    normalizeLocal()
    Normalizes the vector to length=1 and returns the (modified) current instance.
    void
    read(JmeImporter importer)
    De-serializes the vector from the specified importer, for example when loading from a J3O file.
    void
    readExternal(ObjectInput in)
    Sets the vector from an ObjectInput object.
    void
    rotateAroundOrigin(float angle, boolean cw)
    Rotates the vector around (0,0) by the specified angle.
    Vector2f
    set(float x, float y)
    Sets both components to specified values.
    Vector2f
    set(Vector2f vec)
    Copies both components from the argument.
    Vector2f
    setX(float x)
    Sets the X component.
    Vector2f
    setY(float y)
    Sets the Y component.
    float
    smallestAngleBetween(Vector2f otherVector)
    Returns the unsigned angle between the current instance and the argument, provided both vectors have length=1.
    Vector2f
    subtract(float valX, float valY)
    Subtracts the specified amounts from the vector's components and returns the difference as a new instance.
    Vector2f
    subtract(Vector2f vec)
    Subtracts the argument and returns the difference as a new instance.
    Vector2f
    subtract(Vector2f vec, Vector2f store)
    Subtracts the specified vector and returns the difference in a 3rd vector.
    Vector2f
    subtractLocal(float valX, float valY)
    Subtracts the specified amounts from the vector's components and returns the (modified) current instance.
    Vector2f
    subtractLocal(Vector2f vec)
    Subtracts the argument and returns the (modified) current instance.
    float[]
    toArray(float[] floats)
    Copies the vector to the array argument.
    String
    toString()
    Returns a string representation of the vector.
    void
    write(JmeExporter e)
    Serializes the vector to the specified exporter, for example when saving to a J3O file.
    void
    writeExternal(ObjectOutput out)
    Writes the vector to an ObjectOutput object.
    Vector2f
    zero()
    Sets both components to zero.

    Methods inherited from class java.lang.Object

    finalize, getClass, notify, notifyAll, wait, wait, wait

  • Field Details

    • ZERO

      public static final Vector2f ZERO
      Shared instance of the all-zero vector (0,0). Do not modify!

    • UNIT_XY

      public static final Vector2f UNIT_XY
      Shared instance of the all-ones vector (1,1). Do not modify!

    • x

      public float x
      The first (X) component.

    • y

      public float y
      The 2nd (Y) component.

  • Constructor Details

    • Vector2f

      public Vector2f(float x, float y)
      Instantiates a vector with specified components.
      Parameters:
      x - the desired X component
      y - the desired Y component

    • Vector2f

      public Vector2f()
      Instantiates an all-zero vector (0,0).

    • Vector2f

      public Vector2f(Vector2f vector2f)
      Instantiates a copy of the argument.
      Parameters:
      vector2f - the vector to copy (not null, unaffected)

  • Method Details

    • set

      public Vector2f set(float x, float y)
      Sets both components to specified values.
      Parameters:
      x - the desired X component
      y - the desired Y component
      Returns:
      the (modified) current instance (for chaining)

    • set

      public Vector2f set(Vector2f vec)
      Copies both components from the argument.
      Parameters:
      vec - the Vector2f to copy (not null, unaffected)
      Returns:
      the (modified) current instance (for chaining)

    • add

      public Vector2f add(Vector2f vec)
      Adds the argument and returns the sum as a new instance. If the argument is null, null is returned. Either way, the current instance is unaffected.
      Parameters:
      vec - the vector to add (unaffected) or null for none
      Returns:
      a new Vector2f or null

    • addLocal

      public Vector2f addLocal(Vector2f vec)
      Adds the argument and returns the (modified) current instance. If the argument is null, null is returned.
      Parameters:
      vec - the vector to add (unaffected unless it's this) or null for none
      Returns:
      the (modified) current instance or null

    • addLocal

      public Vector2f addLocal(float addX, float addY)
      Adds specified amounts to the vector's components and returns the (modified) current instance.
      Parameters:
      addX - the amount to add to the X component
      addY - the amount to add to the Y component
      Returns:
      the (modified) current instance (for chaining)

    • add

      public Vector2f add(Vector2f vec, Vector2f result)
      Adds a specified vector and returns the sum in a 3rd vector. If the argument is null, null is returned. Either way, the current instance is unaffected unless it's result.
      Parameters:
      vec - the vector to add (unaffected unless it's result) or null for none
      result - storage for the sum, or null for a new Vector2f
      Returns:
      the sum (either result or a new Vector2f)

    • dot

      public float dot(Vector2f vec)
      Returns the dot (or inner) product with the argument. If the argument is null, 0 is returned. Either way, the current instance is unaffected.
      Parameters:
      vec - the vector to multiply (unaffected) or null for none
      Returns:
      the product or 0

    • cross

      public Vector3f cross(Vector2f v)
      Calculates a cross product with the argument and returns the product as a new instance. The current instance is unaffected.
      Parameters:
      v - the right factor (not null, unaffected)
      Returns:
      this cross v (a new Vector3f)

    • determinant

      public float determinant(Vector2f v)
      Returns the Z component of the cross product with the argument. The current instance is unaffected.
      Parameters:
      v - the right factor (not null, unaffected)
      Returns:
      the Z component of this cross v

    • interpolateLocal

      public Vector2f interpolateLocal(Vector2f finalVec, float changeAmount)
      Interpolates linearly between the current instance and the specified vector, returning the (modified) current instance.

      this = (1 - changeAmount) * this + changeAmount * finalVec

      Parameters:
      finalVec - the desired value when changeAmount=1 (not null, unaffected unless it's this)
      changeAmount - the fractional change amount
      Returns:
      the (modified) current instance (for chaining)

    • interpolateLocal

      public Vector2f interpolateLocal(Vector2f beginVec, Vector2f finalVec, float changeAmount)
      Interpolates linearly between the specified beginning and final vectors, returning the (modified) current instance.

      this = (1 - changeAmount) * beginVec + changeAmount * finalVec

      Parameters:
      beginVec - the desired value when changeAmount=0 (not null, unaffected unless it's this)
      finalVec - the desired value when changeAmount=1 (not null, unaffected unless it's this)
      changeAmount - the fractional change amount
      Returns:
      the (modified) current instance (for chaining)

    • isValidVector

      public static boolean isValidVector(Vector2f vector)
      Tests whether the argument is a valid vector, returning false if it's null or if any component is NaN or infinite.
      Parameters:
      vector - the vector to test (unaffected)
      Returns:
      true if non-null and finite, otherwise false

    • length

      public float length()
      Returns the length (or magnitude). The current instance is unaffected.
      Returns:
      the root-sum of the squared components (not negative)

    • lengthSquared

      public float lengthSquared()
      Returns the square of the length. The current instance is unaffected.
      Returns:
      the sum of the squared components (not negative)

    • distanceSquared

      public float distanceSquared(Vector2f v)
      Returns the square of the distance between the current instance and the argument. The current instance is unaffected.
      Parameters:
      v - the vector to compare (not null, unaffected)
      Returns:
      the square of the Euclidean distance (not negative)

    • distanceSquared

      public float distanceSquared(float otherX, float otherY)
      Returns the square of the distance between the current instance and a vector with the specified components. The current instance is unaffected.
      Parameters:
      otherX - the X component of the vector to compare
      otherY - the Y component of the vector to compare
      Returns:
      the square of the Euclidean distance (not negative)

    • distance

      public float distance(Vector2f v)
      Returns the distance between the current instance and the argument. The current instance is unaffected.
      Parameters:
      v - the vector to compare (not null, unaffected)
      Returns:
      the Euclidean distance (not negative)

    • mult

      public Vector2f mult(float scalar)
      Multiplies with the scalar argument and returns the product as a new instance. The current instance is unaffected.
      Parameters:
      scalar - the scaling factor
      Returns:
      a new Vector2f

    • multLocal

      public Vector2f multLocal(float scalar)
      Multiplies by the scalar argument and returns the (modified) current instance.
      Parameters:
      scalar - the scaling factor
      Returns:
      the (modified) current instance (for chaining)

    • multLocal

      public Vector2f multLocal(Vector2f vec)
      Multiplies component-wise by the argument and returns the (modified) current instance. If the argument is null, null is returned.
      Parameters:
      vec - the scale vector (unaffected unless it's this) or null for none
      Returns:
      the (modified) current instance (for chaining) or null

    • mult

      public Vector2f mult(float scalar, Vector2f product)
      Multiplies with the specified scalar and stores the product in the specified vector. The current instance is unaffected.
      Parameters:
      scalar - the scaling factor
      product - storage for the product, or null for a new Vector2f
      Returns:
      either product or a new Vector2f

    • mult

      public Vector2f mult(float x, float y)
      Multiplies component-wise by the specified components and returns the product as a new instance. The current instance is unaffected.
      Parameters:
      x - the scale factor for the X component
      y - the scale factor for the Y component
      Returns:
      a new Vector2f

    • multLocal

      public Vector2f multLocal(float x, float y)
      Multiplies component-wise by the specified components and returns the (modified) current instance.
      Parameters:
      x - the scale factor for the X component
      y - the scale factor for the Y component
      Returns:
      the (modified) current instance (for chaining)

    • divide

      public Vector2f divide(float scalar)
      Divides by the scalar argument and returns the quotient as a new instance. The current instance is unaffected.
      Parameters:
      scalar - the divisor
      Returns:
      a new Vector2f

    • divideLocal

      public Vector2f divideLocal(float scalar)
      Divides the vector by the scalar argument and returns the (modified) current instance.
      Parameters:
      scalar - the divisor
      Returns:
      the (modified) current instance (for chaining)

    • divide

      public Vector2f divide(float x, float y)
      Divides component-wise by the specified components and returns the quotient as a new instance. The current instance is unaffected.
      Parameters:
      x - the divisor for the X component
      y - the divisor for the Y component
      Returns:
      a new Vector2f

    • divideLocal

      public Vector2f divideLocal(float x, float y)
      Divides component-wise by the specified components returns the (modified) current instance.
      Parameters:
      x - the divisor for the X component
      y - the divisor for the Y component
      Returns:
      the (modified) current instance (for chaining)

    • negate

      public Vector2f negate()
      Returns the negative of the vector. The current instance is unaffected.
      Returns:
      a new Vector2f

    • negateLocal

      public Vector2f negateLocal()
      Negates both components and returns the (modified) current instance.
      Returns:
      the (modified) current instance (for chaining)

    • subtract

      public Vector2f subtract(Vector2f vec)
      Subtracts the argument and returns the difference as a new instance. The current instance is unaffected.
      Parameters:
      vec - the vector to subtract (not null, unaffected)
      Returns:
      a new Vector2f

    • subtract

      public Vector2f subtract(Vector2f vec, Vector2f store)
      Subtracts the specified vector and returns the difference in a 3rd vector. The current instance is unaffected unless it's store.

      It is safe for vec and store to be the same object.

      Parameters:
      vec - the vector to subtract (not null, unaffected unless it's store)
      store - storage for the difference, or null for a new Vector2f
      Returns:
      either store or a new Vector2f

    • subtract

      public Vector2f subtract(float valX, float valY)
      Subtracts the specified amounts from the vector's components and returns the difference as a new instance. The current instance is unaffected.
      Parameters:
      valX - the amount to subtract from the X component
      valY - the amount to subtract from the Y component
      Returns:
      a new Vector2f

    • subtractLocal

      public Vector2f subtractLocal(Vector2f vec)
      Subtracts the argument and returns the (modified) current instance. If the argument is null, null is returned.
      Parameters:
      vec - the vector to subtract (unaffected unless it's this) or null for none
      Returns:
      the (modified) current instance or null

    • subtractLocal

      public Vector2f subtractLocal(float valX, float valY)
      Subtracts the specified amounts from the vector's components and returns the (modified) current instance.
      Parameters:
      valX - the amount to subtract from the X component
      valY - the amount to subtract from the Y component
      Returns:
      the (modified) current instance (for chaining)

    • normalize

      public Vector2f normalize()
      Normalizes the vector to length=1 and returns the result as a new instance. If the vector has length=0, a clone is returned. Either way, the current instance is unaffected.
      Returns:
      a new Vector2f

    • normalizeLocal

      public Vector2f normalizeLocal()
      Normalizes the vector to length=1 and returns the (modified) current instance. If the vector has length=0, it's unchanged.
      Returns:
      the (modified) current instance (for chaining)

    • smallestAngleBetween

      public float smallestAngleBetween(Vector2f otherVector)
      Returns the unsigned angle between the current instance and the argument, provided both vectors have length=1. If otherVector is null, Pi/2 is returned. The current instance is unaffected.
      Parameters:
      otherVector - the unit vector to compare (unaffected) or null for none
      Returns:
      the angle in radians (not negative)

    • angleBetween

      public float angleBetween(Vector2f otherVector)
      Returns the signed angle between the current instance and the argument. The current instance is unaffected.
      Parameters:
      otherVector - the vector to compare (not null, unaffected)
      Returns:
      the angle in radians, measured counter-clockwise from this to otherVector (≥-2*Pi, ≤2*Pi)

    • getX

      public float getX()
      Returns the X component. The vector is unaffected.
      Returns:
      the value of the x component

    • setX

      public Vector2f setX(float x)
      Sets the X component.
      Parameters:
      x - the desired value
      Returns:
      the (modified) current instance (for chaining)

    • getY

      public float getY()
      Returns the Y component. The vector is unaffected.
      Returns:
      the value of the y component

    • setY

      public Vector2f setY(float y)
      Sets the Y component.
      Parameters:
      y - the desired value
      Returns:
      the (modified) current instance (for chaining)

    • getAngle

      public float getAngle()
      Returns the angle of the vector in polar coordinates. The current instance is unaffected.
      Returns:
      the polar angle in radians, measured counter-clockwise from the +X axis (≥-Pi, ≤Pi)

    • zero

      public Vector2f zero()
      Sets both components to zero.
      Returns:
      the (modified) current instance (for chaining)

    • hashCode

      public int hashCode()
      Returns a hash code. If two vectors are logically equivalent, they will return the same hash code. The current instance is unaffected.
      Overrides:
      hashCode in class Object
      Returns:
      the hash code value

    • clone

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

    • toArray

      public float[] toArray(float[] floats)
      Copies the vector to the array argument. The current instance is unaffected.
      Parameters:
      floats - storage for the components (must have length≥2) or null for a new float[2]
      Returns:
      an array containing the X and Y components in that order (either floats or a new float[2])

    • equals

      public boolean equals(Object o)
      Tests for exact equality with the argument, distinguishing -0 from 0. If o is null, false is returned. Either way, the current instance is unaffected.
      Overrides:
      equals in class Object
      Parameters:
      o - the object to compare (unaffected) or null for none
      Returns:
      true if equal, otherwise false

    • isSimilar

      public boolean isSimilar(Vector2f other, float epsilon)
      Tests for approximate equality with the specified vector, using the specified tolerance. If other is null, false is returned. Either way, the current instance is unaffected.
      Parameters:
      other - the vector to compare (unaffected) or null for none
      epsilon - the tolerance for each component
      Returns:
      true if both components are within tolerance, otherwise false

    • toString

      public String toString()
      Returns a string representation of the vector. The current instance is unaffected. The format is:

      (XX.XXXX, YY.YYYY)

      Overrides:
      toString in class Object
      Returns:
      the string representation

    • readExternal

      public void readExternal(ObjectInput in) throws IOException, ClassNotFoundException
      Sets the vector from an ObjectInput object.

      Used with serialization. Shouldn't be invoked directly by application code.

      Parameters:
      in - the object to read from (not null)
      Throws:
      IOException - if the ObjectInput cannot read a float
      ClassNotFoundException - never
      See Also:

    • writeExternal

      public void writeExternal(ObjectOutput out) throws IOException
      Writes the vector to an ObjectOutput object. The current instance is unaffected.

      Used with serialization. Shouldn't be invoked directly by application code.

      Parameters:
      out - the object to write to (not null)
      Throws:
      IOException - if the ObjectOuput cannot write a float
      See Also:

    • write

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

    • read

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

    • rotateAroundOrigin

      public void rotateAroundOrigin(float angle, boolean cw)
      Rotates the vector around (0,0) by the specified angle.
      Parameters:
      angle - the rotation angle (in radians)
      cw - true to rotate clockwise, false to rotate counter-clockwise