MoonGLMATH Reference Manual

v = vec2(…​)
v = vec3(…​)
v = vec4(…​)
v = vec2r(…​)
v = vec3r(…​)
v = vec4r(…​)
Create a vector. The vecN function creates a column vector of size N (where N may be 2, 3 or 4), whereas the vecNr function creates a row vector of the same size. Values to initialize the vector elements may be optionally passed as a list of numbers, or as a previously created vector (exceeding values are discarded, while missing values are replaced with zeros).

t = tovec2(t)
t = tovec3(t)
t = tovec4(t)
t = tovec2r(t)
t = tovec3r(t)
t = tovec4r(t)
Turn an appropriately sized table into a vector, by adding the relevant meta information to it.

boolean = isvec2(v)
boolean = isvec3(v)
boolean = isvec4(v)
boolean = isvec2r(v)
boolean = isvec3r(v)
boolean = isvec4r(v)
Check if v is a vector of a given type (e.g. isvec2r checks if v is a row vector of size 2).

|v| = norm(v)
|v|² = norm2(v)
v/|v| = normalize(v)
v^T = transpose(v)

v_clamped = clamp(v, v_min, v_max)
Element-wise clamp.

v_mix = mix(v, v₁, k)
Element-wise blend v_mix = (1-k)*v +k*v₁, where k is a number.

v_step = step(v, v_edge)
Element-wise step: v_step=0.0 if v≤v_edge, v_step=1.0 otherwise (element subscripts are omitted for clarity).
The v_edge argument may be a number, meaning a vector with all elements equal to that number.

v_smoothstep = smoothstep(v, v₀, v₁)
Element-wise smoothstep: omitting element subscripts, v_smoothstep is 0.0 if v≤v₀, 1.0 if v≥v₁, and is obtained by smooth Hermite interpolation if v₀<v<v₁ (i.e. v_smoothstep=3t²-2t³, where t=(v-v₀)/(v₁-v₀)). The result is undefined if v₀≥v₁.
The v₀ and v₁ argument may be both be a number, meaning a vector with all elements equal to that number.

v_fade = fade(v, v₀, v₁)
Element-wise improved smoothstep. Same as smoothstep( ), but with the smoother interpolation function v_fade=6t⁵-15t⁴+10t³ (Perlin improved).

Unary minus: v = -v₁.

Addition: v = v₁ + v₂.

Subtraction: v = v₁ - v₂.

Multiplication by a scalar: v = s * v1, and v = v₁ * s, where s is a number.

Division by a scalar: v = v₁ / s, where s is a number.

Dot product: s = v₁ * v₂, where v₁ and v₂ are vectors of the same size (row*column, but row*row and column*column are accepted as well).

Multiplication: m = v₁ * v₂, where v₁ is a column vector and v₂ is a row vector of the same size. The result is a square matrix.

Cross product: v = v₁ % v₂, where v₁ and v₃ are size 3 vectors. Works also on operands of size 2 and 4, adapting them to size 3 (size 2 operands are extended to size 3 by adding a zero element, while size 4 operands are reduced to size 3 by ignoring the 4-th element). The result is always a size 3 vector.

m = mat2(…​)
m = mat3(…​)
m = mat4(…​)
m = mat2x3(…​)
m = mat3x2(…​)
m = mat2x4(…​)
m = mat4x2(…​)
m = mat3x4(…​)
m = mat4x3(…​)
Create a matrix. The matN function creates a square matrix vector size NxN, while the matNxM creates a rectangular matrix of size NxM. Values to initialize the matrix elements may be optionally passed as a list of numbers (to fill the matrix in row-major order), as a list of row vectors (to fill the matrix rows), as a list of column vectors (to fill the matrix columns), or as a matrix (to copy the elements from). In all cases, exceeding values are discarded, while missing values are replaced with zeros. As an exception, the matN function, when invoked without arguments, returns the NxN identity matrix.

t = tomat2(t)
t = tomat3(t)
t = tomat4(t)
t = tomat2x3(t)
t = tomat3x2(t)
t = tomat2x4(t)
t = tomat4x2(t)
t = tomat3x4(t)
t = tomat4x3(t)
Turn an appropriately sized table into a matrix, by adding the relevant meta information to it.

boolean = ismat2(v)
boolean = ismat3(v)
boolean = ismat4(v)
boolean = ismat2x3(v)
boolean = ismat3x2(v)
boolean = ismat2x4(v)
boolean = ismat4x2(v)
boolean = ismat3x4(v)
boolean = ismat4x3(v)
Check if m is a matrix of a given size (e.g. ismat2 checks if m is a 2x2 matrix).

