1 files changed, 406 insertions, 0 deletions
diff --git a/meta/3rd/Defold/library/vector_math.lua b/meta/3rd/Defold/library/vector_math.lua
new file mode 100644
index 00000000..8196bfd6
--- /dev/null
+++ b/meta/3rd/Defold/library/vector_math.lua
@@ -0,0 +1,406 @@
+---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]
+
+---@class 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 # 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 # 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 # 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 # 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|quat # value of which to calculate the length
+---@return number # length
+function vmath.length(v) end
+
+---Returns the squared length of the supplied vector or quaternion.
+---@param v vector3|vector4|quat # value of which to calculate the squared length
+---@return number # squared length
+function vmath.length_sqr(v) 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 # the lerped vector
+function vmath.lerp(t, v1, v2) 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 # the lerped quaternion
+function vmath.lerp(t, q1, q2) 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 # the lerped number
+function vmath.lerp(t, n1, n2) end
+
+---The resulting identity matrix describes a transform with
+---no translation or rotation.
+---@return matrix4 # 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 # 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 # 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 # 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 # 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 # 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 # 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 # 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 # 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 # 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 # 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 # 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 # 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|quat # vector to normalize
+---@return vector3|vector4|quat # 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 # 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 # 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 # new identity quaternion
+function vmath.quat() 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 # new quaternion
+function vmath.quat(q1) 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 # new quaternion
+function vmath.quat(x, y, z, w) 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 # 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 # 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 # 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 # 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 # 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 # 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 # the rotated vector
+function vmath.rotate(q, v1) 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 # the slerped vector
+function vmath.slerp(t, v1, v2) 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 # the slerped quaternion
+function vmath.slerp(t, q1, q2) 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 vector # new vector
+function vmath.vector(t) end
+
+---Creates a new zero vector with all components set to 0.
+---@return vector3 # 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 # new vector
+function vmath.vector3(n) 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 # 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 # new vector
+function vmath.vector3(x, y, z) end
+
+---Creates a new zero vector with all components set to 0.
+---@return vector4 # new zero vector
+function vmath.vector4() end
+
+---Creates a new vector with all components set to the
+---supplied scalar value.
+---@param n number # scalar value to splat
+---@return vector4 # new vector
+function vmath.vector4(n) 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 # new vector
+function vmath.vector4(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
+---@param w number # w coordinate
+---@return vector4 # new vector
+function vmath.vector4(x, y, z, w) end
+
+
+
+
+return vmath
+\ No newline at end of file