Document headset foveation;

api/init.lua

@@ -24769,6 +24769,27 @@ return {
             }
           }
         },
+        {
+          name = "FoveationLevel",
+          summary = "Different foveation levels.",
+          description = "The different levels of foveation supported by `lovr.headset.setFoveation`.",
+          key = "FoveationLevel",
+          module = "lovr.headset",
+          values = {
+            {
+              name = "low",
+              description = "Low foveation."
+            },
+            {
+              name = "medium",
+              description = "Medium foveation."
+            },
+            {
+              name = "high",
+              description = "High foveation."
+            }
+          }
+        },
         {
           name = "HeadsetDriver",
           summary = "VR APIs.",
@@ -25444,6 +25465,32 @@ return {
             }
           }
         },
+        {
+          name = "getFoveation",
+          tag = "headset",
+          summary = "Get the current foveation settings.",
+          description = "Returns the current foveation settings, previously set by `lovr.headset.setFoveation`.'",
+          key = "lovr.headset.getFoveation",
+          module = "lovr.headset",
+          notes = "Foveation is disabled by default.",
+          variants = {
+            {
+              arguments = {},
+              returns = {
+                {
+                  name = "level",
+                  type = "FoveationLevel",
+                  description = "The foveation level (or the maximum level when dynamic foveation is active)."
+                },
+                {
+                  name = "dynamic",
+                  type = "boolean",
+                  description = "Whether dynamic foveation is active, allowing the system to reduce foveation based on GPU load."
+                }
+              }
+            }
+          }
+        },
         {
           name = "getHandles",
           tag = "headset-misc",
@@ -26472,6 +26519,50 @@ return {
             }
           }
         },
+        {
+          name = "setFoveation",
+          tag = "headset",
+          summary = "Set foveated rendering settings.",
+          description = "Sets foveated rendering settings.  Currently only fixed foveated rendering is supported.  This renders the edges of the screen at a lower resolution to improve GPU performance.  Higher foveation levels will save more GPU time, but make the edges of the screen more blocky.",
+          key = "lovr.headset.setFoveation",
+          module = "lovr.headset",
+          notes = "Foveation is disabled by default.",
+          variants = {
+            {
+              arguments = {
+                {
+                  name = "level",
+                  type = "FoveationLevel",
+                  description = "The foveation level (or the maximum level when dynamic foveation is active)."
+                },
+                {
+                  name = "dynamic",
+                  type = "boolean",
+                  description = "Whether the system is allowed to dynamically adjust the foveation level based on GPU load.",
+                  default = "true"
+                }
+              },
+              returns = {
+                {
+                  name = "success",
+                  type = "boolean",
+                  description = "Whether foveation was enabled successfully."
+                }
+              }
+            },
+            {
+              description = "Disables foveation.",
+              arguments = {},
+              returns = {
+                {
+                  name = "success",
+                  type = "boolean",
+                  description = "Whether foveation was enabled successfully."
+                }
+              }
+            }
+          }
+        },
         {
           name = "setLayers",
           tag = "layers",

api/lovr/headset/FoveationLevel.lua

@@ -0,0 +1,18 @@
+return {
+  summary = 'Different foveation levels.',
+  description = 'The different levels of foveation supported by `lovr.headset.setFoveation`.',
+  values = {
+    {
+      name = 'low',
+      description = 'Low foveation.'
+    },
+    {
+      name = 'medium',
+      description = 'Medium foveation.'
+    },
+    {
+      name = 'high',
+      description = 'High foveation.'
+    }
+  }
+}

api/lovr/headset/getFoveation.lua

@@ -0,0 +1,28 @@
+return {
+  tag = 'headset',
+  summary = 'Get the current foveation settings.',
+  description = [[
+    Returns the current foveation settings, previously set by `lovr.headset.setFoveation`.'
+  ]],
+  arguments = {},
+  returns = {
+    level = {
+      type = 'FoveationLevel',
+      description = 'The foveation level (or the maximum level when dynamic foveation is active).'
+    },
+    dynamic = {
+      type = 'boolean',
+      description = [[
+        Whether dynamic foveation is active, allowing the system to reduce foveation based on GPU
+        load.
+      ]]
+    }
+  },
+  variants = {
+    {
+      arguments = {},
+      returns = { 'level', 'dynamic' }
+    }
+  },
+  notes = 'Foveation is disabled by default.'
+}

api/lovr/headset/setFoveation.lua

@@ -0,0 +1,40 @@
+return {
+  tag = 'headset',
+  summary = 'Set foveated rendering settings.',
+  description = [[
+    Sets foveated rendering settings.  Currently only fixed foveated rendering is supported.  This
+    renders the edges of the screen at a lower resolution to improve GPU performance.  Higher
+    foveation levels will save more GPU time, but make the edges of the screen more blocky.
+  ]],
+  arguments = {
+    level = {
+      type = 'FoveationLevel',
+      description = 'The foveation level (or the maximum level when dynamic foveation is active).'
+    },
+    dynamic = {
+      type = 'boolean',
+      default = 'true',
+      description = [[
+        Whether the system is allowed to dynamically adjust the foveation level based on GPU load.
+      ]]
+    }
+  },
+  returns = {
+    success = {
+      type = 'boolean',
+      description = 'Whether foveation was enabled successfully.'
+    }
+  },
+  variants = {
+    {
+      arguments = { 'level', 'dynamic' },
+      returns = { 'success' }
+    },
+    {
+      description = 'Disables foveation.',
+      arguments = {},
+      returns = { 'success' }
+    }
+  },
+  notes = 'Foveation is disabled by default.'
+}