Package jme3utilities.math

Interface ReadXZ

All Known Implementing Classes:
VectorXZ
public interface ReadXZ
Single-precision vector with no 'y' coordinate, used to represent horizontal locations, offsets, orientations, directions, rotations, and extents. For viewport coordinates, use Vector2f instead.

By convention, +X is north/forward and +Z is east/right.

  • Method Summary

    Modifier and Type
    Method
    Description
    boolean
    aboutEquals(ReadXZ otherVector, float absoluteTolerance)
    Test for approximate equality with another vector using a Chebyshev metric.
    ReadXZ
    add(ReadXZ increment)
    Add to (translate) this vector.
    float
    azimuth()
    Determine the azimuth of this vector.
    ReadXZ
    cardinalize()
    Convert this vector to one of the 4 cardinal directions.
    ReadXZ
    clampDirection(float maxAbsAngle)
    Clamp this vector to be within a specified angle of north (the +X axis).
    ReadXZ
    clampElliptical(float maxX, float maxZ)
    Clamp this vector to be within an origin-centered, axis-aligned ellipse.
    ReadXZ
    clampLength(float radius)
    Clamp this vector to be within an origin-centered circle.
    int
    compareTo(float hX, float hZ)
    Compare lexicographically with a hypothetical vector having the specified components, distinguishing 0 and -0 and giving priority to the X components.
    double
    cosineAngleBetween(ReadXZ otherVector)
    Determine the cosine of the angle between this vector and another.
    float
    cross(ReadXZ otherVector)
    Determine the (left-handed) cross product of this vector with another.
    float
    directionError(ReadXZ directionGoal)
    Determine a signed directional error of this vector with respect to a goal.
    ReadXZ
    divide(float scalar)
    Divide this vector by a scalar.
    double
    dot(ReadXZ otherVector)
    Determine the dot (scalar) product of this vector with another.
    boolean
    equals(float hX, float hZ)
    Test for equality with a hypothetical vector having the specified components, distinguishing 0 and -0.
    ReadXZ
    firstQuadrant()
    Mirror (or reflect) this vector to the first quadrant.
    float
    getX()
    Read the X-component of this vector.
    float
    getZ()
    Read the Z-component of this vector.
    ReadXZ
    interpolate(ReadXZ otherVector, float otherFraction)
    Interpolate (blend) this vector with another.
    boolean
    isFirstQuadrant()
    Test whether this vector is in the first quadrant.
    boolean
    isZero()
    Test whether this vector is a zero vector.
    float
    length()
    Determine the length (or magnitude or norm) of this vector.
    double
    lengthSquared()
    Determine the squared length of this vector.
    ReadXZ
    mirrorZ()
    Mirror (or reflect) this vector across the X-axis (complex conjugate or inverse rotation).
    ReadXZ
    mult(float multiplier)
    Scale this vector by a scalar.
    ReadXZ
    mult(ReadXZ multiplier)
    Multiply this vector by another (complex product or rotate-and-scale).
    ReadXZ
    negate()
    Negate this vector (or reverse its direction or reflect it in the origin).
    ReadXZ
    normalize()
    Normalize this vector to a unit vector.
    ReadXZ
    rotate(float radians)
    Rotate a vector CLOCKWISE about the +Y axis.
    ReadXZ
    scale(ReadXZ multiplier)
    Scale this vector by another (non-uniform scaling).
    ReadXZ
    subtract(ReadXZ decrement)
    Subtract from (inverse translate) this vector.
    com.jme3.math.Quaternion
    toQuaternion()
    Treating this vector as a rotation (from north), generate an equivalent Quaternion.
    com.jme3.math.Quaternion
    toQuaternion(com.jme3.math.Quaternion storeResult)
    Treating this vector as a rotation (from north), generate an equivalent Quaternion.
    com.jme3.math.Vector3f
    toVector3f()
    Create an equivalent 3-D vector.
    com.jme3.math.Vector3f
    toVector3f(float y)
    Create an equivalent 3-D vector with the specified y value.
    com.jme3.math.Vector3f
    toVector3f(float y, com.jme3.math.Vector3f storeResult)
    Create an equivalent 3-D vector with the specified y value.

  • Method Details

    • aboutEquals

      boolean aboutEquals(ReadXZ otherVector, float absoluteTolerance)
      Test for approximate equality with another vector using a Chebyshev metric.
      Parameters:
      otherVector - (not null)
      absoluteTolerance - (≥0)
      Returns:
      true if each component differs by tolerance or less, otherwise false

    • add

      ReadXZ add(ReadXZ increment)
      Add to (translate) this vector.
      Parameters:
      increment - vector to be added to this vector (not null)
      Returns:
      a sum vector
      See Also:
      • Vector3f.add(com.jme3.math.Vector3f)

    • azimuth

      float azimuth()
      Determine the azimuth of this vector. Note: the directional convention is left-handed. If this vector is zero, return zero.
      Returns:
      angle in radians (>-Pi, ≤Pi), measured CW from north (the +X direction)

    • cardinalize

      ReadXZ cardinalize()
      Convert this vector to one of the 4 cardinal directions. If this vector is zero, return a zero vector.
      Returns:
      a unit vector (4 possible values) or a zero vector

    • clampDirection

      ReadXZ clampDirection(float maxAbsAngle)
      Clamp this vector to be within a specified angle of north (the +X axis).
      Parameters:
      maxAbsAngle - tolerance angle in radians (≥0, ≤Pi)
      Returns:
      clamped vector with same length

    • clampElliptical

      ReadXZ clampElliptical(float maxX, float maxZ)
      Clamp this vector to be within an origin-centered, axis-aligned ellipse.
      Parameters:
      maxX - radius of the ellipse in the X-direction (≥0)
      maxZ - radius of the ellipse in the Z-direction (≥0)
      Returns:
      clamped vector with the same direction

    • clampLength

      ReadXZ clampLength(float radius)
      Clamp this vector to be within an origin-centered circle.
      Parameters:
      radius - radius of the circle (≥0)
      Returns:
      clamped vector with the same direction
      See Also:

    • compareTo

      int compareTo(float hX, float hZ)
      Compare lexicographically with a hypothetical vector having the specified components, distinguishing 0 and -0 and giving priority to the X components.
      Parameters:
      hX - X component of the hypothetical vector
      hZ - Z component of the hypothetical vector
      Returns:
      0 if this vector equals the hypothetical; negative if this comes before the hypothetical; positive if this comes after hypothetical

    • cosineAngleBetween

      double cosineAngleBetween(ReadXZ otherVector)
      Determine the cosine of the angle between this vector and another. This is used to compare the similarity of direction vectors. Returns a double-precision value for precise comparisons.
      Parameters:
      otherVector - the other vector (not null)
      Returns:
      the cosine of the angle (≥-1, ≤1) or 1 if either vector is zero
      See Also:
      • Vector3f.angleBetween(com.jme3.math.Vector3f)

    • cross

      float cross(ReadXZ otherVector)
      Determine the (left-handed) cross product of this vector with another. For example, north.cross(east) = +1 and east.cross(north) = -1.
      Parameters:
      otherVector - the other vector (not null)
      Returns:
      the left-handed cross product
      See Also:
      • Vector3f.cross(com.jme3.math.Vector3f)

    • directionError

      float directionError(ReadXZ directionGoal)
      Determine a signed directional error of this vector with respect to a goal. The result is positive if the goal is to the right and negative if the goal is to the left.
      Parameters:
      directionGoal - goal direction (not null, not zero)
      Returns:
      the sine of the angle from the goal, or +/-1 if that angle's magnitude exceeds 90 degrees

    • divide

      ReadXZ divide(float scalar)
      Divide this vector by a scalar.
      Parameters:
      scalar - scaling factor (not zero)
      Returns:
      a vector 'scalar' times shorter than this one, with same direction if scalar>0, opposite direction if scalar<0
      See Also:
      • Vector3f.divide(float)

    • dot

      double dot(ReadXZ otherVector)
      Determine the dot (scalar) product of this vector with another.
      Parameters:
      otherVector - other vector (not null)
      Returns:
      the dot product
      See Also:

    • equals

      boolean equals(float hX, float hZ)
      Test for equality with a hypothetical vector having the specified components, distinguishing 0 and -0.
      Parameters:
      hX - X component of the hypothetical vector
      hZ - Z component of the hypothetical vector
      Returns:
      true if equivalent, otherwise false

    • firstQuadrant

      ReadXZ firstQuadrant()
      Mirror (or reflect) this vector to the first quadrant.
      Returns:
      a mirrored vector with the same length, both components ≥0

    • getX

      float getX()
      Read the X-component of this vector.
      Returns:
      the X-component
      See Also:
      • Vector3f.getX()

    • getZ

      float getZ()
      Read the Z-component of this vector.
      Returns:
      the Z-component
      See Also:
      • Vector3f.getZ()

    • interpolate

      ReadXZ interpolate(ReadXZ otherVector, float otherFraction)
      Interpolate (blend) this vector with another.
      Parameters:
      otherVector - other vector (not null)
      otherFraction - how much weight to give to the other vector (≥0, ≤1, 0 → purely this, 1 → purely the other)
      Returns:
      a blended vector

    • isFirstQuadrant

      boolean isFirstQuadrant()
      Test whether this vector is in the first quadrant.
      Returns:
      true if both components are ≥0, false otherwise
      See Also:

    • isZero

      boolean isZero()
      Test whether this vector is a zero vector.
      Returns:
      true if both components are zero, false otherwise
      See Also:

    • length

      float length()
      Determine the length (or magnitude or norm) of this vector.
      Returns:
      the length (≥0)
      See Also:
      • Vector3f.length()

    • lengthSquared

      double lengthSquared()
      Determine the squared length of this vector. This is used to compare the lengths of vectors. Returns a double-precision value for precise comparisons.
      Returns:
      the squared length (≥0)
      See Also:

    • mirrorZ

      ReadXZ mirrorZ()
      Mirror (or reflect) this vector across the X-axis (complex conjugate or inverse rotation).
      Returns:
      a mirrored vector with the same length

    • mult

      ReadXZ mult(float multiplier)
      Scale this vector by a scalar.
      Parameters:
      multiplier - scaling factor
      Returns:
      a vector 'scalar' times longer than this one, with same direction if multiplier>0, opposite direction if multiplier<0
      See Also:
      • Vector3f.mult(float)

    • mult

      ReadXZ mult(ReadXZ multiplier)
      Multiply this vector by another (complex product or rotate-and-scale). This is NOT analogous to Vector3f.mult(Vector3f), which performs non-uniform scaling.
      Parameters:
      multiplier - rotated/scaled result for the current north (not null)
      Returns:
      the complex product
      See Also:

    • negate

      ReadXZ negate()
      Negate this vector (or reverse its direction or reflect it in the origin). This is equivalent to #mult(-1f)
      Returns:
      a vector with same magnitude and opposite direction
      See Also:
      • Vector3f.negate()

    • normalize

      ReadXZ normalize()
      Normalize this vector to a unit vector. If this vector is zero, return a zero vector.
      Returns:
      a unit vector (with the same direction) or a zero vector
      See Also:
      • Vector3f.normalize()

    • rotate

      ReadXZ rotate(float radians)
      Rotate a vector CLOCKWISE about the +Y axis. Note: This method is used to apply azimuths, which is why its angle convention is left-handed.
      Parameters:
      radians - clockwise (LH) angle of rotation in radians
      Returns:
      a vector with the same length
      See Also:
      • Vector2f.rotateAroundOrigin(float, boolean)

    • scale

      ReadXZ scale(ReadXZ multiplier)
      Scale this vector by another (non-uniform scaling).
      Parameters:
      multiplier - scaled result for the current north (not null)
      Returns:
      a scaled vector
      See Also:
      • Vector3f.mult(com.jme3.math.Vector3f)

    • subtract

      ReadXZ subtract(ReadXZ decrement)
      Subtract from (inverse translate) this vector.
      Parameters:
      decrement - vector to be subtracted from this vector (not null)
      Returns:
      a vector equal to the difference of the 2 vectors
      See Also:
      • Vector3f.subtract(com.jme3.math.Vector3f)

    • toQuaternion

      com.jme3.math.Quaternion toQuaternion()
      Treating this vector as a rotation (from north), generate an equivalent Quaternion.
      Returns:
      a new Quaternion

    • toQuaternion

      com.jme3.math.Quaternion toQuaternion(com.jme3.math.Quaternion storeResult)
      Treating this vector as a rotation (from north), generate an equivalent Quaternion.
      Parameters:
      storeResult - storage for the result (modified if not null)
      Returns:
      a Quaternion (either storeResult or a new instance, not null)

    • toVector3f

      com.jme3.math.Vector3f toVector3f()
      Create an equivalent 3-D vector.
      Returns:
      a new 3-D vector with y=0

    • toVector3f

      com.jme3.math.Vector3f toVector3f(float y)
      Create an equivalent 3-D vector with the specified y value.
      Parameters:
      y - the y-coordinate
      Returns:
      a new 3-D vector

    • toVector3f

      com.jme3.math.Vector3f toVector3f(float y, com.jme3.math.Vector3f storeResult)
      Create an equivalent 3-D vector with the specified y value.
      Parameters:
      y - the y-coordinate
      storeResult - storage for the result (modified if not null)
      Returns:
      a 3-D vector (either storeResult or a new instance, not null)