Source pitch/spatial; Image:get/setPixel formats;

api/init.lua

@@ -1367,14 +1367,26 @@ return {
                     {
                       name = "decode",
                       type = "boolean",
-                      description = "Whether to immediately decode compressed sounds.",
+                      description = "Whether to immediately decode compressed sounds, instead of progressively decoding as the Source plays.  Enabling this will use more memory but reduce CPU overhead during playback.  Recommended for short sound effects.",
                       default = "false"
                     },
+                    {
+                      name = "pitchable",
+                      type = "boolean",
+                      description = "Whether the pitch of the Source can be changed with `Source:setPitch`.  Leaving this as false will improve performance slightly.",
+                      default = "false"
+                    },
+                    {
+                      name = "spatial",
+                      type = "boolean",
+                      description = "Whether the Source should use spatial effects.  Non-spatial sources will get routed directly to the speakers without further processing.  Enabling an effect on a non-spatial source will raise an error.",
+                      default = "true"
+                    },
                     {
                       name = "effects",
                       type = "table",
-                      description = "A table of `Effect`s to enable.  Keys can be integers (list) or effect names (map), or a combination of both.  The special value `false` can be used to completely disable effects, bypassing the spatializer entirely and throwing an error when trying to enable effects.  `true` will enable all effects.",
-                      default = "true"
+                      description = "A table of `Effect`s to enable on the Source.  This can be a list (numeric keys, effect name values) or a map (effect name keys, boolean values) or a mix of the two.  Effects can also be enabled later using `Source:setEffectEnabled`.  If nil, all effects will be enabled.  Ignored if the `spatial` flag is false.",
+                      default = "nil"
                     }
                   }
                 }
@@ -1402,14 +1414,26 @@ return {
                     {
                       name = "decode",
                       type = "boolean",
-                      description = "Whether to immediately decode compressed sounds.",
+                      description = "Whether to immediately decode compressed sounds, instead of progressively decoding as the Source plays.  Enabling this will use more memory but reduce CPU overhead during playback.  Recommended for short sound effects.",
                       default = "false"
                     },
+                    {
+                      name = "pitchable",
+                      type = "boolean",
+                      description = "Whether the pitch of the Source can be changed with `Source:setPitch`.  Leaving this as false will improve performance slightly.",
+                      default = "false"
+                    },
+                    {
+                      name = "spatial",
+                      type = "boolean",
+                      description = "Whether the Source should use spatial effects.  Non-spatial sources will get routed directly to the speakers without further processing.  Enabling an effect on a non-spatial source will raise an error.",
+                      default = "true"
+                    },
                     {
                       name = "effects",
                       type = "table",
-                      description = "A table of `Effect`s to enable.  Keys can be integers (list) or effect names (map), or a combination of both.  The special value `false` can be used to completely disable effects, bypassing the spatializer entirely and throwing an error when trying to enable effects.  `true` will enable all effects.",
-                      default = "true"
+                      description = "A table of `Effect`s to enable on the Source.  This can be a list (numeric keys, effect name values) or a map (effect name keys, boolean values) or a mix of the two.  Effects can also be enabled later using `Source:setEffectEnabled`.  If nil, all effects will be enabled.  Ignored if the `spatial` flag is false.",
+                      default = "nil"
                     }
                   }
                 }
