cleanup/commenting

git-svn-id: svn+ssh://src.earth.threerings.net/narya/trunk@1984 542714f4-19e9-0310-aa3c-eee0fc999fb1

src/java/com/threerings/media/sound/MidiPlayer.java

@@ -1,5 +1,5 @@
 //
-// $Id: MidiPlayer.java,v 1.1 2002/11/22 04:23:31 ray Exp $
+// $Id: MidiPlayer.java,v 1.2 2002/11/22 19:21:12 ray Exp $
 
 package com.threerings.media;
 
@@ -17,25 +17,21 @@ import javax.sound.midi.Sequencer;
 import javax.sound.midi.Synthesizer;
 
 /**
- * Does something extraordinary.
+ * Plays midi/rmf sounds using Java's sequencer, which is susceptible
+ * to the accuracy of System.currentTimeMillis() and so currently sounds
+ * like "ass" under Windows.
  */
 public class MidiPlayer extends MusicPlayer
     implements MetaEventListener
 {
     // documentation inherited
     public void init ()
+        throws Exception
     {
-        try {
+        _sequencer = MidiSystem.getSequencer();
-            Sequencer seq = MidiSystem.getSequencer();
+        _sequencer.open();
-            seq.open();
+        if (_sequencer instanceof Synthesizer) {
-            if (seq instanceof Synthesizer) {
+            _channels = ((Synthesizer) _sequencer).getChannels();
-                _channels = ((Synthesizer) seq).getChannels();
-                //updateMusicVolume();
-            }
-            _sequencer = seq;
-
-        } catch (MidiUnavailableException mue) {
-            Log.warning("Midi unavailable! [e=" + mue + "].");
         }
     }
 

src/java/com/threerings/media/sound/ModPlayer.java

@@ -1,5 +1,5 @@
 //
-// $Id: ModPlayer.java,v 1.3 2002/11/22 04:23:31 ray Exp $
+// $Id: ModPlayer.java,v 1.4 2002/11/22 19:21:12 ray Exp $
 
 package com.threerings.media;
 
@@ -18,20 +18,16 @@ import micromod.resamplers.LinearResampler;
 import com.threerings.resource.ResourceManager;
 
 /**
- * Does something extraordinary.
+ * A player that plays .mod format music.
  */
 public class ModPlayer extends MusicPlayer
 {
     // documentation inherited
     public void init ()
+        throws Exception
     {
-        try {
+        _device = new NaryaSoundDevice();
-            _device = new NaryaSoundDevice();
+        _device.start();
-            _device.start();
-        } catch (OutputDeviceException ode) {
-            Log.warning("Unable to allocate sound channel for mod playing " +
-                "[e=" + ode + "].");
-        }
     }
 
     // documentation inherited
@@ -117,6 +113,9 @@ public class ModPlayer extends MusicPlayer
         }
     }
 
+    /** The thread that does the work. */
     protected Thread _player;
+
+    /** The sound output device. */
     protected NaryaSoundDevice _device;
 }

src/java/com/threerings/media/sound/Mp3Player.java

@@ -1,5 +1,5 @@
 //
-// $Id: Mp3Player.java,v 1.1 2002/11/22 04:23:31 ray Exp $
+// $Id: Mp3Player.java,v 1.2 2002/11/22 19:21:12 ray Exp $
 
 package com.threerings.media;
 
@@ -22,7 +22,11 @@ import org.apache.commons.io.StreamUtils;
 import com.threerings.resource.ResourceManager;
 
 /**
- * Does something extraordinary.
+ * Plays mp3 files. Depends on three external jar files that aren't even
+ * imported here:
+ *     tritonus_share.jar
+ *     tritonus_mp3.jar
+ *     javalayer.jar
  */
 public class Mp3Player extends MusicPlayer
 {
@@ -104,7 +108,7 @@ public class Mp3Player extends MusicPlayer
         };
 
         _player.setDaemon(true);
-        _player.setPriority(_player.getPriority() + 1);
+        //_player.setPriority(_player.getPriority() + 1);
         _player.start();
     }
 
@@ -120,7 +124,9 @@ public class Mp3Player extends MusicPlayer
         // TODO
     }
 
+    /** The thread that transfers data to the line. */
     protected Thread _player;
 
+    /** The size of our buffer. */
     protected static final int BUFFER_SIZE = 8192;
 }

src/java/com/threerings/media/sound/MusicPlayer.java

@@ -1,16 +1,17 @@
 //
-// $Id: MusicPlayer.java,v 1.1 2002/11/22 04:23:31 ray Exp $
+// $Id: MusicPlayer.java,v 1.2 2002/11/22 19:21:12 ray Exp $
 
 package com.threerings.media;
 
 import com.threerings.resource.ResourceManager;
 
 /**
- * Does something extraordinary.
+ * Abstract music player.
  */
 public abstract class MusicPlayer
 {
     /**
+     * A watcher interested in music events.
      */
     public interface MusicEventListener
     {
@@ -22,9 +23,11 @@ public abstract class MusicPlayer
     }
 
     /**
+     * Initialize the music player.
      */
     public final void init (
         ResourceManager rmgr, MusicEventListener musicListener)
+        throws Exception
     {
         _rmgr = rmgr;
         _musicListener = musicListener;
@@ -36,6 +39,7 @@ public abstract class MusicPlayer
      * Do your init here.
      */
     public void init ()
+        throws Exception
     {
     }
 

src/java/com/threerings/media/sound/SoundManager.java

@@ -1,5 +1,5 @@
 //
-// $Id: SoundManager.java,v 1.24 2002/11/22 04:23:31 ray Exp $
+// $Id: SoundManager.java,v 1.25 2002/11/22 19:21:12 ray Exp $
 
 package com.threerings.media;
 
@@ -50,8 +50,6 @@ import com.threerings.media.Log;
  */
 // TODO:
 //   - fade music out when stopped?
-//   -- CLEANUP is NEEDED (lots of references to Sequences, when we're now
-//   playing mods and mp3s as well. )
 public class SoundManager
     implements MusicPlayer.MusicEventListener
 {
@@ -424,9 +422,11 @@ public class SoundManager
             // set up the new player
             try {
                 _musicPlayer = (MusicPlayer) playerClass.newInstance();
+                _musicPlayer.init(_rmgr, this);
+
             } catch (Exception e) {
                 Log.warning("Unable to instantiate music player [class=" +
-                        playerClass + "].");
+                        playerClass + ", e=" + e + "].");
 
                 // scrap it, try again with the next song
                 _musicPlayer = null;
@@ -435,7 +435,6 @@ public class SoundManager
                 return;
             }
 
-            _musicPlayer.init(_rmgr, this);
             _musicPlayer.setVolume(_musicVol);
         }