Refactor|Audio: Music interface stack

All audio interfaces are now placed into a single stack in priority
order. There can be any number of Music and CD interfaces. The
most important SFX interface is considered the primary interface;
any others are ignored for now.

The traditional audio plugin command line options (e.g., -fmod)
define the default interfaces at the bottom of the stack. The override
options (-isfx, -imusic, -icd) are processed in order and each add
one interface to the stack. In other words, the last option defines
the most important interface.

For example, to use FMOD but play MIDI music via FluidSynth, the
options would be "-fmod -imusic fluidsynth".

doomsday/engine/api/sys_audiod.h

@@ -28,7 +28,7 @@
  */
 ///@{
 
-typedef enum {
+typedef enum audiodriverid_e {
     AUDIOD_DUMMY,
     AUDIOD_SDL_MIXER,
     AUDIOD_OPENAL,
@@ -37,7 +37,15 @@ typedef enum {
     AUDIOD_DSOUND,  // Win32 only
     AUDIOD_WINMM,   // Win32 only
     AUDIODRIVER_COUNT
-} audiodriver_e;
+} audiodriverid_t;
+
+typedef enum {
+    AUDIO_INONE,
+    AUDIO_ISFX,
+    AUDIO_IMUSIC,
+    AUDIO_ICD,
+    AUDIO_IMUSIC_OR_ICD
+} audiointerfacetype_t;
 
 #ifdef WIN32
 #  define VALID_AUDIODRIVER_IDENTIFIER(id)    ((id) >= AUDIOD_DUMMY && (id) < AUDIODRIVER_COUNT)

doomsday/engine/portable/include/audiodriver.h

@@ -23,6 +23,7 @@
 #ifndef LIBDENG_AUDIO_DRIVER_H
 #define LIBDENG_AUDIO_DRIVER_H
 
+#include "dd_string.h"
 #include "sys_audiod.h"
 #include "sys_audiod_sfx.h"
 #include "sys_audiod_mus.h"
@@ -31,9 +32,16 @@
 extern "C" {
 #endif
 
+#define MAX_AUDIO_INTERFACES  16 // arbitrary
+
 boolean AudioDriver_Init(void);
 void AudioDriver_Shutdown(void);
 
+/**
+ * Prints a list of the selected, active interfaces to the log.
+ */
+void AudioDriver_PrintInterfaces(void);
+
 /**
  * Retrieves the main interface of the audio driver to which @a audioInterface
  * belongs.
@@ -44,23 +52,43 @@ void AudioDriver_Shutdown(void);
  * @return Audio driver interface, or @c NULL if the none of the loaded drivers
  * match.
  */
-audiodriver_t* AudioDriver_Interface(void* audioInterface);
+audiodriver_t* AudioDriver_Interface(void* anyAudioInterface);
+
+AutoStr* AudioDriver_InterfaceName(void* anyAudioInterface);
+
+audiointerfacetype_t AudioDriver_InterfaceType(void* anyAudioInterface);
+
+/**
+ * Lists all active interfaces of a given type, in priority order. Alternatively,
+ * counts the number of active interfaces of a given type.
+ *
+ * @param type              Type of interface to look for.
+ * @param listOfInterfaces  Matching interfaces are written here. Points to an
+ *                          array of pointers. If this is @c NULL,
+ *                          just counts the number of matching interfaces.
+ *
+ * @return Number of matching interfaces.
+ */
+int AudioDriver_FindInterfaces(audiointerfacetype_t type, void** listOfInterfaces);
 
 /**
- * Returns the current active SFX interface. @c NULL is returned is no SFX
- * playback is available.
+ * Returns the current active primary SFX interface. @c NULL is returned is no
+ * SFX playback is available.
  */
 audiointerface_sfx_generic_t* AudioDriver_SFX(void);
 
 /**
- * Returns the currently active Music interface. @c NULL is returned if no music
- * playback is available.
+ * Determines if at least one music interface is available for music playback.
  */
-audiointerface_music_t* AudioDriver_Music(void);
+boolean AudioDriver_Music_Available(void);
 
 /**
  * Returns the currently active CD playback interface. @c NULL is returned if
  * CD playback is not available.
+ *
+ * @note  The CD interface is considered to belong in the music aggregate
+ *        interface (see audiodriver_music.h), and usually does not need to
+ *        be individually manipulated.
  */
 audiointerface_cd_t* AudioDriver_CD(void);
 

doomsday/engine/portable/include/audiodriver_music.h

@@ -5,8 +5,8 @@
  * The main purpose of this low-level thin layer is to group individual music
  * interfaces together as an aggregate that can be treated as one interface.
  *
- * @todo  Integrate the CD interface into this, too, as it is treated as an
- *        additional/alternative music interface.
+ * The CD playback interface is part of the aggregate in addition to the
+ * regular Music interfaces.
  *
  * @authors Copyright © 2012 Jaakko Keränen <jaakko.keranen@iki.fi>
  * @authors Copyright © 2012 Daniel Swanson <danij@dengine.net>
@@ -36,14 +36,22 @@
 extern "C" {
 #endif
 
-void AudioDriver_Music_SetSoundFont(const char* fileName);
+void AudioDriver_Music_Set(int property, void* ptr);
 
 int AudioDriver_Music_PlayNativeFile(const char* fileName, boolean looped);
 
 int AudioDriver_Music_PlayLump(lumpnum_t lump, boolean looped);
 
 int AudioDriver_Music_PlayFile(const char* virtualOrNativePath, boolean looped);
 
+int AudioDriver_Music_PlayCDTrack(int track, boolean looped);
+
+/**
+ * Determines if music is currently playing on any of the Music or CD audio
+ * interfaces.
+ *
+ * @return @c true if music is playing.
+ */
 boolean AudioDriver_Music_IsPlaying(void);
 
 /**