MidiDriver: Some cleanup, added some comments/TODOs, preparations for a potential cleanup

svn-id: r19844

2 files changed, 92 insertions, 39 deletions

diff --git a/sound/mididrv.cpp b/sound/mididrv.cpp
index 97913864cd..d2631623e9 100644
--- a/sound/mididrv.cpp
+++ b/sound/mididrv.cpp
@@ -30,47 +30,54 @@
 
 /** Internal list of all available 'midi' drivers. */
 static const struct MidiDriverDescription midiDrivers[] = {
-	{"auto", "Default", MD_AUTO, MDT_NONE},
+
+	// The flags for the "auto" driver indicate that it is anything you want
+	// it to be.
+	{"auto", "Default", MD_AUTO, MDT_MIDI | MDT_PCSPK | MDT_ADLIB | MDT_TOWNS},
+
+	// The flags for the "null" driver indicate that it does nothing, really.
 	{"null", "No music", MD_NULL, MDT_NONE},
 
 #if defined(WIN32) && !defined(_WIN32_WCE) && !defined(__SYMBIAN32__)
-	{"windows", "Windows MIDI", MD_WINDOWS, MDT_NATIVE},
+	{"windows", "Windows MIDI", MD_WINDOWS, MDT_MIDI},
+#endif
+
+#if defined(UNIX) && defined(USE_ALSA)
+	{"alsa", "ALSA", MD_ALSA, MDT_MIDI},
 #endif
 
 #if defined(UNIX) && !defined(__BEOS__) && !defined(MACOSX)
-	{"seq", "SEQ", MD_SEQ, MDT_NONE},
+	{"seq", "SEQ", MD_SEQ, MDT_MIDI},
 #endif
 
 #if defined(MACOSX)
-	{"qt", "QuickTime", MD_QTMUSIC, MDT_NATIVE},
-	{"core", "CoreAudio", MD_COREAUDIO, MDT_NATIVE},
-	{"coreaudio", "CoreAudio", MD_COREAUDIO, MDT_NATIVE},
-	{"coremidi", "CoreMIDI", MD_COREMIDI, MDT_NATIVE},
+	{"qt", "QuickTime", MD_QTMUSIC, MDT_MIDI},
+	{"core", "CoreAudio", MD_COREAUDIO, MDT_MIDI},
+	{"coreaudio", "CoreAudio", MD_COREAUDIO, MDT_MIDI},
+	{"coremidi", "CoreMIDI", MD_COREMIDI, MDT_MIDI},
 #endif
 
-#if defined(__MORPHOS__)
-	{"etude", "Etude", MD_ETUDE, MDT_NONE},
+#if defined(PALMOS_MODE)
+	{"ypa1", "Yamaha Pa1", MD_YPA1, MDT_MIDI},
+	{"zodiac", "Tapwave Zodiac", MD_ZODIAC, MDT_MIDI},
 #endif
 
-#if defined(UNIX) && defined(USE_ALSA)
-	{"alsa", "ALSA", MD_ALSA, MDT_NONE},
+#if defined(__MORPHOS__)
+	{"etude", "Etude", MD_ETUDE, MDT_MIDI},
 #endif
-
-	{"adlib", "Adlib", MD_ADLIB, MDT_ADLIB},
-	{"towns", "FM Towns", MD_TOWNS, MDT_TOWNS},
-	{"pcspk", "PC Speaker", MD_PCSPK, MDT_PCSPK},
-	{"pcjr", "IBM PCjr", MD_PCJR, MDT_PCSPK},
 #ifdef USE_FLUIDSYNTH
-	{"fluidsynth", "FluidSynth", MD_FLUIDSYNTH, MDT_NONE},
+	{"fluidsynth", "FluidSynth", MD_FLUIDSYNTH, MDT_MIDI},
 #endif
 #ifdef USE_MT32EMU
-	{"mt32", "MT-32", MD_MT32, MDT_NONE},
+	{"mt32", "MT-32", MD_MT32, MDT_MIDI},
 #endif
 
-#if defined(PALMOS_MODE)
-	{"ypa1", "Yamaha Pa1", MD_YPA1, MDT_NATIVE},
-	{"zodiac", "Tapwave Zodiac", MD_ZODIAC, MDT_NATIVE},
-#endif
+	// The flags for the "adlibe" driver indicate that it can do adlib and MIDI.
+	{"adlib", "Adlib", MD_ADLIB, MDT_ADLIB | MDT_MIDI},
+	{"pcspk", "PC Speaker", MD_PCSPK, MDT_PCSPK},
+	{"pcjr", "IBM PCjr", MD_PCJR, MDT_PCSPK},
+	{"towns", "FM Towns", MD_TOWNS, MDT_TOWNS},
+
 	{0, 0, MD_NULL, MDT_NONE}
 };
 
