Pass docs; rm Getting Started image;

api/lovr/graphics/Pass/box.lua

@@ -8,8 +8,8 @@ return {
     transform = {
       type = 'Mat4',
       description = [[
-        The transform of the box.  Can also be provided as position, scale, and rotation using a mix
-        of `Vectors` or numbers.  When using numbers for the scale, 3 numbers are used.
+        The transform of the box.  Can also be provided as position, 3-component scale, and rotation
+        using a mix of `Vectors` or numbers.
       ]]
     },
     style = {

api/lovr/graphics/Pass/compute.lua

@@ -1,7 +1,11 @@
 return {
   tag = 'compute',
-  summary = 'Dispatch a compute shader.',
-  description = 'TODO',
+  summary = 'Run a compute shader.',
+  description = [[
+    Runs a compute shader.  Compute shaders are run in 3D grids of workgroups.  Each workgroup is
+    itself a 3D grid of threads, declared using `local_size_x`, `local_size_y`, and `local_size_z`
+    in the shader code.
+  ]],
   arguments = {
      x = {
        type = 'number',
@@ -43,5 +47,12 @@ return {
       returns = {}
     }
   },
-  notes = 'TODO'
+  notes = [[
+    All these 3D grids can get confusing, but the basic idea is to make the local size a small block
+    of e.g. 8x8 pixels or 4x4x4 voxels, and then dispatch however many workgroups are needed to
+    cover an image or voxel field.  The reason to do it this way is that the GPU runs threads in
+    little bundles called subgroups.  Subgroups usually have 32 or 64 threads in them (the exact
+    size is given by the `subgroupSize` property of `lovr.graphics.getDevice`).  If the local size
+    was `1x1x1`, then the GPU would only run 1 thread per subgroup and waste the other 31 or 63.
+  ]]
 }

api/lovr/graphics/Pass/copy.lua

@@ -1,156 +1,169 @@
 return {
   tag = 'transfer',
   summary = 'Copy data to or between GPU resources.',
-  description = 'TODO',
+  description = [[
+    Copies data to or between `Buffer` and `Texture` objects.  This function must be called on a
+    `transfer` pass.
+  ]],
   arguments = {
     table = {
       type = 'table',
-      description = 'TODO'
+      description = 'A table to copy to the buffer.'
     },
     blob = {
       type = 'Blob',
-      description = 'TODO'
+      description = 'A blob to copy to the buffer.'
     },
     buffersrc = {
       type = 'Buffer',
-      description = 'TODO'
+      description = 'A buffer to copy to the buffer.'
     },
     image = {
       type = 'Image',
-      description = 'TODO'
+      description = 'An image to copy to the texture.'
     },
     texturesrc = {
       type = 'Texture',
-      description = 'TODO'
+      description = 'A texture to copy to the texture.'
     },
     tally = {
       type = 'Tally',
-      description = 'TODO'
+      description = 'A tally to copy to the buffer.'
     },
     bufferdst = {
       type = 'Buffer',
-      description = 'TODO'
+      description = 'The buffer to copy to.'
     },
     texturedst = {
       type = 'Texture',
-      description = 'TODO'
+      description = 'The texture to copy to.'
     },
     srcindex = {
       type = 'number',
       default = '1',
-      description = 'TODO'
+      description = 'The index of the first item to begin copying from.'
     },
     dstindex = {
       type = 'number',
       default = '1',
-      description = 'TODO'
+      description = 'The index of the first item in the buffer to begin copying to.'
     },
     srcoffset = {
       type = 'number',
       default = '0',
-      description = 'TODO'
+      description = 'A byte offset to begin copying from.'
     },
     dstoffset = {
       type = 'number',
       default = '0',
-      description = 'TODO'
+      description = 'A byte offset in the buffer to begin copying to.'
     },
     count = {
       type = 'number',
       default = 'nil',
-      description = 'TODO'
+      description = 'The number of items to copy.  If nil, copies as many items as possible.'
     },
     size = {
       type = 'number',
       default = 'nil',
-      description = 'TODO'
+      description = 'The number of bytes to copy.  If nil, copies as many bytes as possible.'
     },
     srcx = {
       type = 'number',
       default = '0',
-      description = 'TODO'
+      description = 'The x offset of the region in the source texture to copy.'
     },
     srcy = {
       type = 'number',
       default = '0',
-      description = 'TODO'
+      description = 'The y offset of the region in the source texture to copy.'
     },
     dstx = {
       type = 'number',
       default = '0',
-      description = 'TODO'
+      description = 'The x offset of the region in the destination texture to copy to.'
     },
     dsty = {
       type = 'number',
       default = '0',
-      description = 'TODO'
+      description = 'The y offset of the region in the destination texture to copy to.'
     },
     width = {
       type = 'number',
       default = 'nil',
-      description = 'TODO'
+      description = [[
+        The width of the region to copy.  If nil, makes the region as wide as possible.
+      ]]
     },
     height = {
       type = 'number',
       default = 'nil',
-      description = 'TODO'
+      description = [[
+        The height of the region to copy.  If nil, makes the region as tall as possible.
+      ]]
     },
     srclayer = {
       type = 'number',
       default = '1',
-      description = 'TODO'
+      description = 'The index of the first layer in the source texture to copy.'
     },
     dstlayer = {
       type = 'number',
       default = '1',
-      description = 'TODO'
+      description = 'The index of the layer in the destination texture to copy to.'
     },
     layers = {
       type = 'number',
       default = 'nil',
-      description = 'TODO'
+      description = 'The number of layers to copy.  If nil, copies as many layers as possible.'
     },
     srclevel = {
       type = 'number',
       default = '1',
-      description = 'TODO'
+      description = 'The index of the mipmap level in the source texture to copy.'
     },
     dstlevel = {
       type = 'number',
       default = '1',
-      description = 'TODO'
+      description = 'The index of the mipmap level in the destination texture to copy to.'
     }
   },
   returns = {},
   variants = {
     {
-      description = 'Copy table data to a Buffer.',
+      description = 'Copy a table to a Buffer.',
       arguments = { 'table', 'bufferdst', 'srcindex', 'dstindex', 'count' },
       returns = {}
     },
     {
-      description = 'Copy binary data to a Buffer.',
+      description = 'Copy a Blob to a Buffer.',
       arguments = { 'blob', 'bufferdst', 'srcoffset', 'dstoffset', 'size' },
       returns = {}
     },
     {
-      description = 'Copy data between Buffers.',
+      description = 'Copy a Buffer to a Buffer.',
       arguments = { 'buffersrc', 'bufferdst', 'srcoffset', 'dstoffset', 'size' },
       returns = {}
     },
     {
-      description = 'Copy Image data to a Texture.',
+      description = 'Copy an Image to a Texture.',
       arguments = { 'image', 'texturedst', 'srcx', 'srcy', 'dstx', 'dsty', 'width', 'height', 'srclayer', 'dstlayer', 'layers', 'srclevel', 'dstlevel' },
       returns = {}
     },
     {
-      description = 'Copy data between Textures.',
+      description = 'Copy a Texture to a Texture.',
       arguments = { 'texturesrc', 'texturedst', 'srcx', 'srcy', 'dstx', 'dsty', 'width', 'height', 'srclayer', 'dstlayer', 'layers', 'srclevel', 'dstlevel' },
       returns = {}
     },
     {
-      description = 'Copy tally data to a Buffer.',
-      arguments = { 'tally', 'srcindex', 'dstoffset', 'count' },
+      description = [[
+        Copy a Tally to a Buffer.  The size of each item depends on what the tally is measuring:
+
+        - `time` tally slots are a single 4-byte unsigned integer.
+        - `shader` tally slots are four 4-byte unsigned integers (16 bytes).
+        - `pixel` tally slots are a single 4-byte unsigned integer.
+      ]],
+      arguments = { 'tally', 'bufferdst', 'srcindex', 'dstoffset', 'count' },
       returns = {}
     }
   }

api/lovr/graphics/Pass/cube.lua

@@ -6,8 +6,8 @@ return {
     transform = {
       type = 'Mat4',
       description = [[
-        The transform of the cube.  Can also be provided as position, scale, and rotation using a
-        mix of `Vectors` or numbers.  When using numbers for the scale, 1 number is used.
+        The transform of the cube.  Can also be provided as position, 1-component scale, and
+        rotation using a mix of `Vectors` or numbers.
       ]]
     },
     style = {

api/lovr/graphics/Pass/draw.lua

@@ -1,31 +1,38 @@
 return {
   tag = 'drawing',
-  summary = 'Draw a drawable object.',
-  description = 'TODO',
+  summary = 'Draw a model.',
+  description = 'Draws a model.',
   arguments = {
-    transform = {
-      type = 'Transform',
-      description = 'The transform of the object.'
-    },
     model = {
       type = 'Model',
       description = 'The model to draw.'
     },
+    transform = {
+      type = 'Mat4',
+      description = [[
+        The transform of the model.  Can also be provided as a position, 1-component scale, and
+        rotation using a combination of `Vectors` and numbers.
+      ]]
+    },
     nodeindex = {
       type = 'number',
-      description = 'TODO'
+      default = 'nil',
+      description = 'The index of the node to draw.  If nil, the root node is drawn.'
     },
     nodename = {
       type = 'string',
-      description = 'TODO'
+      default = 'nil',
+      description = 'The name of the node to draw.  If nil, the root node is drawn.'
     },
     children = {
       type = 'boolean',
-      description = 'TODO'
+      default = 'true',
+      description = 'Whether the children of the node should be drawn.'
     },
     instances = {
       type = 'number',
-      description = 'TODO'
+      default = '1',
+      description = 'The number of instances to draw.'
     }
   },
   returns = {},

api/lovr/graphics/Pass/getClear.lua

@@ -1,11 +1,15 @@
 return {
-  summary = 'TODO',
-  description = 'TODO',
+  summary = 'Return the clear values of the Pass.',
+  description = 'Returns the clear values of the pass.',
   arguments = {},
   returns = {
     clears = {
       type = 'table',
-      description = 'TODO'
+      description = [[
+        The clear values for the pass.  Numeric keys will contain clear values for color textures,
+        either as a table of r, g, b, a values or a boolean.  If the pass has a depth texture, there
+        will also be `depth` and `stencil` keys containing the clear values or booleans.
+      ]]
     }
   },
   variants = {
@@ -14,5 +18,7 @@ return {
       returns = { 'clears' }
     }
   },
-  notes = 'TODO'
+  related = {
+    'Pass:getTarget'
+  }
 }

api/lovr/graphics/Pass/getTarget.lua

@@ -1,11 +1,14 @@
 return {
-  summary = 'TODO',
-  description = 'TODO',
+  summary = 'Get the textures a render pass is rendering to.',
+  description = 'Returns the textures a render pass is rendering to.',
   arguments = {},
   returns = {
     target = {
       type = 'table',
-      description = 'TODO'
+      description = [[
+        A table of the color textures targeted by the pass, with an additional `depth` key if the
+        pass has a depth texture.
+      ]]
     }
   },
   variants = {
@@ -13,5 +16,8 @@ return {
       arguments = {},
       returns = { 'target' }
     }
+  },
+  related = {
+    'Pass:getClear'
   }
 }

api/lovr/graphics/newShader.lua

@@ -1,19 +1,36 @@
 return {
   tag = 'graphics-objects',
-  summary = 'Create a Shader.',
-  description = 'TODO',
+  summary = 'Create a new Shader.',
+  description = [[
+    Creates a Shader, which is a small program that runs on the GPU.
+
+    Shader code is usually written in GLSL and compiled to SPIR-V bytecode.  SPIR-V is faster to
+    load but requires a build step.  Either form can be used to create a shader.
+  ]],
   arguments = {
     vertex = {
-      type = 'ShaderSource',
-      description = 'TODO'
+      type = 'string',
+      description = [[
+        A string, path to a file, or Blob containing GLSL or SPIR-V code for the vertex stage.  Can
+        also be a `DefaultShader` to use that shader's vertex code.
+      ]]
     },
     fragment = {
-      type = 'ShaderSource',
-      description = 'TODO'
+      type = 'string',
+      description = [[
+        A string, path to a file, or Blob containing GLSL or SPIR-V code for the fragment stage.
+        Can also be a `DefaultShader` to use that shader's fragment code.
+      ]]
     },
     compute = {
-      type = 'ShaderSource',
-      description = 'TODO'
+      type = 'string',
+      description = [[
+        A string, path to a file, or Blob containing GLSL or SPIR-V code for the compute stage.
+      ]]
+    },
+    default = {
+      type = 'DefaultShader',
+      description = 'The default shader to use.'
     },
     options = {
       type = 'table',
@@ -22,7 +39,11 @@ return {
         {
           name = 'flags',
           type = 'table',
-          description = 'TODO'
+          description = [[
+            A table of shader flags.  The keys of the table should be flag names or flag ID numbers.
+            The values can be numbers or booleans, depending on the type of the flag as declared in
+            the shader.
+          ]]
         },
         {
           name = 'label',
@@ -40,7 +61,10 @@ return {
   },
   variants = {
     {
-      description = 'Create a graphics shader.',
+      description = [[
+        Create a graphics shader.  It has a vertex stage that computes vertex positions, and a
+        fragment stage that computes pixel colors.
+      ]],
       arguments = { 'vertex', 'fragment', 'options' },
       returns = { 'shader' }
     },
@@ -48,9 +72,18 @@ return {
       description = 'Create a compute shader.',
       arguments = { 'compute', 'options' },
       returns = { 'shader' }
+    },
+    {
+      description = [[
+        Create a copy of one of the default shaders (used to provide different flags).
+      ]],
+      arguments = { 'default', 'options' },
+      returns = { 'shader' }
     }
   },
   related = {
-    'lovr.graphics.compileShader'
+    'lovr.graphics.compileShader',
+    'ShaderType',
+    'ShaderStage'
   }
 }

api/lovr/graphics/newTally.lua

@@ -1,7 +1,7 @@
 return {
   tag = 'graphics-objects',
   summary = 'Create a new Tally.',
-  description = 'TODO',
+  description = 'Creates a new Tally.',
   arguments = {
     type = {
       type = 'TallyType',
@@ -9,7 +9,7 @@ return {
     },
     count = {
       type = 'number',
-      description = 'The number of slots in the Tally.  Each slot performs one measurement.'
+      description = 'The number of slots in the Tally.  Each slot holds one measurement.'
     },
     views = {
       type = 'number',

guides/Getting_Started.md

@@ -1,9 +1,7 @@
 Getting Started
 ===
 
-This guide will teach you how to install LÖVR, create a project, and run it. TL;DR version:
-
-<img src="https://lovr.org/static/img/gettingStarted.png" width="400" height="515" class="flat">
+This guide will teach you how to install LÖVR, create a project, and run it.
 
 Installing LÖVR
 ---