Enhanced sound support (PR #450)

This fork features some enhancements for the sound system. Although my
plans initially were more ambitious, this will do for now.

Adds sound_file_path option, making the current sound option much easier
to use.

Moved all the sound code to its own set of files for future expansion (I
have some plans). Also, makes it painless to fiddle around with
PLAY_SOUND_COMMAND, which previously was in AppHdr.h despite being used
in just one function.

(UPDATE) Adds multiple cues that can be used in place of typical regular
expressions. Some examples are PICKUP, MEMORISE_SPELL, and CHANGE
QUIVER. See sound.h for a full list. I intend of expanding this.

Very incomplete support for a hold_sound option, which is supposed to
pause the game while the sound is playing. This pause is intended to be
sequential, delaying the rest of the message until the sound finishes. I
have two purposes for this: giving battles a real-time feel, and to
highlight those epic victories. This feature doesn't work as intended,
so I dropped the in-game documentation for now.

(UPDATE) Adds one_SDL_sound_channel. Originally, sound behavior depended
on whether you were playing with SDL or using the SOUND_PLAY_COMMAND
define; if playing with SDL/Tiles, only one sound would play at once,
whereas SOUND_PLAY_COMMAND allowed as many sounds as were necessary. By
default, one_SDL_sound_channel is set to false, making it behave as
SOUND_PLAY_COMMAND. However, players can restore the old behavior by
setting this option to true.

(UPDATE) The version screen now tells the user how sounds will be
played. (i.e. "Windows Multimedia API," "External command," or
"SDL_mixer")

Anyway, I know this works as intended on Linux and Cygwin, and I did run
crawl -test to double check stuff. UPDATE: I have now verified that it
works with Tiles! However, I can't test with Windows, Mac, etc. I may or
may not have broken the sound stuff. At worst, some more files need to
be included in sound.cc.

Finally, the game works as normal when compiled without sound support. I
only tested this in Linux, but I'm certain that it should be the same
everywhere else.

Happy crawling!
~Autofire

Author: Autofire

crawl-ref/INSTALL.txt

@@ -89,8 +89,8 @@ changes to the level compiler, you'll need the flex and bison/byacc tools
 (Other lex/yaccs may also work). More details are available below.
 
 Sound can be provided by SDL2_mixer (the default), by WINMM on Windows (defined
-by WINMM_PLAY_SOUNDS in AppHdr.h), or by an external command on Unix systems
-(SOUND_PLAY_COMMAND in AppHdr.h). To enable this, append SOUND=y to the make
+by WINMM_PLAY_SOUNDS in sound.h), or by an external command on Unix systems
+(SOUND_PLAY_COMMAND in sound.h). To enable this, append SOUND=y to the make
 invocation.
 
 Crawl includes Lua 5.1.4 in its submodules. Crawl uses Lua for dungeon

crawl-ref/docs/keybind.txt

@@ -111,6 +111,7 @@ Meta-commands
 ^A        CMD_TOGGLE_AUTOPICKUP
 ^C        CMD_CLEAR_MAP
 ^D, ~     CMD_MACRO_ADD
+<unbound> CMD_TOGGLE_SOUND      (only when compiled with sound)
 ^Q        CMD_QUIT
 ^R        CMD_REDRAW_SCREEN
 S         CMD_SAVE_GAME

crawl-ref/docs/options_guide.txt

@@ -19,7 +19,8 @@ The contents of this text are:
                 restart_after_game, restart_after_save,
                 default_manual_training, autopickup_starting_ammo
 2-  File System and Sound.
-                crawl_dir, morgue_dir, save_dir, macro_dir, sound
+                crawl_dir, morgue_dir, save_dir, macro_dir, sound, hold_sound,
+                sound_file_path
 3-  Interface.
 3-a     Dropping and Picking up.
                 autopickup, autopickup_exceptions, default_autopickup,
@@ -397,10 +398,36 @@ macro_dir = settings/
         It should end with the path delimiter.
 
 sound ^= <regex>:<path to sound file>, <regex>:<path>, ...
+        (Requires "Sound support"; check your version info)
         (Ordered list option)
         Plays the sound file if a message contains regex. The regex
         should not include commas or colons. For example
              sound += LOW HITPOINT WARNING:sound\sounds2\danger3.wav
+        There are certain pre-defined regexes, as well, which can be
+        used to get a sound to trigger for something that cannot
+        otherwise be matched using a regex string. For example,
+        using FIRE_PROMPT_SOUND for the regex will cause Crawl to
+        play a sound whenever the fire prompt is opened. Check
+        sound.h for a full listing of all these pre-defined regex
+        strings.
+
+sound_file_path = <path>
+        When playing sounds (with the option above), the contents of
+        this variable is appended to the start of the path. This is
+        intended to make it easier to take one configuration across
+        several platforms. These two lines are equivalent to the
+        example above:
+             sound_file_path = sound\sounds2\
+             sound += LOW HITPOINT WARNING:danger3.wav
+        The most recent instance of this option is the one that
+        takes effect, and is not applied retroactively to previous
+        instances of the sound option.
+
+one_SDL_sound_channel = false
+        When true, only one sound can play at a time (if using SDL).
+        Is false by default since non-SDL sound backends don't
+        support such control.
+
 
 3-  Interface.
 ==============

