diff options
Diffstat (limited to 'meta/3rd/lovr/library/lovr.math.lua')
| -rw-r--r-- | meta/3rd/lovr/library/lovr.math.lua | 341 |
1 files changed, 309 insertions, 32 deletions
diff --git a/meta/3rd/lovr/library/lovr.math.lua b/meta/3rd/lovr/library/lovr.math.lua index 9c47ec48..7cf348c6 100644 --- a/meta/3rd/lovr/library/lovr.math.lua +++ b/meta/3rd/lovr/library/lovr.math.lua @@ -46,7 +46,9 @@ function lovr.math.getRandomSeed() end function lovr.math.linearToGamma(lr, lg, lb) end --- ----Creates a temporary 4D matrix. This function takes the same arguments as `Mat4:set`. +---Creates a temporary 4D matrix. +--- +---This function takes the same arguments as `Mat4:set`. --- function lovr.math.mat4() end @@ -62,12 +64,16 @@ function lovr.math.mat4() end function lovr.math.newCurve(x, y, z) end --- ----Creates a new 4D matrix. This function takes the same arguments as `Mat4:set`. +---Creates a new 4D matrix. +--- +---This function takes the same arguments as `Mat4:set`. --- function lovr.math.newMat4() end --- ----Creates a new quaternion. This function takes the same arguments as `Quat:set`. +---Creates a new quaternion. +--- +---This function takes the same arguments as `Quat:set`. --- function lovr.math.newQuat() end @@ -80,22 +86,30 @@ function lovr.math.newQuat() end function lovr.math.newRandomGenerator() end --- ----Creates a new 2D vector. This function takes the same arguments as `Vec2:set`. +---Creates a new 2D vector. +--- +---This function takes the same arguments as `Vec2:set`. --- function lovr.math.newVec2() end --- ----Creates a new 3D vector. This function takes the same arguments as `Vec3:set`. +---Creates a new 3D vector. +--- +---This function takes the same arguments as `Vec3:set`. --- function lovr.math.newVec3() end --- ----Creates a new 4D vector. This function takes the same arguments as `Vec4:set`. +---Creates a new 4D vector. +--- +---This function takes the same arguments as `Vec4:set`. --- function lovr.math.newVec4() end --- ----Returns a 1D, 2D, 3D, or 4D perlin noise value. The number will be between 0 and 1, and it will always be 0.5 when the inputs are integers. +---Returns a 1D, 2D, 3D, or 4D perlin noise value. +--- +---The number will be between 0 and 1, and it will always be 0.5 when the inputs are integers. --- ---@overload fun(x: number, y: number):number ---@overload fun(x: number, y: number, z: number):number @@ -105,12 +119,20 @@ function lovr.math.newVec4() end function lovr.math.noise(x) end --- ----Creates a temporary quaternion. This function takes the same arguments as `Quat:set`. +---Creates a temporary quaternion. +--- +---This function takes the same arguments as `Quat:set`. --- function lovr.math.quat() end --- ----Returns a uniformly distributed pseudo-random number. This function has improved randomness over Lua's `math.random` and also guarantees that the sequence of random numbers will be the same on all platforms (given the same seed). +---Returns a uniformly distributed pseudo-random number. +--- +---This function has improved randomness over Lua's `math.random` and also guarantees that the sequence of random numbers will be the same on all platforms (given the same seed). +--- +--- +---### NOTE: +---You can set the random seed using `lovr.math.setRandomSeed`. --- ---@overload fun(high: number):number ---@overload fun(low: number, high: number):number @@ -118,7 +140,9 @@ function lovr.math.quat() end function lovr.math.random() end --- ----Returns a pseudo-random number from a normal distribution (a bell curve). You can control the center of the bell curve (the mean value) and the overall width (sigma, or standard deviation). +---Returns a pseudo-random number from a normal distribution (a bell curve). +--- +---You can control the center of the bell curve (the mean value) and the overall width (sigma, or standard deviation). --- ---@param sigma? number # The standard deviation of the distribution. This can be thought of how "wide" the range of numbers is or how much variability there is. ---@param mu? number # The average value returned. @@ -126,30 +150,44 @@ function lovr.math.random() end function lovr.math.randomNormal(sigma, mu) end --- ----Seed the random generator with a new seed. Each seed will cause `lovr.math.random` and `lovr.math.randomNormal` to produce a unique sequence of random numbers. This is done once automatically at startup by `lovr.run`. +---Seed the random generator with a new seed. +--- +---Each seed will cause `lovr.math.random` and `lovr.math.randomNormal` to produce a unique sequence of random numbers. +--- +---This is done once automatically at startup by `lovr.run`. --- ---@param seed number # The new seed. function lovr.math.setRandomSeed(seed) end --- ----Creates a temporary 2D vector. This function takes the same arguments as `Vec2:set`. +---Creates a temporary 2D vector. +--- +---This function takes the same arguments as `Vec2:set`. --- function lovr.math.vec2() end --- ----Creates a temporary 3D vector. This function takes the same arguments as `Vec3:set`. +---Creates a temporary 3D vector. +--- +---This function takes the same arguments as `Vec3:set`. --- function lovr.math.vec3() end --- ----Creates a temporary 4D vector. This function takes the same arguments as `Vec4:set`. +---Creates a temporary 4D vector. +--- +---This function takes the same arguments as `Vec4:set`. --- function lovr.math.vec4() end --- ----A Curve is an object that represents a Bézier curve in three dimensions. Curves are defined by an arbitrary number of control points (note that the curve only passes through the first and last control point). +---A Curve is an object that represents a Bézier curve in three dimensions. --- ----Once a Curve is created with `lovr.math.newCurve`, you can use `Curve:evaluate` to get a point on the curve or `Curve:render` to get a list of all of the points on the curve. These points can be passed directly to `lovr.graphics.points` or `lovr.graphics.line` to render the curve. +---Curves are defined by an arbitrary number of control points (note that the curve only passes through the first and last control point). +--- +---Once a Curve is created with `lovr.math.newCurve`, you can use `Curve:evaluate` to get a point on the curve or `Curve:render` to get a list of all of the points on the curve. +--- +---These points can be passed directly to `lovr.graphics.points` or `lovr.graphics.line` to render the curve. --- ---Note that for longer or more complicated curves (like in a drawing application) it can be easier to store the path as several Curve objects. --- @@ -159,6 +197,10 @@ local Curve = {} --- ---Inserts a new control point into the Curve at the specified index. --- +--- +---### NOTE: +---An error will be thrown if the index is less than one or more than the number of control points. +--- ---@param x number # The x coordinate of the control point. ---@param y number # The y coordinate of the control point. ---@param z number # The z coordinate of the control point. @@ -166,7 +208,13 @@ local Curve = {} function Curve:addPoint(x, y, z, index) end --- ----Returns a point on the Curve given a parameter `t` from 0 to 1. 0 will return the first control point, 1 will return the last point, .5 will return a point in the "middle" of the Curve, etc. +---Returns a point on the Curve given a parameter `t` from 0 to 1. +--- +---0 will return the first control point, 1 will return the last point, .5 will return a point in the "middle" of the Curve, etc. +--- +--- +---### NOTE: +---An error will be thrown if `t` is not between 0 and 1, or if the Curve has less than two points. --- ---@param t number # The parameter to evaluate the Curve at. ---@return number x # The x position of the point. @@ -177,6 +225,10 @@ function Curve:evaluate(t) end --- ---Returns a control point of the Curve. --- +--- +---### NOTE: +---An error will be thrown if the index is less than one or more than the number of control points. +--- ---@param index number # The index to retrieve. ---@return number x # The x coordinate of the control point. ---@return number y # The y coordinate of the control point. @@ -190,7 +242,13 @@ function Curve:getPoint(index) end function Curve:getPointCount() end --- ----Returns a direction vector for the Curve given a parameter `t` from 0 to 1. 0 will return the direction at the first control point, 1 will return the direction at the last point, .5 will return the direction at the "middle" of the Curve, etc. +---Returns a direction vector for the Curve given a parameter `t` from 0 to 1. +--- +---0 will return the direction at the first control point, 1 will return the direction at the last point, .5 will return the direction at the "middle" of the Curve, etc. +--- +--- +---### NOTE: +---The direction vector returned by this function will have a length of one. --- ---@param t number # Where on the Curve to compute the direction. ---@return number x # The x position of the point. @@ -201,11 +259,21 @@ function Curve:getTangent(t) end --- ---Removes a control point from the Curve. --- +--- +---### NOTE: +---An error will be thrown if the index is less than one or more than the number of control points. +--- ---@param index number # The index of the control point to remove. function Curve:removePoint(index) end --- ----Returns a list of points on the Curve. The number of points can be specified to get a more or less detailed representation, and it is also possible to render a subsection of the Curve. +---Returns a list of points on the Curve. +--- +---The number of points can be specified to get a more or less detailed representation, and it is also possible to render a subsection of the Curve. +--- +--- +---### NOTE: +---This function will always return 2 points if the Curve is a line with only 2 control points. --- ---@param n? number # The number of points to use. ---@param t1? number # How far along the curve to start rendering. @@ -216,6 +284,10 @@ function Curve:render(n, t1, t2) end --- ---Changes the position of a control point on the Curve. --- +--- +---### NOTE: +---An error will be thrown if the index is less than one or more than the number of control points. +--- ---@param index number # The index to modify. ---@param x number # The new x coordinate. ---@param y number # The new y coordinate. @@ -225,6 +297,12 @@ function Curve:setPoint(index, x, y, z) end --- ---Returns a new Curve created by slicing the Curve at the specified start and end points. --- +--- +---### NOTE: +---The new Curve will have the same number of control points as the existing curve. +--- +---An error will be thrown if t1 or t2 are not between 0 and 1, or if the Curve has less than two points. +--- ---@param t1 number # The starting point to slice at. ---@param t2 number # The ending point to slice at. ---@return lovr.Curve curve # A new Curve. @@ -276,7 +354,15 @@ function Mat4:invert() end function Mat4:lookAt(from, to, up) end --- ----Multiplies this matrix by another value. Multiplying by a matrix combines their two transforms together. Multiplying by a vector applies the transformation from the matrix to the vector and returns the vector. +---Multiplies this matrix by another value. +--- +---Multiplying by a matrix combines their two transforms together. +--- +---Multiplying by a vector applies the transformation from the matrix to the vector and returns the vector. +--- +--- +---### NOTE: +---When multiplying by a vec4, the vector is treated as either a point if its w component is 1, or a direction vector if the w is 0 (the matrix translation won't be applied). --- ---@overload fun(self: lovr.Mat4, v3: lovr.Vec3):lovr.Vec3 ---@overload fun(self: lovr.Mat4, v4: lovr.Vec4):lovr.Vec4 @@ -377,7 +463,11 @@ function Mat4:unpack(raw) end local Quat = {} --- ----Conjugates the input quaternion in place, returning the input. If the quaternion is normalized, this is the same as inverting it. It negates the (x, y, z) components of the quaternion. +---Conjugates the input quaternion in place, returning the input. +--- +---If the quaternion is normalized, this is the same as inverting it. +--- +---It negates the (x, y, z) components of the quaternion. --- ---@return lovr.Quat q # The original quaternion. function Quat:conjugate() end @@ -395,7 +485,11 @@ function Quat:direction() end function Quat:length() end --- ----Multiplies this quaternion by another value. If the value is a quaternion, the rotations in the two quaternions are applied sequentially and the result is stored in the first quaternion. If the value is a vector, then the input vector is rotated by the quaternion and returned. +---Multiplies this quaternion by another value. +--- +---If the value is a quaternion, the rotations in the two quaternions are applied sequentially and the result is stored in the first quaternion. +--- +---If the value is a vector, then the input vector is rotated by the quaternion and returned. --- ---@overload fun(self: lovr.Quat, v3: lovr.vec3):lovr.vec3 ---@param r lovr.quat # A quaternion to combine with the original. @@ -405,11 +499,19 @@ function Quat:mul(r) end --- ---Adjusts the values in the quaternion so that its length becomes 1. --- +--- +---### NOTE: +---A common source of bugs with quaternions is to forget to normalize them after performing a series of operations on them. +--- +---Try normalizing a quaternion if some of the calculations aren't working quite right! +--- ---@return lovr.Quat q # The original quaternion. function Quat:normalize() end --- ----Sets the components of the quaternion. There are lots of different ways to specify the new components, the summary is: +---Sets the components of the quaternion. +--- +---There are lots of different ways to specify the new components, the summary is: --- ---- Four numbers can be used to specify an angle/axis rotation, similar to other LÖVR functions. ---- Four numbers plus the fifth `raw` flag can be used to set the raw values of the quaternion. @@ -436,7 +538,11 @@ function Quat:set(angle, ax, ay, az, raw) end --- ---Performs a spherical linear interpolation between this quaternion and another one, which can be used for smoothly animating between two rotations. --- ----The amount of interpolation is controlled by a parameter `t`. A `t` value of zero leaves the original quaternion unchanged, whereas a `t` of one sets the original quaternion exactly equal to the target. A value between `0` and `1` returns a rotation between the two based on the value. +---The amount of interpolation is controlled by a parameter `t`. +--- +---A `t` value of zero leaves the original quaternion unchanged, whereas a `t` of one sets the original quaternion exactly equal to the target. +--- +---A value between `0` and `1` returns a rotation between the two based on the value. --- ---@param r lovr.Quat # The quaternion to slerp towards. ---@param t number # The lerping parameter. @@ -462,12 +568,22 @@ local RandomGenerator = {} --- ---Returns the seed used to initialize the RandomGenerator. --- +--- +---### NOTE: +---Since the seed is a 64 bit integer, each 32 bits of the seed are returned separately to avoid precision issues. +--- ---@return number low # The lower 32 bits of the seed. ---@return number high # The upper 32 bits of the seed. function RandomGenerator:getSeed() end --- ----Returns the current state of the RandomGenerator. This can be used with `RandomGenerator:setState` to reliably restore a previous state of the generator. +---Returns the current state of the RandomGenerator. +--- +---This can be used with `RandomGenerator:setState` to reliably restore a previous state of the generator. +--- +--- +---### NOTE: +---The seed represents the starting state of the RandomGenerator, whereas the state represents the current state of the generator. --- ---@return string state # The serialized state. function RandomGenerator:getState() end @@ -481,7 +597,9 @@ function RandomGenerator:getState() end function RandomGenerator:random() end --- ----Returns a pseudo-random number from a normal distribution (a bell curve). You can control the center of the bell curve (the mean value) and the overall width (sigma, or standard deviation). +---Returns a pseudo-random number from a normal distribution (a bell curve). +--- +---You can control the center of the bell curve (the mean value) and the overall width (sigma, or standard deviation). --- ---@param sigma? number # The standard deviation of the distribution. This can be thought of how "wide" the range of numbers is or how much variability there is. ---@param mu? number # The average value returned. @@ -489,7 +607,13 @@ function RandomGenerator:random() end function RandomGenerator:randomNormal(sigma, mu) end --- ----Seed the RandomGenerator with a new seed. Each seed will cause the RandomGenerator to produce a unique sequence of random numbers. +---Seed the RandomGenerator with a new seed. +--- +---Each seed will cause the RandomGenerator to produce a unique sequence of random numbers. +--- +--- +---### NOTE: +---For precise 64 bit seeds, you should specify the lower and upper 32 bits of the seed separately. Otherwise, seeds larger than 2^53 will start to lose precision. --- ---@overload fun(self: lovr.RandomGenerator, low: number, high: number) ---@param seed number # The random seed. @@ -498,6 +622,10 @@ function RandomGenerator:setSeed(seed) end --- ---Sets the state of the RandomGenerator, as previously obtained using `RandomGenerator:getState`. This can be used to reliably restore a previous state of the generator. --- +--- +---### NOTE: +---The seed represents the starting state of the RandomGenerator, whereas the state represents the current state of the generator. +--- ---@param state string # The serialized state. function RandomGenerator:setState(state) end @@ -534,6 +662,14 @@ function Vec2:div(u) end --- ---Returns the dot product between this vector and another one. --- +--- +---### NOTE: +---This is computed as: +--- +--- dot = v.x * u.x + v.y * u.y +--- +---The vectors are not normalized before computing the dot product. +--- ---@overload fun(self: lovr.Vec2, x: number, y: number):number ---@param u lovr.Vec2 # The vector to compute the dot product with. ---@return number dot # The dot product between `v` and `u`. @@ -542,11 +678,19 @@ function Vec2:dot(u) end --- ---Returns the length of the vector. --- +--- +---### NOTE: +---The length is equivalent to this: +--- +--- math.sqrt(v.x * v.x + v.y * v.y) +--- ---@return number length # The length of the vector. function Vec2:length() end --- ----Performs a linear interpolation between this vector and another one, which can be used to smoothly animate between two vectors, based on a parameter value. A parameter value of `0` will leave the vector unchanged, a parameter value of `1` will set the vector to be equal to the input vector, and a value of `.5` will set the components to be halfway between the two vectors. +---Performs a linear interpolation between this vector and another one, which can be used to smoothly animate between two vectors, based on a parameter value. +--- +---A parameter value of `0` will leave the vector unchanged, a parameter value of `1` will set the vector to be equal to the input vector, and a value of `.5` will set the components to be halfway between the two vectors. --- ---@overload fun(self: lovr.Vec2, x: number, y: number):lovr.Vec2 ---@return lovr.Vec2 v # The original vector, containing the new lerped values. @@ -605,7 +749,13 @@ local Vec3 = {} function Vec3:add(u) end --- ----Sets this vector to be equal to the cross product between this vector and another one. The new `v` will be perpendicular to both the old `v` and `u`. +---Sets this vector to be equal to the cross product between this vector and another one. +--- +---The new `v` will be perpendicular to both the old `v` and `u`. +--- +--- +---### NOTE: +---The vectors are not normalized before or after computing the cross product. --- ---@overload fun(self: lovr.Vec3, x: number, y: number, z: number):lovr.Vec3 ---@param u lovr.Vec3 # The vector to compute the cross product with. @@ -631,6 +781,14 @@ function Vec3:div(u) end --- ---Returns the dot product between this vector and another one. --- +--- +---### NOTE: +---This is computed as: +--- +--- dot = v.x * u.x + v.y * u.y + v.z * u.z +--- +---The vectors are not normalized before computing the dot product. +--- ---@overload fun(self: lovr.Vec3, x: number, y: number, z: number):number ---@param u lovr.Vec3 # The vector to compute the dot product with. ---@return number dot # The dot product between `v` and `u`. @@ -639,11 +797,19 @@ function Vec3:dot(u) end --- ---Returns the length of the vector. --- +--- +---### NOTE: +---The length is equivalent to this: +--- +--- math.sqrt(v.x * v.x + v.y * v.y + v.z * v.z) +--- ---@return number length # The length of the vector. function Vec3:length() end --- ----Performs a linear interpolation between this vector and another one, which can be used to smoothly animate between two vectors, based on a parameter value. A parameter value of `0` will leave the vector unchanged, a parameter value of `1` will set the vector to be equal to the input vector, and a value of `.5` will set the components to be halfway between the two vectors. +---Performs a linear interpolation between this vector and another one, which can be used to smoothly animate between two vectors, based on a parameter value. +--- +---A parameter value of `0` will leave the vector unchanged, a parameter value of `1` will set the vector to be equal to the input vector, and a value of `.5` will set the components to be halfway between the two vectors. --- ---@overload fun(self: lovr.Vec3, x: number, y: number, z: number, t: number):lovr.Vec3 ---@param u lovr.Vec3 # The vector to lerp towards. @@ -725,6 +891,14 @@ function Vec4:div(u) end --- ---Returns the dot product between this vector and another one. --- +--- +---### NOTE: +---This is computed as: +--- +--- dot = v.x * u.x + v.y * u.y + v.z * u.z + v.w * u.w +--- +---The vectors are not normalized before computing the dot product. +--- ---@overload fun(self: lovr.Vec4, x: number, y: number, z: number, w: number):number ---@param u lovr.Vec4 # The vector to compute the dot product with. ---@return number dot # The dot product between `v` and `u`. @@ -733,11 +907,19 @@ function Vec4:dot(u) end --- ---Returns the length of the vector. --- +--- +---### NOTE: +---The length is equivalent to this: +--- +--- math.sqrt(v.x * v.x + v.y * v.y * v.z + v.z + v.w * v.w) +--- ---@return number length # The length of the vector. function Vec4:length() end --- ----Performs a linear interpolation between this vector and another one, which can be used to smoothly animate between two vectors, based on a parameter value. A parameter value of `0` will leave the vector unchanged, a parameter value of `1` will set the vector to be equal to the input vector, and a value of `.5` will set the components to be halfway between the two vectors. +---Performs a linear interpolation between this vector and another one, which can be used to smoothly animate between two vectors, based on a parameter value. +--- +---A parameter value of `0` will leave the vector unchanged, a parameter value of `1` will set the vector to be equal to the input vector, and a value of `.5` will set the components to be halfway between the two vectors. --- ---@overload fun(self: lovr.Vec4, x: number, y: number, z: number, w: number, t: number):lovr.Vec4 ---@param u lovr.Vec4 # The vector to lerp towards. @@ -788,7 +970,102 @@ function Vec4:sub(u) end function Vec4:unpack() end --- ----LÖVR has math objects for vectors, matrices, and quaternions, collectively called "vector objects". Vectors are useful because they can represent a multidimensional quantity (like a 3D position) using just a single value. +---LÖVR has math objects for vectors, matrices, and quaternions, collectively called "vector objects". +--- +---Vectors are useful because they can represent a multidimensional quantity (like a 3D position) using just a single value. +--- +--- +---### NOTE: +---Most LÖVR functions that accept positions, orientations, transforms, velocities, etc. also accept vector objects, so they can be used interchangeably with numbers: +--- +--- function lovr.draw() +--- -- position and size are vec3's, rotation is a quat +--- lovr.graphics.box('fill', position, size, rotation) +--- end +--- +---### Temporary vs. Permanent +--- +---Vectors can be created in two different ways: **permanent** and **temporary**. +--- +---**Permanent** vectors behave like normal Lua values. +--- +---They are individual objects that are garbage collected when no longer needed. +--- +---They're created using the usual `lovr.math.new<Type>` syntax: +--- +--- self.position = lovr.math.newVec3(x, y, z) +--- +---**Temporary** vectors are created from a shared pool of vector objects. +--- +---This makes them faster because they use temporary memory and do not need to be garbage collected. +--- +---To make a temporary vector, leave off the `new` prefix: +--- +--- local position = lovr.math.vec3(x, y, z) +--- +---As a further shorthand, these vector constructors are placed on the global scope. +--- +---If you prefer to keep the global scope clean, this can be configured using the `t.math.globals` flag in `lovr.conf`. +--- +--- local position = vec3(x1, y1, z1) + vec3(x2, y2, z2) +--- +---Temporary vectors, with all their speed, come with an important restriction: they can only be used during the frame in which they were created. +--- +---Saving them into variables and using them later on will throw an error: +--- +--- local position = vec3(1, 2, 3) +--- +--- function lovr.update(dt) +--- -- Reusing a temporary vector across frames will error: +--- position:add(vec3(dt)) +--- end +--- +---It's possible to overflow the temporary vector pool. +--- +---If that happens, `lovr.math.drain` can be used to periodically drain the pool, invalidating any existing temporary vectors. +--- +---### Metamethods +--- +---Vectors have metamethods, allowing them to be used using the normal math operators like `+`, `-`, `*`, `/`, etc. +--- +--- print(vec3(2, 4, 6) * .5 + vec3(10, 20, 30)) +--- +---These metamethods will create new temporary vectors. +--- +---### Components and Swizzles +--- +---The raw components of a vector can be accessed like normal fields: +--- +--- print(vec3(1, 2, 3).z) --> 3 +--- print(mat4()[16]) --> 1 +--- +---Also, multiple fields can be accessed and combined into a new (temporary) vector, called swizzling: +--- +--- local position = vec3(10, 5, 1) +--- print(position.xy) --> vec2(10, 5) +--- print(position.xyy) --> vec3(10, 5, 5) +--- print(position.zyxz) --> vec4(1, 5, 10, 1) +--- +---The following fields are supported for vectors: +--- +---- `x`, `y`, `z`, `w` +---- `r`, `g`, `b`, `a` +---- `s`, `t`, `p`, `q` +--- +---Quaternions support `x`, `y`, `z`, and `w`. +--- +---Matrices use numbers for accessing individual components in "column-major" order. +--- +---All fields can also be assigned to. +--- +--- -- Swap the components of a 2D vector +--- v.xy = v.yx +--- +---The `unpack` function can be used (on any vector type) to access all of the individual components of a vector object. +--- +---For quaternions you can choose whether you want to unpack the angle/axis representation or the raw quaternion components. +--- +---Similarly, matrices support raw unpacking as well as decomposition into translation/scale/rotation values. --- ---@class lovr.Vectors local Vectors = {} |