Graphics updates;

api/lovr/graphics/Font/getVertices.lua

@@ -0,0 +1,51 @@
+return {
+  summary = 'Get the vertices for a piece of text.',
+  description = [[
+    Returns a table of vertices for a piece of text, along with a Material to use when rendering it.
+    The Material may change over time if the Font's texture atlas needs to be resized to make room
+    for more glyphs.
+  ]],
+  arguments = {
+    {
+      name = 'text',
+      type = 'Text',
+      description = 'TODO'
+    },
+    {
+      name = 'wrap',
+      type = 'number',
+      description = 'TODO'
+    },
+    {
+      name = 'halign',
+      type = 'HorizontalAlign',
+      description = 'TODO'
+    },
+    {
+      name = 'valign',
+      type = 'VerticalAlign',
+      description = 'TODO'
+    }
+  },
+  returns = {
+    {
+      name = 'vertices',
+      type = 'table',
+      description = 'The table of vertices.  See below for the format of each vertex.'
+    },
+    {
+      name = 'material',
+      type = 'Material',
+      description = 'A Material to use when rendering the vertices.'
+    }
+  },
+  notes = [[
+    Each vertex is a table of 4 floating point numbers with the following data:
+
+        { x, y, u, v }
+
+    These could be placed in a vertex buffer using the following buffer format:
+
+        { 'vec2:VertexPosition', 'vec2:VertexUV' }
+  ]]
+}

api/lovr/graphics/Material/getProperties.lua

@@ -0,0 +1,12 @@
+return {
+  summary = 'Get the properties of the Material.',
+  description = 'Returns the properties of the Material in a table.',
+  arguments = {},
+  returns = {
+    {
+      name = 'properties',
+      type = 'table',
+      description = 'The Material properties.'
+    }
+  }
+}

api/lovr/graphics/Pass/multimesh.lua

@@ -1,42 +0,0 @@
-return {
-  tag = 'drawing',
-  summary = 'Use draw parameters stored in a Buffer to draw a mesh multiple times.',
-  description = 'TODO',
-  arguments = {
-    vertices = {
-      type = 'Buffer',
-      description = 'TODO'
-    },
-    indices = {
-      type = 'Buffer',
-      description = 'TODO'
-    },
-    draws = {
-      type = 'Buffer',
-      description = 'TODO'
-    },
-    count = {
-      type = 'number',
-      default = '1',
-      description = 'TODO'
-    },
-    offset = {
-      type = 'number',
-      default = '0',
-      description = 'TODO'
-    },
-    stride = {
-      type = 'number',
-      default = '0',
-      description = 'TODO'
-    }
-  },
-  returns = {},
-  variants = {
-    {
-      arguments = { 'vertices', 'indices', 'draws', 'count', 'offset', 'stride' },
-      returns = {}
-    }
-  },
-  notes = 'TODO'
-}

api/lovr/graphics/Pass/setVertexMode.lua → api/lovr/graphics/Pass/setMeshMode.lua

