Package com.github.stephengold.joltjni

Class Vec3

java.lang.Object
com.github.stephengold.joltjni.Vec3
All Implemented Interfaces:
Vec3Arg
public final class Vec3 extends Object implements Vec3Arg
A vector composed of 3 single-precision components, used to represent directions, extents, forces, impulses, offsets, scaling factors, torques, and velocities in 3-dimensional space.

  • Constructor Summary

    Constructors
    Constructor
    Description
    Vec3()
    Instantiate an all-zero vector (0,0,0).
    Vec3(double x, double y, double z)
    Instantiate a vector with specified components.
    Vec3(float[] array)
    Instantiate a vector from the specified array.
    Vec3(float x, float y, float z)
    Instantiate a vector with specified components.
    Vec3(RVec3Arg vec)
    Instantiate from a location vector.
    Vec3(Vec3Arg vec)
    Instantiate a copy of the argument.

  • Method Summary

    Modifier and Type
    Method
    Description
    static Vec3
    add(Vec3Arg v1, Vec3Arg v2, Vec3Arg v3)
    Return the component-wise sum of the specified vectors.
    Vec3
    cross(Vec3Arg rightFactor)
    Return the cross product with the specified vector.
    float
    dot(Vec3Arg factor)
    Return the dot product with the specified vector.
    boolean
    equals(Object other)
    Tests for exact equality with the argument, distinguishing -0 from 0.
    float
    get(int index)
    Return the specified component.
    Vec3
    getNormalizedPerpendicular()
    Return an arbitrary unit vector perpendicular to the current vector.
    float
    getX()
    Return the first (X) component in single precision.
    float
    getY()
    Return the 2nd (Y) component in single precision.
    float
    getZ()
    Return the 3rd (Z) component in single precision.
    int
    hashCode()
    Return a hash code.
    boolean
    isNearZero()
    Test whether the vector is zero to within a tolerance of 10^-12.
    boolean
    isNearZero(float tolerance)
    Test whether the vector is zero to within the specified tolerance.
    boolean
    isNormalized()
    Test whether the vector is normalized to within a tolerance of 10^-6.
    boolean
    isNormalized(float tolerance)
    Test whether the vector is normalized to within the specified tolerance.
    float
    length()
    Return the length.
    float
    lengthSq()
    Return the squared length.
    Vec3
    normalized()
    Generate a normalized vector with the same direction.
    Vec3
    normalizedOr(Vec3Arg zeroValue)
    Return a copy of the argument if the length of the current vector is zero.
    Vec3
    reciprocal()
    Generate the component-wise reciprocal.
    static Vec3
    sAnd(Vec3Arg v1, Vec3Arg v2)
    Return the bitwise AND of the specified vectors.
    static Vec3
    sAxisX()
    Create a unit vector along the 1st (X) principal axis.
    static Vec3
    sAxisY()
    Create a unit vector along the 2nd (Y) principal axis.
    static Vec3
    sAxisZ()
    Create a unit vector along the 3rd (Z) principal axis.
    void
    set(float[] array)
    Set all 3 components from the specified array.
    void
    set(float x, float y, float z)
    Set all 3 components to specified values.
    void
    setX(float x)
    Alter the first (X) component.
    void
    setY(float y)
    Alter the 2nd (Y) component.
    void
    setZ(float z)
    Alter the 3rd (Z) component.
    void
    splatX()
    Copy the X component to all components.
    void
    splatY()
    Copy the Y component to all components.
    void
    splatZ()
    Copy the Z component to all components.
    static Vec3
    sRandom(DefaultRandomEngine engine)
    Generate a pseudo-random unit vector.
    static Vec3
    sReplicate(float value)
    Create a vector with all components identical.
    static Vec3
    sUnitSpherical(float theta, float phi)
    Generate a unit vector with the specified spherical coordinates.
    static Vec3
    sZero()
    Create a vector with all components zero.
    float[]
    toArray()
    Copy the components to an array.
    String
    toString()
    Return a string representation of the vector, which is unaffected.

    Methods inherited from class java.lang.Object

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

  • Constructor Details

    • Vec3

      public Vec3()
      Instantiate an all-zero vector (0,0,0).

    • Vec3

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

    • Vec3

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

    • Vec3

      public Vec3(float[] array)
      Instantiate a vector from the specified array.
      Parameters:
      array - the desired component values (not null, length≥3, unaffected)

    • Vec3

      public Vec3(RVec3Arg vec)
      Instantiate from a location vector.
      Parameters:
      vec - the vector to copy (not null, unaffected)

    • Vec3

      public Vec3(Vec3Arg vec)
      Instantiate a copy of the argument.
      Parameters:
      vec - the vector to copy (not null, unaffected)

  • Method Details

    • add

      public static Vec3 add(Vec3Arg v1, Vec3Arg v2, Vec3Arg v3)
      Return the component-wise sum of the specified vectors.
      Parameters:
      v1 - the first vector (not null, unaffected)
      v2 - the 2nd vector (not null, unaffected)
      v3 - the 3nd vector (not null, unaffected)
      Returns:
      a new vector

    • sAnd

      public static Vec3 sAnd(Vec3Arg v1, Vec3Arg v2)
      Return the bitwise AND of the specified vectors.
      Parameters:
      v1 - the first vector (not null, unaffected)
      v2 - the 2nd vector (not null, unaffected)
      Returns:
      a new vector

    • sAxisX

      public static Vec3 sAxisX()
      Create a unit vector along the 1st (X) principal axis.
      Returns:
      a new vector

    • sAxisY

      public static Vec3 sAxisY()
      Create a unit vector along the 2nd (Y) principal axis.
      Returns:
      a new vector

    • sAxisZ

      public static Vec3 sAxisZ()
      Create a unit vector along the 3rd (Z) principal axis.
      Returns:
      a new vector

    • set

      public void set(float x, float y, float z)
      Set all 3 components to specified values.
      Parameters:
      x - the desired X component
      y - the desired Y component
      z - the desired Z component

    • set

      public void set(float[] array)
      Set all 3 components from the specified array.
      Parameters:
      array - the desired component values (not null, length≥3, unaffected)

    • setX

      public void setX(float x)
      Alter the first (X) component.
      Parameters:
      x - the desired value

    • setY

      public void setY(float y)
      Alter the 2nd (Y) component.
      Parameters:
      y - the desired value

    • setZ

      public void setZ(float z)
      Alter the 3rd (Z) component.
      Parameters:
      z - the desired value

    • splatX

      public void splatX()
      Copy the X component to all components.

    • splatY

      public void splatY()
      Copy the Y component to all components.

    • splatZ

      public void splatZ()
      Copy the Z component to all components.

    • sRandom

      public static Vec3 sRandom(DefaultRandomEngine engine)
      Generate a pseudo-random unit vector.

      The results are not uniformly distributed over the unit sphere.

      Parameters:
      engine - the generator to use (not null)
      Returns:
      a new unit vector

    • sReplicate

      public static Vec3 sReplicate(float value)
      Create a vector with all components identical.
      Parameters:
      value - the desired component value
      Returns:
      a new vector

    • sUnitSpherical

      public static Vec3 sUnitSpherical(float theta, float phi)
      Generate a unit vector with the specified spherical coordinates.
      Parameters:
      theta - angle from the +Z axis (in radians)
      phi - angle from the +X axis in the X-Y plane (in radians)
      Returns:
      a new unit vector

    • sZero

      public static Vec3 sZero()
      Create a vector with all components zero.
      Returns:
      a new vector

    • cross

      public Vec3 cross(Vec3Arg rightFactor)
      Return the cross product with the specified vector. The current vector is unaffected.
      Specified by:
      cross in interface Vec3Arg
      Parameters:
      rightFactor - the vector to cross with the current one (not null, unaffected)
      Returns:
      a new product vector

    • dot

      public float dot(Vec3Arg factor)
      Return the dot product with the specified vector. The current vector is unaffected.
      Specified by:
      dot in interface Vec3Arg
      Parameters:
      factor - the vector to dot with the current one (not null, unaffected)
      Returns:
      the dot product

    • get

      public float get(int index)
      Return the specified component. The vector is unaffected.
      Specified by:
      get in interface Vec3Arg
      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

    • getNormalizedPerpendicular

      public Vec3 getNormalizedPerpendicular()
      Return an arbitrary unit vector perpendicular to the current vector. The current vector is unaffected.
      Specified by:
      getNormalizedPerpendicular in interface Vec3Arg
      Returns:
      a new vector

    • getX

      public float getX()
      Return the first (X) component in single precision. The vector is unaffected.
      Specified by:
      getX in interface Vec3Arg
      Returns:
      the component value

    • getY

      public float getY()
      Return the 2nd (Y) component in single precision. The vector is unaffected.
      Specified by:
      getY in interface Vec3Arg
      Returns:
      the component value

    • getZ

      public float getZ()
      Return the 3rd (Z) component in single precision. The vector is unaffected.
      Specified by:
      getZ in interface Vec3Arg
      Returns:
      the component value

    • isNearZero

      public boolean isNearZero()
      Test whether the vector is zero to within a tolerance of 10^-12. The vector is unaffected.
      Specified by:
      isNearZero in interface Vec3Arg
      Returns:
      true if near zero, otherwise false

    • isNearZero

      public boolean isNearZero(float tolerance)
      Test whether the vector is zero to within the specified tolerance. The vector is unaffected.
      Specified by:
      isNearZero in interface Vec3Arg
      Parameters:
      tolerance - the desired tolerance (default=1e-12)
      Returns:
      true if near zero, otherwise false

    • isNormalized

      public boolean isNormalized()
      Test whether the vector is normalized to within a tolerance of 10^-6. The vector is unaffected.
      Specified by:
      isNormalized in interface Vec3Arg
      Returns:
      true if normalized, otherwise false

    • isNormalized

      public boolean isNormalized(float tolerance)
      Test whether the vector is normalized to within the specified tolerance. The vector is unaffected.
      Specified by:
      isNormalized in interface Vec3Arg
      Parameters:
      tolerance - the desired tolerance (default=1e-6)
      Returns:
      true if normalized, otherwise false

    • length

      public float length()
      Return the length. The vector is unaffected.
      Specified by:
      length in interface Vec3Arg
      Returns:
      the length

    • lengthSq

      public float lengthSq()
      Return the squared length. The vector is unaffected.
      Specified by:
      lengthSq in interface Vec3Arg
      Returns:
      the squared length

    • normalized

      public Vec3 normalized()
      Generate a normalized vector with the same direction. The current vector is unaffected.
      Specified by:
      normalized in interface Vec3Arg
      Returns:
      a new vector

    • normalizedOr

      public Vec3 normalizedOr(Vec3Arg zeroValue)
      Return a copy of the argument if the length of the current vector is zero. Otherwise, generate a normalized vector with the same direction as the current vector. The current vector is unaffected.
      Specified by:
      normalizedOr in interface Vec3Arg
      Parameters:
      zeroValue - the value to return if the length is zero (not null, unaffected)
      Returns:
      a new vector

    • reciprocal

      public Vec3 reciprocal()
      Generate the component-wise reciprocal. The current vector is unaffected.
      Specified by:
      reciprocal in interface Vec3Arg
      Returns:
      a new vector

    • toArray

      public float[] toArray()
      Copy the components to an array. The vector is unaffected.
      Specified by:
      toArray in interface Vec3Arg
      Returns:
      a new array with length=3

    • equals

      public boolean equals(Object other)
      Tests for exact equality with the argument, distinguishing -0 from 0. If other is null, false is returned. Either way, the current instance is unaffected.
      Overrides:
      equals in class Object
      Parameters:
      other - the object to compare (may be null, unaffected)
      Returns:
      true if this and other have identical values, otherwise false

    • hashCode

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

    • toString

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