Start vector stuff;

api/lovr/math/Vec2/init.lua

@@ -0,0 +1,12 @@
+return {
+  summary = 'A 2D vector.',
+  description = 'A vector object that holds two numbers.',
+  constructors = {
+    'lovr.math.newVec2',
+    'lovr.math.vec2'
+  },
+  related = {
+    'Vec3',
+    'Vec4'
+  }
+}

api/lovr/math/Vec4/init.lua

@@ -0,0 +1,12 @@
+return {
+  summary = 'A 4D vector.',
+  description = 'A vector object that holds four numbers.',
+  constructors = {
+    'lovr.math.newVec4',
+    'lovr.math.vec4'
+  },
+  related = {
+    'Vec2',
+    'Vec3'
+  }
+}

api/lovr/math/mat4.lua

@@ -1,66 +1,20 @@
 return {
-  summary = 'Create a new mat4.',
+  summary = 'Create a temporary mat4.',
   description = [[
-    Creates a new `mat4`.
-
-    Note that this function is also a table containing the `__index` key of the mat4 metatable.
-    This means that you can add your own functions onto the `lovr.math.mat4` table to extend the
-    built-in functionality.
+    Creates a temporary `mat4`.  This function takes the same arguments as `mat4:set`.
+  ]],
+  arguments = {},
+  returns = {},
+  notes = [[
+    Temporary vector objects do not require any memory allocations or garbage collection, so they
+    can be faster in situations that require lots of vector math.  The downside is that they are
+    only valid until the next call to `lovr.math.drain`, which is called at the end of every frame
+    by default.  Attempting to use a temporary vector after it's been drained will result in an
+    error.  If you need permanent vectors that can be saved into variables and survive across
+    multiple frames, see `lovr.math.newMat4`.
   ]],
-  arguments = {
-    n = {
-      type = 'mat4',
-      description = 'An existing matrix to copy the values from.'
-    },
-    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 new matrix.'
-    }
-  },
-  variants = {
-    {
-      description = 'Sets the matrix to the identity matrix.',
-      arguments = {},
-      returns = { 'm' }
-    },
-    {
-      description = 'Copies values from an existing matrix.',
-      arguments = { 'n' },
-      returns = { 'm' }
-    },
-    {
-      arguments = { 'position', 'scale', 'rotation' },
-      returns = { 'm' }
-    },
-    {
-      arguments = { '...' },
-      returns = { 'm' }
-    }
-  },
-  notes = 'This function takes the same arguments as `mat4:set`.',
   related = {
-    'lovr.math.vec3',
-    'lovr.math.quat'
+    'lovr.math.newMat4',
+    'Mat4'
   }
 }

api/lovr/math/mat4/init.lua

@@ -1,34 +1,12 @@
 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 using `lovr.math.mat4`.
-
-    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 matrix.
-
-    Creating huge numbers of matrices every frame can lead to performance problems due to the sheer
-    amount of memory allocation and garbage collection overhead.  If you need lots of matrix objects
-    you can use `Pool`s to make things much more efficient.
-  ]],
-  constructor = 'lovr.math.mat4',
+  description = 'A `mat4` is a math type that holds 16 values in a 4x4 grid.',
+  constructors = {
+    'lovr.math.newMat4',
+    'lovr.math.mat4'
+  },
   related = {
-    'vec3',
-    'quat'
+    'Vec3',
+    'Quat'
   }
 }

api/lovr/math/newMat4.lua

@@ -0,0 +1,11 @@
+return {
+  summary = 'Create a new mat4.',
+  description = 'Creates a new `mat4`.  This function takes the same arguments as `mat4:set`.',
+  arguments = {},
+  returns = {},
+  notes = 'If you need lots of temporary mat4 objects, see `lovr.math.mat4`.',
+  related = {
+    'lovr.math.mat4',
+    'Mat4'
+  }
+}

api/lovr/math/newQuat.lua

