Version: beta
FUNCTION | |
---|---|
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.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_from_to() | creates a quaternion to rotate between two unit vectors |
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_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.matrix4() | creates a new identity matrix |
vmath.matrix4() | creates a new matrix from another existing matrix |
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_from_quat() | creates a matrix from a quaternion |
vmath.matrix4_axis_angle() | creates a matrix from an axis and an angle |
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_translation() | creates a translation matrix from a position vector |
vmath.inv() | calculates the inverse matrix. |
vmath.ortho_inv() | calculates the inverse of an ortho-normal matrix. |
vmath.dot() | calculates the dot-product of two vectors |
vmath.length_sqr() | calculates the squared length of a vector or quaternion |
vmath.length() | calculates the length of a vector or quaternion |
vmath.normalize() | normalizes a vector |
vmath.cross() | calculates the cross-product of two vectors |
vmath.lerp() | lerps between two vectors |
vmath.lerp() | lerps between two quaternions |
vmath.lerp() | lerps between two numbers |
vmath.slerp() | slerps between two vectors |
vmath.slerp() | slerps between two quaternions |
vmath.conj() | calculates the conjugate of a quaternion |
vmath.rotate() | rotates a vector by a quaternion |
vmath.project() | projects a vector onto another vector |
vmath.mul_per_elem() | performs an element wise multiplication of two vectors |
vmath.vector(t)
PARAMETERS
t |
table of numbers |
RETURNS
v |
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()
PARAMETERS
RETURNS
v |
new zero vector |
EXAMPLES
local vec = vmath.vector3() pprint(vec) --> vmath.vector3(0, 0, 0) print(vec.x) --> 0
vmath.vector3(n)
PARAMETERS
n |
scalar value to splat |
RETURNS
v |
new vector |
EXAMPLES
local vec = vmath.vector3(1.0) print(vec) --> vmath.vector3(1, 1, 1) print(vec.x) --> 1
vmath.vector3(v1)
PARAMETERS
v1 |
existing vector |
RETURNS
v |
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)
PARAMETERS
x |
x coordinate |
y |
y coordinate |
z |
z coordinate |
RETURNS
v |
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()
PARAMETERS
RETURNS
v |
new zero vector |
EXAMPLES
local vec = vmath.vector4() print(vec) --> vmath.vector4(0, 0, 0, 0) print(vec.w) --> 0
vmath.vector4(n)
PARAMETERS
n |
scalar value to splat |
RETURNS
v |
new vector |
EXAMPLES
local vec = vmath.vector4(1.0) print(vec) --> vmath.vector4(1, 1, 1, 1) print(vec.w) --> 1
vmath.vector4(v1)
PARAMETERS
v1 |
existing vector |
RETURNS
v |
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)
PARAMETERS
x |
x coordinate |
y |
y coordinate |
z |
z coordinate |
w |
w coordinate |
RETURNS
v |
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)
vmath.quat()
vmath.quat(0, 0, 0, 1)
PARAMETERS
RETURNS
q |
new identity quaternion |
EXAMPLES
local quat = vmath.quat() print(quat) --> vmath.quat(0, 0, 0, 1) print(quat.w) --> 1
vmath.quat(q1)
PARAMETERS
q1 |
existing quaternion |
RETURNS
q |
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)
PARAMETERS
x |
x coordinate |
y |
y coordinate |
z |
z coordinate |
w |
w coordinate |
RETURNS
q |
new quaternion |
EXAMPLES
local quat = vmath.quat(1, 2, 3, 4) print(quat) --> vmath.quat(1, 2, 3, 4)
vmath.quat_from_to(v1,v2)
PARAMETERS
v1 |
first unit vector, before rotation |
v2 |
second unit vector, after rotation |
RETURNS
q |
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_axis_angle(v,angle)
angle
radians around the axis described by the unit vector v
.
PARAMETERS
v |
axis |
angle |
angle |
RETURNS
q |
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)
PARAMETERS
x |
x base vector |
y |
y base vector |
z |
z base vector |
RETURNS
q |
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_rotation_x(angle)
angle
radians around the x-axis.
PARAMETERS
angle |
angle in radians around x-axis |
RETURNS
q |
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)
angle
radians around the y-axis.
PARAMETERS
angle |
angle in radians around y-axis |
RETURNS
q |
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)
angle
radians around the z-axis.
PARAMETERS
angle |
angle in radians around z-axis |
RETURNS
q |
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.matrix4()
PARAMETERS
RETURNS
m |
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)
PARAMETERS
m1 |
existing matrix |
RETURNS
m |
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_frustum(left,right,bottom,top,near,far)
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
m |
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)
PARAMETERS
eye |
eye position |
look_at |
look-at position |
up |
up vector |
RETURNS
m |
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)
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
m |
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)
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
m |
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_from_quat(q)
PARAMETERS
q |
quaternion to create matrix from |
RETURNS
m |
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_from_quat(quat) print(mat * vec) --> vmath.matrix4_frustum(-1, 1, -1, 1, 1, 1000)
vmath.matrix4_axis_angle(v,angle)
PARAMETERS
v |
axis |
angle |
angle in radians |
RETURNS
m |
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_rotation_x(angle)
PARAMETERS
angle |
angle in radians around x-axis |
RETURNS
m |
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)
PARAMETERS
angle |
angle in radians around y-axis |
RETURNS
m |
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)
PARAMETERS
angle |
angle in radians around z-axis |
RETURNS
m |
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_translation(position)
PARAMETERS
position |
position vector to create matrix from |
RETURNS
m |
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.inv(m1)
vmath.ortho_inv()
instead.
The specialized inverse for ortho-normalized matrices is much faster
than the general inverse.
PARAMETERS
m1 |
matrix to invert |
RETURNS
m |
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.ortho_inv(m1)
vmath.inv()
instead.
PARAMETERS
m1 |
ortho-normalized matrix to invert |
RETURNS
m |
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.dot(v1,v2)
P ⋅ Q = |P| |Q| cos θ
where θ is the angle between the vectors P and Q.
PARAMETERS
v1 |
first vector |
v2 |
second vector |
RETURNS
n |
dot product |
EXAMPLES
if vmath.dot(vector1, vector2) == 0 then -- The two vectors are perpendicular (at right-angles to each other) ... end
vmath.length_sqr(v)
PARAMETERS
v |
value of which to calculate the squared length |
RETURNS
n |
squared length |
EXAMPLES
if vmath.length_sqr(vector1) < vmath.length_sqr(vector2) then -- Vector 1 has less magnitude than vector 2 ... end
vmath.length(v)
PARAMETERS
v |
value of which to calculate the length |
RETURNS
n |
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.normalize(v1)
PARAMETERS
v1 |
vector to normalize |
RETURNS
v |
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.cross(v1,v2)
PARAMETERS
v1 |
first vector |
v2 |
second vector |
RETURNS
v |
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.lerp(t,v1,v2)
PARAMETERS
t |
interpolation parameter, 0-1 |
v1 |
vector to lerp from |
v2 |
vector to lerp to |
RETURNS
v |
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)
PARAMETERS
t |
interpolation parameter, 0-1 |
q1 |
quaternion to lerp from |
q2 |
quaternion to lerp to |
RETURNS
q |
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)
PARAMETERS
t |
interpolation parameter, 0-1 |
n1 |
number to lerp from |
n2 |
number to lerp to |
RETURNS
n |
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.slerp(t,v1,v2)
PARAMETERS
t |
interpolation parameter, 0-1 |
v1 |
vector to slerp from |
v2 |
vector to slerp to |
RETURNS
v |
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)
PARAMETERS
t |
interpolation parameter, 0-1 |
q1 |
quaternion to slerp from |
q2 |
quaternion to slerp to |
RETURNS
q |
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.conj(q1)
q* = [w, -v]
PARAMETERS
q1 |
quaternion of which to calculate the conjugate |
RETURNS
q |
the conjugate |
EXAMPLES
local quat = vmath.quat(1, 2, 3, 4) print(vmath.conj(quat)) --> vmath.quat(-1, -2, -3, 4)
vmath.rotate(q,v1)
PARAMETERS
q |
quaternion |
v1 |
vector to rotate |
RETURNS
v |
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.project(v1,v2)
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
n |
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.mul_per_elem(v1,v2)
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
v |
multiplied vector |
EXAMPLES
local blend_color = vmath.mul_per_elem(color1, color2)