Lots of headset docs;

api/init.lua

@@ -17746,6 +17746,31 @@ return {
             }
           }
         },
+        {
+          name = "getDeltaTime",
+          tag = "headset",
+          summary = "Get the predicted delta time.",
+          description = "Returns the headset delta time, which is the difference between the current and previous predicted display times.  When the headset is active, this will be the `dt` value passed in to `lovr.update`.",
+          key = "lovr.headset.getDeltaTime",
+          module = "lovr.headset",
+          related = {
+            "lovr.headset.getTime",
+            "lovr.timer.getTime",
+            "lovr.timer.getDelta"
+          },
+          variants = {
+            {
+              arguments = {},
+              returns = {
+                {
+                  name = "dt",
+                  type = "number",
+                  description = "The delta time."
+                }
+              }
+            }
+          }
+        },
         {
           name = "getDisplayDimensions",
           tag = "headset",
@@ -17932,29 +17957,6 @@ return {
             }
           }
         },
-        {
-          name = "getMirrorTexture",
-          tag = "headset",
-          summary = "Get the Texture containing a view of what's in the headset.",
-          description = "Returns a Texture that contains whatever is currently rendered to the headset.\n\nSometimes this can be `nil` if the current headset driver doesn't have a mirror texture, which can happen if the driver renders directly to the display, like with the `desktop` driver.",
-          key = "lovr.headset.getMirrorTexture",
-          module = "lovr.headset",
-          related = {
-            "lovr.mirror"
-          },
-          variants = {
-            {
-              arguments = {},
-              returns = {
-                {
-                  name = "mirror",
-                  type = "Texture",
-                  description = "The mirror texture."
-                }
-              }
-            }
-          }
-        },
         {
           name = "getName",
           tag = "headset",
@@ -18245,6 +18247,31 @@ return {
             }
           }
         },
+        {
+          name = "getTexture",
+          tag = "headset",
+          summary = "Get the Texture for the headset display.",
+          description = "Returns a Texture that will be submitted to the headset display.  This will be the render target used in the headset's render pass.  The texture is not guaranteed to be the same every frame, and must be called every frame to get the current texture.",
+          key = "lovr.headset.getTexture",
+          module = "lovr.headset",
+          notes = "This function may return `nil` if the headset is not being rendered to this frame.",
+          related = {
+            "lovr.headset.getPass",
+            "lovr.mirror"
+          },
+          variants = {
+            {
+              arguments = {},
+              returns = {
+                {
+                  name = "texture",
+                  type = "Texture",
+                  description = "The headset texture."
+                }
+              }
+            }
+          }
+        },
         {
           name = "getTime",
           summary = "Get the predicted display time.",
@@ -18265,6 +18292,7 @@ return {
             }
           },
           related = {
+            "lovr.headset.getDeltaTime",
             "lovr.timer.getTime"
           }
         },
@@ -18479,6 +18507,28 @@ return {
             }
           }
         },
+        {
+          name = "isFocused",
+          summary = "Check if LÖVR has VR input focus.",
+          description = "Returns whether LÖVR has VR input focus.  Focus is lost when the VR system menu is shown.  The `lovr.focus` callback can be used to detect when this changes.",
+          key = "lovr.headset.isFocused",
+          module = "lovr.headset",
+          related = {
+            "lovr.focus"
+          },
+          variants = {
+            {
+              arguments = {},
+              returns = {
+                {
+                  name = "focused",
+                  type = "boolean",
+                  description = "Whether the application is focused."
+                }
+              }
+            }
+          }
+        },
         {
           name = "isTouched",
           tag = "input",
@@ -18593,37 +18643,6 @@ return {
             }
           }
         },
