public abstract class Vec

Known direct subclasses
ImmutableVec

An immutable two-dimensional vector, i.e. an (x, y) coordinate pair.
MutableVec

A mutable two-dimensional vector, i.e. an (x, y) coordinate pair.

A two-dimensional vector, i.e. an (x, y) coordinate pair. It can be used to represent either:

  1. A two-dimensional offset, i.e. the difference between two points

  2. A point in space, i.e. treating the vector as an offset from the origin

Summary

Public fields
static final @NonNull ImmutableVec

The origin of the coordinate system, i.e. (0, 0).

Public methods
static final @AngleRadiansFloat @FloatRange(from = 0.0, to = 3.141592653589793) float

Returns the absolute angle between the given vectors.
static final void
add(@NonNull Vec lhs, @NonNull Vec rhs, @NonNull MutableVec output)

Adds the x and y values of both Vec objects and stores the result in output.
final @FloatRange(from = -3.141592653589793, to = 3.141592653589793) @AngleRadiansFloat float

The direction of the vec, represented as the angle between the positive x-axis and this vec.
final @FloatRange(from = 0.0) float

The length of the Vec.
final @FloatRange(from = 0.0) float

The squared length of the Vec.
final @NonNull ImmutableVec

Returns a newly allocated vector with the same magnitude, but pointing in the opposite direction.
final @NonNull MutableVec

Modifies outVec into a vector with the same magnitude, but pointing in the opposite direction.
final @NonNull ImmutableVec

Returns a newly allocated vector with the same magnitude as this one, but rotated by (positive) 90 degrees.
final @NonNull MutableVec

Modifies outVec into a vector with the same magnitude as this one, but rotated by (positive) 90 degrees.
final @NonNull ImmutableVec

Returns a newly allocated vector with the same direction as this one, but with a magnitude of 1.
final @NonNull MutableVec

Modifies outVec into a vector with the same direction as this one, but with a magnitude of 1.
static final float

Returns the determinant (×) of the two vectors.
static final void
divide(@NonNull Vec lhs, float rhs, @NonNull MutableVec output)

Divides the x and y values of the Vec by the Float and stores the result in output.
static final float

Returns the dot product (⋅) of the two vectors.
abstract float

The Vec's offset in the x-direction
abstract float

The Vec's offset in the y-direction
final boolean
isAlmostEqual(@NonNull Vec other, @FloatRange(from = 0.0) float tolerance)

Compares this Vec with other, and returns true if the difference between x and other.x is less than tolerance, and likewise for y.
final boolean
isParallelTo(
    @NonNull Vec other,
    @AngleRadiansFloat @FloatRange(from = 0.0) float angleTolerance
)

Returns true if the angle formed by this and other is within angleTolerance of 0 radians or π radians (0 degrees or 180 degrees).
final boolean
isPerpendicularTo(
    @NonNull Vec other,
    @AngleRadiansFloat @FloatRange(from = 0.0) float angleTolerance
)

Returns true if the angle formed by this and other is within angleTolerance of ±π/2 radians (±90 degrees).
static final void
multiply(float lhs, @NonNull Vec rhs, @NonNull MutableVec output)

Multiplies the x and y values of the Vec by the Float and stores the result in output.
static final void
multiply(@NonNull Vec lhs, float rhs, @NonNull MutableVec output)

Multiplies the x and y values of the Vec by the Float and stores the result in output.
static final @AngleRadiansFloat @FloatRange(from = -3.141592653589793, to = 3.141592653589793, fromInclusive = false) float

Returns the signed angle between the given vectors.
static final void
subtract(@NonNull Vec lhs, @NonNull Vec rhs, @NonNull MutableVec output)

Subtracts the x and y values of rhs from the x and y values of lhs and stores the result in output.

Public fields

ORIGIN

public static final @NonNull ImmutableVec ORIGIN

The origin of the coordinate system, i.e. (0, 0).

Public methods

absoluteAngleBetween

Added in 1.0.0-alpha01
public static final @AngleRadiansFloat @FloatRange(from = 0.0, to = 3.141592653589793) float absoluteAngleBetween(@NonNull Vec lhs, @NonNull Vec rhs)

Returns the absolute angle between the given vectors. The return value will lie in the interval 0, π.

add

Added in 1.0.0-alpha01
public static final void add(@NonNull Vec lhs, @NonNull Vec rhs, @NonNull MutableVec output)

Adds the x and y values of both Vec objects and stores the result in output.

computeDirection

Added in 1.0.0-alpha01
public final @FloatRange(from = -3.141592653589793, to = 3.141592653589793) @AngleRadiansFloat float computeDirection()

The direction of the vec, represented as the angle between the positive x-axis and this vec. If either component of the vector is NaN, this returns a NaN angle; otherwise, the returned value will lie in the interval -π, π, and will have the same sign as the vector's y-component.

Following the behavior of atan2, this will return either ±0 or ±π for the zero vector, depending on the signs of the zeros.

computeMagnitude

Added in 1.0.0-alpha01
public final @FloatRange(from = 0.0) float computeMagnitude()

The length of the Vec.

computeMagnitudeSquared

Added in 1.0.0-alpha01
public final @FloatRange(from = 0.0) float computeMagnitudeSquared()

The squared length of the Vec.

computeNegation

