mirror of
https://github.com/Insality/druid
synced 2025-06-27 18:37:45 +02:00
404 lines
17 KiB
Lua
404 lines
17 KiB
Lua
--[[
|
||
Generated with github.com/astrochili/defold-annotations
|
||
Defold 1.8.0
|
||
|
||
Vector math API documentation
|
||
|
||
Functions for mathematical operations on vectors, matrices and quaternions.
|
||
The vector types (vmath.vector3 and vmath.vector4) supports addition and subtraction
|
||
with vectors of the same type. Vectors can be negated and multiplied (scaled) or divided by numbers.
|
||
The quaternion type (vmath.quat) supports multiplication with other quaternions.
|
||
The matrix type (vmath.matrix4) can be multiplied with numbers, other matrices
|
||
and vmath.vector4 values.
|
||
All types performs equality comparison by each component value.
|
||
The following components are available for the various types:
|
||
vector3
|
||
x, y and z. Example: v.y
|
||
vector4
|
||
x, y, z, and w. Example: v.w
|
||
quaternion
|
||
x, y, z, and w. Example: q.w
|
||
matrix4
|
||
m00 to m33 where the first number is the row (starting from 0) and the second
|
||
number is the column. Columns can be accessed with c0 to c3, returning a vector4.
|
||
Example: m.m21 which is equal to m.c1.z
|
||
vector
|
||
indexed by number 1 to the vector length. Example: v[3]
|
||
--]]
|
||
|
||
---@diagnostic disable: lowercase-global
|
||
---@diagnostic disable: missing-return
|
||
---@diagnostic disable: duplicate-doc-param
|
||
---@diagnostic disable: duplicate-set-field
|
||
|
||
---@class defold_api.vmath
|
||
vmath = {}
|
||
|
||
---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]
|
||
---@param q1 quaternion quaternion of which to calculate the conjugate
|
||
---@return quaternion q the conjugate
|
||
function vmath.conj(q1) end
|
||
|
||
---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.
|
||
---@param v1 vector3 first vector
|
||
---@param v2 vector3 second vector
|
||
---@return vector3 v a new vector representing the cross product
|
||
function vmath.cross(v1, v2) end
|
||
|
||
---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.
|
||
---@param v1 vector3|vector4 first vector
|
||
---@param v2 vector3|vector4 second vector
|
||
---@return number n dot product
|
||
function vmath.dot(v1, v2) end
|
||
|
||
---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.
|
||
---@param m1 matrix4 matrix to invert
|
||
---@return matrix4 m inverse of the supplied matrix
|
||
function vmath.inv(m1) end
|
||
|
||
---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).
|
||
---@param v vector3|vector4|quaternion value of which to calculate the length
|
||
---@return number n length
|
||
function vmath.length(v) end
|
||
|
||
---Returns the squared length of the supplied vector or quaternion.
|
||
---@param v vector3|vector4|quaternion value of which to calculate the squared length
|
||
---@return number n squared length
|
||
function vmath.length_sqr(v) end
|
||
|
||
---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.
|
||
---@param t number interpolation parameter, 0-1
|
||
---@param q1 quaternion quaternion to lerp from
|
||
---@param q2 quaternion quaternion to lerp to
|
||
---@return quaternion q the lerped quaternion
|
||
function vmath.lerp(t, q1, q2) end
|
||
|
||
---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.
|
||
---@param t number interpolation parameter, 0-1
|
||
---@param v1 vector3|vector4 vector to lerp from
|
||
---@param v2 vector3|vector4 vector to lerp to
|
||
---@return vector3|vector4 v the lerped vector
|
||
function vmath.lerp(t, v1, v2) end
|
||
|
||
---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.
|
||
---@param t number interpolation parameter, 0-1
|
||
---@param n1 number number to lerp from
|
||
---@param n2 number number to lerp to
|
||
---@return number n the lerped number
|
||
function vmath.lerp(t, n1, n2) end
|
||
|
||
---The resulting identity matrix describes a transform with
|
||
---no translation or rotation.
|
||
---@return matrix4 m identity matrix
|
||
function vmath.matrix4() end
|
||
|
||
---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.
|
||
---@param m1 matrix4 existing matrix
|
||
---@return matrix4 m matrix which is a copy of the specified matrix
|
||
function vmath.matrix4(m1) end
|
||
|
||
---The resulting matrix describes a rotation around the axis by the specified angle.
|
||
---@param v vector3 axis
|
||
---@param angle number angle in radians
|
||
---@return matrix4 m matrix represented by axis and angle
|
||
function vmath.matrix4_axis_angle(v, angle) end
|
||
|
||
---The resulting matrix describes the same rotation as the quaternion, but does not have any translation (also like the quaternion).
|
||
---@param q quaternion quaternion to create matrix from
|
||
---@return matrix4 m matrix represented by quaternion
|
||
function vmath.matrix4_from_quat(q) end
|
||
|
||
---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.
|
||
---@param left number coordinate for left clipping plane
|
||
---@param right number coordinate for right clipping plane
|
||
---@param bottom number coordinate for bottom clipping plane
|
||
---@param top number coordinate for top clipping plane
|
||
---@param near number coordinate for near clipping plane
|
||
---@param far number coordinate for far clipping plane
|
||
---@return matrix4 m matrix representing the frustum
|
||
function vmath.matrix4_frustum(left, right, bottom, top, near, far) end
|
||
|
||
---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.
|
||
---@param eye vector3 eye position
|
||
---@param look_at vector3 look-at position
|
||
---@param up vector3 up vector
|
||
---@return matrix4 m look-at matrix
|
||
function vmath.matrix4_look_at(eye, look_at, up) end
|
||
|
||
---Creates an orthographic projection matrix.
|
||
---This is useful to construct a projection matrix for a camera or rendering in general.
|
||
---@param left number coordinate for left clipping plane
|
||
---@param right number coordinate for right clipping plane
|
||
---@param bottom number coordinate for bottom clipping plane
|
||
---@param top number coordinate for top clipping plane
|
||
---@param near number coordinate for near clipping plane
|
||
---@param far number coordinate for far clipping plane
|
||
---@return matrix4 m orthographic projection matrix
|
||
function vmath.matrix4_orthographic(left, right, bottom, top, near, far) end
|
||
|
||
---Creates a perspective projection matrix.
|
||
---This is useful to construct a projection matrix for a camera or rendering in general.
|
||
---@param fov number angle of the full vertical field of view in radians
|
||
---@param aspect number aspect ratio
|
||
---@param near number coordinate for near clipping plane
|
||
---@param far number coordinate for far clipping plane
|
||
---@return matrix4 m perspective projection matrix
|
||
function vmath.matrix4_perspective(fov, aspect, near, far) end
|
||
|
||
---The resulting matrix describes a rotation around the x-axis
|
||
---by the specified angle.
|
||
---@param angle number angle in radians around x-axis
|
||
---@return matrix4 m matrix from rotation around x-axis
|
||
function vmath.matrix4_rotation_x(angle) end
|
||
|
||
---The resulting matrix describes a rotation around the y-axis
|
||
---by the specified angle.
|
||
---@param angle number angle in radians around y-axis
|
||
---@return matrix4 m matrix from rotation around y-axis
|
||
function vmath.matrix4_rotation_y(angle) end
|
||
|
||
---The resulting matrix describes a rotation around the z-axis
|
||
---by the specified angle.
|
||
---@param angle number angle in radians around z-axis
|
||
---@return matrix4 m matrix from rotation around z-axis
|
||
function vmath.matrix4_rotation_z(angle) end
|
||
|
||
---The resulting matrix describes a translation of a point
|
||
---in euclidean space.
|
||
---@param position vector3|vector4 position vector to create matrix from
|
||
---@return matrix4 m matrix from the supplied position vector
|
||
function vmath.matrix4_translation(position) end
|
||
|
||
---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)
|
||
---@param v1 vector3|vector4 first vector
|
||
---@param v2 vector3|vector4 second vector
|
||
---@return vector3|vector4 v multiplied vector
|
||
function vmath.mul_per_elem(v1, v2) end
|
||
|
||
---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.
|
||
---@param v1 vector3|vector4|quaternion vector to normalize
|
||
---@return vector3|vector4|quaternion v new normalized vector
|
||
function vmath.normalize(v1) end
|
||
|
||
---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.
|
||
---@param m1 matrix4 ortho-normalized matrix to invert
|
||
---@return matrix4 m inverse of the supplied matrix
|
||
function vmath.ortho_inv(m1) end
|
||
|
||
---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.
|
||
---@param v1 vector3 vector to be projected on the second
|
||
---@param v2 vector3 vector onto which the first will be projected, must not have zero length
|
||
---@return number n the projected extent of the first vector onto the second
|
||
function vmath.project(v1, v2) end
|
||
|
||
---Creates a new identity quaternion. The identity
|
||
---quaternion is equal to:
|
||
---vmath.quat(0, 0, 0, 1)
|
||
---@return quaternion q new identity quaternion
|
||
function vmath.quat() end
|
||
|
||
---Creates a new quaternion with the components set
|
||
---according to the supplied parameter values.
|
||
---@param x number x coordinate
|
||
---@param y number y coordinate
|
||
---@param z number z coordinate
|
||
---@param w number w coordinate
|
||
---@return quaternion q new quaternion
|
||
function vmath.quat(x, y, z, w) end
|
||
|
||
---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.
|
||
---@param q1 quaternion existing quaternion
|
||
---@return quaternion q new quaternion
|
||
function vmath.quat(q1) end
|
||
|
||
---The resulting quaternion describes a rotation of angle
|
||
---radians around the axis described by the unit vector v.
|
||
---@param v vector3 axis
|
||
---@param angle number angle
|
||
---@return quaternion q quaternion representing the axis-angle rotation
|
||
function vmath.quat_axis_angle(v, angle) end
|
||
|
||
---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.
|
||
---@param x vector3 x base vector
|
||
---@param y vector3 y base vector
|
||
---@param z vector3 z base vector
|
||
---@return quaternion q quaternion representing the rotation of the specified base vectors
|
||
function vmath.quat_basis(x, y, z) end
|
||
|
||
---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
|
||
---@param v1 vector3 first unit vector, before rotation
|
||
---@param v2 vector3 second unit vector, after rotation
|
||
---@return quaternion q quaternion representing the rotation from first to second vector
|
||
function vmath.quat_from_to(v1, v2) end
|
||
|
||
---The resulting quaternion describes a rotation of angle
|
||
---radians around the x-axis.
|
||
---@param angle number angle in radians around x-axis
|
||
---@return quaternion q quaternion representing the rotation around the x-axis
|
||
function vmath.quat_rotation_x(angle) end
|
||
|
||
---The resulting quaternion describes a rotation of angle
|
||
---radians around the y-axis.
|
||
---@param angle number angle in radians around y-axis
|
||
---@return quaternion q quaternion representing the rotation around the y-axis
|
||
function vmath.quat_rotation_y(angle) end
|
||
|
||
---The resulting quaternion describes a rotation of angle
|
||
---radians around the z-axis.
|
||
---@param angle number angle in radians around z-axis
|
||
---@return quaternion q quaternion representing the rotation around the z-axis
|
||
function vmath.quat_rotation_z(angle) end
|
||
|
||
---Returns a new vector from the supplied vector that is
|
||
---rotated by the rotation described by the supplied
|
||
---quaternion.
|
||
---@param q quaternion quaternion
|
||
---@param v1 vector3 vector to rotate
|
||
---@return vector3 v the rotated vector
|
||
function vmath.rotate(q, v1) end
|
||
|
||
---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.
|
||
---@param t number interpolation parameter, 0-1
|
||
---@param q1 quaternion quaternion to slerp from
|
||
---@param q2 quaternion quaternion to slerp to
|
||
---@return quaternion q the slerped quaternion
|
||
function vmath.slerp(t, q1, q2) end
|
||
|
||
---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.
|
||
---@param t number interpolation parameter, 0-1
|
||
---@param v1 vector3|vector4 vector to slerp from
|
||
---@param v2 vector3|vector4 vector to slerp to
|
||
---@return vector3|vector4 v the slerped vector
|
||
function vmath.slerp(t, v1, v2) end
|
||
|
||
---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.
|
||
---@param t table table of numbers
|
||
---@return vector4|vector3 v new vector
|
||
function vmath.vector(t) end
|
||
|
||
---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.
|
||
---@param v1 vector3 existing vector
|
||
---@return vector3 v new vector
|
||
function vmath.vector3(v1) end
|
||
|
||
---Creates a new vector with the components set to the
|
||
---supplied values.
|
||
---@param x number x coordinate
|
||
---@param y number y coordinate
|
||
---@param z number z coordinate
|
||
---@return vector3 v new vector
|
||
function vmath.vector3(x, y, z) end
|
||
|
||
---Creates a new zero vector with all components set to 0.
|
||
---@return vector3 v new zero vector
|
||
function vmath.vector3() end
|
||
|
||
---Creates a new vector with all components set to the
|
||
---supplied scalar value.
|
||
---@param n number scalar value to splat
|
||
---@return vector3 v new vector
|
||
function vmath.vector3(n) end
|
||
|
||
---Creates a new vector with the components set to the
|
||
---supplied values.
|
||
---@param x number x coordinate
|
||
---@param y number y coordinate
|
||
---@param z number z coordinate
|
||
---@param w number w coordinate
|
||
---@return vector4 v new vector
|
||
function vmath.vector4(x, y, z, w) end
|
||
|
||
---Creates a new vector with all components set to the
|
||
---supplied scalar value.
|
||
---@param n number scalar value to splat
|
||
---@return vector4 v new vector
|
||
function vmath.vector4(n) end
|
||
|
||
---Creates a new zero vector with all components set to 0.
|
||
---@return vector4 v new zero vector
|
||
function vmath.vector4() end
|
||
|
||
---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.
|
||
---@param v1 vector4 existing vector
|
||
---@return vector4 v new vector
|
||
function vmath.vector4(v1) end
|
||
|
||
return vmath |