@@ -0,0 +1,11 @@
+return {
+  summary = 'Create a new quat.',
+  description = 'Creates a new `quat`.  This function takes the same arguments as `quat:set`.',
+  arguments = {},
+  returns = {},
+  notes = 'If you need lots of temporary quat objects, see `lovr.math.quat`.',
+  related = {
+    'lovr.math.quat',
+    'Quat'
+  }
+}

api/lovr/math/newVec2.lua

@@ -0,0 +1,11 @@
+return {
+  summary = 'Create a new vec2.',
+  description = 'Creates a new `vec2`.  This function takes the same arguments as `vec2:set`.',
+  arguments = {},
+  returns = {},
+  notes = 'If you need lots of temporary vec2 objects, see `lovr.math.vec2`.',
+  related = {
+    'lovr.math.vec2',
+    'Vec2'
+  }
+}

api/lovr/math/newVec3.lua

@@ -0,0 +1,11 @@
+return {
+  summary = 'Create a new vec3.',
+  description = 'Creates a new `vec3`.  This function takes the same arguments as `vec3:set`.',
+  arguments = {},
+  returns = {},
+  notes = 'If you need lots of temporary vec3 objects, see `lovr.math.vec3`.',
+  related = {
+    'lovr.math.vec3',
+    'Vec3'
+  }
+}

api/lovr/math/newVec4.lua

@@ -0,0 +1,11 @@
+return {
+  summary = 'Create a new vec4.',
+  description = 'Creates a new `vec4`.  This function takes the same arguments as `vec4:set`.',
+  arguments = {},
+  returns = {},
+  notes = 'If you need lots of temporary vec4 objects, see `lovr.math.vec4`.',
+  related = {
+    'lovr.math.vec4',
+    'Vec4'
+  }
+}

api/lovr/math/quat.lua

@@ -1,96 +1,20 @@
 return {
-  summary = 'Create a new quat.',
+  summary = 'Create a temporary quat.',
   description = [[
-    Creates a new `quat`.  Have a look at `quat:set` for more information about how all these
-    variants can be used.
-
-    Note that this function is also a table containing the `__index` key of the quat metatable.
-    This means that you can add your own functions onto the `lovr.math.quat` table to extend the
-    built-in functionality.
+    Creates a temporary `quat`.  This function takes the same arguments as `quat:set`.
+  ]],
+  arguments = {},
+  returns = {},
+  notes = [[
+    Temporary vector objects do not require any memory allocations or garbage collection, so they
+    can be faster in situations that require lots of vector math.  The downside is that they are
+    only valid until the next call to `lovr.math.drain`, which is called at the end of every frame
+    by default.  Attempting to use a temporary vector after it's been drained will result in an
+    error.  If you need permanent vectors that can be saved into variables and survive across
+    multiple frames, see `lovr.math.newQuat`.
   ]],
-  arguments = {
-    angle = {
-      default = '0',
-      description = 'The angle to use for the rotation, in radians.'
-    },
-    ax = {
-      type = 'number',
-      default = '0',
-      description = 'The x component of the axis of rotation.'
-    },
-    ay = {
-      type = 'number',
-      default = '0',
-      description = 'The y component of the axis of rotation.'
-    },
-    az = {
-      type = 'number',
-      default = '0',
-      description = 'The z component of the axis of rotation.'
-    },
-    axis = {
-      type = 'vec3',
-      description = 'The axis of rotation (does not need to be normalized).'
-    },
-    raw = {
-      type = 'boolean',
-      default = 'false',
-      description = 'Whether the components should be interpreted as raw `(x, y, z, w)` components.'
-    },
-    v = {
-      type = 'vec3',
-      description = 'A normalized direction vector.'
-    },
-    u = {
-      type = 'vec3',
-      description = 'Another normalized direction vector.'
-    },
-    r = {
-      type = 'quat',
-      description = 'An existing quaternion to copy the values from.'
-    },
-    m = {
-      type = 'mat4',
-      description = 'A matrix to use the rotation from.'
-    }
-  },
-  returns = {
-    q = {
-      type = 'quat',
-      description = 'The new quaternion.'
-    }
-  },
-  variants = {
-    {
-      arguments = { 'angle', 'ax', 'ay', 'az', 'raw' },
-      returns = { 'q' }
-    },
-    {
-      arguments = { 'angle', 'axis' },
-      returns = { 'q' }
-    },
-    {
-      arguments = { 'r' },
-      returns = { 'q' }
-    },
-    {
-      description = 'Sets the values from a direction vector.',
-      arguments = { 'v' },
-      returns = { 'q' }
-    },
-    {
-      description = 'Sets the values to represent the rotation between two vectors.',
-      arguments = { 'v', 'u' },
-      returns = { 'q' }
-    },
-    {
-      arguments = { 'm' },
-      returns = { 'q' }
-    }
-  },
-  notes = 'This function takes the same arguments as `quat:set`.',
   related = {
-    'lovr.math.vec3',
-    'lovr.math.mat4'
+    'lovr.math.newQuat',
+    'Quat'
   }
 }

