vectrix.vectors - nphyx/vectrix GitHub Wiki
vectrix/vectors
Description
The vectors module contains functions and objects related to 2d, 3d, and 4d vectors.
Vectors are composed from columnar matrices, so they support all the methods that vectrix.matrices do.
Require the vector module:
const vectors = require("vectrix.vectors.js");
const vec2 = vectors.create.vec2;
const vec3 = vectors.create.vec3;
const vec4 = vectors.create.vec4;
You can construct them with vec2, vec3, and vec4, passing zero, one or N arguments where N is the vector size. Do whatever is convenient.
let first = vec2(); // passing no arguments will give you a vector filled with zeroes
first.toArray(); // [0,0]
let second = vec2([3,7]); // you can pass an array-like object
second.toArray(); // [3,7]
let third = vec2(17,4); // or just pass the components as arguments
third.toArray(); // [14,4]
let fourth = vec3(1,2,3); // and so on with 3d and 4d vectors
fourth.toArray(); // [1,2,3]
Vector functions will operate on any array-like object, returning a plain Float32Array when the result is another vector. Creating vector objects is somewhat expensive, so when you're doing a lot of operations and performance really counts, use the functions for calculations and then use the vector factories on your final result.
const lerp = vectors.lerp;
let res = lerp([0.1, 0.3], [0.3, 0.7], .5); // Float32Array(0.2, 0.5)
create.vec2(res); // vec2(0.2,0.5);
Vectors are composed from columnar matrices, so they can do the things that matrices do.
second.add(second).toArray(); // [6,14]
third.sub(second).toArray(); // [11,-3]
const matrices = require("vectrix.matrices.js");
let identity = matrices.create(2,2,[1,0, 0,1]);
identity.dot(second).toArray(); // [3,7]
let scale2x = matrixes.create(2,2,[2,0, 0,2]);
scale2x.dot(third).toArray(); // [34,8]
Vector dot products are a special case. As in vector math, multplying two vectors produces a scalar:
let first = vec2(2,2);
let second = vec2([2,2]);
first.dot(second); // 8
let third = vec2(1,0);
let fourth = vec2(0,1);
third.dot(fourth); // 0
They also have some of their own useful properties.
You can find the cross product of two 3d vectors using vec.cross():
let first = vec3(1,2,1);
let second = vec3(2,-2,2);
first.cross(second).toArray(); // [6,0,-6]
Cross can be called on 2d vectors, with z implicitly being zero:
let first = vec2(2,4);
let second = vec2(1,3);
first.cross(second).toArray(); // [0,0,2]
If you cross a vec2 with a vec3 for whatever reason, vec2.z is implicitly zero:
let first = vec3(1,2,1);
let second = vec2(1,3);
first.cross(second).toArray(); // [-3,1,1]
Most vector operations are duck typed and make few assumptions internally, so you can just pass in anything array-like of the correct length if you want:
let first = vec3(1,2,1);
first.cross([2,-2,2]).toArray(); // [6,0,-6]
Just beware weird behavior might result if it looks like a duck and quacks like a duck but it's actually a trick-or-treating platypus.
You can produce a homogenous coordinate for matrix multiplication using vec.homogenous():
first.homogenous().toArray(); // [0,0,1]
Which lets you do a few useful matrix-vector ops more easily:
const matrices = require("vectrix.matrices.js");
const vectors = require("vectrix.vectors.js");
let myVec = vectors.vec2([22,9]);
let translate = matrices.create(3,3,[1,0,5, 0,1,6, 0,0,1]);
translate.dot(myVec.homogenous()).toArray(); // [27,15,1]
Making this more intuitive is on the roadmap.
Last but not least, they have a whole bunch of virtual properties that you might be used to in GLSL. Once I used them I couldn't live without.
let position = vectors.vec3([0,-0.5,0.5]);
position.x; // 0
position.y; // -0.5
position.z; // 0.5
position.xy; // vec2(0,-0.5)
position.zx; // vec2(0.5,0)
position.yzx; // vec3(-0.5,0.5,0)
let color = vectors.vec4(255,128,64,0.1)
color.rgb; // vec3(255,128,64)
color.bgr; // vec3(64,128,255)
...and so on - all aliases and combinations thereof for the xyzw and rgba sets are available. vec2s only support x/y because r/g is not useful.
#Functions
mut_copy
mut_copy(a, b) ⇨ vector
Copies values from second operand into first.
Example:
let v = vec3(1,2,3);
let v2 = vec2(31,6);
copy(v, v2); // vec3(31,6,3);
Parameters
| name | type | description |
|---|---|---|
| a | vector |
vector to copy into |
| b | vector |
vector to copy from |
Returns: vectora, with copied values
homogenous
homogenous(a) ⇨ matrix
Homogenous coordinates for a vector. Note this does not return a vector because it's not really useful to do so.
Parameters
| name | type | description |
|---|---|---|
| a | vector |
input vector |
Returns: matrix
normalize
normalize(a) ⇨ vector
Normalize a vector.
Example:
normalize(vector); // function style
vector.normalize(); // method style
Parameters
| name | type | description |
|---|---|---|
| a | vector |
vector to normalize |
Returns: vector
lerp
lerp(a, b, t) ⇨ vector
Perform a linear interpolation between two vectors.
Parameters
| name | type | description |
|---|---|---|
| a | vector |
first operand |
| b | vector |
second operand |
| t | float |
interval |
Returns: vector
cubic
cubic(a, b, c, d, t) ⇨ vector
Perform a cubic bezier interpolation
Parameters
| name | type | description |
|---|---|---|
| a | vector |
start point |
| b | vector |
first control point |
| c | vector |
second control point |
| d | vector |
end point |
| t | float |
interval |
Returns: vector
times
times(a, b, out) ⇨ matrix | float
Vector product for matching vector types. Accepts vectors or generic arrays, or defaults up to the matrix product if the vectors don't match (which supports vector*matrix and scalar products).
Parameters
| name | type | description |
|---|---|---|
| a | vector |
first operand |
| b | `vector | float` |
| out | vector |
out vector |
Returns: matrix | floatproduct of a and b
times
times(a, b) ⇨ matrix | float
Mutating version of times. Note that a is mutated only when a is a vector and b is a scalar.
Parameters
| name | type | description |
|---|---|---|
| a | vector |
first operand |
| b | `vector | float` |
Returns: matrix | floatmutated a, product of a and b
angle
angle(a, b) ⇨ vector
Find the angle between two vectors in radians.
Parameters
| name | type | description |
|---|---|---|
| a | vector |
first operand |
| b | vector |
second operand |
Returns: vector
distance
distance(a, b) ⇨ float
Find the distance between two vectors.
Parameters
| name | type | description |
|---|---|---|
| a | vector |
first operand |
| b | vector |
second operand |
Returns: floatdistance
cross
cross(a, b, out) ⇨ Float32Array(3)
Vector cross products are technically only defined for 3D, but 2D can be crossed with implicit z=0
Parameters
| name | type | description |
|---|---|---|
| a | vector |
first operand |
| b | `vector | float` |
| out | vec3 |
parameter |
Returns: Float32Array(3)cross product
clamp
clamp(a, minv, maxv, out) ⇨ vector
Restricts scalar or vector values to a range.
Example:
let v = vectors.create.vec3([-5,100, -22]); // vec3(-5,100, -22)
clamp(v, -10, 10); // vec3(-5, 10, -10);
let s = 23.0;
clamp(s, 0, 5); // 5
Parameters
| name | type | description |
|---|---|---|
| a | vector |
vector or scalar to clamp |
| minv | float |
minimum value |
| maxv | float |
maximum value |
| out | vector |
output vector |
Returns: vectorclamped vector
mut_clamp
mut_clamp() ⇨ vector
Mutating version of clamp.
Returns: vectorthe mutated vector
magnitude
magnitude(a) ⇨ float
Calculate the magnitude of a vector.
Example:
magnitude(vec3(2,3,6)); // ~6.16
Parameters
| name | type | description |
|---|---|---|
| a | vector |
operand |
Returns: floatmagnitude of a
toString
toString(a) ⇨ string
Get a string representation of a vector.
Example:
vectors.create.vec2([23,1]).toString(); // vec2(23.00, 1.00)
vectors.toString(vectors.create.vec2([23,1])); // vec2(23.00, 1.00)
Parameters
| name | type | description |
|---|---|---|
| a | vector |
input vector |
Returns: string
create
create(len, args, buffer, offset) ⇨ vector
Creates a new vector. Note that vectors created directly with this function will not have convenience aliases, meaning they're initialized faster but... ah, less convenient. Can be supplied with an optional arraybuffer view and optional offset to that view as the last or last two parameters.
Example:
create(2); // vector[0,0]
create(2, 3.3, 3.2); // vector[3.3,3.2]
create(2, [3.3, 3.2]); // vector[3.3,3.2] from an array
create(2, 3.3, 3.2, new ArrayBuffer(2*4)); // vector[3.3,3.2] as view of ArrayBuffer
create(2, 3.3, 3.2, new ArrayBuffer(3*4), 4); // vector[3.3,3.2] as view of ArrayBuffer, offset by 4 bytes
create(2, [3.3, 3.2], new ArrayBuffer(3*4), 4); // vector[3.3,3.2] as view of ArrayBuffer, offset by 4 bytes, from an array
Parameters
| name | type | description |
|---|---|---|
| len | int |
[2...4] vector length |
| args | mixed |
values in any combination of array-like and scalar values |
| buffer | ArrayBuffer |
(optional) an array buffer to create the vector on |
| offset | offset |
(optional) offset for the buffer, ignored if buffer is not supplied |
Returns: vector
vec2
vec2() ⇨ vector
Creates a 2d vector. Curried version of create with first argument presupplied.
Returns: vector
vec3
vec3() ⇨ vector
Creates a 3d vector. Curried version of create with first argument presupplied.
Returns: vector
vec4
vec4() ⇨ vector
Creates a 4d vector. Curried version of create with first argument presupplied.
Returns: vector