Module com.github.stephengold.joltjni
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 the specified components.
    Vec3(float[] array)
    Instantiate from the specified array.
    Vec3(float x, float y, float z)
    Instantiate a vector with the specified components.
    Vec3(Float3 float3)
    Instantiate from a Float3.
    Vec3(RVec3Arg vec)
    Instantiate from a location vector.
    Vec3(Vec3Arg vec)
    Instantiate a copy of the argument.
    Vec3(FloatBuffer buffer)
    Instantiate from a buffer.

  • Method Summary

    Modifier and Type
    Method
    Description
    Vec3
    abs()
    Return the absolute value of each component.
    void
    addInPlace(float xOffset, float yOffset, float zOffset)
    Add the specified offsets.
    Vec3
    cross(Vec3Arg rightFactor)
    Return the cross product with the argument.
    float
    dot(Vec3Arg factor)
    Return the dot product with the argument.
    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.
    Vec3
    getSign()
    Return the component-wise (binary) sign.
    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
    isClose(Vec3Arg v2, float maxDistSq)
    Test whether the specified vector lies within the specified squared distance of this one.
    boolean
    isFinite()
    Test whether the vector contains infinities or NaNs.
    boolean
    isNan()
    Test whether the vector contains NaNs.
    boolean
    isNearZero()
    Test whether the squared length is within 10^-12 of zero.
    boolean
    isNearZero(float tolerance)
    Test whether the squared length is within the specified tolerance of zero.
    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.
    void
    loadOne()
    Set all components to 1.
    void
    loadZero()
    Set all components to 0.
    Vec3
    normalized()
    Generate a unit vector with the same direction.
    Vec3
    normalizedOr(Vec3Arg zeroValue)
    Return a copy of the argument if the length of the current vector is zero.
    void
    normalizeInPlace()
    Change the current vector to a unit vector with the same direction.
    void
    put(FloatBuffer storeBuffer)
    Write all 3 components to the specified buffer and advance the buffer's position by 3.
    Vec3
    reciprocal()
    Generate the component-wise reciprocal.
    float
    reduceMax()
    Return the maximum component.
    float
    reduceMin()
    Return the minimum component.
    void
    rotateInPlace(QuatArg rotation)
    Rotate the current vector by the specified quaternion.
    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
    scaleInPlace(float scale)
    Uniformly scale all 3 components.
    void
    scaleInPlace(float xScale, float yScale, float zScale)
    Separately scale each component.
    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
    set(RVec3Arg source)
    Set all 3 components from the specified location vector.
    void
    set(Vec3Arg source)
    Set all 3 components from the argument.
    Vec3
    setX(float x)
    Alter the first (X) component.
    Vec3
    setY(float y)
    Alter the 2nd (Y) component.
    Vec3
    setZ(float z)
    Alter the 3rd (Z) component.
    static UVec4
    sGreater(Vec3Arg v1, Vec3Arg v2)
    Component-wise comparison of 2 vectors.
    static UVec4
    sGreaterOrEqual(Vec3Arg v1, Vec3Arg v2)
    Component-wise comparison of 2 vectors.
    static UVec4
    sLess(Vec3Arg v1, Vec3Arg v2)
    Component-wise comparison of 2 vectors.
    static UVec4
    sLessOrEqual(Vec3Arg v1, Vec3Arg v2)
    Component-wise comparison of 2 vectors.
    static Vec3
    sOne()
    Create a vector with all components set to one.
    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(RandomNumberEngine engine)
    Generate a pseudo-random unit vector.
    static Vec3
    sReplicate(float value)
    Create a vector with all components identical.
    static Vec3
    sSelect(Vec3Arg notSet, Vec3Arg set, UVec4Arg control)
    Component-wise selection between 2 specified vectors.
    void
    standardizeInPlace()
    Replace any -0 elements with +0, in preparation for hashing.
    void
    storeFloat3(Float3 target)
    Copy to a Float3 object.
    static Vec3
    sum(Vec3Arg... vArray)
    Return the component-wise sum of the specified vectors.
    static Vec3
    sUnitSpherical(float theta, float phi)
    Generate a unit vector with the specified spherical coordinates.
    Vec3
    swizzle(int xi, int yi, int zi)
    Copy the specified components to a new vector.
    static Vec3
    sZero()
    Create a vector with all components zero.
    float[]
    toArray()
    Copy the components to an array.
    FloatBuffer
    toBuffer()
    Copy the components to a direct buffer.
    RVec3
    toRVec3()
    Copy the components to a new location vector.
    String
    toString()
    Return a string representation of the vector, which is unaffected.
    void
    transformInPlace(Mat44Arg matrix)
    Transform the current vector by the specified matrix.

    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 the 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 the specified components.
      Parameters:
      x - the desired X component
      y - the desired Y component
      z - the desired Z component

    • Vec3

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

    • Vec3

      public Vec3(Float3 float3)
      Instantiate from a Float3.
      Parameters:
      float3 - the desired component values (not null, unaffected)

    • Vec3

      public Vec3(FloatBuffer buffer)
      Instantiate from a buffer.
      Parameters:
      buffer - the desired component values (not null, unaffected, capacity≥3)

    • Vec3

      public Vec3(RVec3Arg vec)
      Instantiate from a location vector.
      Parameters:
      vec - the vector to convert (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

    • addInPlace

      public void addInPlace(float xOffset, float yOffset, float zOffset)
      Add the specified offsets.
      Parameters:
      xOffset - the amount to add to the X component
      yOffset - the amount to add to the Y component
      zOffset - the amount to add to the Z component

    • loadOne

      public void loadOne()
      Set all components to 1.

    • loadZero

      public void loadZero()
      Set all components to 0.

    • normalizeInPlace

      public void normalizeInPlace()
      Change the current vector to a unit vector with the same direction.

    • rotateInPlace

      public void rotateInPlace(QuatArg rotation)
      Rotate the current vector by the specified quaternion.
      Parameters:
      rotation - the rotation to apply (not null, normalized, unaffected)

    • 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

    • scaleInPlace

      public void scaleInPlace(float scale)
      Uniformly scale all 3 components.
      Parameters:
      scale - the scale factor to apply

    • scaleInPlace

      public void scaleInPlace(float xScale, float yScale, float zScale)
      Separately scale each component.
      Parameters:
      xScale - the scale factor to apply to the X component
      yScale - the scale factor to apply to the Y component
      zScale - the scale factor to apply to the Z component

    • 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)

    • set

      public void set(RVec3Arg source)
      Set all 3 components from the specified location vector.
      Parameters:
      source - the vector to copy (not null, unaffected)

    • set

      public void set(Vec3Arg source)
      Set all 3 components from the argument.
      Parameters:
      source - the vector to copy (not null, unaffected)

    • setX

      public Vec3 setX(float x)
      Alter the first (X) component.
      Parameters:
      x - the desired value
      Returns:
      the modified vector, for chaining

    • setY

      public Vec3 setY(float y)
      Alter the 2nd (Y) component.
      Parameters:
      y - the desired value
      Returns:
      the modified vector, for chaining

    • setZ

      public Vec3 setZ(float z)
      Alter the 3rd (Z) component.
      Parameters:
      z - the desired value
      Returns:
      the modified vector, for chaining

    • sGreater

      public static UVec4 sGreater(Vec3Arg v1, Vec3Arg v2)
      Component-wise comparison of 2 vectors.
      Parameters:
      v1 - the first vector (not null, unaffected)
      v2 - the 2nd vector (not null, unaffected)
      Returns:
      a new vector (each component 0 or -1)

    • sGreaterOrEqual

      public static UVec4 sGreaterOrEqual(Vec3Arg v1, Vec3Arg v2)
      Component-wise comparison of 2 vectors.
      Parameters:
      v1 - the first vector (not null, unaffected)
      v2 - the 2nd vector (not null, unaffected)
      Returns:
      a new vector (each component 0 or -1)

    • sLess

      public static UVec4 sLess(Vec3Arg v1, Vec3Arg v2)
      Component-wise comparison of 2 vectors.
      Parameters:
      v1 - the first vector (not null, unaffected)
      v2 - the 2nd vector (not null, unaffected)
      Returns:
      a new vector (each component 0 or -1)

    • sLessOrEqual

      public static UVec4 sLessOrEqual(Vec3Arg v1, Vec3Arg v2)
      Component-wise comparison of 2 vectors.
      Parameters:
      v1 - the first vector (not null, unaffected)
      v2 - the 2nd vector (not null, unaffected)
      Returns:
      a new vector (each component 0 or -1)

    • sOne

      public static Vec3 sOne()
      Create a vector with all components set to one.
      Returns:
      a new vector

    • 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(RandomNumberEngine 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

    • sSelect

      public static Vec3 sSelect(Vec3Arg notSet, Vec3Arg set, UVec4Arg control)
      Component-wise selection between 2 specified vectors.
      Parameters:
      notSet - components to select where the control is zero (not null, unaffected)
      set - components to select where the control is non-zero (not null, unaffected)
      control - to control the selection (not null, unaffected)
      Returns:
      a new vector

    • standardizeInPlace

      public void standardizeInPlace()
      Replace any -0 elements with +0, in preparation for hashing.

    • sum

      public static Vec3 sum(Vec3Arg... vArray)
      Return the component-wise sum of the specified vectors.
      Parameters:
      vArray - an array of input vectors (not null, unaffected)
      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

    • transformInPlace

      public void transformInPlace(Mat44Arg matrix)
      Transform the current vector by the specified matrix.
      Parameters:
      matrix - the transformation to apply (not null, unaffected)

    • abs

      public Vec3 abs()
      Return the absolute value of each component. The vector is unaffected.
      Specified by:
      abs in interface Vec3Arg
      Returns:
      a new vector with no negative components

    • cross

      public Vec3 cross(Vec3Arg rightFactor)
      Return the cross product with the argument. Both vectors are 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 argument. Both vectors are 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

    • getSign

      public Vec3 getSign()
      Return the component-wise (binary) sign. The current vector is unaffected.
      Specified by:
      getSign in interface Vec3Arg
      Returns:
      a new vector (each component 1 or -1)

    • 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

    • isFinite

      public boolean isFinite()
      Test whether the vector contains infinities or NaNs. The vector is unaffected.
      Specified by:
      isFinite in interface Vec3Arg
      Returns:
      false if one or more infinities or NaNs, otherwise true

    • isNan

      public boolean isNan()
      Test whether the vector contains NaNs. The vector is unaffected.
      Specified by:
      isNan in interface Vec3Arg
      Returns:
      true if one or more NaNs, otherwise false

    • isNearZero

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

    • isNearZero

      public boolean isNearZero(float tolerance)
      Test whether the squared length is within the specified tolerance of zero. The vector is unaffected.
      Specified by:
      isNearZero in interface Vec3Arg
      Parameters:
      tolerance - the desired tolerance (≥0, default=1e-12)
      Returns:
      true if nearly 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 (≥0, default=1e-6)
      Returns:
      true if normalized, otherwise false

    • isClose

      public boolean isClose(Vec3Arg v2, float maxDistSq)
      Test whether the specified vector lies within the specified squared distance of this one. Both vectors are unaffected.
      Specified by:
      isClose in interface Vec3Arg
      Parameters:
      v2 - the vector to compare with (not null, unaffected)
      maxDistSq - the maximum allowed squared distance (≥0)
      Returns:
      true if within the squared distance, 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 unit 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 unit 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

    • put

      public void put(FloatBuffer storeBuffer)
      Write all 3 components to the specified buffer and advance the buffer's position by 3. The vector is unaffected.
      Specified by:
      put in interface Vec3Arg
      Parameters:
      storeBuffer - the destination buffer (not null)

    • reciprocal

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

    • reduceMax

      public float reduceMax()
      Return the maximum component. The current vector is unaffected.
      Specified by:
      reduceMax in interface Vec3Arg
      Returns:
      a component value

    • reduceMin

      public float reduceMin()
      Return the minimum component. The current vector is unaffected.
      Specified by:
      reduceMin in interface Vec3Arg
      Returns:
      a component value

    • storeFloat3

      public void storeFloat3(Float3 target)
      Copy to a Float3 object. The vector is unaffected.
      Specified by:
      storeFloat3 in interface Vec3Arg
      Parameters:
      target - the destination (not null, modified)

    • swizzle

      public Vec3 swizzle(int xi, int yi, int zi)
      Copy the specified components to a new vector. The current vector is unaffected.
      Specified by:
      swizzle in interface Vec3Arg
      Parameters:
      xi - index of the component to copy to the first (X) component of the result (0, 1, or 2)
      yi - index of the component to copy to the 2nd (Y) component of the result (0, 1, or 2)
      zi - index of the component to copy to the 3rd (Z) component of the result (0, 1, or 2)
      Returns:
      the 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

    • toBuffer

      public FloatBuffer toBuffer()
      Copy the components to a direct buffer. The vector is unaffected.
      Specified by:
      toBuffer in interface Vec3Arg
      Returns:
      a new direct buffer with capacity=3

    • toRVec3

      public RVec3 toRVec3()
      Copy the components to a new location vector. The current vector is unaffected.
      Specified by:
      toRVec3 in interface Vec3Arg
      Returns:
      a new vector

    • 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 (unaffected) or null
      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)