api/lovr/math/quat/init.lua

@@ -1,35 +1,12 @@
 return {
   summary = 'A quaternion.',
-  description = [[
-    A `quat` is a math type that represents a 3D rotation, stored as four numbers.  LÖVR functions
-    that take rotations also accept quaternions.  `quat`s are created using `lovr.math.quat`.
-
-    The four numbers stored in a `quat`, normally called `x, y, z, w`, are not very intuitive to
-    work with.  Instead, rotations in most LÖVR APIs use the angle/axis representation, which is
-    defined by a rotation angle in radians and an axis to rotate around.  Accordingly, the quat
-    functions for getting and setting elements, `quat:unpack` and `quat:set`, don't take the normal
-    `x, y, z, w` elements but instead take four angle/axis values.  If you need to access the raw
-    components, you can pass in `true` as the last argument to signify that you want to work with
-    raw components.
-
-    Two quaternions can be multiplied together to combine their rotations into a single new
-    quaternion.  The `quat:mul` function can be used to multiply two quaternions "in place",
-    modifying the first quaternion.  Alternatively, the `*` operator can be used to multiply them,
-    which will create a new quaternion to store the result in.
-
-    A quaternion can also be multiplied by a vector.  This rotates the vector.  Both `quat:mul` and
-    the `*` operator can be used for this.
-
-    A common source of bugs is to forget to normalize a quaternion.  If you run into weird bugs with
-    rotations, calling `quat:normalize` on your rotations may fix the issue!
-
-    Creating huge numbers of quaternions every frame can lead to performance problems due to the
-    sheer amount of memory allocation and garbage collection overhead.  If you need lots of
-    quaternion objects you can use `Pool`s to make things much more efficient.
-  ]],
-  constructor = 'lovr.math.quat',
+  description = 'A `quat` is a math type that represents a 3D rotation, stored as four numbers.',
+  constructors = {
+    'lovr.math.newQuat',
+    'lovr.math.quat'
+  },
   related = {
-    'vec3',
-    'mat4'
+    'Vec3',
+    'Mat4'
   }
 }

api/lovr/math/vec2.lua

@@ -0,0 +1,20 @@
+return {
+  summary = 'Create a temporary vec2.',
+  description = [[
+    Creates a temporary `vec2`.  This function takes the same arguments as `vec2:set`.
+  ]],
+  arguments = {},
+  returns = {},
+  notes = [[
+    Temporary vector objects do not require any memory allocations or garbage collection, so they
+    can be faster in situations that require lots of vector math.  The downside is that they are
+    only valid until the next call to `lovr.math.drain`, which is called at the end of every frame
+    by default.  Attempting to use a temporary vector after it's been drained will result in an
+    error.  If you need permanent vectors that can be saved into variables and survive across
+    multiple frames, see `lovr.math.newVec2`.
+  ]],
+  related = {
+    'lovr.math.newVec2',
+    'Vec2'
+  }
+}

api/lovr/math/vec3.lua

