kitten/vec2

This module defines a simple two-dimensional vector type and some helper functions to manipulate these vectors. These are used throughout the engine.

Examples:

let v1 = Vec2(10.0, 20.0)
let v2 = Vec2(40.0, 60.0)

vec2.add(v1, v2) 
// -> Vec2(50.0, 80.0)

vec2.dist(v1, v2) 
// -> 50.0

vec2.clamp(v1, Vec2(0.0, 0.0), Vec2(15.0, 15.0)) 
// -> Vec2(10.0, 15.0)

Types

Vec2

</>

pub type Vec2 {
  Vec2(x: Float, y: Float)
}

Constructors

```
Vec2(x: Float, y: Float)
```

Functions

add

</>

pub fn add(v1: Vec2, v2: Vec2) -> Vec2

Adds two vectors component-wise.

Example:

vec2.add(Vec2(10.0, 20.0), Vec2(5.0, -12.0))
// -> Vec2(15.0, 8.0)

angle

</>

pub fn angle(v: Vec2) -> Float

Calculates the angle, in radians, that the given vector makes with the positive x-direction counterclockwise.

Example:

vec2.angle(Vec2(1.0, 2.0))
// -> 1.107...

clamp

</>

pub fn clamp(v: Vec2, min: Vec2, max: Vec2) -> Vec2

Clamps the vector component-wise between a minimum and a maximum.

Examples:

Vec2(6.0, 8.0)
|> vec2.clamp(Vec2(1.0, 1.0), Vec2(5.0, 3.0))
// -> Vec2(5.0, 3.0)

Vec2(6.0, 8.0)
|> vec2.clamp(Vec2(5.0, 9.0), Vec2(10.0, 10.0))
// -> Vec2(6.0, 9.0)

clamp_length

</>

pub fn clamp_length(
  v: Vec2,
  min_length: Float,
  max_length: Float,
) -> Vec2

Clamps the length of a vector between a minimum and a maximum.

Examples:

vec2.clamp_length(Vec2(6.0, 8.0), 1.0, 4.0)
// -> Vec2(1.2, 1.6)

vec2.clamp_length(Vec2(6.0, 8.0), 1.0, 20.0)
// -> Vec2(6.0, 8.0)

clamp_x

</>

pub fn clamp_x(v: Vec2, min_x: Float, max_x: Float) -> Vec2

Clamps the x-component of the vector between a minimum and a maximum.

Examples:

vec2.clamp_x(Vec2(6.0, 8.0), 3.0, 5.0)
// -> Vec2(5.0, 8.0)

vec2.clamp_x(Vec2(6.0, 8.0), 3.0, 7.0)
// -> Vec2(6.0, 8.0)

clamp_y

</>

pub fn clamp_y(v: Vec2, min_y: Float, max_y: Float) -> Vec2

Clamps the y-component of the vector between a minimum and a maximum.

Examples:

vec2.clamp_y(Vec2(6.0, 8.0), 5.0, 7.0)
// -> Vec2(6.0, 7.0)

vec2.clamp_y(Vec2(6.0, 8.0), 5.0, 9.0)
// -> Vec2(6.0, 8.0)

dist

</>

pub fn dist(v1: Vec2, v2: Vec2) -> Float

Calculates the distance between the endpoints of two vectors.

Example:

vec2.dist(Vec2(4.0, 3.0), Vec2(8.0, 6.0))
// -> 5.0

dot_product

</>

pub fn dot_product(v1: Vec2, v2: Vec2) -> Float

Calculates the dot product of two vectors.

Example:

vec2.dot_product(Vec2(10.0, 20.0), Vec2(5.0, -12.0))
// -> -190.0

from_tuple

</>

