Fill out tables for graphics metadata functions;

api/lovr/graphics/Buffer/init.lua

@@ -1,6 +1,6 @@
 return {
   summary = 'A block of memory on the GPU.',
-  description = 'Put dispenser here.',
+  description = 'TODO',
   constructors = {
     'lovr.graphics.newBuffer',
     'lovr.graphics.getBuffer'

api/lovr/graphics/compute.lua

@@ -1,9 +0,0 @@
-return {
-  summary = 'Run compute shaders.',
-  description = 'Runs compute shaders.',
-  arguments = {},
-  returns = {},
-  related = {
-    'lovr.graphics.render'
-  }
-}

api/lovr/graphics/getFeatures.lua

@@ -1,16 +1,80 @@
 return {
   summary = 'Get the set of supported GPU features.',
-  description = '',
+  description = 'TODO',
   arguments = {},
   returns = {
     {
       name = 'features',
       type = 'table',
-      description = 'GPU features.'
+      description = 'Features supported by the GPU.',
+      table = {
+        {
+          name = 'bptc',
+          type = 'boolean',
+          description = 'TODO'
+        },
+        {
+          name = 'astc',
+          type = 'boolean',
+          description = 'TODO'
+        },
+        {
+          name = 'wireframe',
+          type = 'boolean',
+          description = 'TODO'
+        },
+        {
+          name = 'depthClamp',
+          type = 'boolean',
+          description = 'TODO'
+        },
+        {
+          name = 'clipDistance',
+          type = 'boolean',
+          description = 'TODO'
+        },
+        {
+          name = 'cullDistance',
+          type = 'boolean',
+          description = 'TODO'
+        },
+        {
+          name = 'fullIndexBufferRange',
+          type = 'boolean',
+          description = 'TODO'
+        },
+        {
+          name = 'indirectDrawFirstInstance',
+          type = 'boolean',
+          description = 'TODO'
+        },
+        {
+          name = 'dynamicIndexing',
+          type = 'boolean',
+          description = 'TODO'
+        },
+        {
+          name = 'float64',
+          type = 'boolean',
+          description = 'TODO'
+        },
+        {
+          name = 'int64',
+          type = 'boolean',
+          description = 'TODO'
+        },
+        {
+          name = 'int16',
+          type = 'boolean',
+          description = 'TODO'
+        }
+      }
     }
   },
   related = {
+    'lovr.graphics.isFormatSupported',
     'lovr.graphics.getHardware',
-    'lovr.graphics.getLimits'
+    'lovr.graphics.getLimits',
+    'lovr.graphics.getStats'
   }
 }

api/lovr/graphics/getHardware.lua

@@ -1,16 +1,54 @@
 return {
   summary = 'Get information about the current GPU.',
-  description = '',
+  description = 'TODO',
   arguments = {},
   returns = {
     {
       name = 'hardware',
       type = 'table',
-      description = 'GPU info.'
+      description = 'Information about the GPU device.',
+      table = {
+        {
+          name = 'id',
+          type = 'number',
+          description = 'TODO'
+        },
+        {
+          name = 'name',
+          type = 'string',
+          description = 'TODO'
+        },
+        {
+          name = 'vendor',
+          type = 'number',
+          description = 'TODO'
+        },
+        {
+          name = 'driver',
+          type = 'string',
+          description = 'TODO'
+        },
+        {
+          name = 'subgroupSize',
+          type = 'number',
+          description = 'TODO'
+        },
+        {
+          name = 'discrete',
+          type = 'boolean',
+          description = 'TODO'
+        },
+        {
+          name = 'renderer',
+          type = 'string',
+          description = 'TODO'
+        }
+      }
     }
   },
   related = {
     'lovr.graphics.getFeatures',
-    'lovr.graphics.getLimits'
+    'lovr.graphics.getLimits',
+    'lovr.graphics.getStats'
   }
 }

api/lovr/graphics/getLimits.lua

@@ -1,16 +1,131 @@
 return {
   summary = 'Get the limits of the current GPU.',
-  description = '',
+  description = 'TODO',
   arguments = {},
   returns = {
     {
       name = 'limits',
       type = 'table',
-      description = 'GPU limits.'
+      description = 'A table containing GPU limits.',
+      table = {
+        {
+          name = 'textureSize2D',
+          type = 'number',
+          description = 'TOOD'
+        },
+        {
+          name = 'textureSize3D',
+          type = 'number',
+          description = 'TODO'
+        },
+        {
+          name = 'textureSizeCube',
+          type = 'number',
+          description = 'TODO'
+        },
+        {
+          name = 'textureLayers',
+          type = 'number',
+          description = 'TODO'
+        },
+        {
+          name = 'renderSize',
+          type = 'table',
+          description = 'TODO'
+        },
+        {
+          name = 'uniformBufferRange',
+          type = 'number',
+          description = 'TODO'
+        },
+        {
+          name = 'storageBufferRange',
+          type = 'number',
+          description = 'TODO'
+        },
+        {
+          name = 'storageBufferRange',
+          type = 'number',
+          description = 'TODO'
+        },
+        {
+          name = 'uniformBufferAlign',
+          type = 'number',
+          description = 'TODO'
+        },
+        {
+          name = 'storageBufferAlign',
+          type = 'number',
+          description = 'TODO'
+        },
+        {
+          name = 'vertexAttributes',
+          type = 'number',
+          description = 'TODO'
+        },
+        {
+          name = 'vertexBufferStride',
+          type = 'number',
+          description = 'TODO'
+        },
+        {
+          name = 'vertexShaderOutputs',
+          type = 'number',
+          description = 'TODO'
+        },
+        {
+          name = 'computeDispatchCount',
+          type = 'table',
+          description = 'TODO'
+        },
+        {
+          name = 'computeWorkgroupSize',
+          type = 'table',
+          description = 'TODO'
+        },
+        {
+          name = 'computeWorkgroupVolume',
+          type = 'number',
+          description = 'TODO'
+        },
+        {
+          name = 'computeSharedMemory',
+          type = 'number',
+          description = 'TODO'
+        },
+        {
+          name = 'indirectDrawCount',
+          type = 'number',
+          description = 'TODO'
+        },
+        {
+          name = 'instances',
+          type = 'number',
+          description = 'TODO'
+        },
+        {
+          name = 'anisotropy',
+          type = 'number',
+          description = 'TODO'
+        },
+        {
+          name = 'pointSize',
+          type = 'number',
+          description = 'TODO'
+        }
+      }
+    }
+  },
+  variants = {
+    {
+      arguments = {},
+      returns = { 'limits' }
     }
   },
   related = {
+    'lovr.graphics.isFormatSupported',
     'lovr.graphics.getHardware',
-    'lovr.graphics.getFeatures'
+    'lovr.graphics.getFeatures',
+    'lovr.graphics.getStats'
   }
 }

api/lovr/graphics/getStats.lua

@@ -0,0 +1,157 @@
+return {
+  summary = 'Get graphics-related statistics.',
+  description = 'TODO',
+  arguments = {},
+  returns = {
+    {
+      name = 'stats',
+      type = 'table',
+      description = 'Graphics statistics.',
+      table = {
+        {
+          name = 'memory',
+          type = 'table',
+          description = 'TODO',
+          table = {
+            {
+              name = 'total',
+              type = 'number',
+              description = 'TODO'
+            },
+            {
+              name = 'buffer',
+              type = 'number',
+              description = 'TODO'
+            },
+            {
+              name = 'texture',
+              type = 'number',
+              description = 'TODO'
+            }
+          }
+        },
+        {
+          name = 'objects',
+          type = 'table',
+          description = 'TODO',
+          table = {
+            {
+              name = 'buffers',
+              type = 'number',
+              description = 'TODO'
+            },
+            {
+              name = 'textures',
+              type = 'number',
+              description = 'TODO'
+            },
+            {
+              name = 'samplers',
+              type = 'number',
+              description = 'TODO'
+            },
+            {
+              name = 'shaders',
+              type = 'number',
+              description = 'TODO'
+            }
+          }
+        },
+        {
+          name = 'frame',
+          type = 'table',
+          description = 'TODO',
+          table = {
+            {
+              name = 'scratchMemory',
+              type = 'number',
+              description = 'TODO'
+            },
+            {
+              name = 'renderPasses',
+              type = 'number',
+              description = 'TODO'
+            },
+            {
+              name = 'computePasses',
+              type = 'number',
+              description = 'TODO'
+            },
+            {
+              name = 'transferPasses',
+              type = 'number',
+              description = 'TODO'
+            },
+            {
+              name = 'pipelineBinds',
+              type = 'number',
+              description = 'TODO'
+            },
+            {
+              name = 'bundleBinds',
+              type = 'number',
+              description = 'TODO'
+            },
+            {
+              name = 'drawCalls',
+              type = 'number',
+              description = 'TODO'
+            },
+            {
+              name = 'dispatches',
+              type = 'number',
+              description = 'TODO'
+            },
+            {
+              name = 'workgroups',
+              type = 'number',
+              description = 'TODO'
+            },
+            {
+              name = 'copies',
+              type = 'number',
+              description = 'TODO'
+            }
+          }
+        },
+        {
+          name = 'internal',
+          type = 'table',
+          description = 'TODO',
+          table = {
+            {
+              name = 'blocks',
+              type = 'number',
+              description = 'TODO'
+            },
+            {
+              name = 'canvases',
+              type = 'number',
+              description = 'TODO'
+            },
+            {
+              name = 'pipelines',
+              type = 'number',
+              description = 'TODO'
+            },
+            {
+              name = 'layouts',
+              type = 'number',
+              description = 'TODO'
+            },
+            {
+              name = 'bunches',
+              type = 'number',
+              description = 'TODO'
+            }
+          }
+        }
+      }
+    }
+  },
+  related = {
+    'lovr.graphics.getHardware',
+    'lovr.graphics.getFeatures',
+    'lovr.graphics.getLimits'
+  }
+}

api/lovr/graphics/init.lua

@@ -2,87 +2,6 @@ return {
   tag = 'modules',
   summary = 'Renders graphics using the GPU.',
   description = [[
-    The graphics module renders graphics or performs computation using the GPU.
-
-    Work Submission
-    ---
-
-    The GPU is a separate device that runs asynchronously from the main system.  Work is sent to
-    the GPU in chunks.  A chunk of work is started using `lovr.graphics.begin`, and a chunk is
-    submitted to the GPU using `lovr.graphics.submit`.  All graphics work must happen between
-    these two calls.  Normally they are called automatically by the default main loop provided
-    by `lovr.run`, but it's possible to call them yourself to do graphics work at different
-    times, like in `lovr.update` or some other callback.
-
-    Although it's common to use a single chunk for all work in a frame, chunks do not correspond
-    to frames and the work for a frame can be submitted in multiple chunks.  The advantage of
-    this is that the GPU can start processing work for earlier chunks while more chunks are
-    being recorded.  Overlapping CPU and GPU work like this can improve performance.
-
-    There are only 3 types of work that happen within a chunk: **render**, **compute**, and
-    **transfer**.
-
-    Rendering
-    ---
-
-    The only way to render graphics is to call `lovr.graphics.render`.  This function takes a
-    render target and a set of `Batch` objects that define what should be drawn.
-
-    A render target consists of up to 4 color textures and an optional depth buffer.
-
-    Rendering to array textures with multiple layers will broadcast draws to each layer, using a
-    different camera for each view.  This can be used to efficiently render stereo, cubemaps,
-    splitscreen, or anything where the same objects need to be rendered from mulitple views.
-
-    The content to render can be provided as prerecorded `Batch` objects or as a callback
-    function that records a new temporary batch.
-
-    Compute
-    ---
-
-    Compute shaders can only be dispatched inside `lovr.graphics.compute`.  This function takes
-    a list of `Batch` objects, similar to `lovr.graphics.render`.
-
-    Inside of a call to `lovr.graphics.compute`, there is no synchronization, meaning that the
-    Batches and their compute dispatches can run in any order and are not expected to depend on
-    each other.  If a compute shader relies on results from a previous compute dispatch, they
-    should go in distinct calls to `compute`.
-
-    Transfer
-    ---
-
-    Transfer operations do not happen in a dedicated scope but are functions on the 2 GPU resources,
-    `Buffer` and `Texture` objects.  An important aspect of transfers is that they always run before
-    render and compute work in the chunk.  To interleave transfers with other work, multiple chunks
-    must be used.
-
-    Hardware Info
-    ---
-
-    There are a wide variety of GPUs, each with their own set of capabilities and limitations.  The
-    graphics module exposes information about the current GPU using 3 functions:
-
-    - `lovr.graphics.getHardware` exposes general hardware info (e.g. model number).
-    - `lovr.graphics.getFeatures` exposes features, (e.g. extra functions in shaders).
-    - `lovr.graphics.getLimits` exposes limits (e.g. maximum texture size).
-
-    Threading
-    ---
-
-    The graphics module supports multithreaded rendering.  There are some important rules to
-    follow to ensure thread safety and avoid crashes or corrupted data.
-
-    Only one chunk can be recorded at a time.  During `lovr.graphics.begin` and
-    `lovr.graphics.submit`, no other graphics work may occur on other threads.  Within a chunk,
-    graphics and compute work can be recorded on multiple threads.
-
-    Within a chunk, any number of `lovr.graphics.render` and `lovr.graphics.compute` calls can
-    be running on threads simultaneously.  Use the `order` parameter to these functions to
-    define the order that they will run in, so threads don't need to wait for each other.
-
-    A `Batch` object can only be recorded on a single thread at a time, but multiple batches can
-    be recorded in parallel and later passed to a render/compute call.
-
-    Transfers will run in any order, before all of the render and compute for the chunk.
+    The graphics module renders graphics and performs computation using the GPU.
   ]]
 }

api/lovr/graphics/isFormatSupported.lua

@@ -0,0 +1,28 @@
+return {
+  summary = 'Check if a Texture format is supported.',
+  description = 'TODO',
+  arguments = {
+    {
+      name = 'format',
+      type = 'TextureFormat',
+      description = 'TODO'
+    },
+    {
+      name = '...features',
+      type = 'TextureFeature',
+      description = 'TODO'
+    }
+  },
+  returns = {
+    {
+      name = 'supported',
+      type = 'boolean',
+      description = 'TODO'
+    }
+  },
+  related = {
+    'lovr.graphics.getHardware',
+    'lovr.graphics.getFeatures',
+    'lovr.graphics.getLimits'
+  }
+}

api/lovr/graphics/begin.lua → api/lovr/graphics/prepare.lua

@@ -1,6 +1,6 @@
 return {
-  summary = 'Begin a chunk of work.',
-  description = '',
+  summary = 'Start recording graphics work.',
+  description = 'TODO',
   arguments = {},
   returns = {},
   related = {

api/lovr/graphics/render.lua

@@ -1,101 +0,0 @@
-return {
-  summary = 'Render to a set of textures.',
-  description = [[
-    Renders to a set of textures.  Up to 4 color textures may be provided, as well as an optional
-    depth buffer.
-
-    The content to render can be provided by a callback function or a set of prerecorded `Batch`
-    objects.  When using a callback, its first argument will be a temporary Batch to fill out, which
-    will get immediately rendered.
-  ]],
-  arguments = {
-    texture = {
-      type = 'Texture',
-      description = 'A texture to render to.'
-    },
-    canvas = {
-      type = 'table',
-      description = 'A set of textures and other rendering settings.',
-      table = {}
-    },
-    ['...batches'] = {
-      type = 'Batch',
-      description = 'One or more batches to render.'
-    },
-    callback = {
-      type = 'function',
-      description = [[
-        A callback function used to record rendering work.  It will be passed a temporary Batch as
-        its single argument.  The Batch becomes invalid at the end of the callback.
-      ]]
-    },
-    order = {
-      type = 'number',
-      default = '50',
-      description = [[
-        A number from 1 to 100 used to sequence this rendering work with other work in the frame.
-        Smaller order values will run before larger values, and any render/compute work with the
-        same value will run in the order it was submitted.  This is intended to be used to order
-        work across multiple threads.
-      ]]
-    }
-  },
-  returns = {},
-  variants = {
-    {
-      arguments = { 'texture', 'callback', 'order' },
-      returns = {}
-    },
-    {
-      arguments = { 'canvas', 'callback', 'order' },
-      returns = {}
-    },
-    {
-      arguments = { 'texture', '...batches', 'order' },
-      returns = {}
-    },
-    {
-      arguments = { 'canvas', '...batches', 'order' },
-      returns = {}
-    }
-  },
-  notes = [[
-    This function must be called between `lovr.graphics.begin` and `lovr.graphics.submit`.
-
-    The special value `'window'` can be used instead of a Texture to render to the window.
-
-    The default clear for color textures will be the background color, which can be set using
-    `lovr.graphics.setBackgroundColor`.
-
-    Setting clear to `true` for either color or depth textures will leave garbage data in the
-    textures, which is the fastest way to initialize them.  Setting clear to `false` will load the
-    old data from the texture, which is very slow on mobile GPUs.
-
-    The stencil buffer is currently always cleared to zero.
-
-    A depth format can be provided instead of a Texture.  In this case, an internal temporary depth
-    buffer will be used.
-
-    It's valid to have zero color textures, but in that case a depth texture must be provided.
-
-    All textures must be created with the 'render' usage flag.  The textures must have the same
-    dimensions and sample counts, and array textures must have the same number of layers.  Textures
-    can have any renderable format and any number of mipmap levels.  It is valid to render to a view
-    of a texture.
-
-    If the textures have a single sample and the `samples` option is set to a number bigger than 1,
-    internal multisampled buffers will be used and the antialiased result will be copied to the
-    color textures once rendering is complete.
-
-    The topmost mipmap level of each texture will be rendered to.  If the `mipmaps` flag is `true`,
-    mipmaps will be regenerated for each texture once rendering is complete.
-
-    If the textures are array textures with multiple layers, draws get broadcasted to every layer.
-    Each layer can use its own camera.  The first layer uses the first camera view of the Batch, the
-    second layer uses the second view, and so on.  The maximum number of views is given by the
-    `renderViews` limit, and is currently always 6.
-  ]],
-  related = {
-    'lovr.graphics.compute'
-  }
-}

api/lovr/graphics/submit.lua

@@ -1,9 +1,10 @@
 return {
-  summary = 'Submit a chunk of work.',
-  description = '',
+  summary = 'Submit recorded graphics work to the GPU.',
+  description = 'TODO',
   arguments = {},
   returns = {},
   related = {
-    'lovr.graphics.begin'
+    'lovr.graphics.prepare',
+    'lovr.graphics.wait'
   }
 }

api/lovr/graphics/wait.lua

@@ -0,0 +1,10 @@
+return {
+  summary = 'Wait for the GPU to finish all submitted work.',
+  description = 'TODO',
+  arguments = {},
+  returns = {},
+  related = {
+    'lovr.graphics.prepare',
+    'lovr.graphics.submit'
+  }
+}