Vec

Kotlin |Java

abstract class Vec

Known direct subclasses

ImmutableVec, MutableVec

`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:

A two-dimensional offset, i.e. the difference between two points
A point in space, i.e. treating the vector as an offset from the origin

Summary

Public companion functions
`@AngleRadiansFloat @FloatRange(from = 0.0, to = 3.141592653589793) Float`	`absoluteAngleBetween(lhs: Vec, rhs: Vec)` Returns the absolute angle between the given vectors.
`Unit`	`add(lhs: Vec, rhs: Vec, output: MutableVec)` Adds the x and y values of both `Vec` objects and stores the result in `output`.
`Float`	`determinant(lhs: Vec, rhs: Vec)` Returns the determinant (×) of the two vectors.
`Unit`	`divide(lhs: Vec, rhs: Float, output: MutableVec)` Divides the x and y values of the `Vec` by the Float and stores the result in `output`.
`Float`	`dotProduct(lhs: Vec, rhs: Vec)` Returns the dot product (⋅) of the two vectors.
`Unit`	`multiply(lhs: Float, rhs: Vec, output: MutableVec)` Multiplies the x and y values of the `Vec` by the Float and stores the result in `output`.
`Unit`	`multiply(lhs: Vec, rhs: Float, output: MutableVec)` Multiplies the x and y values of the `Vec` by the Float and stores the result in `output`.
`@AngleRadiansFloat @FloatRange(from = -3.141592653589793, to = 3.141592653589793, fromInclusive = false) Float`	`signedAngleBetween(lhs: Vec, rhs: Vec)` Returns the signed angle between the given vectors.
`Unit`	`subtract(lhs: Vec, rhs: Vec, output: MutableVec)` Subtracts the x and y values of `rhs` from the x and y values of `lhs` and stores the result in `output`.

Public companion properties
`ImmutableVec`	`ORIGIN` The origin of the coordinate system, i.e. (0, 0).

Public functions
`@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.
`@FloatRange(from = 0.0) Float`	`computeMagnitude()` The length of the `Vec`.
`@FloatRange(from = 0.0) Float`	`computeMagnitudeSquared()` The squared length of the `Vec`.
`ImmutableVec`	`computeNegation()` Returns a newly allocated vector with the same magnitude, but pointing in the opposite direction.
`MutableVec`	`computeNegation(outVec: MutableVec)` Modifies `outVec` into a vector with the same magnitude, but pointing in the opposite direction.
`ImmutableVec`	`computeOrthogonal()` Returns a newly allocated vector with the same magnitude as this one, but rotated by (positive) 90 degrees.
`MutableVec`	`computeOrthogonal(outVec: MutableVec)` Modifies `outVec` into a vector with the same magnitude as this one, but rotated by (positive) 90 degrees.
`ImmutableVec`	`computeUnitVec()` Returns a newly allocated vector with the same direction as this one, but with a magnitude of `1`.
`MutableVec`	`computeUnitVec(outVec: MutableVec)` Modifies `outVec` into a vector with the same direction as this one, but with a magnitude of `1`.
`Boolean`	`isAlmostEqual(other: Vec, tolerance: @FloatRange(from = 0.0) Float)` Compares this `Vec` with `other`, and returns true if the difference between `x` and other.x is less than `tolerance`, and likewise for `y`.
`Boolean`	`isParallelTo( other: Vec, angleTolerance: @AngleRadiansFloat @FloatRange(from = 0.0) Float )` Returns true if the angle formed by `this` and `other` is within `angleTolerance` of 0 radians or π radians (0 degrees or 180 degrees).
`Boolean`	`isPerpendicularTo( other: Vec, angleTolerance: @AngleRadiansFloat @FloatRange(from = 0.0) Float )` Returns true if the angle formed by `this` and `other` is within `angleTolerance` of ±π/2 radians (±90 degrees).

Public properties
`abstract Float`	`x` The `Vec`'s offset in the x-direction
`abstract Float`	`y` The `Vec`'s offset in the y-direction

Public companion functions

absoluteAngleBetween

Added in 1.0.0-alpha01

fun absoluteAngleBetween(lhs: Vec, rhs: Vec): @AngleRadiansFloat @FloatRange(from = 0.0, to = 3.141592653589793) Float

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

add

Added in 1.0.0-alpha01

fun add(lhs: Vec, rhs: Vec, output: MutableVec): Unit

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

determinant

Added in 1.0.0-alpha01

fun determinant(lhs: Vec, rhs: Vec): Float

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

fun divide(lhs: Vec, rhs: Float, output: MutableVec): Unit

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

fun dotProduct(lhs: Vec, rhs: Vec): Float

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.

multiply

Added in 1.0.0-alpha01

fun multiply(lhs: Float, rhs: Vec, output: MutableVec): Unit

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

fun multiply(lhs: Vec, rhs: Float, output: MutableVec): Unit

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

fun signedAngleBetween(lhs: Vec, rhs: Vec): @AngleRadiansFloat @FloatRange(from = -3.141592653589793, to = 3.141592653589793, fromInclusive = false) Float

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

subtract

Added in 1.0.0-alpha01

fun subtract(lhs: Vec, rhs: Vec, output: MutableVec): Unit

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

Public companion properties

ORIGIN

val ORIGIN: ImmutableVec

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

Public functions

computeDirection

Added in 1.0.0-alpha01

fun computeDirection(): @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. 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

fun computeMagnitude(): @FloatRange(from = 0.0) Float

The length of the Vec.

computeMagnitudeSquared

Added in 1.0.0-alpha01

fun computeMagnitudeSquared(): @FloatRange(from = 0.0) Float

The squared length of the Vec.

computeNegation

Added in 1.0.0-alpha01

fun computeNegation(): ImmutableVec

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

fun computeNegation(outVec: MutableVec): MutableVec

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

computeOrthogonal

Added in 1.0.0-alpha01

fun computeOrthogonal(): ImmutableVec

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

fun computeOrthogonal(outVec: MutableVec): MutableVec

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

fun computeUnitVec(): ImmutableVec

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

fun computeUnitVec(outVec: MutableVec): MutableVec

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.

isAlmostEqual

Added in 1.0.0-alpha01

fun isAlmostEqual(other: Vec, tolerance: @FloatRange(from = 0.0) Float = 1.0E-4f): Boolean

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

fun isParallelTo(
    other: Vec,
    angleTolerance: @AngleRadiansFloat @FloatRange(from = 0.0) Float
): Boolean

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

fun isPerpendicularTo(
    other: Vec,
    angleTolerance: @AngleRadiansFloat @FloatRange(from = 0.0) Float
): Boolean

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

Public properties

x

Added in 1.0.0-alpha01

abstract val x: Float

The Vec's offset in the x-direction

y

Added in 1.0.0-alpha01

abstract val y: Float

The Vec's offset in the y-direction