Start mat4 docs;

api/lovr/math/mat4/identity.lua

@@ -0,0 +1,18 @@
+return {
+  summary = 'Reset the matrix to the identity.',
+  description = [[
+    Resets the matrix to the identity, effectively setting its translation to zero, its scale to 1,
+    and clearing any rotation.
+  ]],
+  arguments = {},
+  returns = {
+    {
+      name = 'm',
+      type = 'mat4',
+      description = 'The original matrix.'
+    }
+  },
+  related = {
+    'lovr.graphics.origin'
+  }
+}

api/lovr/math/mat4/init.lua

@@ -0,0 +1,40 @@
+return {
+  summary = 'A 4x4 matrix.',
+  description = [[
+    A `mat4` is a math type that holds 16 values in a 4x4 grid.  They are very useful for
+    representing and manipulating transforms in 3D space.  LÖVR functions that accept 3D transforms
+    can take a single `mat4` instead of 10 numbers or an assortment of `vec3`s and `quat`s, which
+    is more concise and improves performance slightly.
+
+    `mat4`s are created by allocating them from Pools, by either using `lovr.math.mat4` to allocate
+    from the default pool or creating a new `Pool` and calling `Pool:mat4` on it.  *Note* that
+    matrices created with `lovr.math.mat4` are *temporary*, and will be cleared at the end of a
+    frame!  You can use `mat4:save` to save a permanent copy of the matrix that is managed by the
+    Lua garbage collector.
+
+    Explaining the math behind `mat4`s and transforms is outside the scope of these docs, but there
+    are some fairly straightforward functions that can be used to move, rotate, and scale the
+    transform represented by the matrix:
+
+    - `mat4:translate`
+    - `mat4:rotate`
+    - `mat4:scale`
+
+    The "default" matrix is called the identity matrix and `mat4:identity` can be used to reset any
+    matrix to the default state.
+
+    Matrices can be multiplied together using the normal `*` operator, which combines both of their
+    transformations into a single matrix.  This is really useful for condensing a set of simple
+    transforms into a more complex one, or creating parent-child relationships between objects.
+    Note that the multiplication returns a new temporary matrix that will be cleared at the end of
+    the frame, so be sure to use `mat4:save` if you need to hold onto it.
+  ]],
+  constructors = {
+    'lovr.math.mat4',
+    'Pool:mat4'
+  },
+  related = {
+    'vec3',
+    'quat'
+  }
+}

api/lovr/math/mat4/invert.lua

@@ -0,0 +1,12 @@
+return {
+  summary = 'Invert the matrix.',
+  description = 'Inverts the matrix, causing it to represent the opposite of its old transform.',
+  arguments = {},
+  returns = {
+    {
+      name = 'm',
+      type = 'mat4',
+      description = 'The original matrix.'
+    }
+  }
+}

api/lovr/math/mat4/rotate.lua

@@ -0,0 +1,23 @@
+return {
+  summary = 'Rotate the matrix.',
+  description = 'Rotates the matrix using a quaternion or an angle/axis rotation.',
+  arguments = {
+    {
+      name = 'rotation',
+      type = 'quat',
+      description = 'The rotation to apply to the matrix.'
+    }
+  },
+  returns = {
+    {
+      name = 'm',
+      type = 'mat4',
+      description = 'The original matrix.'
+    }
+  },
+  related = {
+    'mat4:translate',
+    'mat4:scale',
+    'mat4:identity'
+  }
+}

api/lovr/math/mat4/save.lua

@@ -0,0 +1,26 @@
+return {
+  summary = 'Create a non-temporary copy of the matrix.',
+  description = [[
+    Creates and returns a permanent copy of the matrix.  This copy exists as a normal Lua variable
+    instead of belonging to a `Pool`, so it won't get destroyed when the Pool is drained and it will
+    be garbage collected when it's no longer in use.
+  ]],
+  arguments = {},
+  returns = {
+    {
+      name = 'm',
+      type = 'mat4',
+      description = 'The new matrix.'
+    }
+  },
+  notes = [[
+    This function should be used only when needed, as creating huge numbers of saved matrices can
+    begin to impact the garbage collector and decrease performance.
+  ]],
+  related = {
+    'mat4:set',
+    'lovr.math.mat4',
+    'Pool:mat4',
+    'Pool:drain'
+  }
+}

api/lovr/math/mat4/scale.lua

