Package com.simsilica.mathd

Class Vec3d

java.lang.Object
com.simsilica.mathd.Vec3d
All Implemented Interfaces:
Cloneable
public class Vec3d extends Object implements Cloneable
A vector composed of 3 double-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 avoid creating temporary vectors.

The conventional order of components is (X, Y, Z).

  • Field Summary

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

  • Constructor Summary

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

  • Method Summary

    Modifier and Type
    Method
    Description
    final Vec3d
    add(double vx, double vy, double vz)
    Adds specified amounts to the vector's components and returns the sum as a new instance.
    final Vec3d
    add(Vec3d v)
    Adds the argument and returns the sum as a new instance.
    final Vec3d
    addLocal(double vx, double vy, double vz)
    Adds specified amounts to the vector's components and returns the (modified) current instance.
    final Vec3d
    addLocal(Vec3d v)
    Adds the argument and returns the (modified) current instance.
    final Vec3d
    clone()
    Creates a copy.
    final Vec3d
    cross(Vec3d v)
    Calculates a cross product with the argument and returns the product as a new instance.
    final Vec3d
    divideLocal(Vec3d v)
    Divides component-wise by the argument and returns the (modified) current instance.
    final double
    dot(Vec3d v)
    Returns the dot (or inner) product with the argument.
    boolean
    equals(Object o)
    Tests for exact equality with the argument, distinguishing -0 from 0.
    double
    get(int i)
    Returns the indexed component.
    int
    hashCode()
    Returns a hash code.
    boolean
    isFinite()
    Tests for finite components.
    final double
    length()
    Returns the length (or magnitude).
    final double
    lengthSq()
    Returns the square of the length.
    final Vec3d
    multLocal(double s)
    Multiplies by the scalar argument and returns the (modified) current instance.
    final Vec3d
    multLocal(Vec3d v)
    Multiplies component-wise by the argument and returns the (modified) current instance.
    final Vec3d
    normalizeLocal()
    Normalize this vector in place.
    final Vec3d
    set(double x, double y, double z)
    Sets all 3 components to specified values.
    Vec3d
    set(int i, double d)
    Alters the indexed component.
    final Vec3d
    set(Vector3f v)
    Copies all 3 components from the argument, converting them to double precision.
    final Vec3d
    set(Vec3d v)
    Copies all 3 components from the argument.
    final Vec3d
    subtract(Vec3d v)
    Subtracts the argument and returns the difference as a new instance.
    final Vec3d
    subtractLocal(Vec3d v)
    Subtracts the argument and returns the (modified) current instance.
    String
    toString()
    Returns a string representation of the vector, which is unaffected.
    Vector3f
    toVector3f()
    Creates a single-precision copy of the current instance.

    Methods inherited from class java.lang.Object

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

  • Field Details

    • UNIT_X

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

    • UNIT_Y

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

    • UNIT_Z

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

    • ZERO

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

    • x

      public double x
      The first (X) component.

    • y

      public double y
      The 2nd (Y) component.

    • z

      public double z
      The 3rd (Z) component.

  • Constructor Details

    • Vec3d

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

    • Vec3d

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

    • Vec3d

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

    • Vec3d

      public Vec3d(Vector3f v)
      Instantiates a double-precision copy of the argument.
      Parameters:
      v - the input Vector3f (not null, unaffected)

  • Method Details

    • toVector3f

      public Vector3f toVector3f()
      Creates a single-precision copy of the current instance.
      Returns:
      a new Vector3f

    • 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

    • 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

    • isFinite

      public boolean isFinite()
      Tests for finite components. The vector is unaffected.
      Returns:
      false if any component is infinite or NaN, otherwise true

    • set

      public final Vec3d set(double x, double y, double 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 final Vec3d set(Vec3d v)
      Copies all 3 components from the argument.
      Parameters:
      v - the Vec3d to copy (not null, unaffected)
      Returns:
      the (modified) current instance (for chaining)

    • set

      public final Vec3d set(Vector3f v)
      Copies all 3 components from the argument, converting them to double precision.
      Parameters:
      v - the Vector3f to copy (not null, unaffected)
      Returns:
      the (modified) current instance (for chaining)

    • clone

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

    • get

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

    • set

      public Vec3d set(int i, double d)
      Alters the indexed component.
      Parameters:
      i - which component to set: 0 → the X component, 1 → the Y component, 2 → the Z component
      d - the desired component value
      Returns:
      the (modified) current instance (for chaining)
      Throws:
      IllegalArgumentException - if i is not 0, 1, or 2

    • add

      public final Vec3d add(Vec3d v)
      Adds the argument and returns the sum as a new instance. The current instance is unaffected.
      Parameters:
      v - the vector to add (not null, unaffected)
      Returns:
      a new Vec3d

    • add

      public final Vec3d add(double vx, double vy, double vz)
      Adds specified amounts to the vector's components and returns the sum as a new instance. The current instance is unaffected.
      Parameters:
      vx - the amount to add to the X component
      vy - the amount to add to the Y component
      vz - the amount to add to the Z component
      Returns:
      a new Vec3d

    • subtract

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

    • addLocal

      public final Vec3d addLocal(Vec3d v)
      Adds the argument and returns the (modified) current instance.

      It IS safe for v and this to be the same object.

      Parameters:
      v - the vector to add (not null, unaffected unless it's this)
      Returns:
      the (modified) current instance (for chaining)

    • addLocal

      public final Vec3d addLocal(double vx, double vy, double vz)
      Adds specified amounts to the vector's components and returns the (modified) current instance.
      Parameters:
      vx - the amount to add to the X component
      vy - the amount to add to the Y component
      vz - the amount to add to the Z component
      Returns:
      the (modified) current instance (for chaining)

    • subtractLocal

      public final Vec3d subtractLocal(Vec3d v)
      Subtracts the argument and returns the (modified) current instance.

      It IS safe for v and this to be the same object.

      Parameters:
      v - the vector to subtract (not null, unaffected unless it's this)
      Returns:
      the (modified) current instance (for chaining)

    • multLocal

      public final Vec3d multLocal(double s)
      Multiplies by the scalar argument and returns the (modified) current instance.
      Parameters:
      s - the scaling factor
      Returns:
      the (modified) current instance (for chaining)

    • multLocal

      public final Vec3d multLocal(Vec3d v)
      Multiplies component-wise by the argument and returns the (modified) current instance.

      It IS safe for v and this to be the same object.

      Parameters:
      v - the scale vector (not null, unaffected unless it's this)
      Returns:
      the (modified) current instance (for chaining)

    • divideLocal

      public final Vec3d divideLocal(Vec3d v)
      Divides component-wise by the argument and returns the (modified) current instance.

      It IS safe for v and this to be the same object.

      Parameters:
      v - the divisor (not null, unaffected unless it's this)
      Returns:
      the (modified) current instance (for chaining)

    • lengthSq

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

    • length

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

    • normalizeLocal

      public final Vec3d normalizeLocal()
      Normalize this vector in place. For a zero vector, the result is undefined.
      Returns:
      the (normalized) current instance (for chaining)

    • dot

      public final double dot(Vec3d v)
      Returns the dot (or inner) product with the argument. The current instance is unaffected.
      Parameters:
      v - the vector to multiply (not null, unaffected)
      Returns:
      the dot product

    • cross

      public final Vec3d cross(Vec3d 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 Vec3d)

    • toString

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