Added in 1.0.0-alpha01
public final @NonNull ImmutableVec computeNegation()

Returns a newly allocated vector with the same magnitude, but pointing in the opposite direction. For performance-sensitive code, use computeNegation with a pre-allocated instance of MutableVec.

computeNegation

Added in 1.0.0-alpha01
public final @NonNull MutableVec computeNegation(@NonNull MutableVec outVec)

Modifies outVec into a vector with the same magnitude, but pointing in the opposite direction. Returns outVec.

computeOrthogonal

Added in 1.0.0-alpha01
public final @NonNull ImmutableVec computeOrthogonal()

Returns a newly allocated vector with the same magnitude as this one, but rotated by (positive) 90 degrees. For performance-sensitive code, use computeOrthogonal with a pre-allocated instance of MutableVec.

computeOrthogonal

Added in 1.0.0-alpha01
public final @NonNull MutableVec computeOrthogonal(@NonNull MutableVec outVec)

Modifies outVec into a vector with the same magnitude as this one, but rotated by (positive) 90 degrees. Returns outVec.

computeUnitVec

Added in 1.0.0-alpha01
public final @NonNull ImmutableVec computeUnitVec()

Returns a newly allocated vector with the same direction as this one, but with a magnitude of 1. This is equivalent to (but faster than) calling ImmutableVec.fromDirectionAndMagnitude with computeDirection and 1.

In keeping with the above equivalence, this will return <±1, ±0> for the zero vector, depending on the signs of the zeros.

For performance-sensitive code, use computeUnitVec with a pre-allocated instance of MutableVec.

computeUnitVec

Added in 1.0.0-alpha01
public final @NonNull MutableVec computeUnitVec(@NonNull MutableVec outVec)

Modifies outVec into a vector with the same direction as this one, but with a magnitude of 1. Returns outVec. This is equivalent to (but faster than) calling MutableVec.fromDirectionAndMagnitude with computeDirection and 1.

In keeping with the above equivalence, this will return <±1, ±0> for the zero vector, depending on the signs of the zeros.

determinant

Added in 1.0.0-alpha01
public static final float determinant(@NonNull Vec lhs, @NonNull Vec rhs)

Returns the determinant (×) of the two vectors. The determinant can be thought of as the z-component of the 3D cross product of the two vectors, if they were placed on the xy-plane in 3D space. The determinant has the property that, for vectors a and b: a × b = ‖a‖ * ‖b‖ * sin(θ) where ‖d‖ is the magnitude of the vector, and θ is the signed angle from a to b.

divide

Added in 1.0.0-alpha01
public static final void divide(@NonNull Vec lhs, float rhs, @NonNull MutableVec output)

Divides the x and y values of the Vec by the Float and stores the result in output.

dotProduct

Added in 1.0.0-alpha01
public static final float dotProduct(@NonNull Vec lhs, @NonNull Vec rhs)

Returns the dot product (⋅) of the two vectors. The dot product has the property that, for vectors a and b: a ⋅ b = ‖a‖ * ‖b‖ * cos(θ) where ‖d‖ is the magnitude of the vector, and θ is the angle from a to b.

getX

Added in 1.0.0-alpha01
public abstract float getX()

The Vec's offset in the x-direction

getY

Added in 1.0.0-alpha01
public abstract float getY()

The Vec's offset in the y-direction

isAlmostEqual

Added in 1.0.0-alpha01
public final boolean isAlmostEqual(@NonNull Vec other, @FloatRange(from = 0.0) float tolerance)

Compares this Vec with other, and returns true if the difference between x and other.x is less than tolerance, and likewise for y.

isParallelTo

Added in 1.0.0-alpha01
public final boolean isParallelTo(
    @NonNull Vec other,
    @AngleRadiansFloat @FloatRange(from = 0.0) float angleTolerance
)

Returns true if the angle formed by this and other is within angleTolerance of 0 radians or π radians (0 degrees or 180 degrees).

isPerpendicularTo

Added in 1.0.0-alpha01
public final boolean isPerpendicularTo(
    @NonNull Vec other,
    @AngleRadiansFloat @FloatRange(from = 0.0) float angleTolerance
)

Returns true if the angle formed by this and other is within angleTolerance of ±π/2 radians (±90 degrees).

multiply

Added in 1.0.0-alpha01
public static final void multiply(float lhs, @NonNull Vec rhs, @NonNull MutableVec output)

Multiplies the x and y values of the Vec by the Float and stores the result in output.

multiply

Added in 1.0.0-alpha01
public static final void multiply(@NonNull Vec lhs, float rhs, @NonNull MutableVec output)

Multiplies the x and y values of the Vec by the Float and stores the result in output.

signedAngleBetween

Added in 1.0.0-alpha01
public static final @AngleRadiansFloat @FloatRange(from = -3.141592653589793, to = 3.141592653589793, fromInclusive = false) float signedAngleBetween(@NonNull Vec lhs, @NonNull Vec rhs)

Returns the signed angle between the given vectors. The return value will lie in the interval (-π, π].

subtract

Added in 1.0.0-alpha01
public static final void subtract(@NonNull Vec lhs, @NonNull Vec rhs, @NonNull MutableVec output)

Subtracts the x and y values of rhs from the x and y values of lhs and stores the result in output.