@@ -5,7 +5,7 @@ return {
   arguments = {
     {
       name = 'mode',
-      type = 'VertexMode',
+      type = 'MeshMode',
       description = 'TODO'
     }
   },

api/lovr/graphics/Readback/getBlob.lua

@@ -0,0 +1,17 @@
+return {
+  summary = 'Get Readback\'s data as a Blob.',
+  description = 'Returns the Readback\'s data as a Blob.',
+  arguments = {},
+  returns = {
+    {
+      name = 'blob',
+      type = 'Blob',
+      description = 'The Blob.'
+    }
+  },
+  notes = 'TODO what if it\'s an image?!',
+  related = {
+    'Readback:getData',
+    'Readback:getImage'
+  }
+}

api/lovr/graphics/Readback/getData.lua

@@ -0,0 +1,17 @@
+return {
+  summary = 'Get Readback\'s data as a table.',
+  description = 'Returns the data from the Readback, as a table.',
+  arguments = {},
+  returns = {
+    {
+      name = 'data',
+      type = 'table',
+      description = 'A table containing the values that were read back.'
+    }
+  },
+  notes = 'TODO what if the readback is a buffer/texture?!',
+  related = {
+    'Readback:getBlob',
+    'Readback:getImage'
+  }
+}

api/lovr/graphics/Readback/getImage.lua

@@ -0,0 +1,17 @@
+return {
+  summary = 'Get Readback\'s data as an Image.',
+  description = 'Returns the Readback\'s data as an Image.',
+  arguments = {},
+  returns = {
+    {
+      name = 'image',
+      type = 'Image',
+      description = 'The Image.'
+    }
+  },
+  notes = 'TODO what if it\'s a buffer or tally?!',
+  related = {
+    'Readback:getData',
+    'Readback:getBlob'
+  }
+}

api/lovr/graphics/Readback/init.lua

@@ -0,0 +1,5 @@
+return {
+  summary = 'TODO',
+  description = 'TODO',
+  constructor = 'Pass:read'
+}

api/lovr/graphics/Readback/isComplete.lua

@@ -0,0 +1,12 @@
+return {
+  summary = 'Check if a Readback is complete.',
+  description = 'Returns whether the Readback has completed on the GPU and its data is available.',
+  arguments = {},
+  returns = {
+    {
+      name = 'complete',
+      type = 'boolean',
+      description = 'Whether the readback is complete.'
+    }
+  }
+}

api/lovr/graphics/Readback/wait.lua

@@ -0,0 +1,15 @@
+return {
+  summary = 'Wait for the Readback to finish.',
+  description = 'Blocks the CPU until the Readback is finished on the GPU.',
+  arguments = {},
+  returns = {
+    {
+      name = 'waited',
+      type = 'boolean',
+      description = 'Whether the CPU had to be blocked for waiting.'
+    }
+  },
+  notes = [[
+    TODO what if the readback will never complete?!
+  ]]
+}

api/lovr/graphics/Shader/getWorkgroupSize.lua

@@ -0,0 +1,22 @@
+return {
+  summary = 'Get the workgroup size of a compute shader.',
+  description = 'Returns the workgroup size of a compute shader.  TODO what is it.',
+  arguments = {},
+  returns = {
+    {
+      name = 'x',
+      type = 'number',
+      description = 'The x size of a workgroup.'
+    },
+    {
+      name = 'y',
+      type = 'number',
+      description = 'The y size of a workgroup.'
+    }
+    {
+      name = 'z',
+      type = 'number',
+      description = 'The z size of a workgroup.'
+    }
+  }
+}

api/lovr/graphics/Tally/getCount.lua

@@ -0,0 +1,12 @@
+return {
+  summary = 'Get the number of slots in the Tally.',
+  description = 'Returns the number of slots in the Tally.',
+  arguments = {},
+  returns = {
+    {
+      name = 'count',
+      type = 'number',
+      description = 'The number of slots in the Tally.'
+    }
+  }
+}

api/lovr/graphics/Tally/getType.lua

@@ -0,0 +1,12 @@
+return {
+  summary = 'TODO',
+  description = 'TODO',
+  arguments = {},
+  returns = {
+    {
+      name = 'type',
+      type = 'TallyType',
+      description = 'TODO'
+    }
+  }
+}

api/lovr/graphics/Tally/getViewCount.lua

@@ -0,0 +1,15 @@
+return {
+  summary = 'Get the number of render Pass views the Tally is configured for.',
+  description = [[
+    Tally objects with the `time` type can only be used in render passes with a certain number of
+    views.  This returns that number.
+  ]],
+  arguments = {},
+  returns = {
+    {
+      name = 'views',
+      type = 'number',
+      description = 'The number of views the Tally is compatible with.'
+    }
+  }
+}

api/lovr/graphics/Tally/init.lua

@@ -0,0 +1,7 @@
+return {
+  summary = 'TODO',
+  description = 'TODO',
+  constructors = {
+    'lovr.graphics.newTally'
+  }
+}

api/lovr/graphics/TallyType.lua

@@ -0,0 +1,18 @@
+return {
+  summary = 'Different values a Tally can measure.',
+  description = 'TODO',
+  values = {
+    {
+      name = 'time',
+      description = 'Each slot measures elapsed time in nanoseconds.'
+    },
+    {
+      name = 'pixel',
+      description = 'Each slot measures the approximate number of pixels affected by rendering.'
+    },
+    {
+      name = 'shader',
+      description = 'Each slot measures the number of times different shader stages are invoked.'
+    }
+  }
+}

api/lovr/graphics/Texture/getDepth.lua

@@ -1,22 +0,0 @@
-return {
-  summary = 'Get the depth of the Texture.',
-  description = [[
-    Returns the depth of the Texture.  2D textures always have a depth of 1 and cubemap textures
-    always have a depth of 6.  For 3D and array textures, this is the number of images stored in the
-    texture.  3D textures represent a spatial 3D volume, whereas array textures are multiple layers
-    of distinct 2D images.
-  ]],
-  arguments = {},
-  returns = {
-    {
-      name = 'depth',
-      type = 'number',
-      description = 'The depth of the Texture.'
-    }
-  },
-  related = {
-    'Texture:getWidth',
-    'Texture:getHeight',
-    'Texture:getDimensions'
-  }
-}

api/lovr/graphics/Texture/getHeight.lua

@@ -11,7 +11,7 @@ return {
   },
   related = {
     'Texture:getWidth',
-    'Texture:getDepth',
+    'Texture:getLayerCount',
     'Texture:getDimensions'
   }
 }