-        {
-          name = "renderTo",
-          tag = "headset",
-          summary = "Render to the headset using a function.",
-          description = "Renders to each eye of the headset using a function.\n\nThis function takes care of setting the appropriate graphics transformations to ensure that the scene is rendered as though it is being viewed through each eye of the player.  It also takes care of setting the correct projection for the headset lenses.\n\nIf the headset module is enabled, this function is called automatically by `lovr.run` with `lovr.draw` as the callback.",
-          key = "lovr.headset.renderTo",
-          module = "lovr.headset",
-          notes = "At the beginning of the callback, the display is cleared to the background color.  The background color can be changed using `lovr.graphics.setBackgroundColor`.\n\nIf the callback is `nil`, an empty frame cleared to current graphics background color will be submitted to the headset.",
-          variants = {
-            {
-              arguments = {
-                {
-                  name = "callback",
-                  type = "function",
-                  description = "The function used to render.  Any functions called will render to the headset instead of to the window.",
-                  arguments = {},
-                  returns = {},
-                  variants = {
-                    {
-                      arguments = {
-                        "callback"
-                      },
-                      returns = {}
-                    }
-                  }
-                }
-              },
-              returns = {}
-            }
-          }
-        },
         {
           name = "setClipDistance",
           tag = "headset",
@@ -18677,6 +18696,36 @@ return {
             }
           }
         },
