newSound docs; Ambisonic docs;

api/lovr/data/ChannelLayout.lua

@@ -0,0 +1,31 @@
+return {
+  summary = 'Different channel layouts for Sounds.',
+  description = [[
+    Sounds can have different numbers of channels, and those channels can map to various speaker
+    layouts.
+  ]],
+  values = {
+    {
+      name = 'mono',
+      description = '1 channel.'
+    },
+    {
+      name = 'stereo',
+      description = [[
+        2 channels.  The first channel is for the left speaker and the second is for the right.
+      ]]
+    },
+    {
+      name = 'ambisonic',
+      description = [[
+        4 channels.  Ambisonic channels don't map directly to speakers but instead represent
+        directions in 3D space, sort of like the images of a skybox.  Currently, ambisonic sounds
+        can only be loaded, not played.  
+      ]]
+    }
+  },
+  related = {
+    'lovr.data.newSound',
+    'Sound:getFormat'
+  }
+}

api/lovr/data/SampleFormat.lua

@@ -10,5 +10,9 @@ return {
       name = 'i16',
       description = '16 bit integer samples (between -32768 and 32767).'
     }
+  },
+  related = {
+    'lovr.data.newSound',
+    'Sound:getFormat'
   }
 }

api/lovr/data/Sound/getFormat.lua

@@ -0,0 +1,16 @@
+return {
+  summary = 'Get the sample format of the Sound.',
+  description = 'Returns the sample format of the Sound.',
+  arguments = {},
+  returns = {
+    {
+      name = 'format',
+      type = 'SampleFormat',
+      description = 'The data type of each sample.'
+    }
+  },
+  related = {
+    'Sound:getChannelLayout',
+    'Sound:getSampleRate'
+  }
+}

api/lovr/data/Sound/init.lua

@@ -42,6 +42,14 @@ return {
     Keep in mind that streams can still only hold a fixed number of frames.  If too much data is
     written before it is read, older frames will start to get overwritten.  Similary, it's possible
     to read too much data without writing fast enough.
+
+    Ambisonics
+    ---
+
+    Ambisonic sounds can be imported from WAVs, but can not yet be played.  Sounds with a
+    `ChannelLayout` of `ambisonic` are stored as first-order full-sphere ambisonics using the AmbiX
+    format (ACN channel ordering and SN3D channel normalization).  The AMB format is supported for
+    import and will automatically get converted to AmbiX.  See `lovr.data.newSound` for more info.
   ]],
   constructor = 'lovr.data.newSound'
 }

api/lovr/data/newSound.lua

@@ -72,5 +72,25 @@ return {
       arguments = { 'blob', 'decode' },
       returns = { 'sound' }
     }
-  }
+  },
+  notes = [[
+    It is highly recommended to use an audio format that matches the format of the audio module:
+    `f32` sample formats at a sample rate of 48000, with 1 channel for spatialized sources or 2
+    channels for unspatialized sources.  This will avoid the need to convert audio during playback,
+    which boosts performance of the audio thread.
+
+    The WAV importer supports 16, 24, and 32 bit integer data and 32 bit floating point data.  The
+    data must be mono, stereo, or 4-channel full-sphere ambisonic.  The `WAVE_FORMAT_EXTENSIBLE`
+    extension is supported.
+
+    Ambisonic channel layouts are supported for import (but not yet for playback).  Ambisonic data
+    can be loaded from WAV files.  It must be first-order full-sphere ambisonic data with 4
+    channels.  If the WAV has a `WAVE_FORMAT_EXTENSIBLE` chunk with an `AMBISONIC_B_FORMAT` format
+    GUID, then the data is understood as using the AMB format with Furse-Malham channel ordering and
+    normalization.  *All other* 4-channel files are assumed to be using the AmbiX format with ACN
+    channel ordering and SN3D normalization.  AMB files will get automatically converted to AmbiX on
+    import, so ambisonic Sounds will always be in a consistent format.
+
+    OGG and MP3 files will always have the `f32` format when loaded.
+  ]]
 }