determinant = det(m)
trace = trace(m)
adjoint = adj(m)
m^-1 = inv(m)
Apply only to square matrices. If m is singular, inv(m) returns nil.

m^T = transpose(m)

q = quat(m)

v = m:row(i)
Returns the i-th row as a row vector (vecNr).

v = m:column(i)
Returns the i-th column as a column vector (vecN).

m_clamped = clamp(m, m_min, m_max)
Element-wise clamp.

m_mix = mix(m, m₁, k)
Element-wise blend m_mix = (1-k)*m +k*m₁, where k is a number.

m_step = step(m, m_edge)
Element-wise step: m_step=0.0 if m≤m_edge, m_step=1.0 otherwise (element subscripts are omitted for clarity).
The m_edge argument may be a number, meaning a matrix with all elements equal to that number.

m_smoothstep = smoothstep(m, m₀, m₁)
Element-wise smoothstep: omitting element subscripts, m_smoothstep is 0.0 if m≤m₀, 1.0 if m≥m₁, and is obtained by smooth Hermite interpolation if m₀<m<m₁ (i.e. m_smoothstep=3t²-2t³, where t=(m-m₀)/(m₁-m₀)). The result is undefined if m₀≥m₁.
The m₀ and m₁ argument may be both be a number, meaning a matrix with all elements equal to that number.

m_fade = fade(m, m₀, m₁)
Element-wise improved smoothstep. Same as smoothstep( ), but with the smoother interpolation function m_fade=6t⁵-15t⁴+10t³ (Perlin improved).

Unary minus: m = -m₁.

Addition: m = m₁ + m₂.

Subtraction: m = m₁ - m₂.

Multiplication by a scalar: m = s * m₁, and m = m₁ * s, where s is a number.

Division by a scalar: m = m₁ / s, where s is a number.

Integer power: m = m₁ ^ n, where m₁ is a square matrix and n is an integer.

Matrix multiplication: m = m₁ * m₂, where m₁ is a NxK matrix and m₂ a KxM matrix. The result m is an NxM matrix.

Matrix-vector multiplication: u = m * v where m is an NxM matrix and v is a size M column vector. The result u is a size N column vector.

Vector-matrix multiplication: u = v * m where v is a size N row vector and m is an NxM matrix. The result u is a size M row vector.

q = quat([w], [x], [y], [z])
q = quat(w, v)
q = quat(v_axis, angle)
q = quat(q)
q = quat(m)
Create a quaternion. Values to initialize the quaternion elements may be optionally passed as a list of numbers, as a scalar w and a vector v, or as a previously created quaternion q (exceeding values are discarded, while missing values are replaced with zeros). If a matrix m is passed instead, the constructor assumes - without checking it - that m is a rotation matrix and returns the equivalent quaternion (m may be either a 3x3 or a 4x4 matrix, in which case its upper-left 3x3 submatrix is regarded as the rotation matrix).

t = toquat(t)
Turn an appropriately sized table into a quaternion, by adding the relevant meta information to it.

boolean = isquat(q)
Returns true if q is a quaternion, false otherwise.

w, v = parts(q)
Returns the scalar and vector parts of q (w is a number and v is a vec3).

q^* = conj(q)
|q| = norm(q)
|q|² = norm2(q)
q/|q| = normalize(q)
q^-1 = inv(q)

m = q:mat3( )
m = q:mat4( )
Convert the quaternion q to a 3x3 or a 4x4 rotation matrix.

q_mix = mix(q, q₁, k)
Element-wise blend q_mix = (1-k)*q +k*q₁, where k is a number.

q_slerp = slerp(q, q₁, k)
Spherical linear interpolation.

Unary minus: q = -q₁.

Addition: q = q₁ + q₂.

Subtraction: q = q₁ - q₂.

Multiplication by a scalar: q = s * q₁, and q = q₁ * s, where s is a number.

Division by a scalar: q = q₁ / s, where s is a number.

Integer power: q = q₁ ^ n, where n is an integer.

Quaternion multiplication: q = q₁ * q₂.

{ minx, maxx, miny, maxy } if v.dimensions=2 (2D box), or

{ minx, maxx, miny, maxy, minz, maxz } if v.dimensions=3 (3D box).

b = box2(…​)
b = box3(…​)
Create an axis-aligned box. The boxN function creates a N-dimensional box (where N may be 2 or 3). Values to initialize the box coordinates may be optionally passed as a list of numbers, or as a previously created box (exceeding values are discarded, while missing values are replaced with zeros). No consistency check is performed on the passed coordinates.

t = tobox2(t)
t = tobox3(t)
Turn an appropriately sized table into a box, by adding the relevant meta information to it.

