@defold-typescript/types 0.4.2 → 0.5.0

package/generated/vmath.d.ts

@@ -3,59 +3,973 @@ import type { Matrix4, Quaternion, Vector, Vector3, Vector4 } from "../src/core-
 
 declare global {
   namespace vmath {
+    /**
+     * 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
+     *
+     * @param value - Input value or vector of values
+     * @param min - Min value(s) border
+     * @param max - Max value(s) border
+     * @returns Clamped value or vector
+     * @example
+     * ```lua
+     * local value1 = 56
+     * print(vmath.clamp(value1, 89, 134)) -> 89
+     * local v2 = vmath.vector3(190, 190, -10)
+     * print(vmath.clamp(v2, -50, 150)) -> vmath.vector3(150, 150, -10)
+     * local v3 = vmath.vector4(30, -30, 45, 1)
+     * print(vmath.clamp(v3, 0, 20)) -> vmath.vector4(20, 0, 20, 1)
+     *
+     * local min_v = vmath.vector4(0, -10, -10, 1)
+     * print(vmath.clamp(v3, min_v, 20)) -> vmath.vector4(20, -10, 20, 1)
+     * ```
+     */
     function clamp(value: number | Vector3 | Vector4, min: number | Vector3 | Vector4, max: number | Vector3 | Vector4): number | Vector3 | Vector4;
+    /**
+     * 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 of which to calculate the conjugate
+     * @returns the conjugate
+     * @example
+     * ```lua
+     * local quat = vmath.quat(1, 2, 3, 4)
+     * print(vmath.conj(quat)) --> vmath.quat(-1, -2, -3, 4)
+     * ```
+     */
     function conj(q1: Quaternion): Quaternion;
+    /**
+     * 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 - first vector
+     * @param v2 - second vector
+     * @returns a new vector representing the cross product
+     * @example
+     * ```lua
+     * 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)
+     * ```
+     */
     function cross(v1: Vector3, v2: Vector3): Vector3;
+    /**
+     * 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 - first vector
+     * @param v2 - second vector
+     * @returns dot product
+     * @example
+     * ```lua
+     * if vmath.dot(vector1, vector2) == 0 then
+     *     -- The two vectors are perpendicular (at right-angles to each other)
+     *     ...
+     * end
+     * ```
+     */
     function dot(v1: Vector3 | Vector4, v2: Vector3 | Vector4): number;
+    /**
+     * 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.
+     *
+     * @param x - rotation around x-axis in degrees or vector3 with euler angles in degrees
+     * @param y - rotation around y-axis in degrees
+     * @param z - rotation around z-axis in degrees
+     * @returns quaternion describing an equivalent rotation (231 (YZX) rotation sequence)
+     * @example
+     * ```lua
+     * local q = vmath.euler_to_quat(0, 45, 90)
+     * print(q) --> vmath.quat(0.27059805393219, 0.27059805393219, 0.65328145027161, 0.65328145027161)
+     *
+     * local v = vmath.vector3(0, 0, 90)
+     * print(vmath.euler_to_quat(v)) --> vmath.quat(0, 0, 0.70710676908493, 0.70710676908493)
+     * ```
+     */
     function euler_to_quat(x: number | Vector3, y: number, z: number): Quaternion;
+    /**
+     * 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 - matrix to invert
+     * @returns inverse of the supplied matrix
+     * @example
+     * ```lua
+     * 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)
+     * ```
+     */
     function inv(m1: Matrix4): Matrix4;
+    /**
+     * 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 - value of which to calculate the length
+     * @returns length
+     * @example
+     * ```lua
+     * 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
+     * ```
+     */
     function length(v: Vector3 | Vector4 | Quaternion): number;
+    /**
+     * Returns the squared length of the supplied vector or quaternion.
+     *
+     * @param v - value of which to calculate the squared length
+     * @returns squared length
+     * @example
+     * ```lua
+     * if vmath.length_sqr(vector1) < vmath.length_sqr(vector2) then
+     *     -- Vector 1 has less magnitude than vector 2
+     *     ...
+     * end
+     * ```
+     */
     function length_sqr(v: Vector3 | Vector4 | Quaternion): number;
+    /**
+     * 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 - interpolation parameter, 0-1
+     * @param v1 - vector to lerp from
+     * @param v2 - vector to lerp to
+     * @returns the lerped vector
+     * @example
+     * ```lua
+     * 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
+     * ```
+     */
     function lerp(t: number, v1: Vector3 | Vector4, v2: Vector3 | Vector4): Vector3 | Vector4;
+    /**
+     * 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 - interpolation parameter, 0-1
+     * @param q1 - quaternion to lerp from
+     * @param q2 - quaternion to lerp to
+     * @returns the lerped quaternion
+     * @example
+     * ```lua
+     * 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
+     * ```
+     */
     function lerp(t: number, q1: Quaternion, q2: Quaternion): Quaternion;
+    /**
+     * 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 - interpolation parameter, 0-1
+     * @param n1 - number to lerp from
+     * @param n2 - number to lerp to
+     * @returns the lerped number
+     * @example
+     * ```lua
+     * 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
+     * ```
+     */
     function lerp(t: number, n1: number, n2: number): number;
+    /**
+     * The resulting identity matrix describes a transform with
+     * no translation or rotation.
+     *
+     * @returns identity matrix
+     * @example
+     * ```lua
+     * 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
+     * ```
+     */
     function matrix4(): Matrix4;
+    /**
+     * 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 - existing matrix
+     * @returns matrix which is a copy of the specified matrix
+     * @example
+     * ```lua
+     * 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
+     * ```
+     */
     function matrix4(m1: Matrix4): Matrix4;
+    /**
+     * The resulting matrix describes a rotation around the axis by the specified angle.
+     *
+     * @param v - axis
+     * @param angle - angle in radians
+     * @returns matrix represented by axis and angle
+     * @example
+     * ```lua
+     * 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)
+     * ```
+     */
     function matrix4_axis_angle(v: Vector3, angle: number): Matrix4;
+    /**
+     * Creates a new matrix constructed from separate
+     * translation vector, roation quaternion and scale vector
+     *
+     * @param translation - translation
+     * @param rotation - rotation
+     * @param scale - scale
+     * @returns new matrix4
+     * @example
+     * ```lua
+     * 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)
+     * ```
+     */
     function matrix4_compose(translation: Vector3 | Vector4, rotation: Quaternion, scale: Vector3): Matrix4;
+    /**
+     * 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 - coordinate for left clipping plane
+     * @param right - coordinate for right clipping plane
+     * @param bottom - coordinate for bottom clipping plane
+     * @param top - coordinate for top clipping plane
+     * @param near - coordinate for near clipping plane
+     * @param far - coordinate for far clipping plane
+     * @returns matrix representing the frustum
+     * @example
+     * ```lua
+     * -- 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)
+     * ```
+     */
     function matrix4_frustum(left: number, right: number, bottom: number, top: number, near: number, far: number): Matrix4;
+    /**
+     * 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 - eye position
+     * @param look_at - look-at position
+     * @param up - up vector
+     * @returns look-at matrix
+     * @example
+     * ```lua
+     * -- 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)
+     * ```
+     */
     function matrix4_look_at(eye: Vector3, look_at: Vector3, up: Vector3): Matrix4;
+    /**
+     * Creates an orthographic projection matrix.
+     * This is useful to construct a projection matrix for a camera or rendering in general.
+     *
+     * @param left - coordinate for left clipping plane
+     * @param right - coordinate for right clipping plane
+     * @param bottom - coordinate for bottom clipping plane
+     * @param top - coordinate for top clipping plane
+     * @param near - coordinate for near clipping plane
+     * @param far - coordinate for far clipping plane
+     * @returns orthographic projection matrix
+     * @example
+     * ```lua
+     * -- 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)
+     * ```
+     */
     function matrix4_orthographic(left: number, right: number, bottom: number, top: number, near: number, far: number): Matrix4;
+    /**
+     * Creates a perspective projection matrix.
+     * This is useful to construct a projection matrix for a camera or rendering in general.
+     *
+     * @param fov - angle of the full vertical field of view in radians
+     * @param aspect - aspect ratio
+     * @param near - coordinate for near clipping plane
+     * @param far - coordinate for far clipping plane
+     * @returns perspective projection matrix
+     * @example
+     * ```lua
+     * -- 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)
+     * ```
+     */
     function matrix4_perspective(fov: number, aspect: number, near: number, far: number): Matrix4;
+    /**
+     * The resulting matrix describes the same rotation as the quaternion, but does not have any translation (also like the quaternion).
+     *
+     * @param q - quaternion to create matrix from
+     * @returns matrix represented by quaternion
+     * @example
+     * ```lua
+     * 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)
+     * ```
+     */
     function matrix4_quat(q: Quaternion): Matrix4;
+    /**
+     * The resulting matrix describes a rotation around the x-axis
+     * by the specified angle.
+     *
+     * @param angle - angle in radians around x-axis
+     * @returns matrix from rotation around x-axis
+     * @example
+     * ```lua
+     * 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)
+     * ```
+     */
     function matrix4_rotation_x(angle: number): Matrix4;
+    /**
+     * The resulting matrix describes a rotation around the y-axis
+     * by the specified angle.
+     *
+     * @param angle - angle in radians around y-axis
+     * @returns matrix from rotation around y-axis
+     * @example
+     * ```lua
+     * 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)
+     * ```
+     */
     function matrix4_rotation_y(angle: number): Matrix4;
+    /**
+     * The resulting matrix describes a rotation around the z-axis
+     * by the specified angle.
+     *
+     * @param angle - angle in radians around z-axis
+     * @returns matrix from rotation around z-axis
+     * @example
+     * ```lua
+     * 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)
+     * ```
+     */
     function matrix4_rotation_z(angle: number): Matrix4;
+    /**
+     * Creates a new matrix constructed from scale vector
+     *
+     * @param scale - scale
+     * @returns new matrix4
+     * @example
+     * ```lua
+     * 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)
+     * ```
+     */
     function matrix4_scale(scale: Vector3): Matrix4;
+    /**
+     * creates a new matrix4 from uniform scale
+     *
+     * @param scale - scale
+     * @returns new matrix4
+     * @example
+     * ```lua
+     * 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)
+     * ```
+     */
     function matrix4_scale(scale: number): Matrix4;
+    /**
+     * Creates a new matrix4 from three scale components
+     *
+     * @param scale_x - scale along X axis
+     * @param scale_y - sclae along Y axis
+     * @param scale_z - scale along Z asis
+     * @returns new matrix4
+     * @example
+     * ```lua
+     * 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)
+     * ```
+     */
     function matrix4_scale(scale_x: number, scale_y: number, scale_z: number): Matrix4;
+    /**
+     * The resulting matrix describes a translation of a point
+     * in euclidean space.
+     *
+     * @param position - position vector to create matrix from
+     * @returns matrix from the supplied position vector
+     * @example
+     * ```lua
+     * -- 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)
+     * ```
+     */
     function matrix4_translation(position: Vector3 | Vector4): Matrix4;
+    /**
+     * 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 - first vector
+     * @param v2 - second vector
+     * @returns multiplied vector
+     * @example
+     * ```lua
+     * local blend_color = vmath.mul_per_elem(color1, color2)
+     * ```
+     */
     function mul_per_elem(v1: Vector3 | Vector4, v2: Vector3 | Vector4): Vector3 | 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.
+     *
+     * @param v1 - vector to normalize
+     * @returns new normalized vector
+     * @example
+     * ```lua
+     * 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
+     * ```
+     */
     function normalize(v1: Vector3 | Vector4 | Quaternion): Vector3 | Vector4 | Quaternion;
+    /**
+     * 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 - ortho-normalized matrix to invert
+     * @returns inverse of the supplied matrix
+     * @example
+     * ```lua
+     * 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)
+     * ```
+     */
     function ortho_inv(m1: Matrix4): Matrix4;
+    /**
+     * Calculates the extent the projection of the first vector onto the second.
+     * The returned value is a scalar p defined as:
+     * `p = |P| cos &#x03B8; / |Q|`
+     * where &#x03B8; is the angle between the vectors P and Q.
+     *
+     * @param v1 - vector to be projected on the second
+     * @param 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
+     * @example
+     * ```lua
+     * local v1 = vmath.vector3(1, 1, 0)
+     * local v2 = vmath.vector3(2, 0, 0)
+     * print(vmath.project(v1, v2)) --> 0.5
+     * ```
+     */
     function project(v1: Vector3, v2: Vector3): number;
+    /**
+     * Creates a new identity quaternion. The identity
+     * quaternion is equal to:
+     * `vmath.quat(0, 0, 0, 1)`
+     *
+     * @returns new identity quaternion
+     * @example
+     * ```lua
+     * local quat = vmath.quat()
+     * print(quat) --> vmath.quat(0, 0, 0, 1)
+     * print(quat.w) --> 1
+     * ```
+     */
     function quat(): Quaternion;
+    /**
+     * 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 - existing quaternion
+     * @returns new quaternion
+     * @example
+     * ```lua
+     * 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
+     * ```
+     */
     function quat(q1: Quaternion): Quaternion;
+    /**
+     * Creates a new quaternion with the components set
+     * according to the supplied parameter values.
+     *
+     * @param x - x coordinate
+     * @param y - y coordinate
+     * @param z - z coordinate
+     * @param w - w coordinate
+     * @returns new quaternion
+     * @example
+     * ```lua
+     * local quat = vmath.quat(1, 2, 3, 4)
+     * print(quat) --> vmath.quat(1, 2, 3, 4)
+     * ```
+     */
     function quat(x: number, y: number, z: number, w: number): Quaternion;
+    /**
+     * The resulting quaternion describes a rotation of `angle`
+     * radians around the axis described by the unit vector `v`.
+     *
+     * @param v - axis
+     * @param angle - angle
+     * @returns quaternion representing the axis-angle rotation
+     * @example
+     * ```lua
+     * 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)
+     * ```
+     */
     function quat_axis_angle(v: Vector3, angle: number): Quaternion;
+    /**
+     * 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 - x base vector
+     * @param y - y base vector
+     * @param z - z base vector
+     * @returns quaternion representing the rotation of the specified base vectors
+     * @example
+     * ```lua
+     * -- 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
+     * ```
+     */
     function quat_basis(x: Vector3, y: Vector3, z: Vector3): Quaternion;
+    /**
+     * 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 - first unit vector, before rotation
+     * @param v2 - second unit vector, after rotation
+     * @returns quaternion representing the rotation from first to second vector
+     * @example
+     * ```lua
+     * 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)
+     * ```
+     */
     function quat_from_to(v1: Vector3, v2: Vector3): Quaternion;
+    /**
+     * Creates a new quaternion with the components set
+     * according to the supplied parameter values.
+     *
+     * @param matrix - source matrix4
+     * @returns new quaternion
+     */
     function quat_matrix4(matrix: Matrix4): Quaternion;
+    /**
+     * The resulting quaternion describes a rotation of `angle`
+     * radians around the x-axis.
+     *
+     * @param angle - angle in radians around x-axis
+     * @returns quaternion representing the rotation around the x-axis
+     * @example
+     * ```lua
+     * 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)
+     * ```
+     */
     function quat_rotation_x(angle: number): Quaternion;
+    /**
+     * The resulting quaternion describes a rotation of `angle`
+     * radians around the y-axis.
+     *
+     * @param angle - angle in radians around y-axis
+     * @returns quaternion representing the rotation around the y-axis
+     * @example
+     * ```lua
+     * 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)
+     * ```
+     */
     function quat_rotation_y(angle: number): Quaternion;
+    /**
+     * The resulting quaternion describes a rotation of `angle`
+     * radians around the z-axis.
+     *
+     * @param angle - angle in radians around z-axis
+     * @returns quaternion representing the rotation around the z-axis
+     * @example
+     * ```lua
+     * 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)
+     * ```
+     */
     function quat_rotation_z(angle: number): Quaternion;
+    /**
+     * 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
+     *
+     * @param q - source quaternion
+     * @example
+     * ```lua
+     * local q = vmath.quat_rotation_z(math.rad(90))
+     * print(vmath.quat_to_euler(q)) --> 0 0 90
+     *
+     * local q2 = vmath.quat_rotation_y(math.rad(45)) * vmath.quat_rotation_z(math.rad(90))
+     * local v = vmath.vector3(vmath.quat_to_euler(q2))
+     * print(v) --> vmath.vector3(0, 45, 90)
+     * ```
+     */
     function quat_to_euler(q: Quaternion): LuaMultiReturn<[number, number, number]>;
+    /**
+     * Returns a new vector from the supplied vector that is
+     * rotated by the rotation described by the supplied
+     * quaternion.
+     *
+     * @param q - quaternion
+     * @param v1 - vector to rotate
+     * @returns the rotated vector
+     * @example
+     * ```lua
+     * 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)
+     * ```
+     */
     function rotate(q: Quaternion, v1: Vector3): Vector3;
+    /**
+     * 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 - interpolation parameter, 0-1
+     * @param v1 - vector to slerp from
+     * @param v2 - vector to slerp to
+     * @returns the slerped vector
+     * @example
+     * ```lua
+     * 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
+     * ```
+     */
     function slerp(t: number, v1: Vector3 | Vector4, v2: Vector3 | Vector4): Vector3 | Vector4;
+    /**
+     * 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 - interpolation parameter, 0-1
+     * @param q1 - quaternion to slerp from
+     * @param q2 - quaternion to slerp to
+     * @returns the slerped quaternion
+     * @example
+     * ```lua
+     * 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
+     * ```
+     */
     function slerp(t: number, q1: Quaternion, q2: Quaternion): Quaternion;
+    /**
+     * 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 of numbers
+     * @returns new vector
+     * @example
+     * ```lua
+     * 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
+     * ```
+     */
     function vector(t: number[]): Vector;
+    /**
+     * Creates a new zero vector with all components set to 0.
+     *
+     * @returns new zero vector
+     * @example
+     * ```lua
+     * local vec = vmath.vector3()
+     * pprint(vec) --> vmath.vector3(0, 0, 0)
+     * print(vec.x) --> 0
+     * ```
+     */
     function vector3(): Vector3;
+    /**
+     * Creates a new vector with all components set to the
+     * supplied scalar value.
+     *
+     * @param n - scalar value to splat
+     * @returns new vector
+     * @example
+     * ```lua
+     * local vec = vmath.vector3(1.0)
+     * print(vec) --> vmath.vector3(1, 1, 1)
+     * print(vec.x) --> 1
+     * ```
+     */
     function vector3(n: number): Vector3;
+    /**
+     * 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 - existing vector
+     * @returns new vector
+     * @example
+     * ```lua
+     * 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
+     * ```
+     */
     function vector3(v1: Vector3): Vector3;
+    /**
+     * Creates a new vector with the components set to the
+     * supplied values.
+     *
+     * @param x - x coordinate
+     * @param y - y coordinate
+     * @param z - z coordinate
+     * @returns new vector
+     * @example
+     * ```lua
+     * 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)
+     * ```
+     */
     function vector3(x: number, y: number, z: number): Vector3;
+    /**
+     * Creates a new zero vector with all components set to 0.
+     *
+     * @returns new zero vector
+     * @example
+     * ```lua
+     * local vec = vmath.vector4()
+     * print(vec) --> vmath.vector4(0, 0, 0, 0)
+     * print(vec.w) --> 0
+     * ```
+     */
     function vector4(): Vector4;
+    /**
+     * Creates a new vector with all components set to the
+     * supplied scalar value.
+     *
+     * @param n - scalar value to splat
+     * @returns new vector
+     * @example
+     * ```lua
+     * local vec = vmath.vector4(1.0)
+     * print(vec) --> vmath.vector4(1, 1, 1, 1)
+     * print(vec.w) --> 1
+     * ```
+     */
     function vector4(n: number): Vector4;
+    /**
+     * 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 - existing vector
+     * @returns new vector
+     * @example
+     * ```lua
+     * 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
+     * ```
+     */
     function vector4(v1: Vector4): Vector4;
+    /**
+     * Creates a new vector with the components set to the
+     * supplied values.
+     *
+     * @param x - x coordinate
+     * @param y - y coordinate
+     * @param z - z coordinate
+     * @param w - w coordinate
+     * @returns new vector
+     * @example
+     * ```lua
+     * 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)
+     * ```
+     */
     function vector4(x: number, y: number, z: number, w: number): Vector4;
   }
 }