+        {
+          name = "start",
+          summary = "Starts the headset session.",
+          description = "Starts the headset session.  This must be called after the graphics module is initialized, and can only be called once.  Normally it is called automatically by `boot.lua`.",
+          key = "lovr.headset.start",
+          module = "lovr.headset",
+          variants = {
+            {
+              arguments = {},
+              returns = {}
+            }
+          }
+        },
+        {
+          name = "submit",
+          summary = "Submit a frame to the headset display.",
+          description = "Submits the current headset texture to the VR display.  This should be called after calling `lovr.graphics.submit` with the headset render pass.  Normally this is taken care of by `lovr.run`.",
+          key = "lovr.headset.submit",
+          module = "lovr.headset",
+          related = {
+            "lovr.headset.getPass",
+            "lovr.headset.getTexture"
+          },
+          variants = {
+            {
+              arguments = {},
+              returns = {}
+            }
+          }
+        },
         {
           name = "vibrate",
           tag = "input",
@@ -30858,7 +30907,9 @@ return {
       description = "The `lovr.focus` callback is called whenever the application acquires or loses focus (for example, when opening or closing the Steam dashboard).  The callback receives a single argument, focused, which is a boolean indicating whether or not the application is now focused.  It may make sense to pause the game or reduce visual fidelity when the application loses focus.",
       key = "lovr.focus",
       module = "lovr",
-      related = {},
+      related = {
+        "lovr.headset.isFocused"
+      },
       variants = {
         {
           arguments = {

api/lovr/callbacks/focus.lua

@@ -15,5 +15,7 @@ return {
     }
   },
   returns = {},
-  related = {}
+  related = {
+    'lovr.headset.isFocused'
+  }
 }

api/lovr/headset/getDeltaTime.lua

@@ -0,0 +1,27 @@
+return {
+  tag = 'headset',
+  summary = 'Get the predicted delta time.',
+  description = [[
+    Returns the headset delta time, which is the difference between the current and previous
+    predicted display times.  When the headset is active, this will be the `dt` value passed in to
+    `lovr.update`.
+  ]],
+  arguments = {},
+  returns = {
+    dt = {
+      type = 'number',
+      description = 'The delta time.'
+    }
+  },
+  variants = {
+    {
+      arguments = {},
+      returns = { 'dt' }
+    }
+  },
+  related = {
+    'lovr.headset.getTime',
+    'lovr.timer.getTime',
+    'lovr.timer.getDelta'
+  }
+}

api/lovr/headset/getMirrorTexture.lua

@@ -1,26 +0,0 @@
-return {
-  tag = 'headset',
-  summary = 'Get the Texture containing a view of what\'s in the headset.',
-  description = [[
-    Returns a Texture that contains whatever is currently rendered to the headset.
-
-    Sometimes this can be `nil` if the current headset driver doesn't have a mirror texture, which
-    can happen if the driver renders directly to the display, like with the `desktop` driver.
-  ]],
-  arguments = {},
-  returns = {
-    mirror = {
-      type = 'Texture',
-      description = 'The mirror texture.'
-    }
-  },
-  variants = {
-    {
-      arguments = {},
-      returns = { 'mirror' }
-    }
-  },
-  related = {
-    'lovr.mirror'
-  }
-}

api/lovr/headset/getTexture.lua

@@ -0,0 +1,29 @@
+return {
+  tag = 'headset',
+  summary = 'Get the Texture for the headset display.',
+  description = [[
+    Returns a Texture that will be submitted to the headset display.  This will be the render target
+    used in the headset's render pass.  The texture is not guaranteed to be the same every frame,
+    and must be called every frame to get the current texture.
+  ]],
+  arguments = {},
+  returns = {
+    texture = {
+      type = 'Texture',
+      description = 'The headset texture.'
+    }
+  },
+  variants = {
+    {
+      arguments = {},
+      returns = { 'texture' }
+    }
+  },
+  notes = [[
+    This function may return `nil` if the headset is not being rendered to this frame.
+  ]],
+  related = {
+    'lovr.headset.getPass',
+    'lovr.mirror'
+  }
+}

api/lovr/headset/getTime.lua

@@ -25,6 +25,7 @@ return {
     that value.
   ]],
   related = {
+    'lovr.headset.getDeltaTime',
     'lovr.timer.getTime'
   }
 }

api/lovr/headset/isFocused.lua

@@ -0,0 +1,23 @@
+return {
+  summary = 'Check if LÖVR has VR input focus.',
+  description = [[
+    Returns whether LÖVR has VR input focus.  Focus is lost when the VR system menu is shown.  The
+    `lovr.focus` callback can be used to detect when this changes.
+  ]],
+  arguments = {},
+  returns = {
+    focused = {
+      type = 'boolean',
+      description = 'Whether the application is focused.'
+    }
+  },
+  variants = {
+    {
+      arguments = {},
+      returns = { 'focused' }
+    }
+  },
+  related = {
+    'lovr.focus'
+  }
+}

api/lovr/headset/renderTo.lua

@@ -1,45 +0,0 @@
-return {
-  tag = 'headset',
-  summary = 'Render to the headset using a function.',
-  description = [[
-    Renders to each eye of the headset using a function.
-
-    This function takes care of setting the appropriate graphics transformations to ensure that the
-    scene is rendered as though it is being viewed through each eye of the player.  It also takes
-    care of setting the correct projection for the headset lenses.
-
-    If the headset module is enabled, this function is called automatically by `lovr.run` with
-    `lovr.draw` as the callback.
-  ]],
-  arguments = {
-    callback = {
-      type = 'function',
-      arguments = {},
-      returns = {},
-  variants = {
-    {
-      arguments = { 'callback' },
-      returns = {}
-    }
-  },
-      description = [[
-        The function used to render.  Any functions called will render to the headset instead of to
-        the window.
-      ]]
-    }
-  },
-  returns = {},
-  variants = {
-    {
-      arguments = { 'callback' },
-      returns = {}
-    }
-  },
-  notes = [[
-    At the beginning of the callback, the display is cleared to the background color.  The
-    background color can be changed using `lovr.graphics.setBackgroundColor`.
-
-    If the callback is `nil`, an empty frame cleared to current graphics background color will be
-    submitted to the headset.
-  ]]
-}

api/lovr/headset/start.lua

@@ -0,0 +1,15 @@
+return {
+  summary = 'Starts the headset session.',
+  description = [[
+    Starts the headset session.  This must be called after the graphics module is initialized, and
+    can only be called once.  Normally it is called automatically by `boot.lua`.
+  ]],
+  arguments = {},
+  returns = {},
+  variants = {
+    {
+      arguments = {},
+      returns = {}
+    }
+  }
+}

api/lovr/headset/submit.lua

@@ -0,0 +1,20 @@
+return {
+  summary = 'Submit a frame to the headset display.',
+  description = [[
+    Submits the current headset texture to the VR display.  This should be called after calling
+    `lovr.graphics.submit` with the headset render pass.  Normally this is taken care of by
+    `lovr.run`.
+  ]],
+  arguments = {},
+  returns = {},
+  variants = {
+    {
+      arguments = {},
+      returns = {}
+    }
+  },
+  related = {
+    'lovr.headset.getPass',
+    'lovr.headset.getTexture'
+  }
+}