api/lovr/graphics/Texture/getLayerCount.lua

@@ -0,0 +1,22 @@
+return {
+  summary = 'Get the layer count of the Texture.',
+  description = [[
+    Returns the layer count of the Texture.  2D textures always have 1 layer and cubemaps always
+    have 6 layers.  For 3D and array textures, this is the number of images stored in the texture.
+    3D textures represent a spatial 3D volume, whereas array textures are multiple layers of
+    distinct 2D images.
+  ]],
+  arguments = {},
+  returns = {
+    {
+      name = 'layers',
+      type = 'number',
+      description = 'The layer count of the Texture.'
+    }
+  },
+  related = {
+    'Texture:getWidth',
+    'Texture:getHeight',
+    'Texture:getDimensions'
+  }
+}

api/lovr/graphics/Texture/getWidth.lua

@@ -11,7 +11,7 @@ return {
   },
   related = {
     'Texture:getHeight',
-    'Texture:getDepth',
+    'Texture:getLayerCount',
     'Texture:getDimensions'
   }
 }

api/lovr/graphics/TextureFeature.lua

@@ -0,0 +1,44 @@
+return {
+  summary = 'Different ways Textures can be used.',
+  description = [[
+    These are the different ways `Texture` objects can be used.  These are passed in to
+    `lovr.graphics.isFormatSupported` to see which texture operations are supported by the GPU for a
+    given format.
+  ]],
+  values = {
+    {
+      name = 'sample',
+      description = [[
+        The Texture can be sampled (e.g. a `texture2D` or `sampler2D` variable in shaders).
+      ]]
+    },
+    {
+      name = 'filter',
+      description = 'The Texture can be used with a `Sampler` using a `FilterMode` of `linear`.'
+    },
+    {
+      name = 'render',
+      description = 'The Texture can be rendered to by using it as a target in a render `Pass`.'
+    },
+    {
+      name = 'blend',
+      description = 'Blending can be enabled when rendering to this format in a render pass.'
+    },
+    {
+      name = 'storage',
+      description = 'The Texture can be sent to an image variable in shaders (e.g. `image2D`).'
+    },
+    {
+      name = 'atomic',
+      description = 'Atomic operations can be used on storage textures with this format.'
+    },
+    {
+      name = 'blitsrc',
+      description = 'Source textures in `Pass:blit` can use this format.'
+    },
+    {
+      name = 'blitdst',
+      description = 'Destination textures in `Pass:blit` can use this format.'
+    }
+  }
+}

api/lovr/graphics/getBackground.lua → api/lovr/graphics/getBackgroundColor.lua

@@ -24,5 +24,6 @@ return {
       type = 'number',
       description = 'The alpha component of the background color.',
     }
-  }
+  },
+  notes = 'TODO'
 }

api/lovr/graphics/getBuffer.lua