@@ -120,13 +127,36 @@ int MidiDriver::parseMusicDriver(const Common::String &str) {
 }
 
 int MidiDriver::detectMusicDriver(int midiFlags) {
+	/*
+	TODO: The code in this method is very complicated and convuluted. Maybe we
+	can improve it. 
+	
+	First off, one needs to understand why it is so complex. It tries to honor
+	the user's music_driver config, but with the restrictions imposed by midiFlags.
+	Hence it must either select a suitable default driver (for example if
+	musicDriver is set to MD_AUTO), or it must try to fall back to a suitable
+	driver resp. the NULL driver.
+	
+	Different games support different output drivers, as indicated by midiFlags.
+	Some of the occuring combinations are:
+	 - TOWNS games always want towns or null
+	 - some scumm games allow only pcspk, pcjr
+	 - some scumm games allow pcspk, pcjr, adlib, MIDI
+	 - some games allow adlib, MIDI
+	 - some games only allow MIDI
+	 - did I miss something?
+	
+	My hope is that we can simplify the whole selection process by iterating over
+	the list of available drivers and looking at their "flags" member.
+	*/
+
 	int musicDriver = parseMusicDriver(ConfMan.get("music_driver"));
 	/* Use the adlib sound driver if auto mode is selected,
 	 * and the game is one of those that want adlib as
 	 * default, OR if the game is an older game that doesn't
 	 * support anything else anyway. */
 	if (musicDriver == MD_AUTO || musicDriver < 0) {
-		if (midiFlags & MDT_PREFER_NATIVE) {
+		if (midiFlags & MDT_PREFER_MIDI) {
 			if (musicDriver == MD_AUTO) {
 				#if defined(WIN32) && !defined(_WIN32_WCE) &&  !defined(__SYMBIAN32__)
 					musicDriver = MD_WINDOWS; // MD_WINDOWS is default MidiDriver on windows targets
diff --git a/sound/mididrv.h b/sound/mididrv.h
index 62f00c31f9..4242998036 100644
--- a/sound/mididrv.h
+++ b/sound/mididrv.h
@@ -32,8 +32,16 @@ namespace Audio {
 }
 namespace Common { class String; }
 
-/** MIDI Driver Types */
+/**
+ * Music Driver Types, used to uniquely identify each music driver.
+ *
+ * The pseudo drivers are listed first, then all native drivers,
+ * then all other MIDI drivers, and finally the non-MIDI drivers.
+ *
+ * @todo Rename MidiDriverType to MusicDriverType
+ */
 enum MidiDriverType {
+	// Pseudo drivers
 	MD_AUTO,
 	MD_NULL,
 
@@ -56,43 +64,58 @@ enum MidiDriverType {
 	// MorphOS
 	MD_ETUDE,
 
+	// MIDI softsynths
+	MD_FLUIDSYNTH,
+	MD_MT32,
+
 	// "Fake" MIDI devices
 	MD_ADLIB,
 	MD_PCSPK,
 	MD_PCJR,
-	MD_TOWNS,
-
-	// MIDI softsynths
-	MD_MT32,
-	MD_FLUIDSYNTH
+	MD_TOWNS
 };
 
 /**
- * A set of bitmasks which can be used to specify what kind of midi
- * driver is prefered.
+ * A set of flags to be passed to detectMusicDriver() which can be used to
+ * specify what kind of music driver is preferred / accepted.
+ *
+ * The flags (except for MDT_PREFER_NATIVE) indicate whether a given driver
+ * type is acceptable. E.g. the TOWNS music driver could be returned by
+ * detectMusicDriver if and only if MDT_TOWNS is specified. 
+ *
+ * @todo Rename MidiDriverFlags to MusicDriverFlags
  */
 enum MidiDriverFlags {
 	MDT_NONE   = 0,
-	MDT_PCSPK  = 1, // MD_PCSPK and MD_PCJR
-	MDT_ADLIB  = 2, // MD_ADLIB
-	MDT_TOWNS  = 4, // MD_TOWNS
-	MDT_NATIVE = 8, // Everything else
-	MDT_PREFER_NATIVE = 16
+	MDT_PCSPK  = 1 << 0,      // PC Speaker: Maps to MD_PCSPK and MD_PCJR
+	MDT_ADLIB  = 1 << 1,      // Adlib: Maps to MD_ADLIB
+	MDT_TOWNS  = 1 << 2,      // FM-TOWNS: Maps to MD_TOWNS
+	MDT_MIDI   = 1 << 3,      // Real MIDI
+	MDT_PREFER_MIDI = 1 << 4, // Real MIDI output is preferred
+
+	MDT_NATIVE = MDT_MIDI,    // Alias for MDT_MIDI
+	MDT_PREFER_NATIVE = MDT_PREFER_MIDI // Alias for MDT_PREFER_MIDI
 };
 
 /**
  * Abstract description of a MIDI driver. Used by the config file and command
  * line parsing code, and also to be able to give the user a list of available
  * drivers.
+ *
+ * @todo Rename MidiDriverType to MusicDriverType
  */
 struct MidiDriverDescription {
 	const char *name;
 	const char *description;
-	MidiDriverType id;
-	MidiDriverFlags flags;
+	MidiDriverType id;		// A unique ID for each driver
+	int flags;				// Capabilities of this driver
 };
 
-/** Abstract MIDI Driver Class */
+/**
+ * Abstract MIDI Driver Class
+ *
+ * @todo Rename MidiDriver to MusicDriver
+ */
 class MidiDriver {
 public:
 	/** Convert a string containing a music driver name into MIDI Driver type. */