Document the audio code in SDL

1 files changed, 21 insertions, 1 deletions

diff --git a/src/library_sdl.js b/src/library_sdl.js
index 38231557..73e66e2a 100644
--- a/src/library_sdl.js
+++ b/src/library_sdl.js
@@ -18,7 +18,9 @@ var LibrarySDL = {
     events: [],
     fonts: [null],
 
+    // The currently preloaded audio elements ready to be played
     audios: [null],
+    // The currently playing audio element.  There's only one music track.
     music: {
       audio: null,
       volume: 1.0
@@ -515,6 +517,10 @@ var LibrarySDL = {
 
     // Sound
 
+    // Channels are a SDL abstraction for allowing multiple sound tracks to be
+    // played at the same time.  We don't need to actually implement the mixing
+    // since the browser engine handles that for us.  Therefore, in JS we just
+    // maintain a list of channels and return IDs for them to the SDL consumer.
     allocateChannels: function(num) { // called from Mix_AllocateChannels and init
       if (SDL.numChannels && SDL.numChannels >= num) return;
       SDL.numChannels = num;
@@ -1026,6 +1032,7 @@ var LibrarySDL = {
 
   // SDL_Audio
 
+  // TODO fix SDL_OpenAudio, and add some tests for it.  It's currently broken.
   SDL_OpenAudio: function(desired, obtained) {
     SDL.allocateChannels(32);
 
@@ -1104,6 +1111,7 @@ var LibrarySDL = {
 
   Mix_OpenAudio: function(frequency, format, channels, chunksize) {
     SDL.allocateChannels(32);
+    // Just record the values for a later call to Mix_QuickLoad_RAW
     SDL.mixerFrequency = frequency;
     SDL.mixerFormat = format;
     SDL.mixerNumChannels = channels;
@@ -1148,6 +1156,7 @@ var LibrarySDL = {
       Module["preloadedAudios"][filename] = null;
     }
     var id = SDL.audios.length;
+    // Keep the loaded audio in the audio arrays, ready for playback
     SDL.audios.push({
       source: filename,
       audio: raw
@@ -1157,13 +1166,15 @@ var LibrarySDL = {
 
   Mix_QuickLoad_RAW: function(mem, len) {
     var audio = new Audio();
+    // Record the number of channels and frequency for later usage
     audio.setAttribute("data-numchannels", SDL.mixerNumChannels);
     audio.setAttribute("data-frequency", SDL.mixerFrequency);
-    var numSamples = len >> 1;
+    var numSamples = len >> 1; // len is the length in bytes, and the array contains 16-bit PCM values
     var buffer = new Float32Array(numSamples);
     for (var i = 0; i < numSamples; ++i) {
       buffer[i] = ({{{ makeGetValue('mem', 'i*2', 'i16', 0, 0) }}}) / 0x8000; // hardcoded 16-bit audio, signed (TODO: reSign if not ta2?)
     }
+    // FIXME: doesn't make sense to keep the audio element in the buffer
     var id = SDL.audios.length;
     SDL.audios.push({
       source: '',
@@ -1179,10 +1190,15 @@ var LibrarySDL = {
 
   Mix_PlayChannel: function(channel, id, loops) {
     // TODO: handle loops
+
+    // Get the audio element associated with the ID
     var info = SDL.audios[id];
     if (!info) return 0;
     var audio = info.audio;
     if (!audio) return 0;
+
+    // If the user asks us to allocate a channel automatically, get the first
+    // free one.
     if (channel == -1) {
       channel = 0;
       for (var i = 0; i < SDL.numChannels; i++) {
@@ -1192,6 +1208,9 @@ var LibrarySDL = {
         }
       }
     }
+
+    // We clone the audio node to utilize the preloaded audio buffer, since
+    // the browser has already preloaded the audio file.
     var channelInfo = SDL.channels[channel];
     channelInfo.audio = audio = audio.cloneNode(true);
     if (SDL.channelFinished) {
@@ -1199,6 +1218,7 @@ var LibrarySDL = {
         Runtime.getFuncWrapper(SDL.channelFinished)(channel);
       }
     }
+    // Either play the element, or load the dynamic data into it
     if (info.buffer) {
       audio['mozSetup'](audio.getAttribute("data-numchannels"), audio.getAttribute("data-frequency"));
       audio["mozWriteAudio"](info.buffer);