Graphics enums; Readback;

api/lovr/graphics/BlendAlphaMode.lua

@@ -0,0 +1,28 @@
+return {
+  summary = 'Whether premultiplied alpha is enabled.',
+  description = 'Controls whether premultiplied alpha is enabled.',
+  values = {
+    {
+      name = 'alphamultiply',
+      description = 'Color channel values are multiplied by the alpha channel during blending.'
+    },
+    {
+      name = 'premultiplied',
+      description = [[
+        Color channel values are not multiplied by the alpha.  Instead, it's assumed that the colors
+        have already been multiplied by the alpha.  This should be used if the pixels being drawn
+        have already been blended, or "pre-multiplied".
+      ]]
+    }
+  },
+  notes = [[
+    The premultiplied mode should be used if pixels being drawn have already been blended, or
+    "pre-multiplied", by the alpha channel.  This happens when rendering to a texture that contains
+    pixels with transparent alpha values, since the stored color values have already been faded by
+    alpha and don't need to be faded a second time with the alphamultiply blend mode.
+  ]],
+  related = {
+    'BlendMode',
+    'Pass:setBlendMode'
+  }
+}

api/lovr/graphics/BlendMode.lua

@@ -0,0 +1,41 @@
+return {
+  summary = 'Blend modes.',
+  description = 'Different ways pixels can blend with the pixels behind them.',
+  values = {
+    {
+      name = 'alpha',
+      description = 'Colors will be mixed based on alpha.'
+    },
+    {
+      name = 'add',
+      description = 'Colors will be added to the existing color, alpha will not be changed.'
+    },
+    {
+      name = 'subtract',
+      description = 'Colors will be subtracted from the existing color, alpha will not be changed.'
+    },
+    {
+      name = 'multiply',
+      description = 'All color channels will be multiplied together, producing a darkening effect.'
+    },
+    {
+      name = 'lighten',
+      description = 'The maximum value of each color channel will be used.'
+    },
+    {
+      name = 'darken',
+      description = 'The minimum value of each color channel will be used.'
+    },
+    {
+      name = 'screen',
+      description = [[
+        The opposite of multiply: the pixel colors are inverted, multiplied, and inverted again,
+        producing a lightening effect.
+      ]]
+    }
+  },
+  related = {
+    'BlendAlphaMode',
+    'Pass:setBlendMode'
+  }
+}

api/lovr/graphics/CompareMode.lua

@@ -0,0 +1,47 @@
+return {
+  summary = 'Different ways of performing comparisons.',
+  description = [[
+    The method used to compare depth and stencil values when performing the depth and stencil tests.
+    Also used for compare modes in `Sampler`s.
+  ]],
+  values = {
+    {
+      name = 'none',
+      description = 'The test does not take place, and acts as though it always passes.'
+    },
+    {
+      name = 'equal',
+      description = 'The test passes if the values are equal.'
+    },
+    {
+      name = 'notequal',
+      description = 'The test passes if the values are not equal.'
+    },
+    {
+      name = 'less',
+      description = 'The test passes if the value is less than the existing one.'
+    },
+    {
+      name = 'lequal',
+      description = 'The test passes if the value is less than or equal to the existing one.'
+    },
+    {
+      name = 'greater',
+      description = 'The test passes if the value is greater than the existing one.'
+    },
+    {
+      name = 'gequal',
+      description = 'The test passes if the value is greater than or equal to the existing one.'
+    },
+  },
+  notes = [[
+    This type can also be specified using mathematical notation, e.g. `=`, `>`, `<=`, etc.
+    `notequal` can be provided as `~=` or `!=`.
+  ]],
+  related = {
+    'Pass:setDepthTest',
+    'Pass:setStencilTest',
+    'Pass:setDepthWrite',
+    'Pass:setStencilWrite'
+  }
+}

api/lovr/graphics/CullMode.lua

@@ -0,0 +1,23 @@
+return {
+  summary = 'Different ways of doing face culling.',
+  description = 'The different ways of doing triangle backface culling.',
+  values = {
+    {
+      name = 'none',
+      description = 'Both sides of triangles will be drawn.'
+    },
+    {
+      name = 'back',
+      description = 'Skips rendering the back side of triangles.'
+    },
+    {
+      name = 'front',
+      description = 'Skips rendering the front side of triangles.'
+    }
+  },
+  related = {
+    'Winding',
+    'Pass:setCullMode',
+    'Pass:setWinding'
+  }
+}

api/lovr/graphics/DefaultShader.lua

@@ -0,0 +1,35 @@
+return {
+  summary = 'Built-in shaders.',
+  description = [[
+    The set of shaders built in to LÖVR.  These can be passed to `Pass:setShader` or
+    `lovr.graphics.newShader` instead of writing GLSL code.  The shaders can be further customized
+    by using the `flags` to change their behavior.  If the active shader is set to `nil`, LÖVR picks
+    one of these shaders to use.
+  ]],
+  values = {
+    {
+      name = 'unlit',
+      description = 'Basic shader without lighting that uses colors and a texture.'
+    },
+    {
+      name = 'normal',
+      description = 'Shades triangles based on their normal, resulting in a cool rainbow effect.'
+    },
+    {
+      name = 'font',
+      description = 'Renders font glyphs.'
+    },
+    {
+      name = 'cubemap',
+      description = 'Renders cubemaps from a fullscreen triangle.'
+    },
+    {
+      name = 'equirect',
+      description = 'Renders spherical textures from a fullscreen triangle.'
+    },
+    {
+      name = 'fill',
+      description = 'Renders a fullscreen triangle, sampling from the color texture.'
+    }
+  }
+}