boolean = isbox2(b)
boolean = isbox3(b)
Check if b is a box of the given dimensions (e.g. isbox2 checks if b is a 2D box).

r = rect(…​)
Creates a 2D axis-aligned rect. Values to initialize the rect may be optionally passed as a list of numbers, or as a previously created rect (exceeding values are discarded, while missing values are replaced with zeros). No consistency check is performed on the passed coordinates.

t = torect(t)
Turn an appropriately sized table into a rect, by adding the relevant meta information to it.

boolean = isrect(r)
Check if r is a rect.

z = complex([re], [im])
z = complex(z)
{z₁, z₂, …​} = complex({re₁, im₁, re₂, im₂, …​})
Create a complex number from its real and imaginary parts (which default to 0) or from a previously created complex number z.

t = tocomplex(t)
Turn an appropriately sized table into a complex number, by adding the relevant meta information to it.

boolean = iscomplex(z)
Returns true if z is a complex number or a Lua number, false otherwise.

re = creal(z)
im = cimag(z)
re, im = parts(z)
|z| = cabs(z)
|z| = norm(z)
rad = carg(z)
|z|² = norm2(z)
z/|z| = normalize(z)
z^* = conj(z)
z₁ = cproj(z)
z^-1 = inv(z)

e^z = cexp(z)
ln(z) = clog(z)
z^1/2 = csqrt(z)
z^w = cpow(z, w)

z₁ = csin(z)
z₁ = ccos(z)
z₁ = ctan(z)
z₁ = casin(z)
z₁ = cacos(z)
z₁ = catan(z)

z₁ = csinh(z)
z₁ = ccosh(z)
z₁ = ctanh(z)
z₁ = casinh(z)
z₁ = cacosh(z)
z₁ = catanh(z)

Unary minus: z = -z₁.

Addition: z = z₁ + z₂.

Subtraction: z = z₁ - z₂.

Multiplication: z = z₁ * z₂.

Division: z = z₁ / z₂.

Power: z = z₁ ^ z₂.

m = translate(v)
m = translate(x , y , z)
Returns the 4x4 translation matrix, given the vector v or its components x, y, and z.

m = scale(v)
m = scale(x, [y] , [z])
Returns the 4x4 scaling matrix, given the scaling factors x, y, and z, which may also be passed as a vector.
If y and z are not given, they are assumed equal to x (i.e. uniform scaling by a factor x).

m = rotate(angle, v)
m = rotate(angle, x , y , z)
Return the 4x4 rotation matrix given the angle (in radians) and the direction vector v = (x, y, z).

m = rotate_x(angle)
m = rotate_y(angle)
m = rotate_z(angle)
Return the 4x4 rotation matrix for a rotation by angle radians around the x, y or z axis, respectively.

m = look_at(eye, at, up)
Returns a 4x4 matrix to transform from world coordinates to camera coordinates, given the camera position and orientation in world coordinates: eye is the camera position, at is its target point, and up is the direction from the camera to a point on the vertical above the target.

m = ortho(left, right, bottom, top, [near], [far])
Returns a 4x4 ortographic projection matrix that transforms an axis-aligned box into the axis-aligned cube of side 2 centered at the origin.
The box is bounded by the planes x=left, x=right, y=bottom, y=top, z=-near, and z=-far.
The near and far values default to -1.0 and 1.0 respectively (2D projection).

m = frustum(left, right, bottom, top, near, far)
Returns a 4x4 perspective projection matrix. The view frustum has the center of projection in the origin, its near face is the rectangle (left<x<right, bottom<y<top) in the z=-near plane, and its far face is in the z=-far plane.

m = perspective(fovy, aspect, near, far)
Returns a 4x4 perspective projection matrix. The view frustum has the center of projection in the origin, a vertical field of view given by fovy (radians), and its near and far faces have the given aspect ratio (width/height), and are at z=-near and z=-far, respectively.

val₁, …​, val_N = flatten(table)
Flattens out the given table and returns the terminal elements in the order they are found.
Similar to Lua’s table.unpack( ), but it also unpacks any nested table. Only the array part of the table and of nested tables is considered.

{val₁, …​, val_N} = flatten_table(table)
Same as flatten( ), but returns the values in a flat table. Unlike flatten( ), this function can be used also with very large tables.

size = sizeof(type)
Returns the size in bytes of the given type.

data = pack(type, val₁, …​, val_N)
data = pack(type, table)
Packs the numbers val₁, …​, val_N, encoding them according to the given type, and returns the resulting binary string.
The values may also be passed in a (possibly nested) table. Only the array part of the table (and of nested tables) is considered.