@@ -1437,14 +1461,26 @@ return {
                     {
                       name = "decode",
                       type = "boolean",
-                      description = "Whether to immediately decode compressed sounds.",
+                      description = "Whether to immediately decode compressed sounds, instead of progressively decoding as the Source plays.  Enabling this will use more memory but reduce CPU overhead during playback.  Recommended for short sound effects.",
                       default = "false"
                     },
+                    {
+                      name = "pitchable",
+                      type = "boolean",
+                      description = "Whether the pitch of the Source can be changed with `Source:setPitch`.  Leaving this as false will improve performance slightly.",
+                      default = "false"
+                    },
+                    {
+                      name = "spatial",
+                      type = "boolean",
+                      description = "Whether the Source should use spatial effects.  Non-spatial sources will get routed directly to the speakers without further processing.  Enabling an effect on a non-spatial source will raise an error.",
+                      default = "true"
+                    },
                     {
                       name = "effects",
                       type = "table",
-                      description = "A table of `Effect`s to enable.  Keys can be integers (list) or effect names (map), or a combination of both.  The special value `false` can be used to completely disable effects, bypassing the spatializer entirely and throwing an error when trying to enable effects.  `true` will enable all effects.",
-                      default = "true"
+                      description = "A table of `Effect`s to enable on the Source.  This can be a list (numeric keys, effect name values) or a map (effect name keys, boolean values) or a mix of the two.  Effects can also be enabled later using `Source:setEffectEnabled`.  If nil, all effects will be enabled.  Ignored if the `spatial` flag is false.",
+                      default = "nil"
                     }
                   }
                 }
@@ -1969,6 +2005,27 @@ return {
                 }
               }
             },
+            {
+              name = "getPitch",
+              tag = "sourcePlayback",
+              summary = "Get the pitch of the Source.",
+              description = "Returns the pitch of the Source.",
+              key = "Source:getPitch",
+              module = "lovr.audio",
+              notes = "The default pitch is 1.  Every doubling/halving of the pitch will raise/lower the pitch by one octave.  Changing the pitch also changes the playback speed.",
+              variants = {
+                {
+                  arguments = {},
+                  returns = {
+                    {
+                      name = "pitch",
+                      type = "number",
+                      description = "The pitch."
+                    }
+                  }
+                }
+              }
+            },
             {
               name = "getPose",
               tag = "sourceEffects",
@@ -2137,7 +2194,7 @@ return {
               description = "Returns whether a given `Effect` is enabled for the Source.",
               key = "Source:isEffectEnabled",
               module = "lovr.audio",
-              notes = "The active spatializer will determine which effects are supported.  If an unsupported effect is enabled on a Source, no error will be reported.  Instead, it will be silently ignored.  See `lovr.audio.getSpatializer` for a table showing the effects supported by each spatializer.\n\nCalling this function on a Source that was created with `{ effects = false }` will always return false.",
+              notes = "The active spatializer will determine which effects are supported.  If an unsupported effect is enabled on a Source, no error will be reported.  Instead, it will be silently ignored.  See `lovr.audio.getSpatializer` for a table showing the effects supported by each spatializer.\n\nCalling this function on a non-spatial Source will always return false.",
               variants = {
                 {
                   arguments = {
@@ -2155,6 +2212,9 @@ return {
                     }
                   }
                 }
+              },
+              related = {
+                "Source:isSpatial"
               }
             },
             {
@@ -2202,6 +2262,30 @@ return {
                 }
               }
             },