api/lovr/graphics/Pass/setShader.lua

@@ -50,6 +50,8 @@ return {
     buffer variable that has been cleared is not well-defined, and may return random data or even
     crash the GPU.  For textures, white pixels will be returned.  Samplers will use `linear`
     filtering and the `repeat` wrap mode.
+
+    Changing the shader will not clear push constants set in the `Constants` block.
   ]],
   related = {
     'Pass:send',

api/lovr/graphics/Pass/text.lua

@@ -1,7 +1,9 @@
 return {
   tag = 'drawing',
   summary = 'Draw text.',
-  description = 'TODO',
+  description = [[
+    Draws text.  The font can be changed using `Pass:setFont`.
+  ]],
   arguments = {
     text = {
       type = 'string',
@@ -44,12 +46,36 @@ return {
       returns = {}
     },
     {
+      description = 'Renders multicolor text with a single draw call.',
       arguments = { 'colortext', 'transform', 'wrap', 'halign', 'valign' },
       returns = {}
     }
   },
-  notes = 'TODO',
+  notes = [[
+    Strings should be encoded as UTF-8.
+
+    Newlines will start a new line of text.  Tabs will be rendered as four spaces.  Carriage returns
+    are ignored.
+
+    With the default font pixel density, a scale of 1.0 makes the text height 1 meter.
+
+    The wrap value does not take into account the text's scale.
+
+    Text rendering requires a special shader, which will only be automatically used when the active
+    shader is set to `nil`.
+
+    Blending should be enabled when rendering text (it's on by default).
+
+    This function can draw up to 16384 visible characters at a time.
+  ]],
   related = {
-    'Pass:setFont'
+    'Pass:setFont',
+    'lovr.graphics.getDefaultFont',
+    'Pass:setShader',
+    'Font:getWidth',
+    'Font:getHeight',
+    'Font:getLines',
+    'Font:getVertices',
+    'Font'
   }
 }

api/lovr/graphics/Readback/getBlob.lua

@@ -14,7 +14,7 @@ return {
       returns = { 'blob' }
     }
   },
-  notes = 'TODO what if it\'s an image?!',
+  notes = 'If the Readback is reading back a Texture, returns `nil`.',
   related = {
     'Readback:getData',
     'Readback:getImage'

api/lovr/graphics/Readback/getData.lua

@@ -5,7 +5,7 @@ return {
   returns = {
     data = {
       type = 'table',
-      description = 'A table containing the values that were read back.'
+      description = 'A flat table of numbers containing the values that were read back.'
     }
   },
   variants = {
@@ -14,7 +14,13 @@ return {
       returns = { 'data' }
     }
   },
-  notes = 'TODO what if the readback is a buffer/texture?!',
+  notes = [[
+    This currently returns `nil` for readbacks of `Buffer` and `Texture` objects.  Only readbacks of
+    `Tally` objects return valid data.
+
+    For `time` and `pixel` tallies, the table will have 1 number per slot that was read.  For
+    `shader` tallies, there will be 4 numbers for each slot.
+  ]],
   related = {
     'Readback:getBlob',
     'Readback:getImage'

api/lovr/graphics/Readback/getImage.lua

@@ -14,7 +14,7 @@ return {
       returns = { 'image' }
     }
   },
-  notes = 'TODO what if it\'s a buffer or tally?!',
+  notes = 'If the Readback is not reading back a Texture, returns `nil`.',
   related = {
     'Readback:getData',
     'Readback:getBlob'

api/lovr/graphics/Readback/init.lua

@@ -1,5 +1,8 @@
 return {
-  summary = 'TODO',
-  description = 'TODO',
+  summary = 'An asynchronous read of a GPU resource.',
+  description = [[
+    Readbacks track the progress of an asynchronous read of a `Buffer`, `Texture`, or `Tally`.  Once
+    a Readback is created, TODO
+  ]],
   constructor = 'Pass:read'
 }

api/lovr/graphics/Readback/wait.lua

@@ -15,6 +15,7 @@ return {
     }
   },
   notes = [[
-    TODO what if the readback will never complete?!
+    If the transfer pass that created the readback has not been submitted yet, no wait will occur
+    and this function will return `false`.
   ]]
 }

api/lovr/graphics/StencilAction.lua

@@ -0,0 +1,43 @@
+return {
+  summary = 'Different ways of updating the stencil buffer.',
+  description = 'Different ways of updating the stencil buffer with `Pass:setStencilWrite.',
+  values = {
+    {
+      name = 'keep',
+      description = 'Stencil buffer pixels will not be changed by draws.'
+    },
+    {
+      name = 'zero',
+      description = 'Stencil buffer pixels will be set to zero.'
+    },
+    {
+      name = 'replace',
+      description = 'Stencil buffer pixels will be replaced with a custom value.'
+    },
+    {
+      name = 'increment',
+      description = 'Stencil buffer pixels will be incremented each time they\'re rendered to.'
+    },
+    {
+      name = 'decrement',
+      description = 'Stencil buffer pixels will be decremented each time they\'re rendered to.'
+    },
+    {
+      name = 'incrementwrap',
+      description = 'Similar to increment, but will wrap around to 0 when it exceeds 255.'
+    },
+    {
+      name = 'decrementwrap',
+      description = 'Similar to decrement, but will wrap around to 255 when it goes below 0.'
+    },
+    {
+      name = 'invert',
+      description = 'The bits in the stencil buffer pixels will be inverted.'
+    }
+  },
+  related = {
+    'Pass:setStencilWrite',
+    'Pass:setStencilTest',
+    'Pass:setColorWrite'
+  }
+}