Clarify Pass:setDepthOffset;

api/init.lua

@@ -20607,10 +20607,10 @@ return {
               name = "setDepthOffset",
               tag = "pipeline",
               summary = "Configure the depth offset.",
-              description = "Set the depth offset.  This is a constant offset added to the depth value of pixels.  It can be used to fix Z fighting when rendering decals or other nearly-overlapping objects.",
+              description = "Set the depth offset.  This is a constant offset added to the depth value of pixels, as well as a \"sloped\" depth offset that is scaled based on the \"slope\" of the depth at the pixel.\n\nThis can be used to fix Z fighting when rendering decals or other nearly-overlapping objects, and is also useful for shadow biasing when implementing shadow mapping.",
               key = "Pass:setDepthOffset",
               module = "lovr.graphics",
-              notes = "The default depth offset is zero for both values.",
+              notes = "The default depth offset is zero for both values.\n\nThis only applies to triangles, not points or lines.\n\nThe units for these offsets aren't specified very well -- they depend on the format of the depth texture, and the GPU can use them slightly differently for its depth calculations.  However, an `offset` of 1 will roughly correspond to the smallest-possible depth difference (e.g. 2^-16 for a `d16` depth texture).\n\nThe sloped depth scale is multiplied by the slope of the depth of the triangle.  For example, if pixels in the triangle all have the same depth (i.e. the triangle is facing the camera), then the slope of the depth will be zero and the sloped depth offset won't have any effect.  As the triangle starts to face away from the camera, the slope of the depth will increase and the sloped depth offset will begin to apply.  This can also be thought of corresponding to the normal vector of the triangle relative to the camera.",
               related = {
                 "Pass:setDepthTest",
                 "Pass:setDepthWrite"

api/lovr/graphics/Pass/setDepthOffset.lua

@@ -2,8 +2,11 @@ return {
   tag = 'pipeline',
   summary = 'Configure the depth offset.',
   description = [[
-    Set the depth offset.  This is a constant offset added to the depth value of pixels.  It can be
-    used to fix Z fighting when rendering decals or other nearly-overlapping objects.
+    Set the depth offset.  This is a constant offset added to the depth value of pixels, as well as
+    a "sloped" depth offset that is scaled based on the "slope" of the depth at the pixel.
+
+    This can be used to fix Z fighting when rendering decals or other nearly-overlapping objects,
+    and is also useful for shadow biasing when implementing shadow mapping.
   ]],
   arguments = {
     offset = {
@@ -24,7 +27,23 @@ return {
       returns = {}
     }
   },
-  notes = 'The default depth offset is zero for both values.',
+  notes = [[
+    The default depth offset is zero for both values.
+
+    This only applies to triangles, not points or lines.
+
+    The units for these offsets aren't specified very well -- they depend on the format of the depth
+    texture, and the GPU can use them slightly differently for its depth calculations.  However, an
+    `offset` of 1 will roughly correspond to the smallest-possible depth difference (e.g. 2^-16 for
+    a `d16` depth texture).
+
+    The sloped depth scale is multiplied by the slope of the depth of the triangle.  For example,
+    if pixels in the triangle all have the same depth (i.e. the triangle is facing the camera), then
+    the slope of the depth will be zero and the sloped depth offset won't have any effect.  As the
+    triangle starts to face away from the camera, the slope of the depth will increase and the
+    sloped depth offset will begin to apply.  This can also be thought of corresponding to the
+    normal vector of the triangle relative to the camera.
+  ]],
   related = {
     'Pass:setDepthTest',
     'Pass:setDepthWrite'