+            {
+              name = "isSpatial",
+              tag = "sourceEffects",
+              summary = "Check if the Source is spatial.",
+              description = "Returns whether the Source was created with the `spatial` flag.  Non-spatial sources are routed directly to the speakers and can not use effects.",
+              key = "Source:isSpatial",
+              module = "lovr.audio",
+              related = {
+                "Source:isEffectEnabled",
+                "Source:setEffectEnabled"
+              },
+              variants = {
+                {
+                  arguments = {},
+                  returns = {
+                    {
+                      name = "spatial",
+                      type = "boolean",
+                      description = "Whether the source is spatial."
+                    }
+                  }
+                }
+              }
+            },
             {
               name = "pause",
               tag = "sourcePlayback",
@@ -2296,7 +2380,7 @@ return {
               description = "Enables or disables an effect on the Source.",
               key = "Source:setEffectEnabled",
               module = "lovr.audio",
-              notes = "The active spatializer will determine which effects are supported.  If an unsupported effect is enabled on a Source, no error will be reported.  Instead, it will be silently ignored.  See `lovr.audio.getSpatializer` for a table showing the effects supported by each spatializer.\n\nCalling this function on a Source that was created with `{ effects = false }` will throw an error.",
+              notes = "The active spatializer will determine which effects are supported.  If an unsupported effect is enabled on a Source, no error will be reported.  Instead, it will be silently ignored.  See `lovr.audio.getSpatializer` for a table showing the effects supported by each spatializer.\n\nCalling this function on a non-spatial Source will throw an error.",
               variants = {
                 {
                   arguments = {
@@ -2313,6 +2397,9 @@ return {
                   },
                   returns = {}
                 }
+              },
+              related = {
+                "Source:isSpatial"
               }
             },
             {
@@ -2376,6 +2463,27 @@ return {
                 }
               }
             },
+            {
+              name = "setPitch",
+              tag = "sourcePlayback",
+              summary = "Set the pitch of the Source.",
+              description = "Sets the pitch of the Source.",
+              key = "Source:setPitch",
+              module = "lovr.audio",
+              notes = "The default pitch is 1.  Every doubling/halving of the pitch will raise/lower the pitch by one octave.  Changing the pitch also changes the playback speed.",
+              variants = {
+                {
+                  arguments = {
+                    {
+                      name = "pitch",
+                      type = "number",
+                      description = "The new pitch."
+                    }
+                  },
+                  returns = {}
+                }
+              }
+            },
             {
               name = "setPose",
               tag = "sourceEffects",
@@ -3620,7 +3728,7 @@ return {
                   }
                 }
               },
-              notes = "The following texture formats are supported: `rgba`, `rgb`, `r32f`, `rg32f`, and `rgba32f`."
+              notes = "The following texture formats are supported: `r8`, `rg8`, `rgba8`, `r16`, `rg16`, `rgba16`, `r32f`, `rg32f`, `rgba32f`."
             },
             {
               name = "getWidth",
@@ -3756,7 +3864,7 @@ return {
                   returns = {}
                 }
               },
-              notes = "The following texture formats are supported: `rgba`, `rgb`, `r32f`, `rg32f`, and `rgba32f`."
+              notes = "The following texture formats are supported: `r8`, `rg8`, `rgba8`, `r16`, `rg16`, `rgba16`, `r32f`, `rg32f`, `rgba32f`."
             }
           },
           constructors = {

api/lovr/audio/Source/getPitch.lua

@@ -0,0 +1,22 @@
+return {
+  tag = 'sourcePlayback',
+  summary = 'Get the pitch of the Source.',
+  description = 'Returns the pitch of the Source.',
+  arguments = {},
+  returns = {
+    pitch = {
+      type = 'number',
+      description = 'The pitch.'
+    }
+  },
+  variants = {
+    {
+      arguments = {},
+      returns = { 'pitch' }
+    }
+  },
+  notes = [[
+    The default pitch is 1.  Every doubling/halving of the pitch will raise/lower the pitch by one
+    octave.  Changing the pitch also changes the playback speed.
+  ]]
+}

api/lovr/audio/Source/isEffectEnabled.lua

@@ -25,7 +25,9 @@ return {
     enabled on a Source, no error will be reported.  Instead, it will be silently ignored.  See
     `lovr.audio.getSpatializer` for a table showing the effects supported by each spatializer.
 
-    Calling this function on a Source that was created with `{ effects = false }` will always return
-    false.
-  ]]
+    Calling this function on a non-spatial Source will always return false.
+  ]],
+  related = {
+    'Source:isSpatial'
+  }
 }

api/lovr/audio/Source/isSpatial.lua

@@ -0,0 +1,25 @@
+return {
+  tag = 'sourceEffects',
+  summary = 'Check if the Source is spatial.',
+  description = [[
+    Returns whether the Source was created with the `spatial` flag.  Non-spatial sources are routed
+    directly to the speakers and can not use effects.
+  ]],
+  arguments = {},
+  returns = {
+    spatial = {
+      type = 'boolean',
+      description = 'Whether the source is spatial.'
+    }
+  },
+  variants = {
+    {
+      arguments = {},
+      returns = { 'spatial' }
+    }
+  },
+  related = {
+    'Source:isEffectEnabled',
+    'Source:setEffectEnabled'
+  }
+}