@@ -0,0 +1,26 @@
+return {
+  summary = 'Scale the matrix.',
+  description = 'Scales the matrix.',
+  arguments = {
+    scale = {
+      type = 'vec3',
+      description = 'The 3D scale to apply.'
+    },
+    x = {
+      type = 'number',
+      description = 'A uniform scale to apply.'
+    }
+  },
+  returns = {
+    {
+      name = 'm',
+      type = 'mat4',
+      description = 'The original matrix.'
+    }
+  },
+  related = {
+    'mat4:translate',
+    'mat4:rotate',
+    'mat4:identity'
+  }
+}

api/lovr/math/mat4/set.lua

@@ -0,0 +1,70 @@
+return {
+  summary = 'Set the components of the matrix.',
+  description = [[
+    Sets the components of the matrix from separate position, rotation, and scale arguments or an
+    existing matrix.
+  ]],
+  arguments = {
+    n = {
+      type = 'mat4',
+      description = 'An existing matrix to copy the values from.'
+    },
+    x = {
+      type = 'number',
+      description = 'A number to set as the diagonal values of the matrix.'
+    },
+    position = {
+      type = 'vec3',
+      default = '0, 0, 0',
+      description = 'The translation of the matrix.'
+    },
+    scale = {
+      type = 'vec3',
+      default = '1, 1, 1',
+      description = 'The scale of the matrix.'
+    },
+    rotation = {
+      type = 'quat',
+      default = '0, 0, 0, 0',
+      description = 'The rotation of the matrix.'
+    },
+    ['...'] = {
+      type = 'number',
+      description = '16 numbers to use as the raw values of the matrix (column-major).'
+    }
+  },
+  returns = {
+    m = {
+      type = 'mat4',
+      description = 'The original matrix.'
+    }
+  },
+  variants = {
+    {
+      description = 'Resets the matrix to the identity matrix.',
+      arguments = {},
+      returns = { 'm' }
+    },
+    {
+      description = 'Sets the diagonal values of the matrix equal to a number.',
+      arguments = { 'x' },
+      returns = { 'm' }
+    },
+    {
+      description = 'Copies the values from an existing matrix.',
+      arguments = { 'n' },
+      returns = { 'm' }
+    },
+    {
+      arguments = { 'position', 'scale', 'rotation' },
+      returns = { 'm' }
+    },
+    {
+      arguments = { '...' },
+      returns = { 'm' }
+    }
+  },
+  related = {
+    'mat4:unpack'
+  }
+}

api/lovr/math/mat4/translate.lua

@@ -0,0 +1,23 @@
+return {
+  summary = 'Translate the matrix.',
+  description = 'Translates the matrix.',
+  arguments = {
+    {
+      name = 'translation',
+      type = 'vec3',
+      description = 'The translation vector.'
+    }
+  },
+  returns = {
+    {
+      name = 'm',
+      type = 'mat4',
+      description = 'The original matrix.'
+    }
+  },
+  related = {
+    'mat4:rotate',
+    'mat4:scale',
+    'mat4:identity'
+  }
+}

api/lovr/math/mat4/transpose.lua

@@ -0,0 +1,12 @@
+return {
+  summary = 'Transpose the matrix.',
+  description = 'Transposes the matrix, mirroring its values along the diagonal.',
+  arguments = {},
+  returns = {
+    {
+      name = 'm',
+      type = 'mat4',
+      description = 'The original matrix.'
+    }
+  }
+}

api/lovr/math/mat4/unpack.lua

@@ -0,0 +1,15 @@
+return {
+  summary = 'Get the raw components of the matrix.',
+  description = 'Returns the 16 components of matrix as numbers.',
+  arguments = {},
+  returns = {
+    {
+      name = '...',
+      type = 'number',
+      description = 'The 16 matrix values.'
+    }
+  },
+  related = {
+    'mat4:set'
+  }
+}

api/lovr/math/vec3/init.lua

@@ -24,5 +24,9 @@ return {
   constructors = {
     'lovr.math.vec3',
     'Pool:vec3'
+  },
+  related = {
+    'quat',
+    'mat4'
   }
 }

api/lovr/math/vec3/save.lua

@@ -2,7 +2,7 @@ return {
   summary = 'Create a non-temporary copy of the vector.',
   description = [[
     Creates and returns a permanent copy of the vector.  This copy exists as a normal Lua variable
-    instead of belonging to a `Pool`, so it won't get destroyed when the Pool is drained and will
+    instead of belonging to a `Pool`, so it won't get destroyed when the Pool is drained and it will
     be garbage collected when it's no longer in use.
   ]],
   arguments = {},