Functions for mathematical operations on vectors, matrices and quaternions.
The vector types (Vector3 and Vector4) supports addition and subtraction
with vectors of the same type. Vectors can be negated and multiplied with numbers
(scaled).
The quaternion type (Quaternion) supports multiplication with other quaternions.
The matrix type (Matrix4) can be multiplied with numbers, other matrices and Vector4 values.
All types performs equality comparison by each component value.
Static methods
staticconj(q1:Quaternion):Quaternion
Calculates the conjugate of a quaternion. The result is a quaternion with the same magnitudes but with the sign of the imaginary (vector) parts changed:
q* = [w, -v]
Parameters:
q1 | quaternion of which to calculate the conjugate |
|---|
Returns:
the conjugate
staticcross(v1:Vector3, v2:Vector3):Vector3
Calculates the cross-product of two vectors.
Given two linearly independent vectors P and Q, the cross product, P x Q, is a vector that is perpendicular to both P and Q and therefore normal to the plane containing them.
If the two vectors have the same direction (or have the exact opposite direction from one another, i.e. are not linearly independent) or if either one has zero length, then their cross product is zero.
Parameters:
v1 | first vector |
|---|---|
v2 | second vector |
Returns:
a new vector representing the cross product
staticdot(v1:Vector3, v2:Vector3):Float
staticdot(v1:Vector4, v2:Vector4):Float
Calculates the dot-product of two vectors.
The returned value is a scalar defined as:
| `P ⋅ Q = | P | Q | cos θ` |
|---|
where θ is the angle between the vectors P and Q.
- If the dot product is positive then the angle between the vectors is below 90 degrees.
- If the dot product is zero the vectors are perpendicular (at right-angles to each other).
- If the dot product is negative then the angle between the vectors is more than 90 degrees.
Parameters:
v1 | first vector |
|---|---|
v1 | second vector |
Returns:
dot product
staticinv(m1:Matrix4):Matrix4
Calculates the inverse matrix..
The resulting matrix is the inverse of the supplied matrix.
For ortho-normal matrices, e.g. regular object transformation,
use Vmath.ortho_inv instead.
The specialized inverse for ortho-normalized matrices is much faster
than the general inverse.
Parameters:
m1 | matrix to invert |
|---|
Returns:
inverse of the supplied matrix
staticlength(v:Vector3):Float
staticlength(v:Quaternion):Float
staticlength(v:Vector4):Float
Returns the length of the supplied vector or quaternion.
If you are comparing the lengths of vectors or quaternions, you should compare the length squared instead as it is slightly more efficient to calculate (it eliminates a square root calculation).
Parameters:
v | value of which to calculate the length |
|---|
Returns:
length
staticlength_sqr(v:Vector3):Float
staticlength_sqr(v:Quaternion):Float
staticlength_sqr(v:Vector4):Float
Calculates the squared length of a vector or quaternion.
Returns the squared length of the supplied vector or quaternion.
Parameters:
v | vector of which to calculate the squared length |
|---|
Returns:
squared vector length
staticlerp(t:Float, v1:Vector3, v2:Vector3):Vector3
staticlerp(t:Float, q1:Quaternion, q2:Quaternion):Quaternion
staticlerp(t:Float, n1:Float, n2:Float):Float
staticlerp(t:Float, v1:Vector4, v2:Vector4):Vector4
Lerps between two vectors/quaternions/numbers.
The function treats the vectors as positions and interpolates between the positions in a straight line. Lerp is useful to describe transitions from one place to another over time.
Linear interpolation of rotations are only useful for small
rotations. For interpolations of arbitrary rotations,
Vmath.slerp() yields much better results.
Number lerp is useful to describe transitions from one value to another over time.
The function does not clamp t between 0 and 1.
Parameters:
t | interpolation parameter, 0-1 |
|---|---|
v1 | vector to lerp from |
v2 | vector to lerp to |
n1 | number to lerp from |
n2 | number to lerp to |
q1 | quaternion to lerp from |
q2 | quaternion to lerp to |
Returns:
the lerped vector/quaternion/number
staticmatrix4(?m1:Matrix4):Matrix4
Creates a new matrix.
If m is not specified, the resulting matrix is an indentity matrix,
describing a transform with no translation or rotation.
Otherwise creates a new matrix with all components set to the corresponding values from the supplied matrix. I.e. the function creates a copy of the given matrix.
Parameters:
m1 | existing matrix |
|---|
Returns:
identity or copy matrix
staticmatrix4_axis_angle(v:Vector3, angle:Float):Matrix4
Creates a matrix from an axis and an angle.
The resulting matrix describes a rotation around the axis by the specified angle.
Parameters:
v | axis |
|---|---|
angle | angle in radians |
Returns:
matrix represented by axis and angle
staticmatrix4_from_quat(q:Quaternion):Matrix4
Creates a matrix from a quaternion.
The resulting matrix describes the same rotation as the quaternion, but does not have any translation (also like the quaternion).
Parameters:
q | quaternion to create matrix from |
|---|
Returns:
matrix represented by quaternion
staticmatrix4_frustum(left:Float, right:Float, bottom:Float, top:Float, near:Float, far:Float):Matrix4
Creates a frustum matrix.
Constructs a frustum matrix from the given values. The left, right, top and bottom coordinates of the view cone are expressed as distances from the center of the near clipping plane. The near and far coordinates are expressed as distances from the tip of the view frustum cone.
Parameters:
left | coordinate for left clipping plane |
|---|---|
right | coordinate for right clipping plane |
bottom | coordinate for bottom clipping plane |
top | coordinate for top clipping plane |
near | coordinate for near clipping plane |
far | coordinate for far clipping plane |
Returns:
matrix representing the frustum
staticmatrix4_look_at(eye:Vector3, look_at:Vector3, up:Vector3):Matrix4
Creates a look-at view matrix.
The resulting matrix is created from the supplied look-at parameters. This is useful for constructing a view matrix for a camera or rendering in general.
Parameters:
eye | eye position |
|---|---|
look_at | look-at position |
up | up vector |
Returns:
look-at matrix
staticmatrix4_orthographic(left:Float, right:Float, bottom:Float, top:Float, near:Float, far:Float):Matrix4
Creates an orthographic projection matrix. This is useful to construct a projection matrix for a camera or rendering in general.
Parameters:
left | coordinate for left clipping plane |
|---|---|
right | coordinate for right clipping plane |
bottom | coordinate for bottom clipping plane |
top | coordinate for top clipping plane |
near | coordinate for near clipping plane |
far | coordinate for far clipping plane |
Returns:
orthographic projection matrix
staticmatrix4_perspective(fov:Float, aspect:Float, near:Float, far:Float):Matrix4
Creates a perspective projection matrix. This is useful to construct a projection matrix for a camera or rendering in general.
Parameters:
fov | angle of the full vertical field of view in radians |
|---|---|
aspect | aspect ratio |
near | coordinate for near clipping plane |
far | coordinate for far clipping plane |
Returns:
perspective projection matrix
staticmatrix4_rotation_x(angle:Float):Matrix4
Creates a matrix from rotation around x-axis.
The resulting matrix describes a rotation around the x-axis by the specified angle.
Parameters:
angle | angle in radians around x-axis |
|---|
Returns:
matrix from rotation around x-axis
staticmatrix4_rotation_y(angle:Float):Matrix4
Creates a matrix from rotation around y-axis.
The resulting matrix describes a rotation around the y-axis by the specified angle.
Parameters:
angle | angle in radians around y-axis |
|---|
Returns:
matrix from rotation around y-axis
staticmatrix4_rotation_z(angle:Float):Matrix4
Creates a matrix from rotation around z-axis.
The resulting matrix describes a rotation around the z-axis by the specified angle.
Parameters:
angle | angle in radians around z-axis |
|---|
Returns:
matrix from rotation around z-axis
staticmatrix4_translation(position:EitherType<Vector3, Vector4>):Matrix4
The resulting matrix describes a translation of a point in euclidean space.
Parameters:
position | position vector to create matrix from |
|---|
Returns:
matrix from the supplied position vector
staticmul_per_elem(v1:Vector4, v2:Vector4):Vector4
staticmul_per_elem(v1:Vector3, v2:Vector3):Vector3
Performs an element wise multiplication between two vectors of the same type The returned value is a vector defined as (e.g. for a vector3):
v = vmath.mul_per_elem(a, b) = vmath.vector3(a.x * b.x, a.y * b.y, a.z * b.z)
Parameters:
v1 | first vector |
|---|---|
v2 | second vector |
Returns:
multiplied vector
staticnormalize(v1:Vector3):Vector3
staticnormalize(v1:Quaternion):Quaternion
staticnormalize(v1:Vector4):Vector4
Normalizes a vector, i.e. returns a new vector with the same direction as the input vector, but with length 1.
The length of the vector must be above 0, otherwise a division-by-zero will occur.
Parameters:
v1 | vector to normalize |
|---|
Returns:
new normalized vector
staticortho_inv(m1:Matrix4):Matrix4
Calculates the inverse of an ortho-normal matrix..
The resulting matrix is the inverse of the supplied matrix. The supplied matrix has to be an ortho-normal matrix, e.g. describe a regular object transformation.
For matrices that are not ortho-normal
use the general inverse Vmath.inv instead.
Parameters:
m1 | ortho-normalized matrix to invert |
|---|
Returns:
inverse of the supplied matrix
staticproject(v1:Vector3, v2:Vector3):Float
Projects a vector onto another vector.
Calculates the extent the projection of the first vector onto the second. The returned value is a scalar p defined as:
| `p = | P | cos θ / | Q | ` |
|---|
where θ is the angle between the vectors P and Q.
Parameters:
v1 | vector to be projected on the second |
|---|---|
v2 | vector onto which the first will be projected, must not have zero length |
Returns:
the projected extent of the first vector onto the second
staticquat(x:Float, y:Float, z:Float, w:Float):Quaternion
staticquat(?q1:Quaternion):Quaternion
Creates a new quaternion from another existing quaternion, from its coordinates or a new identity quaternion,
If q is not given, the identity quaternion is returned (equal to: Vmath.quat(0, 0, 0, 1)).
Otherwise creates a new quaternion with all components set to the corresponding values from the supplied quaternion.
I.e. This function creates a copy of the given quaternion.
Parameters:
x | x coordinate |
|---|---|
y | y coordinate |
z | z coordinate |
w | w coordinate |
staticquat_axis_angle(v:Vector3, angle:Float):Quaternion
Creates a quaternion to rotate around a unit vector.
The resulting quaternion describes a rotation of angle
radians around the axis described by the unit vector v.
Parameters:
v | axis |
|---|---|
angle | angle |
Returns:
quaternion representing the axis-angle rotation
staticquat_basis(x:Vector3, y:Vector3, z:Vector3):Quaternion
Creates a quaternion from three base unit vectors.
The resulting quaternion describes the rotation from the identity quaternion (no rotation) to the coordinate system as described by the given x, y and z base unit vectors.
Parameters:
x | x base vector |
|---|---|
y | y base vector |
z | z base vector |
Returns:
quaternion representing the rotation of the specified base vectors
staticquat_from_to(v1:Vector3, v2:Vector3):Quaternion
Creates a quaternion to rotate between two unit vectors.
The resulting quaternion describes the rotation that, if applied to the first vector, would rotate the first vector to the second. The two vectors must be unit length vectors (of length 1).
The result is undefined if the two vectors point in opposite directions
Parameters:
v1 | first unit vector, before rotation |
|---|---|
v2 | second unit vector, after rotation |
Returns:
quaternion representing the rotation from first to second vector
staticquat_rotation_x(angle:Float):Quaternion
Creates a quaternion from rotation around x-axis.
The resulting quaternion describes a rotation of angle
radians around the x-axis.
Parameters:
angle | angle in radians around x-axis |
|---|
Returns:
quaternion representing the rotation around the x-axis
staticquat_rotation_y(angle:Float):Quaternion
Creates a quaternion from rotation around y-axis.
The resulting quaternion describes a rotation of angle
radians around the y-axis.
Parameters:
angle | angle in radians around y-axis |
|---|
Returns:
quaternion representing the rotation around the y-axis
staticquat_rotation_z(angle:Float):Quaternion
Creates a quaternion from rotation around z-axis.
The resulting quaternion describes a rotation of angle
radians around the z-axis.
Parameters:
angle | angle in radians around z-axis |
|---|
Returns:
quaternion representing the rotation around the z-axis
staticrotate(q:Quaternion, v:Vector3):Vector3
Rotates a vector by a quaternion.
Returns a new vector from the supplied vector that is rotated by the rotation described by the supplied quaternion.
Parameters:
q | quaternion |
|---|---|
v | vector to rotate |
Returns:
the rotated vector
staticslerp(t:Float, v1:Vector3, v2:Vector3):Vector3
staticslerp(t:Float, q1:Quaternion, q2:Quaternion):Quaternion
staticslerp(t:Float, v1:Vector4, v2:Vector4):Vector4
Slerps between two vectors or quaternions.
Spherically interpolates between two vectors. The difference to lerp is that slerp treats the vectors as directions instead of positions in space.
The direction of the returned vector is interpolated by the angle and the magnitude is interpolated between the magnitudes of the from and to vectors.
Slerp travels the torque-minimal path maintaining constant velocity, which means it travels along the straightest path along the rounded surface of a sphere. Slerp is useful for interpolation of rotations.
Slerp travels the torque-minimal path, which means it travels along the straightest path the rounded surface of a sphere.
Slerp is computationally more expensive than lerp.
The function does not clamp t between 0 and 1.
Parameters:
t | interpolation parameter, 0-1 |
|---|---|
v1 | vector to slerp from |
v2 | vector to slerp to |
q1 | quaternion to slerp from |
q2 | quaternion to slerp to |
Returns:
the slerped vector
staticvector(t:Table<Int, Float>):EitherType<Vector3, Vector4>
Creates a new vector from a table of values.
Parameters:
t | table of numbers |
|---|
Returns:
new vector