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
vector
mut_copy(a, b) ⇨ 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: vector
a, with copied values
homogenous
matrix
homogenous(a) ⇨ 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
vector
normalize(a) ⇨ Normalize a vector.
Example:
normalize(vector); // function style
vector.normalize(); // method style
Parameters
name | type | description |
---|---|---|
a | vector |
vector to normalize |
Returns: vector
lerp
vector
lerp(a, b, t) ⇨ 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
vector
cubic(a, b, c, d, t) ⇨ 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
matrix | float
times(a, b, out) ⇨ 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 | float
product of a and b
times
matrix | float
times(a, b) ⇨ 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 | float
mutated a, product of a and b
angle
vector
angle(a, b) ⇨ Find the angle between two vectors in radians.
Parameters
name | type | description |
---|---|---|
a | vector |
first operand |
b | vector |
second operand |
Returns: vector
distance
float
distance(a, b) ⇨ Find the distance between two vectors.
Parameters
name | type | description |
---|---|---|
a | vector |
first operand |
b | vector |
second operand |
Returns: float
distance
cross
Float32Array(3)
cross(a, b, out) ⇨ 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
vector
clamp(a, minv, maxv, out) ⇨ 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: vector
clamped vector
mut_clamp
vector
mut_clamp() ⇨ Mutating version of clamp.
Returns: vector
the mutated vector
magnitude
float
magnitude(a) ⇨ Calculate the magnitude of a vector.
Example:
magnitude(vec3(2,3,6)); // ~6.16
Parameters
name | type | description |
---|---|---|
a | vector |
operand |
Returns: float
magnitude of a
toString
string
toString(a) ⇨ 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
vector
create(len, args, buffer, offset) ⇨ 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
vector
vec2() ⇨ Creates a 2d vector. Curried version of create with first argument presupplied.
Returns: vector
vec3
vector
vec3() ⇨ Creates a 3d vector. Curried version of create with first argument presupplied.
Returns: vector
vec4
vector
vec4() ⇨ Creates a 4d vector. Curried version of create with first argument presupplied.
Returns: vector