More docs;

api/init.lua

@@ -375,7 +375,7 @@ return {
       name = "focus",
       tag = "callbacks",
       summary = "Called when the application gains or loses input focus.",
-      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.",
+      description = "The `lovr.focus` callback is called whenever the application acquires or loses focus (for example, when opening or closing the system VR menu).  The callback receives a `focused` argument, indicating whether or not the application is now focused.  Additionally, both the headset and desktop window have separate focus states, so a `display` argument indicates which display gained or lost input focus.  It may make sense to pause the game, reduce visual fidelity, or mute audio when the application loses focus.",
       key = "lovr.focus",
       module = "lovr",
       related = {
@@ -389,6 +389,11 @@ return {
               name = "focused",
               type = "boolean",
               description = "Whether the program is now focused."
+            },
+            {
+              name = "display",
+              type = "DisplayType",
+              description = "Whether the headset or desktop window changed input focus."
             }
           },
           returns = {}
@@ -970,7 +975,7 @@ return {
       name = "visible",
       tag = "callbacks",
       summary = "Called when the application gains or loses visibility.",
-      description = "The `lovr.visible` callback is called whenever the application becomes visible or invisible. `lovr.draw` may still be called even while invisible to give the VR runtime timing info.  If the VR runtime decides the application doesn't need to render anymore, LÖVR will detect this and stop calling `lovr.draw`.",
+      description = "The `lovr.visible` callback is called whenever the application becomes visible or invisible. `lovr.draw` may still be called even while invisible to give the VR runtime timing info.  If the VR runtime decides the application doesn't need to render anymore, LÖVR will detect this and stop calling `lovr.draw`.\n\nThis event is also fired when the desktop window is minimized or restored.  It's possible to distinguish between the headset and window using the `display` parameter.",
       key = "lovr.visible",
       module = "lovr",
       related = {
@@ -984,6 +989,11 @@ return {
               name = "visible",
               type = "boolean",
               description = "Whether the application is visible in the headset display."
+            },
+            {
+              name = "display",
+              type = "DisplayType",
+              description = "Whether the headset or desktop window changed visibility."
             }
           },
           returns = {}
@@ -8398,6 +8408,27 @@ return {
       description = "The `lovr.event` module handles events from the operating system.\n\nDue to its low-level nature, it's rare to use `lovr.event` in simple projects.",
       key = "lovr.event",
       enums = {
+        {
+          name = "DisplayType",
+          summary = "Distinguishes between the headset and window displays.",
+          description = "This enum is used to distinguish whether a display is the headset display or the desktop window.",
+          key = "DisplayType",
+          module = "lovr.event",
+          related = {
+            "lovr.focus",
+            "lovr.visible"
+          },
+          values = {
+            {
+              name = "headset",
+              description = "The headset."
+            },
+            {
+              name = "window",
+              description = "The desktop window."
+            }
+          }
+        },
         {
           name = "KeyCode",
           summary = "Keys that can be pressed.",
@@ -13553,8 +13584,8 @@ return {
         },
         {
           name = "newTextureView",
-          tag = "texture-view",
-          summary = "Create a texture view referencing a parent Texture.",
+          tag = "graphics-objects",
+          summary = "Create a texture view.",
           description = "Creates a new Texture view.  A texture view does not store any pixels on its own, but instead uses the pixel data of a \"parent\" Texture object.  The width, height, format, sample count, and usage flags all match the parent.  The view may have a different `TextureType`, and it may reference a subset of the parent texture's layers and mipmap levels.\n\nTexture views are used for:\n\n- Reinterpretation of texture contents.  For example, a cubemap can be treated as an array\n  texture.\n- Rendering to a particular array layer or mipmap level of a texture.\n- Binding a particular range of layers or mipmap levels to a shader.",
           key = "lovr.graphics.newTextureView",
           module = "lovr.graphics",
@@ -23595,7 +23626,8 @@ return {
           key = "Texture",
           module = "lovr.graphics",
           constructors = {
-            "lovr.graphics.newTexture"
+            "lovr.graphics.newTexture",
+            "lovr.graphics.newTextureView"
           },
           methods = {
             {
@@ -24480,10 +24512,6 @@ return {
               name = "Transfers",
               tag = "texture-transfer"
             },
-            {
-              name = "Texture Views",
-              tag = "texture-view"
-            },
             {
               name = "Sampler",
               tag = "texture-sampler"
@@ -24800,31 +24828,6 @@ return {
               description = "Color values from virtual content will be added to the real world.  This is the most common mode used for AR.  Notably, black pixels will not show up at all."
             }
           }
-        },
-        {
-          name = "ViewMask",
-          summary = "Different eyes a Layer can show up in.",
-          description = "The different eyes a Layer can show up in",
-          key = "ViewMask",
-          module = "lovr.headset",
-          related = {
-            "Layer:getViewMask",
-            "Layer:setViewMask"
-          },
-          values = {
-            {
-              name = "both",
-              description = "The layer will show up in both eyes."
-            },
-            {
-              name = "left",
-              description = "The layer will only show up in the left eye."
-            },
-            {
-              name = "right",
-              description = "The layer will only show up in the right eye."
-            }
-          }
         }
       },
       functions = {
@@ -26682,6 +26685,61 @@ return {
             "lovr.headset.newLayer"
           },
           methods = {
+            {
+              name = "getColor",
+              summary = "Get the color of the layer.",
+              description = "Returns the color of the layer.  This will tint the contents of its texture.  It can be used to fade the layer without re-rendering its texture, which is especially useful for layers created with the `static` option.",
+              key = "Layer:getColor",
+              module = "lovr.headset",
+              notes = "The default color is white (all 1s).\n\nNot every headset system supports layer colors.  See the `layerColor` property of `lovr.headset.getFeatures` to check for support.",
+              variants = {
+                {
+                  arguments = {},
+                  returns = {
+                    {
+                      name = "r",
+                      type = "number",
+                      description = "The red component of the color."
+                    },
+                    {
+                      name = "g",
+                      type = "number",
+                      description = "The green component of the color."
+                    },
+                    {
+                      name = "b",
+                      type = "number",
+                      description = "The blue component of the color."
+                    },
+                    {
+                      name = "a",
+                      type = "number",
+                      description = "The alpha component of the color."
+                    }
+                  }
+                }
+              }
+            },
+            {
+              name = "getCurve",
+              summary = "Get the curve of the layer.",
+              description = "Returns the curve of the layer.  Curving a layer renders it on a piece of a cylinder instead of a plane. The radius of the cylinder is `1 / curve` meters, so increasing the curve decreases the radius of the cylinder.",
+              key = "Layer:getCurve",
+              module = "lovr.headset",
+              notes = "When a layer is created, its curve is zero.\n\nNot every headset system supports curved layers.  See the `layerCurve` property of `lovr.headset.getFeatures` to check for support.\n\nNo matter what the curve is, the center of the layer texture will always get rendered at the layer's pose.\n\nThe largest possible curve is `2 * math.pi / width`, where `width` is the width of the layer in meters.  This would cause the cylinder to fully wrap around.",
+              variants = {
+                {
+                  arguments = {},
+                  returns = {
+                    {
+                      name = "curve",
+                      type = "number",
+                      description = "The curve of the layer."
+                    }
+                  }
+                }
+              }
+            },
             {
               name = "getDimensions",
               summary = "Get the size of the layer.",
@@ -26918,6 +26976,89 @@ return {
                 }
               }
             },
+            {
+              name = "setColor",
+              summary = "Set the color of the layer.",
+              description = "Sets the color of the layer.  This will tint the contents of its texture.  It can be used to fade the layer without re-rendering its texture, which is especially useful for layers created with the `static` option.",
+              key = "Layer:setColor",
+              module = "lovr.headset",
+              notes = "The default color is white (all 1s).\n\nNot every headset system supports layer colors.  See the `layerColor` property of `lovr.headset.getFeatures` to check for support.",
+              variants = {
+                {
+                  arguments = {
+                    {
+                      name = "r",
+                      type = "number",
+                      description = "The red component of the color."
+                    },
+                    {
+                      name = "g",
+                      type = "number",
+                      description = "The green component of the color."
+                    },
+                    {
+                      name = "b",
+                      type = "number",
+                      description = "The blue component of the color."
+                    },
+                    {
+                      name = "a",
+                      type = "number",
+                      description = "The alpha component of the color.",
+                      default = "1.0"
+                    }
+                  },
+                  returns = {}
+                },
+                {
+                  arguments = {
+                    {
+                      name = "t",
+                      type = "table",
+                      descriptioin = "A table of 3 or 4 color components."
+                    }
+                  },
+                  returns = {}
+                },
+                {
+                  arguments = {
+                    {
+                      name = "hex",
+                      type = "number",
+                      description = "A hexcode."
+                    },
+                    {
+                      name = "a",
+                      type = "number",
+                      description = "The alpha component of the color.",
+                      default = "1.0"
+                    }
+                  },
+                  returns = {}
+                }
+              }
+            },
+            {
+              name = "setCurve",
+              summary = "Set the curve of the layer.",
+              description = "Sets the curve of the layer.  Curving a layer renders it on a piece of a cylinder instead of a plane. The radius of the cylinder is `1 / curve` meters, so increasing the curve decreases the radius of the cylinder.",
+              key = "Layer:setCurve",
+              module = "lovr.headset",
+              notes = "When a layer is created, its curve is zero.\n\nNot every headset system supports curved layers.  See the `layerCurve` property of `lovr.headset.getFeatures` to check for support.  If curved layers are not supported, this function will do nothing.\n\nNo matter what the curve is, the center of the layer texture will always get rendered at the layer's pose.\n\nThe largest possible curve is `2 * math.pi / width`, where `width` is the width of the layer in meters.  This would cause the cylinder to fully wrap around.",
+              variants = {
+                {
+                  arguments = {
+                    {
+                      name = "curve",
+                      type = "number",
+                      description = "The curve of the layer.  Negative values or zero means no curve.",
+                      default = "0"
+                    }
+                  },
+                  returns = {}
+                }
+              }
+            },
             {
               name = "setDimensions",
               summary = "Set the size of the layer.",
@@ -44081,6 +44222,33 @@ return {
             }
           }
         },
+        {
+          name = "isWindowFocused",
+          tag = "system-window",
+          summary = "Check if the desktop window is focused.",
+          description = "Returns whether the desktop window is focused.",
+          key = "lovr.system.isWindowFocused",
+          module = "lovr.system",
+          related = {
+            "lovr.focus",
+            "lovr.headset.isFocused",
+            "lovr.system.openWindow",
+            "lovr.system.isWindowOpen",
+            "lovr.system.isWindowVisible"
+          },
+          variants = {
+            {
+              arguments = {},
+              returns = {
+                {
+                  name = "focused",
+                  type = "boolean",
+                  description = "Whether the desktop window is focused."
+                }
+              }
+            }
+          }
+        },
         {
           name = "isWindowOpen",
           tag = "system-window",
@@ -44089,7 +44257,9 @@ return {
           key = "lovr.system.isWindowOpen",
           module = "lovr.system",
           related = {
-            "lovr.system.openWindow"
+            "lovr.system.openWindow",
+            "lovr.system.isWindowVisible",
+            "lovr.system.isWindowFocused"
           },
           variants = {
             {
@@ -44104,6 +44274,33 @@ return {
             }
           }
         },
+        {
+          name = "isWindowVisible",
+          tag = "system-window",
+          summary = "Check if the desktop window is visible.",
+          description = "Returns whether the desktop window is visible (open and not minimized).",
+          key = "lovr.system.isWindowVisible",
+          module = "lovr.system",
+          related = {
+            "lovr.visible",
+            "lovr.headset.isVisible",
+            "lovr.system.openWindow",
+            "lovr.system.isWindowOpen",
+            "lovr.system.isWindowFocused"
+          },
+          variants = {
+            {
+              arguments = {},
+              returns = {
+                {
+                  name = "visible",
+                  type = "boolean",
+                  description = "Whether the desktop window is visible."
+                }
+              }
+            }
+          }
+        },
         {
           name = "openWindow",
           tag = "system-window",

api/lovr/callbacks/focus.lua

@@ -3,20 +3,26 @@ return {
   summary = 'Called when the application gains or loses input focus.',
   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.
+    example, when opening or closing the system VR menu).  The callback receives a `focused` argument,
+    indicating whether or not the application is now focused.  Additionally, both the headset and
+    desktop window have separate focus states, so a `display` argument indicates which display
+    gained or lost input focus.  It may make sense to pause the game, reduce visual fidelity, or
+    mute audio when the application loses focus.
   ]],
   arguments = {
     focused = {
       type = 'boolean',
       description = 'Whether the program is now focused.'
+    },
+    display = {
+      type = 'DisplayType',
+      description = 'Whether the headset or desktop window changed input focus.'
     }
   },
   returns = {},
   variants = {
     {
-      arguments = { 'focused' },
+      arguments = { 'focused', 'display' },
       returns = {}
     }
   },

api/lovr/callbacks/visible.lua

@@ -6,17 +6,24 @@ return {
     `lovr.draw` may still be called even while invisible to give the VR runtime timing info.  If the
     VR runtime decides the application doesn't need to render anymore, LÖVR will detect this and
     stop calling `lovr.draw`.
+
+    This event is also fired when the desktop window is minimized or restored.  It's possible to
+    distinguish between the headset and window using the `display` parameter.
   ]],
   arguments = {
     visible = {
       type = 'boolean',
       description = 'Whether the application is visible in the headset display.'
+    },
+    display = {
+      type = 'DisplayType',
+      description = 'Whether the headset or desktop window changed visibility.'
     }
   },
   returns = {},
   variants = {
     {
-      arguments = { 'visible' },
+      arguments = { 'visible', 'display' },
       returns = {}
     }
   },

api/lovr/event/DisplayType.lua

@@ -0,0 +1,20 @@
+return {
+  summary = 'Distinguishes between the headset and window displays.',
+  description = [[
+    This enum is used to distinguish whether a display is the headset display or the desktop window.
+  ]],
+  values = {
+    {
+      name = 'headset',
+      description = 'The headset.'
+    },
+    {
+      name = 'window',
+      description = 'The desktop window.'
+    }
+  },
+  related = {
+    'lovr.focus',
+    'lovr.visible'
+  }
+}

api/lovr/graphics/Texture/init.lua

@@ -6,7 +6,8 @@ return {
     textures loaded from images provide surface data to `Material` objects.
   ]],
   constructors = {
-    'lovr.graphics.newTexture'
+    'lovr.graphics.newTexture',
+    'lovr.graphics.newTextureView'
   },
   sections = {
     {
@@ -17,10 +18,6 @@ return {
       name = 'Transfers',
       tag = 'texture-transfer'
     },
-    {
-      name = 'Texture Views',
-      tag = 'texture-view'
-    },
     {
       name = 'Sampler',
       tag = 'texture-sampler'

api/lovr/graphics/newTextureView.lua

@@ -1,6 +1,6 @@
 return {
-  tag = 'texture-view',
-  summary = 'Create a texture view referencing a parent Texture.',
+  tag = 'graphics-objects',
+  summary = 'Create a texture view.',
   description = [[
     Creates a new Texture view.  A texture view does not store any pixels on its own, but instead
     uses the pixel data of a "parent" Texture object.  The width, height, format, sample count, and

api/lovr/headset/Layer/getColor.lua

@@ -0,0 +1,39 @@
+return {
+  summary = 'Get the color of the layer.',
+  description = [[
+    Returns the color of the layer.  This will tint the contents of its texture.  It can be used to
+    fade the layer without re-rendering its texture, which is especially useful for layers created
+    with the `static` option.
+  ]],
+  arguments = {},
+  returns = {
+    r = {
+      type = 'number',
+      description = 'The red component of the color.'
+    },
+    g = {
+      type = 'number',
+      description = 'The green component of the color.'
+    },
+    b = {
+      type = 'number',
+      description = 'The blue component of the color.'
+    },
+    a = {
+      type = 'number',
+      description = 'The alpha component of the color.'
+    }
+  },
+  variants = {
+    {
+      arguments = {},
+      returns = { 'r', 'g', 'b', 'a' }
+    }
+  },
+  notes = [[
+    The default color is white (all 1s).
+
+    Not every headset system supports layer colors.  See the `layerColor` property of
+    `lovr.headset.getFeatures` to check for support.
+  ]]
+}

api/lovr/headset/Layer/getCurve.lua

@@ -0,0 +1,33 @@
+return {
+  summary = 'Get the curve of the layer.',
+  description = [[
+    Returns the curve of the layer.  Curving a layer renders it on a piece of a cylinder instead of
+    a plane. The radius of the cylinder is `1 / curve` meters, so increasing the curve decreases the
+    radius of the cylinder.
+  ]],
+  arguments = {},
+  returns = {
+    curve = {
+      type = 'number',
+      description = 'The curve of the layer.'
+    }
+  },
+  variants = {
+    {
+      arguments = {},
+      returns = { 'curve' }
+    }
+  },
+  notes = [[
+    When a layer is created, its curve is zero.
+
+    Not every headset system supports curved layers.  See the `layerCurve` property of
+    `lovr.headset.getFeatures` to check for support.
+
+    No matter what the curve is, the center of the layer texture will always get rendered at the
+    layer's pose.
+
+    The largest possible curve is `2 * math.pi / width`, where `width` is the width of the layer in
+    meters.  This would cause the cylinder to fully wrap around.
+  ]]
+}

api/lovr/headset/Layer/setColor.lua

@@ -0,0 +1,56 @@
+return {
+  summary = 'Set the color of the layer.',
+  description = [[
+    Sets the color of the layer.  This will tint the contents of its texture.  It can be used to
+    fade the layer without re-rendering its texture, which is especially useful for layers created
+    with the `static` option.
+  ]],
+  arguments = {
+    r = {
+      type = 'number',
+      description = 'The red component of the color.'
+    },
+    g = {
+      type = 'number',
+      description = 'The green component of the color.'
+    },
+    b = {
+      type = 'number',
+      description = 'The blue component of the color.'
+    },
+    a = {
+      type = 'number',
+      default = '1.0',
+      description = 'The alpha component of the color.'
+    },
+    t = {
+      type = 'table',
+      descriptioin = 'A table of 3 or 4 color components.'
+    },
+    hex = {
+      type = 'number',
+      description = 'A hexcode.'
+    }
+  },
+  returns = {},
+  variants = {
+    {
+      arguments = { 'r', 'g', 'b', 'a' },
+      returns = {}
+    },
+    {
+      arguments = { 't' },
+      returns = {}
+    },
+    {
+      arguments = { 'hex', 'a' },
+      returns = {}
+    }
+  },
+  notes = [[
+    The default color is white (all 1s).
+
+    Not every headset system supports layer colors.  See the `layerColor` property of
+    `lovr.headset.getFeatures` to check for support.
+  ]]
+}

api/lovr/headset/Layer/setCurve.lua

@@ -0,0 +1,35 @@
+return {
+  summary = 'Set the curve of the layer.',
+  description = [[
+    Sets the curve of the layer.  Curving a layer renders it on a piece of a cylinder instead of a
+    plane. The radius of the cylinder is `1 / curve` meters, so increasing the curve decreases the
+    radius of the cylinder.
+  ]],
+  arguments = {
+    curve = {
+      type = 'number',
+      default = '0',
+      description = 'The curve of the layer.  Negative values or zero means no curve.'
+    }
+  },
+  returns = {},
+  variants = {
+    {
+      arguments = { 'curve' },
+      returns = {}
+    }
+  },
+  notes = [[
+    When a layer is created, its curve is zero.
+
+    Not every headset system supports curved layers.  See the `layerCurve` property of
+    `lovr.headset.getFeatures` to check for support.  If curved layers are not supported, this
+    function will do nothing.
+
+    No matter what the curve is, the center of the layer texture will always get rendered at the
+    layer's pose.
+
+    The largest possible curve is `2 * math.pi / width`, where `width` is the width of the layer in
+    meters.  This would cause the cylinder to fully wrap around.
+  ]]
+}

api/lovr/headset/ViewMask.lua

@@ -1,22 +0,0 @@
-return {
-  summary = 'Different eyes a Layer can show up in.',
-  description = 'The different eyes a Layer can show up in',
-  values = {
-    {
-      name = 'both',
-      description = 'The layer will show up in both eyes.'
-    },
-    {
-      name = 'left',
-      description = 'The layer will only show up in the left eye.'
-    },
-    {
-      name = 'right',
-      description = 'The layer will only show up in the right eye.'
-    }
-  },
-  related = {
-    'Layer:getViewMask',
-    'Layer:setViewMask'
-  }
-}

api/lovr/system/isWindowFocused.lua

@@ -0,0 +1,25 @@
+return {
+  tag = 'system-window',
+  summary = 'Check if the desktop window is focused.',
+  description = 'Returns whether the desktop window is focused.',
+  arguments = {},
+  returns = {
+    focused = {
+      type = 'boolean',
+      description = 'Whether the desktop window is focused.'
+    }
+  },
+  variants = {
+    {
+      arguments = {},
+      returns = { 'focused' }
+    }
+  },
+  related = {
+    'lovr.focus',
+    'lovr.headset.isFocused',
+    'lovr.system.openWindow',
+    'lovr.system.isWindowOpen',
+    'lovr.system.isWindowVisible'
+  }
+}

api/lovr/system/isWindowOpen.lua

@@ -20,6 +20,8 @@ return {
     }
   },
   related = {
-    'lovr.system.openWindow'
+    'lovr.system.openWindow',
+    'lovr.system.isWindowVisible',
+    'lovr.system.isWindowFocused'
   }
 }

api/lovr/system/isWindowVisible.lua

@@ -0,0 +1,25 @@
+return {
+  tag = 'system-window',
+  summary = 'Check if the desktop window is visible.',
+  description = 'Returns whether the desktop window is visible (open and not minimized).',
+  arguments = {},
+  returns = {
+    visible = {
+      type = 'boolean',
+      description = 'Whether the desktop window is visible.'
+    }
+  },
+  variants = {
+    {
+      arguments = {},
+      returns = { 'visible' }
+    }
+  },
+  related = {
+    'lovr.visible',
+    'lovr.headset.isVisible',
+    'lovr.system.openWindow',
+    'lovr.system.isWindowOpen',
+    'lovr.system.isWindowFocused'
+  }
+}

api/main.lua

@@ -365,7 +365,7 @@ local function validateObject(object)
         end
       end
 
-      warnIf(not found, '%s is missing a parent link/tag', method.key)
+      warnIf(not found, '%s is missing from its parent\'s page', method.key)
     end
   end
 
@@ -438,9 +438,15 @@ local function validateModule(module)
     end
   end
 
+  local ignore = {
+    setSource = true,
+    getBundlePath = true,
+    openConsole = true
+  }
+
   for name in pairs(t or {}) do
     local key = ('%s.%s'):format(module.key, name)
-    warnIf(not lookup[key], 'Missing docs for %s', key)
+    warnIf(not ignore[name] and not lookup[key], 'Missing docs for %s', key)
   end
 
   for _, fn in ipairs(module.enums) do