@@ -10,9 +10,9 @@ return {
     data = {
       type = 'table',
       description = [[
-        The initial data to put into the Buffer.  The length of the table will be used as the length
-        of the Buffer.  Note: this means the table should only contain nested tables or
-        individual number/vector elements, which is less flexible than `Buffer:setData`.
+        The initial data to put into the Buffer.  The length of the Buffer will be determined by the
+        contents of the table.  The contents can be a mix of tables, numbers, and vectors, but the
+        length calculation requires each field to consistently use one type of data.
       ]]
     },
     blob = {

api/lovr/graphics/getDefaultFont.lua

@@ -1,7 +1,7 @@
 return {
   summary = 'Get the default Font.',
   description = [[
-    Returns the default Font.  The default font is Varela Round, created at 24px with a spread value
+    Returns the default Font.  The default font is Varela Round, created at 32px with a spread value
     of `4.0`.  It's used by `Pass:text` if no Font is provided.
   ]],
   arguments = {},

api/lovr/graphics/getLimits.lua

@@ -132,12 +132,12 @@ return {
           ]]
         },
         {
-          name = 'computeDispatchCount',
+          name = 'workgroupCount',
           type = 'table',
           description = 'The maximum values of `x`, `y`, and `z` in `Pass:compute`.'
         },
         {
-          name = 'computeWorkgroupSize',
+          name = 'workgroupSize',
           type = 'table',
           description = [[
             The maximum values of `local_size_x`, `local_size_y`, and `local_size_z` declared in a
@@ -145,7 +145,7 @@ return {
           ]]
         },
         {
-          name = 'computeWorkgroupVolume',
+          name = 'totalWorkgroupSize',
           type = 'number',
           description = [[
             The maximum product of `local_size_x`, `local_size_y`, and `local_size_z` in a compute

api/lovr/graphics/getWindowPass.lua

@@ -0,0 +1,22 @@
+return {
+  summary = 'Get the window pass.',
+  description = [[
+    Returns the window pass.  This is a builtin render `Pass` object that renders to the desktop
+    window texture.  If the desktop window was not open when the graphics module was initialized,
+    this function will return `nil`.
+  ]],
+  arguments = {},
+  returns = {
+    {
+      name = 'pass',
+      type = 'Pass',
+      description = 'The window pass, or `nil` if there is no window.'
+    }
+  },
+  notes = [[
+    - TODO is the same pass always returned
+    - TODO does the texture change
+    - TODO what settings does the Pass use (incl conf.lua)
+    - TODO is it reset
+  ]]
+}

api/lovr/graphics/newBuffer.lua

@@ -10,9 +10,9 @@ return {
     data = {
       type = 'table',
       description = [[
-        The initial data to put into the Buffer.  The length of the table will be used as the length
-        of the Buffer.  Note: this means the table should only contain nested tables or
-        individual number/vector elements, which is less flexible than `Buffer:setData`.
+        The initial data to put into the Buffer.  The length of the Buffer will be determined by the
+        contents of the table.  The contents can be a mix of tables, numbers, and vectors, but the
+        length calculation requires each field to consistently use one type of data.
       ]]
     },
     blob = {

api/lovr/graphics/getPass.lua → api/lovr/graphics/newPass.lua

@@ -1,6 +1,6 @@
 return {
   tag = 'graphics-objects',
-  summary = 'Get a new Pass.',
+  summary = 'Create a new Pass.',
   description = 'TODO',
   arguments = {
     type = {
@@ -37,10 +37,6 @@ return {
           description = 'TODO'
         }
       }
-    },
-    label = {
-      type = 'string',
-      description = 'TODO'
     }
   },
   returns = {
@@ -51,19 +47,22 @@ return {
   },
   variants = {
     {
-      arguments = { 'type', 'label' },
+      arguments = { 'type' },
       returns = { 'pass' }
     },
     {
-      arguments = { 'type', 'texture', 'label' },
+      arguments = { 'type', 'texture' },
       returns = { 'pass' }
     },
     {
-      arguments = { 'type', 'canvas', 'label' },
+      arguments = { 'type', 'canvas' },
       returns = { 'pass' }
     }
   },
   related = {
-    'lovr.graphics.submit'
+    'lovr.graphics.submit',
+    'lovr.graphics.getWindowPass',
+    'lovr.headset.getPass',
+    'Pass:reset'
   }
 }

api/lovr/graphics/newTally.lua

@@ -0,0 +1,37 @@
+return {
+  tag = 'graphics-objects',
+  summary = 'Create a new Tally.',
+  description = 'TODO',
+  arguments = {
+    {
+      name = 'type',
+      type = 'TallyType',
+      description = 'The type of the Tally, which controls what "thing" it measures.'
+    },
+    {
+      name = 'count',
+      type = 'number',
+      description = 'The number of slots in the Tally.  Each slot performs one measurement.'
+    },
+    {
+      name = 'views',
+      type = 'number',
+      default = '2',
+      description = [[
+        Tally objects with the `time` type can only be used in render passes with a certain number
+        of views.  This is ignored for other types of tallies.
+      ]]
+    }
+  },
+  returns = {
+    {
+      name = 'tally',
+      type = 'Tally',
+      description = 'The new Tally.'
+    }
+  },
+  related = {
+    'Pass:tick',
+    'Pass:tock'
+  }
+}

api/lovr/graphics/present.lua

@@ -0,0 +1,18 @@
+return {
+  tag = 'work-submission',
+  summary = 'Update the desktop window contents.',
+  description = [[
+    Presents the window texture to the desktop window.  This function is called automatically by the
+    default implementation of `lovr.run`, so it normally does not need to be called.
+  ]],
+  arguments = {},
+  returns = {},
+  notes = [[
+    This should be called after submitting the window pass (`lovr.graphics.getWindowPass`).  If the
+    window texture has not been rendered to since the last present, this function does nothing.
+  ]],
+  related = {
+    'lovr.graphics.submit',
+    'lovr.graphics.getWindowPass'
+  }
+}

api/lovr/graphics/setBackground.lua → api/lovr/graphics/setBackgroundColor.lua

@@ -48,5 +48,6 @@ return {
       arguments = { 'color' },
       returns = {}
     }
-  }
+  },
+  notes = 'TODO'
 }

api/lovr/graphics/wait.lua

@@ -1,6 +1,6 @@
 return {
   tag = 'work-submission',
-  summary = 'Wait for the GPU to finish all submitted work.',
+  summary = 'Stalls the CPU until all submitted GPU work is finished.',
   description = 'TODO',
   arguments = {},
   returns = {},