api/lovr/audio/Source/setEffectEnabled.lua

@@ -24,7 +24,9 @@ return {
     enabled on a Source, no error will be reported.  Instead, it will be silently ignored.  See
     `lovr.audio.getSpatializer` for a table showing the effects supported by each spatializer.
 
-    Calling this function on a Source that was created with `{ effects = false }` will throw an
-    error.
-  ]]
+    Calling this function on a non-spatial Source will throw an error.
+  ]],
+  related = {
+    'Source:isSpatial'
+  }
 }

api/lovr/audio/Source/setPitch.lua

@@ -0,0 +1,22 @@
+return {
+  tag = 'sourcePlayback',
+  summary = 'Set the pitch of the Source.',
+  description = 'Sets the pitch of the Source.',
+  arguments = {
+    pitch = {
+      type = 'number',
+      description = 'The new pitch.'
+    }
+  },
+  returns = {},
+  variants = {
+    {
+      arguments = { 'pitch' },
+      returns = {}
+    }
+  },
+  notes = [[
+    The default pitch is 1.  Every doubling/halving of the pitch will raise/lower the pitch by one
+    octave.  Changing the pitch also changes the playback speed.
+  ]]
+}

api/lovr/audio/newSource.lua

@@ -23,17 +23,40 @@ return {
           name = 'decode',
           type = 'boolean',
           default = 'false',
-          description = 'Whether to immediately decode compressed sounds.'
+          description = [[
+            Whether to immediately decode compressed sounds, instead of progressively decoding as
+            the Source plays.  Enabling this will use more memory but reduce CPU overhead during
+            playback.  Recommended for short sound effects.
+          ]]
+        },
+        {
+          name = 'pitchable',
+          type = 'boolean',
+          default = 'false',
+          description = [[
+            Whether the pitch of the Source can be changed with `Source:setPitch`.  Leaving this as
+            false will improve performance slightly.
+          ]]
+        },
+        {
+          name = 'spatial',
+          type = 'boolean',
+          default = 'true',
+          description = [[
+            Whether the Source should use spatial effects.  Non-spatial sources will get routed
+            directly to the speakers without further processing.  Enabling an effect on a
+            non-spatial source will raise an error.
+          ]]
         },
         {
           name = 'effects',
           type = 'table',
-          default = 'true',
+          default = 'nil',
           description = [[
-            A table of `Effect`s to enable.  Keys can be integers (list) or effect names (map), or a
-            combination of both.  The special value `false` can be used to completely disable
-            effects, bypassing the spatializer entirely and throwing an error when trying to enable
-            effects.  `true` will enable all effects.
+            A table of `Effect`s to enable on the Source.  This can be a list (numeric keys, effect
+            name values) or a map (effect name keys, boolean values) or a mix of the two.  Effects
+            can also be enabled later using `Source:setEffectEnabled`.  If nil, all effects will be
+            enabled.  Ignored if the `spatial` flag is false.
           ]]
         }
       }

api/lovr/data/Image/getPixel.lua

@@ -36,7 +36,8 @@ return {
     }
   },
   notes = [[
-    The following texture formats are supported: `rgba`, `rgb`, `r32f`, `rg32f`, and `rgba32f`.
+    The following texture formats are supported: `r8`, `rg8`, `rgba8`, `r16`, `rg16`, `rgba16`,
+    `r32f`, `rg32f`, `rgba32f`.
   ]],
   related = {
     'Image:setPixel',

api/lovr/data/Image/setPixel.lua

@@ -36,7 +36,8 @@ return {
     }
   },
   notes = [[
-    The following texture formats are supported: `rgba`, `rgb`, `r32f`, `rg32f`, and `rgba32f`.
+    The following texture formats are supported: `r8`, `rg8`, `rgba8`, `r16`, `rg16`, `rgba16`,
+    `r32f`, `rg32f`, `rgba32f`.
   ]],
   related = {
     'Image:getPixel',