vec3 docs;

api/lovr/math/vec3/__add.lua

@@ -0,0 +1,30 @@
+return {
+  summary = 'Add two vectors.',
+  description = 'Adds two vectors, returning a new temporary vector containing the sum.',
+  arguments = {
+    {
+      name = 'v',
+      type = 'vec3',
+      description = 'The first vector.'
+    },
+    {
+      name = 'u',
+      type = 'vec3',
+      description = 'The second vector.'
+    }
+  },
+  returns = {
+    {
+      name = 'out',
+      type = 'vec3',
+      description = 'The result.'
+    }
+  },
+  related = {
+    'vec3:add',
+    'vec3:__sub',
+    'vec3:__mul',
+    'vec3:__div',
+    'vec3:save'
+  }
+}

api/lovr/math/vec3/__div.lua

@@ -0,0 +1,35 @@
+return {
+  summary = 'Divide vectors by vectors or numbers.',
+  description = [[
+    Divides a vector by another vector or a vector by a number.  Returns a new vector that contains
+    the divided values.
+  ]],
+  arguments = {
+    v = {
+      type = 'vec3',
+      description = 'The first vector.'
+    },
+    u = {
+      type = 'vec3',
+      description = 'The second vector.'
+    },
+    x = {
+      type = 'number',
+      description = 'A number to divide each value in the vector by.'
+    }
+  },
+  returns = {
+    {
+      name = 'out',
+      type = 'vec3',
+      description = 'The result.'
+    }
+  },
+  related = {
+    'vec3:div',
+    'vec3:__add',
+    'vec3:__sub',
+    'vec3:__mul',
+    'vec3:save'
+  }
+}

api/lovr/math/vec3/__len.lua

@@ -0,0 +1,22 @@
+return {
+  summary = 'Get the length of the vector.',
+  description = 'Returns the length of the vector.',
+  arguments = {
+    {
+      name = 'v',
+      type = 'vec3',
+      description = 'The first vector.'
+    }
+  },
+  returns = {
+    {
+      name = 'length',
+      type = 'number',
+      description = 'The length of the vector.'
+    }
+  },
+  related = {
+    'vec3:length',
+    'vec3:distance'
+  }
+}

api/lovr/math/vec3/__mul.lua

@@ -0,0 +1,35 @@
+return {
+  summary = 'Multiply vectors by vectors or numbers.',
+  description = [[
+    Multiplies a vector by another vector or a vector by a number.  Returns a new vector that
+    contains the multiplied values.
+  ]],
+  arguments = {
+    v = {
+      type = 'vec3',
+      description = 'The first vector.'
+    },
+    u = {
+      type = 'vec3',
+      description = 'The second vector.'
+    },
+    x = {
+      type = 'number',
+      description = 'A number to scale each value in the vector by.'
+    }
+  },
+  returns = {
+    {
+      name = 'out',
+      type = 'vec3',
+      description = 'The result.'
+    }
+  },
+  related = {
+    'vec3:mul',
+    'vec3:__add',
+    'vec3:__sub',
+    'vec3:__div',
+    'vec3:save'
+  }
+}

api/lovr/math/vec3/__sub.lua

@@ -0,0 +1,32 @@
+return {
+  summary = 'Subtract two vectors.',
+  description = [[
+    Subtracts two vectors, returning a new temporary vector containing the difference.
+  ]],
+  arguments = {
+    {
+      name = 'v',
+      type = 'vec3',
+      description = 'The first vector.'
+    },
+    {
+      name = 'u',
+      type = 'vec3',
+      description = 'The second vector.'
+    }
+  },
+  returns = {
+    {
+      name = 'out',
+      type = 'vec3',
+      description = 'The result.'
+    }
+  },
+  related = {
+    'vec3:sub',
+    'vec3:__add',
+    'vec3:__mul',
+    'vec3:__div',
+    'vec3:save'
+  }
+}

api/lovr/math/vec3/__unm.lua

@@ -0,0 +1,18 @@
+return {
+  summary = 'Negate a vector.',
+  description = 'Returns a new vector with the negated components of the original.',
+  arguments = {
+    {
+      name = 'v',
+      type = 'vec3',
+      description = 'The first vector.'
+    }
+  },
+  returns = {
+    {
+      name = 'negated',
+      type = 'vec3',
+      description = 'The result.'
+    }
+  }
+}

api/lovr/math/vec3/add.lua

@@ -0,0 +1,29 @@
+return {
+  summary = 'Add a vector to this vector.',
+  description = 'Adds a vector to this vector.',
+  arguments = {
+    {
+      name = 'u',
+      type = 'vec3',
+      description = 'The other vector.'
+    }
+  },
+  returns = {
+    {
+      name = 'v',
+      type = 'vec3',
+      description = 'The original vector.'
+    }
+  },
+  notes = [[
+    This function modifies `v` and sets the values to equal the summed values, like this:
+
+        v.x, v.y, v.z = v.x + u.x, v.y + u.y, v.z + u.z
+  ]],
+  related = {
+    'vec3:__add',
+    'vec3:sub',
+    'vec3:mul',
+    'vec3:div'
+  }
+}

