Version: beta
FUNCTIONS | |
---|---|
vmath.clamp() | clamp input value in range [min, max] and return clamped value |
vmath.conj() | calculates the conjugate of a quaternion |
vmath.cross() | calculates the cross-product of two vectors |
vmath.dot() | calculates the dot-product of two vectors |
vmath.euler_to_quat() | converts euler angles into a quaternion |
vmath.inv() | calculates the inverse matrix. |
vmath.length() | calculates the length of a vector or quaternion |
vmath.length_sqr() | calculates the squared length of a vector or quaternion |
vmath.lerp() | lerps between two vectors |
vmath.lerp() | lerps between two quaternions |
vmath.lerp() | lerps between two numbers |
vmath.matrix4() | creates a new identity matrix |
vmath.matrix4() | creates a new matrix from another existing matrix |
vmath.matrix4_axis_angle() | creates a matrix from an axis and an angle |
vmath.matrix4_compose() | creates a new matrix4 from translation, rotation and scale |
vmath.matrix4_frustum() | creates a frustum matrix |
vmath.matrix4_look_at() | creates a look-at view matrix |
vmath.matrix4_orthographic() | creates an orthographic projection matrix |
vmath.matrix4_perspective() | creates a perspective projection matrix |
vmath.matrix4_quat() | creates a matrix from a quaternion |
vmath.matrix4_rotation_x() | creates a matrix from rotation around x-axis |
vmath.matrix4_rotation_y() | creates a matrix from rotation around y-axis |
vmath.matrix4_rotation_z() | creates a matrix from rotation around z-axis |
vmath.matrix4_scale() | creates a new matrix4 from scale vector |
vmath.matrix4_scale() | creates a new matrix4 from uniform scale |
vmath.matrix4_scale() | creates a new matrix4 from three scale components |
vmath.matrix4_translation() | creates a translation matrix from a position vector |
vmath.mul_per_elem() | performs an element wise multiplication of two vectors |
vmath.normalize() | normalizes a vector |
vmath.ortho_inv() | calculates the inverse of an ortho-normal matrix. |
vmath.project() | projects a vector onto another vector |
vmath.quat() | creates a new identity quaternion |
vmath.quat() | creates a new quaternion from another existing quaternion |
vmath.quat() | creates a new quaternion from its coordinates |
vmath.quat_axis_angle() | creates a quaternion to rotate around a unit vector |
vmath.quat_basis() | creates a quaternion from three base unit vectors |
vmath.quat_from_to() | creates a quaternion to rotate between two unit vectors |
vmath.quat_matrix4() | creates a new quaternion from matrix4 |
vmath.quat_rotation_x() | creates a quaternion from rotation around x-axis |
vmath.quat_rotation_y() | creates a quaternion from rotation around y-axis |
vmath.quat_rotation_z() | creates a quaternion from rotation around z-axis |
vmath.quat_to_euler() | converts a quaternion into euler angles |
vmath.rotate() | rotates a vector by a quaternion |
vmath.slerp() | slerps between two vectors |
vmath.slerp() | slerps between two quaternions |
vmath.vector() | create a new vector from a table of values |
vmath.vector3() | creates a new zero vector |
vmath.vector3() | creates a new vector from scalar value |
vmath.vector3() | creates a new vector from another existing vector |
vmath.vector3() | creates a new vector from its coordinates |
vmath.vector4() | creates a new zero vector |
vmath.vector4() | creates a new vector from scalar value |
vmath.vector4() | creates a new vector from another existing vector |
vmath.vector4() | creates a new vector from its coordinates |
vmath.clamp(value,min,max)
Clamp input value to be in range of [min, max]. In case if input value has vector3|vector4 type return new vector3|vector4 with clamped value at every vector's element. Min/max arguments can be vector3|vector4. In that case clamp excuted per every vector's element
PARAMETERS
value |
number, vector3, vector4 |
Input value or vector of values |
min |
number, vector3, vector4 |
Min value(s) border |
max |
number, vector3, vector4 |
Max value(s) border |
RETURNS
clamped_value |
number, vector3, vector4 | Clamped value or vector |
vmath.conj(q1)
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
PARAMETERS
q1 |
quaternion |
quaternion of which to calculate the conjugate |
RETURNS
q |
quaternion | the conjugate |
EXAMPLES
local quat = vmath.quat(1, 2, 3, 4)
print(vmath.conj(quat)) --> vmath.quat(-1, -2, -3, 4)
vmath.cross(v1,v2)
Given two linearly independent vectors P and Q, the cross product, P × 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 |
vector3 |
first vector |
v2 |
vector3 |
second vector |
RETURNS
v |
vector3 | a new vector representing the cross product |
EXAMPLES
local vec1 = vmath.vector3(1, 0, 0)
local vec2 = vmath.vector3(0, 1, 0)
print(vmath.cross(vec1, vec2)) --> vmath.vector3(0, 0, 1)
local vec3 = vmath.vector3(-1, 0, 0)
print(vmath.cross(vec1, vec3)) --> vmath.vector3(0, -0, 0)
vmath.dot(v1,v2)
The returned value is a scalar defined as:
P ⋅ Q = |P| |Q| cos θ
where θ is the angle between the vectors P and Q.
PARAMETERS
v1 |
vector3, vector4 |
first vector |
v2 |
vector3, vector4 |
second vector |
RETURNS
n |
number | dot product |
EXAMPLES
if vmath.dot(vector1, vector2) == 0 then
-- The two vectors are perpendicular (at right-angles to each other)
...
end
vmath.euler_to_quat(x,y,z)
Converts euler angles (x, y, z) in degrees into a quaternion The error is guaranteed to be less than 0.001. If the first argument is vector3, its values are used as x, y, z angles.
PARAMETERS
x |
number, vector3 |
rotation around x-axis in degrees or vector3 with euler angles in degrees |
y |
number |
rotation around y-axis in degrees |
z |
number |
rotation around z-axis in degrees |
RETURNS
q |
quaternion | quaternion describing an equivalent rotation (231 (YZX) rotation sequence) |
vmath.inv(m1)
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 |
matrix4 |
matrix to invert |
RETURNS
m |
matrix4 | inverse of the supplied matrix |
EXAMPLES
local mat1 = vmath.matrix4_rotation_z(3.141592653)
local mat2 = vmath.inv(mat1)
-- M * inv(M) = identity matrix
print(mat1 * mat2) --> vmath.matrix4(1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1)
vmath.length(v)
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 |
vector3, vector4, quat |
value of which to calculate the length |
RETURNS
n |
number | length |
EXAMPLES
if vmath.length(self.velocity) < max_velocity then
-- The speed (velocity vector) is below max.
-- TODO: max_velocity can be expressed as squared
-- so we can compare with length_sqr() instead.
...
end
vmath.length_sqr(v)
Returns the squared length of the supplied vector or quaternion.
PARAMETERS
v |
vector3, vector4, quat |
value of which to calculate the squared length |
RETURNS
n |
number | squared length |
EXAMPLES
if vmath.length_sqr(vector1) < vmath.length_sqr(vector2) then
-- Vector 1 has less magnitude than vector 2
...
end
vmath.lerp(t,v1,v2)
Linearly interpolate between two vectors. 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. The function does not clamp t between 0 and 1.
PARAMETERS
t |
number |
interpolation parameter, 0-1 |
v1 |
vector3, vector4 |
vector to lerp from |
v2 |
vector3, vector4 |
vector to lerp to |
RETURNS
v |
vector3, vector4 | the lerped vector |
EXAMPLES
function init(self)
self.t = 0
end
function update(self, dt)
self.t = self.t + dt
if self.t <= 1 then
local startpos = vmath.vector3(0, 600, 0)
local endpos = vmath.vector3(600, 0, 0)
local pos = vmath.lerp(self.t, startpos, endpos)
go.set_position(pos, "go")
end
end
vmath.lerp(t,q1,q2)
Linearly interpolate between two quaternions. Linear interpolation of rotations are only useful for small rotations. For interpolations of arbitrary rotations, vmath.slerp yields much better results. The function does not clamp t between 0 and 1.
PARAMETERS
t |
number |
interpolation parameter, 0-1 |
q1 |
quaternion |
quaternion to lerp from |
q2 |
quaternion |
quaternion to lerp to |
RETURNS
q |
quaternion | the lerped quaternion |
EXAMPLES
function init(self)
self.t = 0
end
function update(self, dt)
self.t = self.t + dt
if self.t <= 1 then
local startrot = vmath.quat_rotation_z(0)
local endrot = vmath.quat_rotation_z(3.141592653)
local rot = vmath.lerp(self.t, startrot, endrot)
go.set_rotation(rot, "go")
end
end
vmath.lerp(t,n1,n2)
Linearly interpolate between two values. 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 |
number |
interpolation parameter, 0-1 |
n1 |
number |
number to lerp from |
n2 |
number |
number to lerp to |
RETURNS
n |
number | the lerped number |
EXAMPLES
function init(self)
self.t = 0
end
function update(self, dt)
self.t = self.t + dt
if self.t <= 1 then
local startx = 0
local endx = 600
local x = vmath.lerp(self.t, startx, endx)
go.set_position(vmath.vector3(x, 100, 0), "go")
end
end
vmath.matrix4()
The resulting identity matrix describes a transform with no translation or rotation.
PARAMETERS
None
RETURNS
m |
matrix4 | identity matrix |
EXAMPLES
local mat = vmath.matrix4()
print(mat) --> vmath.matrix4(1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1)
-- get column 0:
print(mat.c0) --> vmath.vector4(1, 0, 0, 0)
-- get the value in row 3 and column 2:
print(mat.m32) --> 0
vmath.matrix4(m1)
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 |
matrix4 |
existing matrix |
RETURNS
m |
matrix4 | matrix which is a copy of the specified matrix |
EXAMPLES
local mat1 = vmath.matrix4_rotation_x(3.141592653)
local mat2 = vmath.matrix4(mat1)
if mat1 == mat2 then
-- yes, they are equal
print(mat2) --> vmath.matrix4(1, 0, 0, 0, 0, -1, 8.7422776573476e-08, 0, 0, -8.7422776573476e-08, -1, 0, 0, 0, 0, 1)
end
vmath.matrix4_axis_angle(v,angle)
The resulting matrix describes a rotation around the axis by the specified angle.
PARAMETERS
v |
vector3 |
axis |
angle |
number |
angle in radians |
RETURNS
m |
matrix4 | matrix represented by axis and angle |
EXAMPLES
local vec = vmath.vector4(1, 1, 0, 0)
local axis = vmath.vector3(0, 0, 1) -- z-axis
local mat = vmath.matrix4_axis_angle(axis, 3.141592653)
print(mat * vec) --> vmath.vector4(-0.99999994039536, -1.0000001192093, 0, 0)
vmath.matrix4_compose(translation,rotation,scale)
Creates a new matrix constructed from separate translation vector, roation quaternion and scale vector
PARAMETERS
translation |
vector3, vecto4 |
translation |
rotation |
quaternion |
rotation |
scale |
vector3 |
scale |
RETURNS
matrix |
matrix4 | new matrix4 |
EXAMPLES
local translation = vmath.vector3(103, -95, 14)
local quat = vmath.quat(1, 2, 3, 4)
local scale = vmath.vector3(1, 0.5, 0.5)
local result = vmath.matrix4_compose(translation, quat, scale)
print(result) --> vmath.matrix4(-25, -10, 11, 103, 28, -9.5, 2, -95, -10, 10, -4.5, 14, 0, 0, 0, 1)
vmath.matrix4_frustum(left,right,bottom,top,near,far)
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 |
number |
coordinate for left clipping plane |
right |
number |
coordinate for right clipping plane |
bottom |
number |
coordinate for bottom clipping plane |
top |
number |
coordinate for top clipping plane |
near |
number |
coordinate for near clipping plane |
far |
number |
coordinate for far clipping plane |
RETURNS
m |
matrix4 | matrix representing the frustum |
EXAMPLES
-- Construct a projection frustum with a vertical and horizontal
-- FOV of 45 degrees. Useful for rendering a square view.
local proj = vmath.matrix4_frustum(-1, 1, -1, 1, 1, 1000)
render.set_projection(proj)
vmath.matrix4_look_at(eye,look_at,up)
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 |
vector3 |
eye position |
look_at |
vector3 |
look-at position |
up |
vector3 |
up vector |
RETURNS
m |
matrix4 | look-at matrix |
EXAMPLES
-- Set up a perspective camera at z 100 with 45 degrees (pi/2) FOV
-- Aspect ratio 4:3
local eye = vmath.vector3(0, 0, 100)
local look_at = vmath.vector3(0, 0, 0)
local up = vmath.vector3(0, 1, 0)
local view = vmath.matrix4_look_at(eye, look_at, up)
render.set_view(view)
local proj = vmath.matrix4_perspective(3.141592/2, 4/3, 1, 1000)
render.set_projection(proj)
vmath.matrix4_orthographic(left,right,bottom,top,near,far)
Creates an orthographic projection matrix. This is useful to construct a projection matrix for a camera or rendering in general.
PARAMETERS
left |
number |
coordinate for left clipping plane |
right |
number |
coordinate for right clipping plane |
bottom |
number |
coordinate for bottom clipping plane |
top |
number |
coordinate for top clipping plane |
near |
number |
coordinate for near clipping plane |
far |
number |
coordinate for far clipping plane |
RETURNS
m |
matrix4 | orthographic projection matrix |
EXAMPLES
-- Set up an orthographic projection based on the width and height
-- of the game window.
local w = render.get_width()
local h = render.get_height()
local proj = vmath.matrix4_orthographic(- w / 2, w / 2, -h / 2, h / 2, -1000, 1000)
render.set_projection(proj)
vmath.matrix4_perspective(fov,aspect,near,far)
Creates a perspective projection matrix. This is useful to construct a projection matrix for a camera or rendering in general.
PARAMETERS
fov |
number |
angle of the full vertical field of view in radians |
aspect |
number |
aspect ratio |
near |
number |
coordinate for near clipping plane |
far |
number |
coordinate for far clipping plane |
RETURNS
m |
matrix4 | perspective projection matrix |
EXAMPLES
-- Set up a perspective camera at z 100 with 45 degrees (pi/2) FOV
-- Aspect ratio 4:3
local eye = vmath.vector3(0, 0, 100)
local look_at = vmath.vector3(0, 0, 0)
local up = vmath.vector3(0, 1, 0)
local view = vmath.matrix4_look_at(eye, look_at, up)
render.set_view(view)
local proj = vmath.matrix4_perspective(3.141592/2, 4/3, 1, 1000)
render.set_projection(proj)
vmath.matrix4_quat(q)
The resulting matrix describes the same rotation as the quaternion, but does not have any translation (also like the quaternion).
PARAMETERS
q |
quaternion |
quaternion to create matrix from |
RETURNS
m |
matrix4 | matrix represented by quaternion |
EXAMPLES
local vec = vmath.vector4(1, 1, 0, 0)
local quat = vmath.quat_rotation_z(3.141592653)
local mat = vmath.matrix4_quat(quat)
print(mat * vec) --> vmath.matrix4_frustum(-1, 1, -1, 1, 1, 1000)
vmath.matrix4_rotation_x(angle)
The resulting matrix describes a rotation around the x-axis by the specified angle.
PARAMETERS
angle |
number |
angle in radians around x-axis |
RETURNS
m |
matrix4 | matrix from rotation around x-axis |
EXAMPLES
local vec = vmath.vector4(1, 1, 0, 0)
local mat = vmath.matrix4_rotation_x(3.141592653)
print(mat * vec) --> vmath.vector4(1, -1, -8.7422776573476e-08, 0)
vmath.matrix4_rotation_y(angle)
The resulting matrix describes a rotation around the y-axis by the specified angle.
PARAMETERS
angle |
number |
angle in radians around y-axis |
RETURNS
m |
matrix4 | matrix from rotation around y-axis |
EXAMPLES
local vec = vmath.vector4(1, 1, 0, 0)
local mat = vmath.matrix4_rotation_y(3.141592653)
print(mat * vec) --> vmath.vector4(-1, 1, 8.7422776573476e-08, 0)
vmath.matrix4_rotation_z(angle)
The resulting matrix describes a rotation around the z-axis by the specified angle.
PARAMETERS
angle |
number |
angle in radians around z-axis |
RETURNS
m |
matrix4 | matrix from rotation around z-axis |
EXAMPLES
local vec = vmath.vector4(1, 1, 0, 0)
local mat = vmath.matrix4_rotation_z(3.141592653)
print(mat * vec) --> vmath.vector4(-0.99999994039536, -1.0000001192093, 0, 0)
vmath.matrix4_scale(scale)
Creates a new matrix constructed from scale vector
PARAMETERS
scale |
vector3 |
scale |
RETURNS
matrix |
matrix4 | new matrix4 |
EXAMPLES
local scale = vmath.vector3(1, 0.5, 0.5)
local result = vmath.matrix4_scale(scale)
print(result) --> vmath.matrix4(1, 0, 0, 0, 0, 0.5, 0, 0, 0, 0, 0.5, 0, 0, 0, 0, 1)
vmath.matrix4_scale(scale)
creates a new matrix4 from uniform scale
PARAMETERS
scale |
number |
scale |
RETURNS
matrix |
matrix4 | new matrix4 |
EXAMPLES
local result = vmath.matrix4_scale(0.5)
print(result) --> vmath.matrix4(0.5, 0, 0, 0, 0, 0.5, 0, 0, 0, 0, 0.5, 0, 0, 0, 0, 1)
vmath.matrix4_scale(scale_x,scale_y,scale_z)
Creates a new matrix4 from three scale components
PARAMETERS
scale_x |
number |
scale along X axis |
scale_y |
number |
sclae along Y axis |
scale_z |
number |
scale along Z asis |
RETURNS
matrix |
matrix4 | new matrix4 |
EXAMPLES
local result = vmath.matrix4_scale(1, 0.5, 0.5)
print(result) --> vmath.matrix4(1, 0, 0, 0, 0, 0.5, 0, 0, 0, 0, 0.5, 0, 0, 0, 0, 1)
vmath.matrix4_translation(position)
The resulting matrix describes a translation of a point in euclidean space.
PARAMETERS
position |
vector3, vector4 |
position vector to create matrix from |
RETURNS
m |
matrix4 | matrix from the supplied position vector |
EXAMPLES
-- Set camera view from custom view and translation matrices
local mat_trans = vmath.matrix4_translation(vmath.vector3(0, 10, 100))
local mat_view = vmath.matrix4_rotation_y(-3.141592/4)
render.set_view(mat_view * mat_trans)
vmath.mul_per_elem(v1,v2)
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 |
vector3, vector4 |
first vector |
v2 |
vector3, vector4 |
second vector |
RETURNS
v |
vector3, vector4 | multiplied vector |
EXAMPLES
local blend_color = vmath.mul_per_elem(color1, color2)
vmath.normalize(v1)
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 |
vector3, vector4, quat |
vector to normalize |
RETURNS
v |
vector3, vector4, quat | new normalized vector |
EXAMPLES
local vec = vmath.vector3(1, 2, 3)
local norm_vec = vmath.normalize(vec)
print(norm_vec) --> vmath.vector3(0.26726123690605, 0.5345224738121, 0.80178368091583)
print(vmath.length(norm_vec)) --> 0.99999994039536
vmath.ortho_inv(m1)
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 |
matrix4 |
ortho-normalized matrix to invert |
RETURNS
m |
matrix4 | inverse of the supplied matrix |
EXAMPLES
local mat1 = vmath.matrix4_rotation_z(3.141592653)
local mat2 = vmath.ortho_inv(mat1)
-- M * inv(M) = identity matrix
print(mat1 * mat2) --> vmath.matrix4(1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1)
vmath.project(v1,v2)
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 |
vector3 |
vector to be projected on the second |
v2 |
vector3 |
vector onto which the first will be projected, must not have zero length |
RETURNS
n |
number | the projected extent of the first vector onto the second |
EXAMPLES
local v1 = vmath.vector3(1, 1, 0)
local v2 = vmath.vector3(2, 0, 0)
print(vmath.project(v1, v2)) --> 0.5
vmath.quat()
Creates a new identity quaternion. The identity
quaternion is equal to:
vmath.quat(0, 0, 0, 1)
PARAMETERS
None
RETURNS
q |
quaternion | new identity quaternion |
EXAMPLES
local quat = vmath.quat()
print(quat) --> vmath.quat(0, 0, 0, 1)
print(quat.w) --> 1
vmath.quat(q1)
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
q1 |
quaternion |
existing quaternion |
RETURNS
q |
quaternion | new quaternion |
EXAMPLES
local quat1 = vmath.quat(1, 2, 3, 4)
local quat2 = vmath.quat(quat1)
if quat1 == quat2 then
-- yes, they are equal
print(quat2) --> vmath.quat(1, 2, 3, 4)
end
vmath.quat(x,y,z,w)
Creates a new quaternion with the components set according to the supplied parameter values.
PARAMETERS
x |
number |
x coordinate |
y |
number |
y coordinate |
z |
number |
z coordinate |
w |
number |
w coordinate |
RETURNS
q |
quaternion | new quaternion |
EXAMPLES
local quat = vmath.quat(1, 2, 3, 4)
print(quat) --> vmath.quat(1, 2, 3, 4)
vmath.quat_axis_angle(v,angle)
The resulting quaternion describes a rotation of angle
radians around the axis described by the unit vector v
.
PARAMETERS
v |
vector3 |
axis |
angle |
number |
angle |
RETURNS
q |
quaternion | quaternion representing the axis-angle rotation |
EXAMPLES
local axis = vmath.vector3(1, 0, 0)
local rot = vmath.quat_axis_angle(axis, 3.141592653)
local vec = vmath.vector3(1, 1, 0)
print(vmath.rotate(rot, vec)) --> vmath.vector3(1, -1, -8.7422776573476e-08)
vmath.quat_basis(x,y,z)
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 |
vector3 |
x base vector |
y |
vector3 |
y base vector |
z |
vector3 |
z base vector |
RETURNS
q |
quaternion | quaternion representing the rotation of the specified base vectors |
EXAMPLES
-- Axis rotated 90 degrees around z.
local rot_x = vmath.vector3(0, -1, 0)
local rot_y = vmath.vector3(1, 0, 0)
local z = vmath.vector3(0, 0, 1)
local rot1 = vmath.quat_basis(rot_x, rot_y, z)
local rot2 = vmath.quat_from_to(vmath.vector3(0, 1, 0), vmath.vector3(1, 0, 0))
if rot1 == rot2 then
-- These quaternions are equal!
print(rot2) --> vmath.quat(0, 0, -0.70710676908493, 0.70710676908493)
end
vmath.quat_from_to(v1,v2)
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 vectors (of length 1). The result is undefined if the two vectors point in opposite directions
PARAMETERS
v1 |
vector3 |
first unit vector, before rotation |
v2 |
vector3 |
second unit vector, after rotation |
RETURNS
q |
quaternion | quaternion representing the rotation from first to second vector |
EXAMPLES
local v1 = vmath.vector3(1, 0, 0)
local v2 = vmath.vector3(0, 1, 0)
local rot = vmath.quat_from_to(v1, v2)
print(vmath.rotate(rot, v1)) --> vmath.vector3(0, 0.99999994039536, 0)
vmath.quat_matrix4(matrix)
Creates a new quaternion with the components set according to the supplied parameter values.
PARAMETERS
matrix |
matrix4 |
source matrix4 |
RETURNS
q |
quaternion | new quaternion |
vmath.quat_rotation_x(angle)
The resulting quaternion describes a rotation of angle
radians around the x-axis.
PARAMETERS
angle |
number |
angle in radians around x-axis |
RETURNS
q |
quaternion | quaternion representing the rotation around the x-axis |
EXAMPLES
local rot = vmath.quat_rotation_x(3.141592653)
local vec = vmath.vector3(1, 1, 0)
print(vmath.rotate(rot, vec)) --> vmath.vector3(1, -1, -8.7422776573476e-08)
vmath.quat_rotation_y(angle)
The resulting quaternion describes a rotation of angle
radians around the y-axis.
PARAMETERS
angle |
number |
angle in radians around y-axis |
RETURNS
q |
quaternion | quaternion representing the rotation around the y-axis |
EXAMPLES
local rot = vmath.quat_rotation_y(3.141592653)
local vec = vmath.vector3(1, 1, 0)
print(vmath.rotate(rot, vec)) --> vmath.vector3(-1, 1, 8.7422776573476e-08)
vmath.quat_rotation_z(angle)
The resulting quaternion describes a rotation of angle
radians around the z-axis.
PARAMETERS
angle |
number |
angle in radians around z-axis |
RETURNS
q |
quaternion | quaternion representing the rotation around the z-axis |
EXAMPLES
local rot = vmath.quat_rotation_z(3.141592653)
local vec = vmath.vector3(1, 1, 0)
print(vmath.rotate(rot, vec)) --> vmath.vector3(-0.99999988079071, -1, 0)
vmath.quat_to_euler(q)
Converts a quaternion into euler angles (r0, r1, r2), based on YZX rotation order. To handle gimbal lock (singularity at r1 ~ +/- 90 degrees), the cut off is at r0 = +/- 88.85 degrees, which snaps to +/- 90. The provided quaternion is expected to be normalized. The error is guaranteed to be less than +/- 0.02 degrees
PARAMETERS
q |
quaternion |
source quaternion |
RETURNS
x |
number | euler angle x in degrees |
y |
number | euler angle y in degrees |
z |
number | euler angle z in degrees |
vmath.rotate(q,v1)
Returns a new vector from the supplied vector that is rotated by the rotation described by the supplied quaternion.
PARAMETERS
q |
quaternion |
quaternion |
v1 |
vector3 |
vector to rotate |
RETURNS
v |
vector3 | the rotated vector |
EXAMPLES
local vec = vmath.vector3(1, 1, 0)
local rot = vmath.quat_rotation_z(3.141592563)
print(vmath.rotate(rot, vec)) --> vmath.vector3(-1.0000002384186, -0.99999988079071, 0)
vmath.slerp(t,v1,v2)
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 is computationally more expensive than lerp. The function does not clamp t between 0 and 1.
PARAMETERS
t |
number |
interpolation parameter, 0-1 |
v1 |
vector3, vector4 |
vector to slerp from |
v2 |
vector3, vector4 |
vector to slerp to |
RETURNS
v |
vector3, vector4 | the slerped vector |
EXAMPLES
function init(self)
self.t = 0
end
function update(self, dt)
self.t = self.t + dt
if self.t <= 1 then
local startpos = vmath.vector3(0, 600, 0)
local endpos = vmath.vector3(600, 0, 0)
local pos = vmath.slerp(self.t, startpos, endpos)
go.set_position(pos, "go")
end
end
vmath.slerp(t,q1,q2)
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. The function does not clamp t between 0 and 1.
PARAMETERS
t |
number |
interpolation parameter, 0-1 |
q1 |
quaternion |
quaternion to slerp from |
q2 |
quaternion |
quaternion to slerp to |
RETURNS
q |
quaternion | the slerped quaternion |
EXAMPLES
function init(self)
self.t = 0
end
function update(self, dt)
self.t = self.t + dt
if self.t <= 1 then
local startrot = vmath.quat_rotation_z(0)
local endrot = vmath.quat_rotation_z(3.141592653)
local rot = vmath.slerp(self.t, startrot, endrot)
go.set_rotation(rot, "go")
end
end
vmath.vector(t)
Creates a vector of arbitrary size. The vector is initialized with numeric values from a table. The table values are converted to floating point values. If a value cannot be converted, a 0 is stored in that value position in the vector.
PARAMETERS
t |
table |
table of numbers |
RETURNS
v |
vector | new vector |
EXAMPLES
How to create a vector with custom data to be used for animation easing:local values = { 0, 0.5, 0 }
local vec = vmath.vector(values)
print(vec) --> vmath.vector (size: 3)
print(vec[2]) --> 0.5
vmath.vector3()
Creates a new zero vector with all components set to 0.
PARAMETERS
None
RETURNS
v |
vector3 | new zero vector |
EXAMPLES
local vec = vmath.vector3()
pprint(vec) --> vmath.vector3(0, 0, 0)
print(vec.x) --> 0
vmath.vector3(n)
Creates a new vector with all components set to the supplied scalar value.
PARAMETERS
n |
number |
scalar value to splat |
RETURNS
v |
vector3 | new vector |
EXAMPLES
local vec = vmath.vector3(1.0)
print(vec) --> vmath.vector3(1, 1, 1)
print(vec.x) --> 1
vmath.vector3(v1)
Creates a new vector with all components set to the corresponding values from the supplied vector. I.e. This function creates a copy of the given vector.
PARAMETERS
v1 |
vector3 |
existing vector |
RETURNS
v |
vector3 | new vector |
EXAMPLES
local vec1 = vmath.vector3(1.0)
local vec2 = vmath.vector3(vec1)
if vec1 == vec2 then
-- yes, they are equal
print(vec2) --> vmath.vector3(1, 1, 1)
end
vmath.vector3(x,y,z)
Creates a new vector with the components set to the supplied values.
PARAMETERS
x |
number |
x coordinate |
y |
number |
y coordinate |
z |
number |
z coordinate |
RETURNS
v |
vector3 | new vector |
EXAMPLES
local vec = vmath.vector3(1.0, 2.0, 3.0)
print(vec) --> vmath.vector3(1, 2, 3)
print(-vec) --> vmath.vector3(-1, -2, -3)
print(vec * 2) --> vmath.vector3(2, 4, 6)
print(vec + vmath.vector3(2.0)) --> vmath.vector3(3, 4, 5)
print(vec - vmath.vector3(2.0)) --> vmath.vector3(-1, 0, 1)
vmath.vector4()
Creates a new zero vector with all components set to 0.
PARAMETERS
None
RETURNS
v |
vector4 | new zero vector |
EXAMPLES
local vec = vmath.vector4()
print(vec) --> vmath.vector4(0, 0, 0, 0)
print(vec.w) --> 0
vmath.vector4(n)
Creates a new vector with all components set to the supplied scalar value.
PARAMETERS
n |
number |
scalar value to splat |
RETURNS
v |
vector4 | new vector |
EXAMPLES
local vec = vmath.vector4(1.0)
print(vec) --> vmath.vector4(1, 1, 1, 1)
print(vec.w) --> 1
vmath.vector4(v1)
Creates a new vector with all components set to the corresponding values from the supplied vector. I.e. This function creates a copy of the given vector.
PARAMETERS
v1 |
vector4 |
existing vector |
RETURNS
v |
vector4 | new vector |
EXAMPLES
local vect1 = vmath.vector4(1.0)
local vect2 = vmath.vector4(vec1)
if vec1 == vec2 then
-- yes, they are equal
print(vec2) --> vmath.vector4(1, 1, 1, 1)
end
vmath.vector4(x,y,z,w)
Creates a new vector with the components set to the supplied values.
PARAMETERS
x |
number |
x coordinate |
y |
number |
y coordinate |
z |
number |
z coordinate |
w |
number |
w coordinate |
RETURNS
v |
vector4 | new vector |
EXAMPLES
local vec = vmath.vector4(1.0, 2.0, 3.0, 4.0)
print(vec) --> vmath.vector4(1, 2, 3, 4)
print(-vec) --> vmath.vector4(-1, -2, -3, -4)
print(vec * 2) --> vmath.vector4(2, 4, 6, 8)
print(vec + vmath.vector4(2.0)) --> vmath.vector4(3, 4, 5, 6)
print(vec - vmath.vector4(2.0)) --> vmath.vector4(-1, 0, 1, 2)