Package com.jme3.math

Class Vector3f

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

Methods with names ending in "Local" modify the current instance. They are used to cut down on the creation of new instances.

See Also:

  • Field Summary

    Fields
    Modifier and Type
    Field
    Description
    static final Vector3f
    UNIT_X
    Shared instance of the +X direction (1,0,0).
    static final Vector3f
    UNIT_XYZ
    Shared instance of the all-ones vector (1,1,1).
    static final Vector3f
    UNIT_Y
    Shared instance of the +Y direction (0,1,0).
    static final Vector3f
    UNIT_Z
    Shared instance of the +Z direction (0,0,1).
    float
    x
    The first (X) component.
    float
    y
    The 2nd (Y) component.
    float
    z
    The 3rd (Z) component.
    static final Vector3f
    ZERO
    Shared instance of the all-zero vector (0,0,0).

  • Constructor Summary

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

  • Method Summary

    Modifier and Type
    Method
    Description
    Vector3f
    add(float addX, float addY, float addZ)
    Adds specified amounts to the vector's components and returns the sum as a new instance.
    Vector3f
    add(Vector3f vec)
    Adds the argument and returns the sum as a new instance.
    Vector3f
    add(Vector3f vec, Vector3f result)
    Adds a specified vector and returns the sum in a 3rd vector.
    Vector3f
    addLocal(float addX, float addY, float addZ)
    Adds specified amounts to the vector's components and returns the (modified) current instance.
    Vector3f
    addLocal(Vector3f vec)
    Adds the argument and returns the (modified) current instance.
    Vector3f
    clone()
    Creates a copy.
    Vector3f
    cross(float otherX, float otherY, float otherZ, Vector3f result)
    Calculates a cross product with specified components and returns the product in the specified vector.
    Vector3f
    cross(Vector3f v)
    Calculates a cross product with the argument and returns the product as a new instance.
    Vector3f
    cross(Vector3f v, Vector3f result)
    Calculates a cross product with a specified vector and returns the product in a 3rd vector.
    Vector3f
    crossLocal(float otherX, float otherY, float otherZ)
    Right multiplies by the specified components (cross product) and returns the (modified) current instance.
    float
    distance(Vector3f v)
    Returns the distance between this vector and the argument.
    Vector3f
    divide(float x, float y, float z)
    Divides component-wise by the specified components and returns the quotient as a new instance.
    Vector3f
    divide(Vector3f divisor)
    Divides component-wise by the argument and returns the quotient as a new instance.
    Vector3f
    divideLocal(float scalar)
    Divides by the argument and returns the (modified) current instance.
    Vector3f
    divideLocal(float x, float y, float z)
    Divides component-wise by the specified components returns the (modified) current instance.
    Vector3f
    divideLocal(Vector3f divisor)
    Divides component-wise by the argument and returns the (modified) current instance.
    float
    dot(Vector3f 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
    get(int index)
    Returns the indexed component.
    int
    hashCode()
    Returns a hash code.
    boolean
    isUnitVector()
    Tests for a unit vector, with 1% tolerance.
    static boolean
    isValidVector(Vector3f 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.
    Vector3f
    mult(float scalar)
    Multiplies with the argument and returns the product as a new instance.
    Vector3f
    mult(float x, float y, float z)
    Multiplies component-wise by the specified components and returns the product as a new instance.
    Vector3f
    mult(float scalar, Vector3f product)
    Multiplies with the specified scalar and returns the product in the specified vector.
    Vector3f
    mult(Vector3f vec)
    Multiplies component-wise with the argument and returns the product as a new instance.
    Vector3f
    mult(Vector3f vec, Vector3f store)
    Multiplies component-wise with the specified vector and returns the product in a 3rd vector.
    Vector3f
    multLocal(float scalar)
    Multiplies by the argument and returns the (modified) current instance.
    Vector3f
    multLocal(float x, float y, float z)
    Multiplies component-wise by the specified components and returns the (modified) current instance.
    Vector3f
    multLocal(Vector3f vec)
    Multiplies component-wise by the argument and returns the (modified) current instance.
    Vector3f
    negate()
    Returns the negative.
    Vector3f
    negateLocal()
    Negates all 3 components and returns the (modified) current instance.
    Vector3f
    normalize()
    Normalizes the vector to length=1 and returns the result as a new instance.
    Vector3f
    set(float x, float y, float z)
    Sets all 3 components to specified values.
    void
    set(int index, float value)
    Sets the indexed component.
    Vector3f
    set(Vector3f vect)
    Copies all 3 components from the argument.
    Vector3f
    subtract(float subtractX, float subtractY, float subtractZ)
    Subtracts the specified amounts from the vector's components and returns the difference as a new instance.
    Vector3f
    subtract(Vector3f vec)
    Subtracts the argument and returns the difference as a new instance.
    Vector3f
    subtract(Vector3f vec, Vector3f result)
    Subtracts the specified vector and returns the difference in a 3rd vector.
    Vector3f
    subtractLocal(float subtractX, float subtractY, float subtractZ)
    Subtracts the specified amounts from the vector's components and returns the (modified) current instance.
    Vector3f
    subtractLocal(Vector3f vec)
    Subtracts the argument and returns the (modified) current instance.
    String
    toString()
    Returns a string representation of the vector, which is unaffected.
    Vector3f
    zero()
    Sets all 3 components to zero.

    Methods inherited from class java.lang.Object

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

  • Field Details

    • ZERO

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

    • UNIT_X

      public static final Vector3f UNIT_X
      Shared instance of the +X direction (1,0,0). Do not modify!

    • UNIT_Y

      public static final Vector3f UNIT_Y
      Shared instance of the +Y direction (0,1,0). Do not modify!

    • UNIT_Z

      public static final Vector3f UNIT_Z
      Shared instance of the +Z direction (0,0,1). Do not modify!

    • UNIT_XYZ

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

    • x

      public float x
      The first (X) component.

    • y

      public float y
      The 2nd (Y) component.

    • z

      public float z
      The 3rd (Z) component.

  • Constructor Details

    • Vector3f

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

    • Vector3f

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

    • Vector3f

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

  • Method Details

    • set

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

    • set

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

    • add

      public Vector3f add(Vector3f 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 Vector3f or null

    • add

      public Vector3f add(Vector3f vec, Vector3f result)
      Adds a specified vector and returns the sum in a 3rd vector. The current instance is unaffected unless it's result.
      Parameters:
      vec - the vector to add (not null, unaffected unless it's result)
      result - storage for the sum (not null)
      Returns:
      result (for chaining)

    • addLocal

      public Vector3f addLocal(Vector3f 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

    • add

      public Vector3f add(float addX, float addY, float addZ)
      Adds specified amounts to the vector's components and returns the sum as a new instance. The current instance is unaffected.
      Parameters:
      addX - the amount to add to the X component
      addY - the amount to add to the Y component
      addZ - the amount to add to the Z component
      Returns:
      a new Vector3f

    • addLocal

      public Vector3f addLocal(float addX, float addY, float addZ)
      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
      addZ - the amount to add to the Z component
      Returns:
      the (modified) current instance (for chaining)

    • dot

      public float dot(Vector3f 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(Vector3f 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)

    • cross

      public Vector3f cross(Vector3f v, Vector3f result)
      Calculates a cross product with a specified vector and returns the product in a 3rd vector. The current instance is unaffected unless it's result.
      Parameters:
      v - the right factor (not null, unaffected unless it's result)
      result - storage for the product, or null for a new Vector3f
      Returns:
      this cross v (either result or a new Vector3f)

    • cross

      public Vector3f cross(float otherX, float otherY, float otherZ, Vector3f result)
      Calculates a cross product with specified components and returns the product in the specified vector. The current instance is unaffected unless it's result.
      Parameters:
      otherX - the X component of the right factor
      otherY - the Y component of the right factor
      otherZ - the Z component of the right factor
      result - storage for the product, or null for a new Vector3f
      Returns:
      this cross (X,Y,Z) (either result or a new Vector3f)

    • crossLocal

      public Vector3f crossLocal(float otherX, float otherY, float otherZ)
      Right multiplies by the specified components (cross product) and returns the (modified) current instance.
      Parameters:
      otherX - the X component of the right factor
      otherY - the Y component of the right factor
      otherZ - the Z component of the right factor
      Returns:
      the (modified) current instance (for chaining)

    • isUnitVector

      public boolean isUnitVector()
      Tests for a unit vector, with 1% tolerance. The current instance is unaffected.
      Returns:
      true if the current vector's length is between 0.99 and 1.01 inclusive, 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)

    • distance

      public float distance(Vector3f v)
      Returns the distance between this vector 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 Vector3f mult(float scalar)
      Multiplies with the argument and returns the product as a new instance. The current instance is unaffected.
      Parameters:
      scalar - the scaling factor
      Returns:
      a new Vector3f

    • mult

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

    • multLocal

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

    • multLocal

      public Vector3f multLocal(Vector3f 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

    • multLocal

      public Vector3f multLocal(float x, float y, float z)
      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
      z - the scale factor for the Z component
      Returns:
      the (modified) current instance (for chaining)

    • mult

      public Vector3f mult(Vector3f vec)
      Multiplies component-wise with the argument and returns the product as a new instance. If the argument is null, null is returned. Either way, the current instance is unaffected.
      Parameters:
      vec - the scale vector (unaffected) or null for none
      Returns:
      a new Vector3f or null

    • mult

      public Vector3f mult(float x, float y, float z)
      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
      z - the scale factor for the Z component
      Returns:
      a new Vector3f

    • mult

      public Vector3f mult(Vector3f vec, Vector3f store)
      Multiplies component-wise with the specified vector and returns the product in a 3rd vector. If the argument is null, null is returned. Either way, the current instance is unaffected, unless it's store.
      Parameters:
      vec - the scale vector (unaffected unless it's store) or null for none
      store - storage for the product, or null for a new Vector3f
      Returns:
      either store or a new Vector3f or null

    • divideLocal

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

    • divideLocal

      public Vector3f divideLocal(float x, float y, float z)
      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
      z - the divisor for the Z component
      Returns:
      the (modified) current instance (for chaining)

    • divide

      public Vector3f divide(Vector3f divisor)
      Divides component-wise by the argument and returns the quotient as a new instance. The current instance is unaffected.
      Parameters:
      divisor - the divisor (not null, unaffected)
      Returns:
      a new Vector3f

    • divide

      public Vector3f divide(float x, float y, float z)
      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
      z - the divisor for the Z component
      Returns:
      a new Vector3f

    • divideLocal

      public Vector3f divideLocal(Vector3f divisor)
      Divides component-wise by the argument and returns the (modified) current instance.
      Parameters:
      divisor - the divisor (not null, unaffected unless it's this)
      Returns:
      the (modified) current instance (for chaining)

    • negate

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

    • negateLocal

      public Vector3f negateLocal()
      Negates all 3 components and returns the (modified) current instance.
      Returns:
      the (modified) current instance (for chaining)

    • subtract

      public Vector3f subtract(Vector3f 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 Vector3f

    • subtractLocal

      public Vector3f subtractLocal(Vector3f 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

    • subtract

      public Vector3f subtract(Vector3f vec, Vector3f result)
      Subtracts the specified vector and returns the difference in a 3rd vector. The current instance is unaffected unless it's result.
      Parameters:
      vec - the vector to subtract (not null, unaffected unless it's result)
      result - storage for the difference, or null for a new Vector3f
      Returns:
      either result or a new Vector3f

    • subtract

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

    • subtractLocal

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

    • normalize

      public Vector3f 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 Vector3f

    • zero

      public Vector3f zero()
      Sets all 3 components to zero.
      Returns:
      the (modified) current instance (for chaining)

    • isValidVector

      public static boolean isValidVector(Vector3f 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

    • clone

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

    • 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 (may be null, unaffected)
      Returns:
      true if this and o have identical values, otherwise false

    • hashCode

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

    • toString

      public String toString()
      Returns a string representation of the vector, which is unaffected. For example, the +X direction vector is represented by: 
       (1.0, 0.0, 0.0)
      Overrides:
      toString in class Object
      Returns:
      the string representation (not null, not empty)

    • get

      public float get(int index)
      Returns the indexed component. The vector is unaffected.
      Parameters:
      index - 0, 1, or 2
      Returns:
      the X component if index=0, the Y component if index=1, or the Z component if index=2
      Throws:
      IllegalArgumentException - if index is not 0, 1, or 2

    • set

      public void set(int index, float value)
      Sets the indexed component.
      Parameters:
      index - which component to set: 0 → the X component, 1 → the Y component, 2 → the Z component
      value - the desired component value
      Throws:
      IllegalArgumentException - if index is not 0, 1, or 2