@@ -1,52 +1,20 @@
 return {
-  summary = 'Create a new vec3.',
+  summary = 'Create a temporary vec3.',
   description = [[
-    Creates a new `vec3`.
-
-    Note that this function is also a table containing the `__index` key of the vec3 metatable.
-    This means that you can add your own functions onto the `lovr.math.vec3` table to extend the
-    built-in functionality.
+    Creates a temporary `vec3`.  This function takes the same arguments as `vec3:set`.
+  ]],
+  arguments = {},
+  returns = {},
+  notes = [[
+    Temporary vector objects do not require any memory allocations or garbage collection, so they
+    can be faster in situations that require lots of vector math.  The downside is that they are
+    only valid until the next call to `lovr.math.drain`, which is called at the end of every frame
+    by default.  Attempting to use a temporary vector after it's been drained will result in an
+    error.  If you need permanent vectors that can be saved into variables and survive across
+    multiple frames, see `lovr.math.newVec3`.
   ]],
-  arguments = {
-    x = {
-      type = 'number',
-      default = '0',
-      description = 'The x value of the vector.'
-    },
-    y = {
-      type = 'number',
-      default = 'x',
-      description = 'The y value of the vector.'
-    },
-    z = {
-      type = 'number',
-      default = 'x',
-      description = 'The z value of the vector.'
-    },
-    u = {
-      type = 'vec3',
-      description = 'The vector to copy the values from.'
-    }
-  },
-  returns = {
-    v = {
-      type = 'vec3',
-      description = 'The new vector.'
-    }
-  },
-  variants = {
-    {
-      arguments = { 'x', 'y', 'z' },
-      returns = { 'v' }
-    },
-    {
-      arguments = { 'u' },
-      returns = { 'v' }
-    }
-  },
-  notes = 'This function takes the same arguments as `vec3:set`.',
   related = {
-    'lovr.math.quat',
-    'lovr.math.mat4'
+    'lovr.math.newVec3',
+    'Vec3'
   }
 }

api/lovr/math/vec3/init.lua

@@ -1,27 +1,12 @@
 return {
   summary = 'A 3D vector.',
-  description = [[
-    A `vec3` is a math type that holds three numbers.  It's very helpful for representing and
-    manipulating 3D positions and directions.  LÖVR functions that accept 3D positions, directions,
-    or velocities generally also accept `vec3`s.  `vec3`s are created using `lovr.math.vec3`.
-
-    `vec3`s have metamethods, allowing you to add, subtract, multiply, and divide them using the
-    usual binary operators that you would use on numbers.  Note that these create new vectors to
-    store their results in.  If you want to modify a vector instead of creating new ones, you can
-    use the named operator functions like `vec3:add`.
-
-    Creating huge numbers of vectors every frame can lead to performance problems due to the sheer
-    amount of memory allocation and garbage collection overhead.  If you need lots of vector objects
-    you can use `Pool`s to make things much more efficient.
-
-    Note that accessing properties directly (like `v.x`) is not an officially supported feature
-    right now (for performance reasons), though it does happen to work by accident in LuaJIT.  This
-    limitation may be improved in the future.  For now, it is recommended to use `vec3:unpack` and
-    `vec3:set` if you need to work with individual components of a vector.
-  ]],
-  constructor = 'lovr.math.vec3',
+  description = 'A vector object that holds three numbers.',
+  constructors = {
+    'lovr.math.newVec3',
+    'lovr.math.vec3'
+  },
   related = {
-    'quat',
-    'mat4'
+    'Vec2',
+    'Vec4'
   }
 }

api/lovr/math/vec4.lua

@@ -0,0 +1,20 @@
+return {
+  summary = 'Create a temporary vec4.',
+  description = [[
+    Creates a temporary `vec4`.  This function takes the same arguments as `vec4:set`.
+  ]],
+  arguments = {},
+  returns = {},
+  notes = [[
+    Temporary vector objects do not require any memory allocations or garbage collection, so they
+    can be faster in situations that require lots of vector math.  The downside is that they are
+    only valid until the next call to `lovr.math.drain`, which is called at the end of every frame
+    by default.  Attempting to use a temporary vector after it's been drained will result in an
+    error.  If you need permanent vectors that can be saved into variables and survive across
+    multiple frames, see `lovr.math.newVec4`.
+  ]],
+  related = {
+    'lovr.math.newVec4',
+    'Vec4'
+  }
+}