Merge pull request #50 from jmiskovic/add/target

Add targetTo() doc, fix UI/Spectator_Camera example

api/lovr/math/Mat4/lookAt.lua

@@ -1,7 +1,12 @@
 return {
-  summary = 'Create a transform that makes a viewer look at a target.',
+  summary = 'Create a view transform that looks from a position to target position.',
   description = [[
-    Sets a transform matrix that positions a viewer so that it looks at a target point.
+    Sets a view transform matrix that moves and orients camera to look at a target point.
+
+    This is useful for changing camera position and orientation. The resulting Mat4 matrix can be
+    passed to `lovr.graphics.transform()` directly (without inverting) before rendering the scene.
+
+    The lookAt() function produces same result as target() after matrix inversion.
   ]],
   arguments = {
     {
@@ -29,6 +34,7 @@ return {
     }
   },
   related = {
+    'Mat4:target',
     'Quat:direction'
   }
 }

api/lovr/math/Mat4/target.lua

@@ -0,0 +1,40 @@
+return {
+  summary = 'Create a model transform that targets from a position to target position.',
+  description = [[
+    Sets a model transform matrix that moves to `from` and orients model towards `to` point.
+
+    This is used when rendered model should always point torwards a point of interest. The
+    resulting Mat4 object can be used as model pose.
+
+    The target() function produces same result as lookAt() after matrix inversion.
+  ]],
+  arguments = {
+    {
+      name = 'from',
+      type = 'Vec3',
+      description = 'The position of the viewer.'
+    },
+    {
+      name = 'to',
+      type = 'Vec3',
+      description = 'The position of the target.'
+    },
+    {
+      name = 'up',
+      type = 'Vec3',
+      default = 'Vec3(0, 1, 0)',
+      description = 'The up vector of the viewer.'
+    }
+  },
+  returns = {
+    {
+      name = 'm',
+      type = 'Mat4',
+      description = 'The original matrix.'
+    }
+  },
+  related = {
+    'Mat4:lookAt',
+    'Quat:direction'
+  }
+}

examples/UI/Spectator_Camera/main.lua

@@ -3,8 +3,8 @@ function lovr.load()
 
   -- Precompute camera transform (could also be attached to a controller)
   local x, y, z = -3, 3, 3
-  camera = lovr.math.newMat4():lookAt(vec3(x, y, z), vec3(0, 0, 0))
-  view = lovr.math.newMat4(camera):invert()
+  camera = lovr.math.newMat4():target(vec3(x, y, z), vec3(0, 0, 0))
+  view   = lovr.math.newMat4():lookAt(vec3(x, y, z), vec3(0, 0, 0))
 end
 
 local renderScene