Module com.github.stephengold.joltjni
Package com.github.stephengold.joltjni

Class RVec3

java.lang.Object
com.github.stephengold.joltjni.RVec3
All Implemented Interfaces:
RVec3Arg
public final class RVec3 extends Object implements RVec3Arg
A vector composed of 3 double-precision components, used to represent locations in 3-dimensional space.

  • Constructor Summary

    Constructors
    Constructor
    Description
    RVec3()
    Instantiate an all-zero vector (0,0,0).
    RVec3(double[] array)
    Instantiate from the specified array.
    RVec3(double x, double y, double z)
    Instantiate a vector with the specified components.
    RVec3(Float3 float3)
    Instantiate from a Float3.
    RVec3(RVec3Arg vec)
    Instantiate a copy of the argument.
    RVec3(Vec3Arg vec)
    Instantiate from a single-precision vector.
    RVec3(DoubleBuffer buffer)
    Instantiate from a buffer.

  • Method Summary

    Modifier and Type
    Method
    Description
    void
    addInPlace(double xOffset, double yOffset, double zOffset)
    Add the specified offsets.
    RVec3
    cross(RVec3Arg rightFactor)
    Return the cross product with the argument.
    double
    dot(RVec3Arg factor)
    Return the dot product with the argument.
    double
    get(int index)
    Return the specified component in double precision.
    Object
    getX()
    Return the first (X) component at positional precision.
    Object
    getY()
    Return the 2nd (Y) component at positional precision.
    Object
    getZ()
    Return the 3rd (Z) component at positional precision.
    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 (single-precision) or 10^-24 (double-precision) of zero.
    boolean
    isNearZero(double 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 (single precision) or 10^-12 (double precision).
    boolean
    isNormalized(double tolerance)
    Test whether the vector is normalized to within the specified tolerance.
    double
    length()
    Return the length.
    double
    lengthSq()
    Return the squared length.
    void
    loadOne()
    Set all components to 1.
    void
    loadZero()
    Set all components to 0.
    RVec3
    normalized()
    Generate a unit vector with the same direction.
    void
    normalizeInPlace()
    Change the current vector to a unit vector with the same direction.
    RVec3
    reciprocal()
    Generate the component-wise reciprocal.
    void
    rotateInPlace(QuatArg rotation)
    Rotate the current vector by the specified quaternion.
    static RVec3
    sAxisX()
    Create a unit vector along the 1st (X) principal axis.
    static RVec3
    sAxisY()
    Create a unit vector along the 2nd (Y) principal axis.
    static RVec3
    sAxisZ()
    Create a unit vector along the 3rd (Z) principal axis.
    void
    scaleInPlace(double scale)
    Uniformly scale all 3 components.
    void
    scaleInPlace(double xScale, double yScale, double zScale)
    Separately scale each component.
    void
    set(double[] array)
    Set all 3 components from the specified array.
    void
    set(double x, double y, double z)
    Set all 3 components to specified values.
    void
    set(RVec3Arg source)
    Set all 3 components from the argument.
    void
    set(Vec3Arg source)
    Set all 3 components from the specified single-precision vector.
    RVec3
    setX(double x)
    Alter the first (X) component.
    RVec3
    setY(double y)
    Alter the 2nd (Y) component.
    RVec3
    setZ(double z)
    Alter the 3rd (Z) component.
    static RVec3
    sReplicate(double value)
    Create a vector with all components identical.
    static RVec3
    sum(RVec3Arg... vArray)
    Return the component-wise sum of the specified vectors.
    static RVec3
    sZero()
    Create a vector with all components zero.
    double[]
    toArray()
    Copy the components to an array.
    String
    toString()
    Return a string representation of the vector, which is unaffected.
    Vec3
    toVec3()
    Convert to single-precision vector.
    void
    transformInPlace(RMat44Arg matrix)
    Transform the current vector by the specified matrix.
    float
    x()
    Return the first (X) component in single precision.
    double
    xx()
    Return the first (X) component in double precision.
    float
    y()
    Return the 2nd (Y) component in single precision.
    double
    yy()
    Return the 2nd (Y) component in double precision.
    float
    z()
    Return the 3rd (Z) component in single precision.
    double
    zz()
    Return the 3rd (Z) component in double precision.

    Methods inherited from class java.lang.Object

    clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

  • Constructor Details

    • RVec3

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

    • RVec3

      public RVec3(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

    • RVec3

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

    • RVec3

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

    • RVec3

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

    • RVec3

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

    • RVec3

      public RVec3(Vec3Arg vec)
      Instantiate from a single-precision vector.
      Parameters:
      vec - the vector to convert (not null, unaffected)

  • Method Details

    • addInPlace

      public void addInPlace(double xOffset, double yOffset, double 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)

    • sAxisX

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

    • sAxisY

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

    • sAxisZ

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

    • scaleInPlace

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

    • scaleInPlace

      public void scaleInPlace(double xScale, double yScale, double 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(double x, double y, double 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(double[] 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 argument.
      Parameters:
      source - the vector to copy (not null, unaffected)

    • set

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

    • setX

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

    • setY

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

    • setZ

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

    • sReplicate

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

    • sum

      public static RVec3 sum(RVec3Arg... vArray)
      Return the component-wise sum of the specified vectors.
      Parameters:
      vArray - an array of input vectors (not null, unaffected)
      Returns:
      a new vector

    • sZero

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

    • transformInPlace

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

    • cross

      public RVec3 cross(RVec3Arg rightFactor)
      Return the cross product with the argument. Both vectors are unaffected.
      Specified by:
      cross in interface RVec3Arg
      Parameters:
      rightFactor - the vector to cross with the current one (not null, unaffected)
      Returns:
      a new product vector

    • dot

      public double dot(RVec3Arg factor)
      Return the dot product with the argument. Both vectors are unaffected.
      Specified by:
      dot in interface RVec3Arg
      Parameters:
      factor - the vector to dot with the current one (not null, unaffected)
      Returns:
      the dot product

    • get

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

    • getX

      public Object getX()
      Return the first (X) component at positional precision. The vector is unaffected.
      Specified by:
      getX in interface RVec3Arg
      Returns:
      the component value

    • getY

      public Object getY()
      Return the 2nd (Y) component at positional precision. The vector is unaffected.
      Specified by:
      getY in interface RVec3Arg
      Returns:
      the component value

    • getZ

      public Object getZ()
      Return the 3rd (Z) component at positional precision. The vector is unaffected.
      Specified by:
      getZ in interface RVec3Arg
      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 RVec3Arg
      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 RVec3Arg
      Returns:
      true if one or more NaNs, otherwise false

    • isNearZero

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

    • isNearZero

      public boolean isNearZero(double tolerance)
      Test whether the squared length is within the specified tolerance of zero. The vector is unaffected.
      Specified by:
      isNearZero in interface RVec3Arg
      Parameters:
      tolerance - the desired tolerance (≥0, default=1e-12 or 1e-24)
      Returns:
      true if nearly zero, otherwise false

    • isNormalized

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

    • isNormalized

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

    • length

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

    • lengthSq

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

    • normalized

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

    • reciprocal

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

    • toArray

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

    • toVec3

      public Vec3 toVec3()
      Convert to single-precision vector. The current vector is unaffected.
      Specified by:
      toVec3 in interface RVec3Arg
      Returns:
      a new vector

    • x

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

    • xx

      public double xx()
      Return the first (X) component in double precision. The vector is unaffected.
      Specified by:
      xx in interface RVec3Arg
      Returns:
      the component value

    • y

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

    • yy

      public double yy()
      Return the 2nd (Y) component in double precision. The vector is unaffected.
      Specified by:
      yy in interface RVec3Arg
      Returns:
      the component value

    • z

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

    • zz

      public double zz()
      Return the 3rd (Z) component in double precision. The vector is unaffected.
      Specified by:
      zz in interface RVec3Arg
      Returns:
      the component value

    • toString

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