{val₁, …​, val_N} = unpack(type, data)
Unpacks the binary string data, interpreting it as a sequence of values of the given type, and returns the extracted values in a flat table.
The length of data must be a multiple of sizeof(type).

hostmem = malloc(size)
hostmem = malloc(data)
hostmem = malloc(type, {value₁, …​, value_N})
hostmem = malloc(type, value₁, …​, value_N)
Allocates host memory and creates an hostmem object to encapsulate it.
malloc(size), where size is an integer, allocates size bytes of contiguous memory and initializes them to 0;
malloc(data), where data is a binary string, allocates #data bytes of contiguous memory and initializes them with the contents of data;
malloc(type, …​) is functionally equivalent to malloc(glmath.pack(type, …​)).

hostmem = aligned_alloc(alignment, size)
hostmem = aligned_alloc(alignment, data)
hostmem = aligned_alloc(alignment, type, {value₁, …​, value_N})
hostmem = aligned_alloc(alignment, type, value₁, …​, value_N)
Same as malloc( ), with the additional alignment parameter to control memory address alignment (rfr. aligned_alloc(3)).

hostmem = hostmem(size, ptr)
hostmem = hostmem(data)
Creates a hostmem object encapsulating user provided memory.
Such memory may be provided in form of a lightuserdata (ptr) containing a valid pointer to size bytes of contiguous memory, or as a binary string (data).
In both cases, care must be taken that the memory area remains valid until the hostmem object is deleted, or at least until it is accessed via its methods. In the data case, this means ensuring that data is not garbage collected during the hostmem object lifetime.
(Note that malloc(data) and hostmem(data) differ in that the former allocates memory and copies data in it, while the latter just stores a pointer to data).

free(hostmem)
hostmem:free( )
Deletes the hostmem object. If hostmem was created with glmath.malloc( ) or glmath.aligned_alloc( ), this function also releases the encapsulated memory.

ptr = hostmem:ptr([offset=0], [nbytes=0])
Returns a pointer (lightuserdata) to the location at offset bytes from the beginning of the encapsulated memory.
Raises an error if the requested location is beyond the boundaries of the memory area, or if there are not at least nbytes of memory after it.

nbytes = hostmem:size([offset=0])
nbytes = hostmem:size(ptr)
Returns the number of bytes of memory available after offset bytes from the beginning of the encapsulated memory area, or after ptr (a lightuserdata obtained with hostmem:ptr( )).

data = hostmem:read([offset], [nbytes])
{val₁, …​, val_N} = hostmem:read([offset], [nbytes], type)
Reads nbytes of data starting from offset, and returns it as a binary string or as a table of primitive values.
The offset parameter defaults to 0, and nbytes defaults to the memory size minus offset.
hostmem:read(offset, nbytes, type) is functionally equivalent to glmath.unpack(type, hostmem:read(offset, nbytes)).

hostmem:write(offset, nil, data)
hostmem:write(offset, type, val₁, …​, val_N)
hostmem:write(offset, type, {value₁, …​, value_N})
Writes to the encapsulated memory area, starting from the byte at offset.
write(offset, nil, data) writes the contents of data (a binary string);
write(offset, type, …​) is equivalent to write(offset, nil, glmath.pack(type, …​)).

hostmem:copy(offset, size, srcptr)
hostmem:copy(offset, size, srchostmem, srcoffset)
Copies size bytes to the encapsulated memory area, starting from the byte at offset.
copy(offset, size, srcptr), copies the size bytes pointed to by srcptr (a lightuserdata).
copy(offset, size, srchostmem, srcoffset), copies size bytes from the memory encapsulated by srchostmem (a hostmem object), starting from the location at srcoffset.

hostmem:clear(offset, nbytes, [val=0])
Clears nbytes of memory starting from offset. If the val parameter is given, the bytes are set to its value instead of 0 (val may be an integer or a character, i.e. a string of length 1).

trace_objects(boolean)
Enable/disable tracing of objects creation and destruction (which by default is disabled).
If enabled, a printf is generated whenever an object is created or deleted, indicating the object type and the value of its raw handle.

t = now( )
Returns the current time in seconds (a Lua number).
This is implemented with monotonic clock_gettime(3), if available, or with gettimeofday(3) otherwise.

dt = since(t)
Returns the time in seconds (a Lua number) elapsed since the time t, previously obtained with the now( ) function.

mean, var, min, max = stats({number})
Computes the mean, variance, and the minimum and maximum values for the given array of numbers.

dumpdata({number}, filename, [mode='w'])
Writes the given array of numbers to the given file file (plain ascii format, two columns index-value).
The data can then be displayed, for example, using gnuplot (gnuplot> plot "filename" using 1:2 with lines).
mode is the same as in io.open( ).