crawl-ref/source/AppHdr.h

@@ -148,12 +148,6 @@ static inline double pow(int x, double y) { return std::pow((double)x, y); }
     // uncomment the line below and add -lpcre to your makefile.
     // #define REGEX_PCRE
 
-    // Uncomment (and edit as appropriate) to play sounds.
-    //
-    // WARNING: Filenames passed to this command *are not validated in any way*.
-    //
-    // #define SOUND_PLAY_COMMAND "/usr/bin/play -v .5 \"%s\" 2>/dev/null &"
-
     #include "libunix.h"
 
 #elif defined(TARGET_OS_WINDOWS)
@@ -172,9 +166,6 @@ static inline double pow(int x, double y) { return std::pow((double)x, y); }
     #define FILE_SEPARATOR '/'
     #define ALT_FILE_SEPARATOR '\\'
 
-    // Uncomment to play sounds. winmm must be linked in if this is uncommented.
-    // #define WINMM_PLAY_SOUNDS
-
     // Use Perl-compatible regular expressions. libpcre must be available and
     // linked in. Required in the absence of POSIX regexes.
     #ifndef REGEX_PCRE

crawl-ref/source/MSVC/crawl.vcxproj

@@ -468,6 +468,7 @@ perl.exe "util/gen-cflg.pl" compflag.h "<UNKNOWN>" "<UNKNOWN>"
     <ClCompile Include="..\skills.cc" />
     <ClCompile Include="..\skill-menu.cc" />
     <ClCompile Include="..\species.cc" />
+    <ClCompile Include="..\sound.cc" />
     <ClCompile Include="..\spl-book.cc" />
     <ClCompile Include="..\spl-cast.cc" />
     <ClCompile Include="..\spl-clouds.cc" />

crawl-ref/source/Makefile

@@ -18,7 +18,8 @@
 # Typical parameters:
 #    TILES         -- set to anything to enable tiles build
 #
-#    SOUND         -- set to anything to enable sound
+#    SOUND         -- set to anything to enable sound; note that you will need to
+#                     uncomment some lines in sound.h if not building tiles
 #
 #    CROSSHOST     -- target system, eg, i386-pc-msdosdjgpp or i586-mingw32msvc
 #

crawl-ref/source/Makefile.obj

@@ -202,6 +202,7 @@ show.o \
 showsymb.o \
 skill-menu.o \
 skills.o \
+sound.o \
 species.o \
 spl-book.o \
 spl-cast.o \

crawl-ref/source/android-project/jni/src/Android.mk

@@ -222,6 +222,7 @@ LOCAL_SRC_FILES := $(SDL_PATH)/src/main/android/SDL_android_main.c \
     $(CRAWL_PATH)/showsymb.cc \
     $(CRAWL_PATH)/skill-menu.cc \
     $(CRAWL_PATH)/skills.cc \
+    $(CRAWL_PATH)/sound.cc \
     $(CRAWL_PATH)/species.cc \
     $(CRAWL_PATH)/spl-book.cc \
     $(CRAWL_PATH)/spl-cast.cc \

crawl-ref/source/command-type.h

@@ -51,6 +51,7 @@ enum command_type
     CMD_GO_UPSTAIRS,
     CMD_GO_DOWNSTAIRS,
     CMD_TOGGLE_AUTOPICKUP,
+    CMD_TOGGLE_SOUND,
     CMD_TOGGLE_TRAVEL_SPEED,
     CMD_PICKUP,
     CMD_PICKUP_QUANTITY,

crawl-ref/source/command.cc

@@ -27,6 +27,7 @@
 #include "output.h"
 #include "prompt.h"
 #include "showsymb.h"
+#include "sound.h"
 #include "state.h"
 #include "stringutil.h"
 #include "syscalls.h"
@@ -65,8 +66,8 @@ static const char *features[] =
     "Glob patterns",
 #endif
 
-#if defined(SOUND_PLAY_COMMAND) || defined(WINMM_PLAY_SOUNDS)
-    "Sound support",
+#if defined(USE_SOUND) && defined(SOUND_BACKEND)
+    SOUND_BACKEND,
 #endif
 
 #ifdef DGL_MILESTONES
@@ -1026,6 +1027,9 @@ static void _add_formatted_keyhelp(column_composer &cols)
     _add_command(cols, 1, CMD_SHOW_TERRAIN, "toggle view layers");
     _add_command(cols, 1, CMD_DISPLAY_OVERMAP, "show dungeon Overview");
     _add_command(cols, 1, CMD_TOGGLE_AUTOPICKUP, "toggle auto-pickup");
+#ifdef USE_SOUND
+    _add_command(cols, 1, CMD_TOGGLE_SOUND, "mute/unmute sound effects");
+#endif
     _add_command(cols, 1, CMD_TOGGLE_TRAVEL_SPEED, "set your travel speed to your");
     cols.add_formatted(1, "         slowest ally\n",
                            false);