Some Pass docs;

api/lovr/graphics/Pass/compute.lua

@@ -3,6 +3,10 @@ return {
   summary = 'Run a compute shader.',
   description = [[
     Runs a compute shader.  There must be an active compute shader set using `Pass:setShader`.
+
+    All of the compute shader dispatches in a Pass will run **before** all of the draws in the Pass
+    (if any).  They will also run at the same time in parallel, unless `Pass:barrier` is used to
+    control the order.
   ]],
   arguments = {
      x = {
@@ -50,10 +54,9 @@ return {
     }
   },
   notes = [[
-    Usually compute shaders are run many times in parallel: once for each pixel in an image, once
-    per particle, once per object, etc.  The 3 arguments represent how many times to run, or
-    "dispatch", the compute shader, in up to 3 dimensions.  Each element of this grid is called a
-    **workgroup**.
+    Compute shaders are usually run once for each pixel in an image, once per particle, once per
+    object, etc.  The 3 arguments represent how many times to run, or "dispatch", the compute
+    shader, in up to 3 dimensions.  Each element of this grid is called a **workgroup**.
 
     To make things even more complicated, each workgroup itself is made up of a set of "mini GPU
     threads", which are called **local workgroups**.  Like workgroups, the local workgroup size can
@@ -139,9 +142,8 @@ return {
     ]=]
   },
   related = {
+    'Pass:barrier',
     'Pass:setShader',
-    'Pass:send',
-    'lovr.graphics.newShader',
-    'lovr.graphics.getPass'
+    'Pass:send'
   }
 }

api/lovr/graphics/Pass/getDimensions.lua

@@ -1,7 +1,7 @@
 return {
-  tag = 'pass-misc',
-  summary = 'Get the texture dimensions of a render pass.',
-  description = 'Returns the dimensions of the textures attached to the render pass.',
+  tag = 'canvas',
+  summary = 'Get the dimensions of the Pass\'s canvas.',
+  description = 'Returns the dimensions of the textures of the Pass\'s canvas, in pixels.',
   arguments = {},
   returns = {
     width = {
@@ -19,14 +19,13 @@ return {
       returns = { 'width', 'height' }
     }
   },
-  notes = [[
-    If the pass is not a render pass, this function returns zeros.
-  ]],
+  notes = 'If the pass doesn\'t have a canvas, this function returns zeros.',
   related = {
     'Pass:getWidth',
     'Pass:getHeight',
     'Pass:getViewCount',
-    'lovr.graphics.getPass',
+    'Pass:getCanvas',
+    'Pass:setCanvas',
     'lovr.system.getWindowDimensions',
     'lovr.headset.getDisplayDimensions'
   }

api/lovr/graphics/Pass/getHeight.lua

@@ -1,7 +1,7 @@
 return {
-  tag = 'pass-misc',
-  summary = 'Get the texture height of a render pass.',
-  description = 'Returns the height of the textures attached to the render pass.',
+  tag = 'canvas',
+  summary = 'Get the height of the Pass\'s canvas.',
+  description = 'Returns the height of the textures of the Pass\'s canvas, in pixels.',
   arguments = {},
   returns = {
     height = {
@@ -15,14 +15,13 @@ return {
       returns = { 'height' }
     }
   },
-  notes = [[
-    If the pass is not a render pass, this function returns zero.
-  ]],
+  notes = 'If the pass doesn\'t have a canvas, this function returns zero.',
   related = {
     'Pass:getWidth',
     'Pass:getDimensions',
     'Pass:getViewCount',
-    'lovr.graphics.getPass',
+    'Pass:getCanvas',
+    'Pass:setCanvas',
     'lovr.system.getWindowHeight',
     'lovr.headset.getDisplayHeight'
   }

api/lovr/graphics/Pass/getWidth.lua

@@ -1,7 +1,7 @@
 return {
-  tag = 'pass-misc',
-  summary = 'Get the texture width of a render pass.',
-  description = 'Returns the width of the textures attached to the render pass.',
+  tag = 'canvas',
+  summary = 'Get the width of the Pass\'s canvas.',
+  description = 'Returns the width of the textures of the Pass\'s canvas, in pixels.',
   arguments = {},
   returns = {
     width = {
@@ -15,14 +15,13 @@ return {
       returns = { 'width' }
     }
   },
-  notes = [[
-    If the pass is not a render pass, this function returns zero.
-  ]],
+  notes = 'If the pass doesn\'t have a canvas, this function returns zero.',
   related = {
     'Pass:getHeight',
     'Pass:getDimensions',
     'Pass:getViewCount',
-    'lovr.graphics.getPass',
+    'Pass:getCanvas',
+    'Pass:setCanvas',
     'lovr.system.getWindowWidth',
     'lovr.headset.getDisplayWidth'
   }

api/lovr/graphics/Pass/init.lua

@@ -1,14 +1,29 @@
 return {
   summary = 'A stream of graphics commands.',
   description = [[
-    Pass objects are used to record commands for the GPU.  Commands can be recorded by calling
-    functions on the Pass.  After recording a set of passes, they can be submitted for the GPU to
-    process using `lovr.graphics.submit`.
+    Pass objects are used to record work for the GPU.  They contain a list of things to draw and a
+    list of compute shaders to run.
+
+    Methods like `Pass:sphere` will "record" a draw on the Pass, which adds it to the list.  Other
+    methods like `Pass:setBlendMode` or `Pass:setShader` will change the way future draws are
+    processed.
+
+    Once all of the work has been recorded to a Pass, it can be sent to the GPU using
+    `lovr.graphics.submit`, which will start processing all of the compute work and draws (in that
+    order).
+
+    A Pass can have a **canvas**, which is a set of textures that the draws will render to.
+
+    `Pass:reset` is used to clear all of the computes and draws, putting the Pass in a fresh state.
+
+    `lovr.draw` is called every frame with a `Pass` that is configured to render to either the
+    headset or the window.  The Pass will automatically get submitted afterwards.
   ]],
   constructors = {
-    'lovr.graphics.getPass',
+    'lovr.graphics.newPass',
     'lovr.graphics.getWindowPass',
-    'lovr.headset.getPass'
+    'lovr.headset.getPass',
+    'lovr.graphics.getPass'
   },
   sections = {
     {
@@ -30,20 +45,24 @@ return {
       ]]
     },
     {
-      name = 'Shader Variables',
-      tag = 'shader-inputs',
+      name = 'Camera',
+      tag = 'camera'
     },
     {
-      name = 'Camera',
-      tag = 'camera',
+      name = 'Shaders',
+      tag = 'shaders'
     },
     {
       name = 'Compute',
-      tag = 'compute',
+      tag = 'compute'
+    },
+    {
+      name = 'Tally',
+      tag = 'tally'
     },
     {
-      name = 'Transfers',
-      tag = 'transfer'
+      name = 'Canvas',
+      tag = 'canvas'
     },
     {
       name = 'Miscellaneous',

api/lovr/graphics/Pass/send.lua

@@ -1,5 +1,5 @@
 return {
-  tag = 'shader-inputs',
+  tag = 'shaders',
   summary = 'Set the value of a shader variable.',
   description = [[
     Sends a value to a variable in the Pass's active `Shader`.  The active shader is changed using

api/lovr/graphics/Pass/setShader.lua

@@ -1,5 +1,5 @@
 return {
-  tag = 'pipeline',
+  tag = 'shaders',
   summary = 'Set the active Shader.',
   description = [[
     Sets the active shader.  In a render pass, the Shader will affect all drawing operations until

api/lovr/graphics/getPass.lua

@@ -1,4 +1,5 @@
 return {
+  deprecated = true,
   tag = 'graphics-objects',
   summary = 'Get a temporary Pass.',
   description = 'Creates and returns a temporary Pass object.',
@@ -40,32 +41,9 @@ return {
               name = 'texture',
               type = 'Texture',
               description = 'A Texture to use as the depth buffer.  Takes precedence over `format`.'
-            },
-            {
-              name = 'clear',
-              type = 'number',
-              default = '0',
-              description = [[
-                How to clear the depth buffer at the beginning of the pass.  Can be a floating point
-                number to clear each pixel to, `true` to do a "fast clear" that clears to random
-                data, or `false` to not clear at all and instead load the depth texture's pixels.
-              ]]
             }
           }
         },
-        {
-          name = 'clear',
-          type = '*',
-          description = [[
-            How to clear the color textures at the beginning of the pass.  If this is a boolean or a
-            color, that value will be used for all color textures.  It can also be a table of colors
-            or booleans, one for each color texture.  Colors may be provided as `Vec3`, `Vec4`,
-            hexcodes, or tables of numbers.  Note that tables of hexcode colors are ambiguous and
-            therefore unsupported.  When using a boolean, `true` means to do a "fast clear" that
-            clears the texture to random data, and `false` means to not clear at all and instead
-            load the texture's existing pixels.
-          ]]
-        },
         {
           name = 'samples',
           type = 'number',
@@ -74,15 +52,6 @@ return {
             The number of multisamples to use.  Can be 4 for antialiasing, or 1 to disable
             antialiasing.
           ]]
-        },
-        {
-          name = 'mipmap',
-          type = 'boolean',
-          default = [[false]],
-          description = [[
-            Whether mipmaps for the color and depth textures should be regenerated after the pass is
-            finished.
-          ]]
         }
       }
     }
@@ -95,7 +64,7 @@ return {
   },
   variants = {
     {
-      description = 'Create a compute or transfer pass.',
+      description = 'Create a compute pass.',
       arguments = { 'type' },
       returns = { 'pass' }
     },
@@ -120,18 +89,16 @@ return {
       allowing each layer to be rendered from a different viewpoint.  This enables fast stereo
       rendering, but can also be used to efficiently render to cubemaps.  The `ViewIndex` variable
       can also be used in shaders to set up any desired per-view behavior.
-    - If `mipmap` is true, then any textures with mipmaps must have the `transfer` `TextureUsage`.
+    - Mipmaps will automatically be generated for textures at the end of the render pass.
     - It's okay to have zero color textures, but in this case there must be a depth texture.
-    - Setting `clear` to `false` for textures is usually very slow on mobile GPUs.
     - It's possible to render to a specific mipmap level of a Texture, or a subset of its layers, by
       rendering to texture views, see `Texture:newView`.
 
-    For `compute` and `transfer` passes, all of the commands in the pass act as though they run in
-    parallel.  This means that writing to the same element of a buffer twice, or writing to it and
-    reading from it again is not guaranteed to work properly on all GPUs.  LÖVR is not currently
-    able to check for this.  If compute or transfers need to be sequenced, multiple passes should be
-    used.  It is, however, completely fine to read and write to non-overlapping regions of the same
-    buffer or texture.
+    For `compute` passes, all of the commands in the pass act as though they run in parallel.  This
+    means that writing to the same element of a buffer twice, or writing to it and reading from it
+    again is not guaranteed to work properly on all GPUs.  If compute or transfers need to be
+    sequenced, multiple passes should be used.  It is, however, completely fine to read and write to
+    non-overlapping regions of the same buffer or texture.
   ]],
   related = {
     'lovr.graphics.submit',

api/lovr/graphics/newPass.lua

@@ -0,0 +1,103 @@
+return {
+  tag = 'graphics-objects',
+  summary = 'Create a new Pass.',
+  description = [[
+    Creates and returns a new Pass object.  The canvas (the set of textures the Pass renders to) can
+    be specified when creating the Pass, or later using `Pass:setCanvas`.
+  ]],
+  arguments = {
+    ['...textures'] = {
+      type = 'Texture',
+      description = [[
+        One or more textures the pass will render to.  This can be changed later using
+        `Pass:setCanvas`.
+      ]]
+    },
+    canvas = {
+      type = 'table',
+      description = [[
+        Render target configuration.  Up to 4 textures can be provided in table keys 1 through 4, as
+        well as the following keys:
+      ]],
+      table = {
+        {
+          name = 'depth',
+          type = 'table',
+          description = [[
+            Depth/stencil buffer settings.  In addition to a table, it can be a `Texture`, a
+            `TextureFormat`, or `false` to disable the depth buffer.
+          ]],
+          table = {
+            {
+              name = 'format',
+              type = 'TextureFormat',
+              default = [['d32f']],
+              description = [[
+                The format of the depth buffer texture, which must be a depth format (the ones that
+                start with `d`).  LÖVR will create or reuse an internal depth buffer with this
+                format.
+              ]]
+            },
+            {
+              name = 'texture',
+              type = 'Texture',
+              description = 'A Texture to use as the depth buffer.  Takes precedence over `format`.'
+            }
+          }
+        },
+        {
+          name = 'samples',
+          type = 'number',
+          default = '4',
+          description = [[
+            The number of multisamples to use.  Can be 4 for antialiasing, or 1 to disable
+            antialiasing.
+          ]]
+        }
+      }
+    }
+  },
+  returns = {
+    pass = {
+      type = 'Pass',
+      description = 'The new Pass.'
+    }
+  },
+  variants = {
+    {
+      description = 'Create a pass that renders to a set of textures.',
+      arguments = { '...textures' },
+      returns = { 'pass' }
+    },
+    {
+      description = 'Create a pass, with extra canvas settings.',
+      arguments = { 'canvas' },
+      returns = { 'pass' }
+    },
+    {
+      description = 'Create an empty Pass without a canvas.',
+      arguments = {},
+      returns = { 'pass' }
+    }
+  },
+  notes = [[
+    Fun facts about render passes:
+
+    - Textures must have been created with the `render` `TextureUsage`.
+    - Textures must have the same dimensions, layer counts, and sample counts.
+    - When rendering to textures with multiple layers, each draw will be broadcast to all layers.
+      Render passes have multiple "views" (cameras), and each layer uses a corresponding view,
+      allowing each layer to be rendered from a different viewpoint.  This enables fast stereo
+      rendering, but can also be used to efficiently render to cubemaps.  The `ViewIndex` variable
+      can also be used in shaders to set up any desired per-view behavior.
+    - Mipmaps will automatically be generated for textures at the end of the render pass.
+    - It's okay to have zero color textures, but in this case there must be a depth texture.
+    - It's possible to render to a specific mipmap level of a Texture, or a subset of its layers, by
+      rendering to texture views, see `Texture:newView`.
+  ]],
+  related = {
+    'lovr.graphics.submit',
+    'lovr.graphics.getWindowPass',
+    'lovr.headset.getPass'
+  }
+}

tests/canvas.lua

@@ -0,0 +1,8 @@
+function lovr.load()
+  pass = lovr.graphics.newPass()
+  assert(pass:getWidth() == 0 and pass:getHeight() == 0)
+  pass:setCanvas(lovr.graphics.newTexture(1, 1))
+  assert(pass:getWidth() == 1 and pass:getHeight() == 1)
+  pass:setCanvas()
+  assert(pass:getWidth() == 0 and pass:getHeight() == 0)
+end