api/lovr/math/vec3/cross.lua

@@ -0,0 +1,25 @@
+return {
+  summary = 'Get the cross product with another vector.',
+  description = [[
+    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`.
+  ]],
+  arguments = {
+    {
+      name = 'u',
+      type = 'vec3',
+      description = 'The vector to compute the cross product with.'
+    }
+  },
+  returns = {
+    {
+      name = 'v',
+      type = 'vec3',
+      description = 'The original vector, with the cross product as its values.'
+    }
+  },
+  notes = 'The vectors are not normalized before or after computing the cross product.',
+  related = {
+    'vec3:dot'
+  }
+}

api/lovr/math/vec3/distance.lua

@@ -0,0 +1,24 @@
+return {
+  summary = 'Get the distance to another vector.',
+  description = 'Returns the distance to another vector.',
+  arguments = {
+    {
+      name = 'u',
+      type = 'vec3',
+      description = 'The vector to measure the distance to.'
+    }
+  },
+  returns = {
+    {
+      name = 'distance',
+      type = 'number',
+      description = 'The distance to `u`.'
+    }
+  },
+  related = {
+    'vec3:__len',
+    'vec3:length',
+    'vec3:dot',
+    'vec3:cross'
+  }
+}

api/lovr/math/vec3/div.lua

@@ -0,0 +1,37 @@
+return {
+  summary = 'Divides the vector by a vector or a number.',
+  description = 'Divides the vector by a vector or a number.',
+  arguments = {
+    u = {
+      type = 'vec3',
+      description = 'The other vector to divide the components by.'
+    },
+    x = {
+      type = 'number',
+      description = 'The number to divide each component by.'
+    }
+  },
+  returns = {
+    {
+      name = 'v',
+      type = 'vec3',
+      description = 'The original vector.'
+    }
+  },
+  notes = [[
+    This function modifies `v` and sets the values to equal the divided values.  When dividing by a
+    vector, the division is component-wise, like this:
+
+        v.x, v.y, v.z = v.x / u.x, v.y / u.y, v.z / u.z
+
+    Dividing by a number divides each component of the vector by that number:
+
+        v.x, v.y, v.z = v.x / x, v.y / x, v.z / x
+  ]],
+  related = {
+    'vec3:__div',
+    'vec3:add',
+    'vec3:sub',
+    'vec3:mul'
+  }
+}

api/lovr/math/vec3/dot.lua

@@ -0,0 +1,31 @@
+return {
+  summary = 'Get the dot product with another vector.',
+  description = 'Returns the dot product between this vector and another one.',
+  arguments = {
+    {
+      name = 'u',
+      type = 'vec3',
+      description = 'The vector to compute the dot product with.'
+    }
+  },
+  returns = {
+    {
+      name = 'dot',
+      type = 'number',
+      description = 'The dot product between `v` and `u`.'
+    }
+  },
+  notes = [[
+    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.
+  ]],
+  related = {
+    'vec3:cross',
+    'vec3:__len',
+    'vec3:length',
+    'vec3:distance'
+  }
+}

api/lovr/math/vec3/init.lua

@@ -0,0 +1,28 @@
+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 by allocating them from Pools, by either using `lovr.math.vec3` to allocate
+    from the default pool or creating a new `Pool` and calling `Pool:vec3` on it.  *Note* that
+    vectors created with `lovr.math.vec3` are *temporary*, and will be cleared at the end of a
+    frame!  You can use `vec3:save` to save a permanent copy of the vector that is managed by the
+    Lua garbage collector.
+
+    `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 *temporary*
+    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`.
+
+    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.
+  ]],
+  constructors = {
+    'lovr.math.vec3',
+    'Pool:vec3'
+  }
+}

api/lovr/math/vec3/length.lua

@@ -0,0 +1,22 @@
+return {
+  summary = 'Get the length of the vector.',
+  description = 'Returns the length of the vector.',
+  arguments = {},
+  returns = {
+    {
+      name = 'length',
+      type = 'number',
+      description = 'The length of the vector.'
+    }
+  },
+  notes = [[
+    The length is equivalent to this:
+
+        math.sqrt(v.x * v.x + v.y * v.y + v.z * v.z)
+  ]],
+  related = {
+    'vec3:__len',
+    'vec3:normalize',
+    'vec3:distance'
+  }
+}

api/lovr/math/vec3/lerp.lua

@@ -0,0 +1,31 @@
+return {
+  summary = 'Moves this vector some amount towards another one.',
+  description = [[
+    Sets the components of this vector to be somewhere between their current values and the values
+    of the input vector, based on a parameter.  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.
+  ]],
+  arguments = {
+    {
+      name = 'u',
+      type = 'vec3',
+      description = 'The vector to lerp towards.'
+    },
+    {
+      name = 't',
+      type = 'number',
+      description = 'The lerping parameter.'
+    }
+  },
+  returns = {
+    {
+      name = 'v',
+      type = 'vec3',
+      description = 'The original vector, with lerped values.'
+    }
+  },
+  related = {
+    'quat:slerp'
+  }
+}

api/lovr/math/vec3/mul.lua

@@ -0,0 +1,37 @@
+return {
+  summary = 'Multiply the vector by a vector or a number.',
+  description = 'Multiplies the vector by a vector or a number.',
+  arguments = {
+    u = {
+      type = 'vec3',
+      description = 'The other vector to multiply the components by.'
+    },
+    x = {
+      type = 'number',
+      description = 'The number to multiply each component by.'
+    }
+  },
+  returns = {
+    {
+      name = 'v',
+      type = 'vec3',
+      description = 'The original vector.'
+    }
+  },
+  notes = [[
+    This function modifies `v` and sets the values to equal the multiplied values.  When multiplying
+    by a vector, the multiplication is component-wise, like this:
+
+        v.x, v.y, v.z = v.x * u.x, v.y * u.y, v.z * u.z
+
+    Multiplying by a number scales each component of the vector by that number:
+
+        v.x, v.y, v.z = v.x * x, v.y * x, v.z * x
+  ]],
+  related = {
+    'vec3:__mul',
+    'vec3:add',
+    'vec3:sub',
+    'vec3:div'
+  }
+}

api/lovr/math/vec3/normalize.lua

@@ -0,0 +1,18 @@
+return {
+  summary = 'Normalize the length of the vector to 1.',
+  description = [[
+    Adjusts the values in the vector so that its direction stays the same but its length becomes 1.
+  ]],
+  arguments = {},
+  returns = {
+    {
+      name = 'v',
+      type = 'vec3',
+      description = 'The original vector.'
+    }
+  },
+  related = {
+    'vec3:__len',
+    'vec3:length'
+  }
+}

api/lovr/math/vec3/save.lua

@@ -0,0 +1,26 @@
+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
+    be garbage collected when it's no longer in use.
+  ]],
+  arguments = {},
+  returns = {
+    {
+      name = 'v',
+      type = 'vec3',
+      description = 'The new vector.'
+    }
+  },
+  notes = [[
+    This function should be used only when needed, as creating huge numbers of saved vectors can
+    begin to impact the garbage collector and decrease performance.
+  ]],
+  related = {
+    'vec3:set',
+    'lovr.math.vec3',
+    'Pool:vec3',
+    'Pool:drain'
+  }
+}

api/lovr/math/vec3/set.lua

@@ -0,0 +1,46 @@
+return {
+  summary = 'Set the components of the vector.',
+  description = 'Sets the components of the vector, either from numbers or an existing vector.',
+  arguments = {
+    x = {
+      type = 'number',
+      default = '0',
+      description = 'The new x value of the vector.'
+    },
+    y = {
+      type = 'number',
+      default = 'x',
+      description = 'The new y value of the vector.'
+    },
+    z = {
+      type = 'number',
+      default = 'x',
+      description = 'The new z value of the vector.'
+    },
+    u = {
+      type = 'vec3',
+      description = 'The vector to copy the values from.'
+    }
+  },
+  returns = {
+    v = {
+      type = 'vec3',
+      description = 'The input vector.'
+    }
+  },
+  variants = {
+    {
+      arguments = { 'x', 'y', 'z' },
+      returns = { 'v' }
+    },
+    {
+      arguments = { 'u' },
+      returns = { 'v' }
+    }
+  },
+  related = {
+    'vec3:unpack',
+    'lovr.math.vec3',
+    'Pool:vec3'
+  }
+}

api/lovr/math/vec3/sub.lua

@@ -0,0 +1,29 @@
+return {
+  summary = 'Subtract a vector from this vector.',
+  description = 'Subtracts a vector from this vector.',
+  arguments = {
+    {
+      name = 'u',
+      type = 'vec3',
+      description = 'The other vector.'
+    }
+  },
+  returns = {
+    {
+      name = 'v',
+      type = 'vec3',
+      description = 'The original vector.'
+    }
+  },
+  notes = [[
+    This function modifies `v` and sets the values to equal the subtracted values, like this:
+
+        v.x, v.y, v.z = v.x - u.x, v.y - u.y, v.z - u.z
+  ]],
+  related = {
+    'vec3:__sub',
+    'vec3:add',
+    'vec3:mul',
+    'vec3:div'
+  }
+}

api/lovr/math/vec3/unpack.lua

@@ -0,0 +1,25 @@
+return {
+  summary = 'Get the components of the vector.',
+  description = 'Returns the 3 components of vector as numbers.',
+  arguments = {},
+  returns = {
+    {
+      name = 'x',
+      type = 'number',
+      description = 'The x value.'
+    },
+    {
+      name = 'y',
+      type = 'number',
+      description = 'The y value.'
+    },
+    {
+      name = 'z',
+      type = 'number',
+      description = 'The z value.'
+    }
+  },
+  related = {
+    'vec3:set'
+  }
+}