pub fn from_tuple(x_y: #(Float, Float)) -> Vec2

Constructs a Vec2 from a tuple of the x and y components.

Useful in function pipes, but prefer to use the actual constructor otherwise.

Example:

vec2.from_tuple(6.0, 8.0)
// -> Vec2(6.0, 8.0)

get_x

</>

pub fn get_x(v: Vec2) -> Float

Extracts the x-component of the vector.

Useful in function pipes, but prefer to use the v.x syntax otherwise.

Example:

vec2.get_x(Vec2(6.0, 8.0))
// -> 6.0

get_y

</>

pub fn get_y(v: Vec2) -> Float

Extracts the y-component of the vector.

Useful in function pipes, but prefer to use the v.y syntax otherwise.

Example:

vec2.get_y(Vec2(6.0, 8.0))
// -> 8.0

id

</>

pub fn id(v: Vec2) -> Vec2

A simple identity function specific to the Vec2 type.

Useful in function pipes for extra type safety and readability.

Example:

vec2.id(Vec2(1.0, 2.0))
// -> Vec2(1.0, 2.0)

invert

</>

pub fn invert(v: Vec2) -> Vec2

Returns the vector with its direction flipped.

Example:

vec2.invert(Vec2(1.0, 2.0))
// -> Vec2(-1.0, -2.0)

length

</>

pub fn length(v: Vec2) -> Float

Calculates the length / magnitude of a vector.

Example:

vec2.length(Vec2(4.0, 3.0))
// -> 5.0

length_squared

</>

pub fn length_squared(v: Vec2) -> Float

Calculates the length / magnitude of a vector squared. Useful to make length comparisons slightly cheaper computationally.

Example:

vec2.length_squared(Vec2(4.0, 3.0))
// -> 25.0

lerp

</>

pub fn lerp(v1: Vec2, v2: Vec2, p: Float) -> Vec2

Linearly interpolates between two vectors. Think of the reult as the point 100 * p percent along the line between them.

Example:

vec2.lerp(Vec2(10.0, 20.0), Vec2(5.0, -12.0), 0.3)
// -> Vec2(8.5, 10.4)

loosely_equals

</>

pub fn loosely_equals(
  v1: Vec2,
  v2: Vec2,
  precision: Float,
) -> Bool

Checks if the two vectors are loosely equal to the specified precision, similar to float.loosely_equals. The comparison is made component-wise.

Examples:

vec2.loosely_equals(Vec2(1.0, 2.0), Vec2(1.01, 2.01), 0.05)
// -> True

vec2.loosely_equals(Vec2(1.0, 2.0), Vec2(1.01, 2.01), 0.001)
// -> False

multiply

</>

pub fn multiply(v1: Vec2, v2: Vec2) -> Vec2

Multiplies two vectors component-wise.

Example:

vec2.multiply(Vec2(10.0, 20.0), Vec2(5.0, -12.0))
// -> Vec2(50.0, -240.0)

normalize

</>

pub fn normalize(v: Vec2) -> Vec2

Returns the normal vector (i.e. of length 1) in the same direction as the original.

Example:

vec2.normalize(Vec2(6.0, 8.0))
// -> Vec2(0.6, 0.8)

rotate

</>

pub fn rotate(v: Vec2, t: Float) -> Vec2

Rotates the vector through the given angle, in radians, counterclockwise.

Example:

vec2.rotate(Vec2(1.0, 2.0), 0.4636483268)
// -> Vec2(0.0, 2.236) (approx.)

rotate_left

</>

pub fn rotate_left(v: Vec2) -> Vec2

Returns the vector rotated through 90 degrees or pi/2 radians to the left.

Useful in function pipes.

Example:

vec2.rotate_left(Vec2(1.0, 2.0))
// -> Vec2(-2.0, 1.0)

rotate_right

</>

pub fn rotate_right(v: Vec2) -> Vec2

Returns the vector rotated through 90 degrees or pi/2 radians to the right.

Useful in function pipes.

Example:

vec2.rotate_right(Vec2(1.0, 2.0))
// -> Vec2(2.0, -1.0)

scale

</>

pub fn scale(v: Vec2, factor: Float) -> Vec2

Scales the vector by the given factor. Works for all Floats.

Example:

vec2.scale(Vec2(4.0, 3.0), 2.0)
// -> Vec2(8.0, 6.0)

set_angle

</>

pub fn set_angle(v: Vec2, t: Float) -> Vec2

Returns the vector with the same length as the original, rotated through the angle t radians counterclockwise away from the positive x-direction.

Example:

vec2.set_angle(Vec2(1.0, 2.0), math.pi /. 2.0)
// -> Vec2(0.0, 2.236) (approx.)

set_length

</>

pub fn set_length(v: Vec2, new_length: Float) -> Vec2

Returns the vector that has the same direction as the original and the specified length.

Example:

vec2.set_length(Vec2(6.0, 8.0), 1.0)
// -> Vec2(0.6, 0.8)

set_x

</>

pub fn set_x(v: Vec2, new_x: Float) -> Vec2

Sets the x-component of the vector.

Useful in function pipes.

Example:

vec2.set_x(Vec2(6.0, 8.0), 3.0)
// -> Vec2(3.0, 8.0)

set_y

</>

pub fn set_y(v: Vec2, new_y: Float) -> Vec2

Sets the y-component of the vector.

Useful in function pipes.

Example:

vec2.set_y(Vec2(6.0, 8.0), 5.0)
// -> Vec2(6.0, 5.0)

subtract

</>

pub fn subtract(v1: Vec2, v2: Vec2) -> Vec2

Subtracts two vectors component-wise.

Example:

vec2.subtract(Vec2(10.0, 20.0), Vec2(5.0, -12.0))
// -> Vec2(5.0, 32.0)

to_tuple

</>

pub fn to_tuple(v: Vec2) -> #(Float, Float)

Converts a Vec2 to a tuple of the x and y components.

Useful in function pipes.

Example:

vec2.to_tuple(Vec2(6.0, 8.0))
// -> #(6.0, 8.0)

unit

</>

pub fn unit(t: Float) -> Vec2

Returns a unit vector (i.e. vector of length 1.0) in the given direction, t radians from the positive x-direction counterclockwise.

Example:

vec2.length_squared(Vec2(4.0, 3.0))
// -> 25.0

unit_random

</>

pub fn unit_random() -> Vec2

Returns a unit vector a random direction.

Example:

vec2.unit_random()
// -> Vec2(0.6, -0.8)

unit_x

</>

pub fn unit_x() -> Vec2

Returns a unit vector in the positive x direction.

Useful in function pipes.

Example:

vec2.unit_x()
// -> Vec2(1.0, 0.0)

unit_y

</>

pub fn unit_y() -> Vec2

Returns a unit vector in the positive y direction.

Useful in function pipes.

Example:

vec2.unit_y()
// -> Vec2(0.0, 1.0)