update soundlib interface

Add SOUND_TRIGGER_AMBIENCE

doc/sound.txt

@@ -52,8 +52,8 @@ There are 4 distinct types of sound sound_triggers used by NetHack.
 
     SOUND_TRIGGER_ACHIEVEMENTS   Invoked by the core when an in-game
                                  achievement is reached. The soundlib routines
-                                 could play appropriate theme or mood music in
+                                 could play appropriate theme or some fanfare
-                                 response.
+                                 in response.
                                  There needs to be a way to map each
                                  achievement to a specific external
                                  sound file or resource. The sound
@@ -77,8 +77,19 @@ There are 4 distinct types of sound sound_triggers used by NetHack.
                                  file. The sound interface function
                                  pointer used to invoke it:
 
-                                 void (*sound_soundeffect)
+                                 void (*sound_soundeffect)(char *desc,
-                                       (char *desc, int32_t, int32_t volume);
+                                               int32_t seid, int32_t volume);
+
+    SOUND_TRIGGER_AMBIENCE       Invoked by the core in response to something
+                                 atmosphere or mood-producing or flavorful.
+                                 Unlike the other interface functions, this
+                                 one gets called to notify the sound interface
+                                 at the outset (amb_action_begin), at the
+                                 termination (amb_action_end), and
+                                 periodically in-between as needed
+                                 (amb_action_upate), likely with a different
+                                 hero proximity value.
+
 
 The types of sound sound_triggers supported by a particular soundlib
 implementation are specified in that library's soundlib file, which is usually
@@ -97,6 +108,8 @@ the sound_triggers field of the sound_procs struct:
               int32_t volume);
         void (*sound_play_usersound)(char *filename, int32_t volume,
               int32_t usidx);
+        void (*sound_ambience)(int32_t ambienceid, int32_t ambience_action,
+               int32_t hero_proximity);
     };
 
 A sound library integration support file can implement one, two, three or
@@ -211,6 +224,29 @@ sound_play_usersound(char *filename, int32_t volume, int32_t usidx);
        volume adjustments. If it doesn't, the volume argument would
        just have to be ignored.
 
+sound_ambience(int32_t ambienceid, int32_t ambience_action,
+               int32_t hero_proximity);
+    -- NetHack will call this function when it wants a particular
+       ambience related sound played in order to provide ambience or flavor.
+    -- The ambienceid is used to identify the particular ambience sound
+       being sought. The abienceid identifiers are from the
+       'enum ambiences' list in include/sndprocs.h.  It is recommended
+       that you look them up there as new ones get added periodically
+       as game development continues. The identifiers all begin
+       with 'amb_'.
+    -- ambience_action. A soundlib integration support file that has
+       SOUND_TRIGGER_AMBIENCE support is expected to commence playing the
+       sound when it receives an ambience_action of ambience_begin. It
+       will receive an ambience_action of ambience_end when it should cease
+       playing the sound. It may receive an ambience_action of
+       ambience_update periodically, anytime the ambience is underway,
+       and it should respond accordingly: perhaps by adjusting the nature
+       of the sound being heard, or possibly by just adjusting the volume.
+    -- hero_proximity could be zero, in which case the ambience being
+       triggered is not impacted by the hero's distance from anything.
+       If the distance of the hero from the source of the ambience does
+       matter, then a distance value will be in hero_proximity.
+
 
 III.  Global variables
 
@@ -322,13 +358,15 @@ use the following guidelines:
        struct sound_procs myprefix_procs = {
            SOUNDID(myprefix),
            SOUND_TRIGGER_USERSOUNDS | SOUND_TRIGGER_HEROMUSIC
-              | SOUND_TRIGGER_ACHIEVEMENTS |SOUND_TRIGGER_SOUNDEFFECTS,
+              | SOUND_TRIGGER_ACHIEVEMENTS |SOUND_TRIGGER_SOUNDEFFECTS
+              | SOUND_TRIGGER_AMBIENCE,
            myprefix_init_nhsound,
            myprefix_exit_nhsound,
            myprefix_achievement,
            myprefix_soundeffect,
            myprefix_hero_playnotes,
            myprefix_play_usersound,
+           myprefix_ambience),
        };
 
    The first entry in this structure should be the SOUNDID(myprefix)
@@ -485,17 +523,21 @@ static void sample_achievement(schar, schar, int32_t);
 static void sample_soundeffect(char *, int32_t, int32_t);
 static void sample_hero_playnotes(int32_t, const char *, int32_t);
 static void sample_play_usersound(char *, int32_t, int32_t);
+static void sample_ambience(int32_t ambienceid, int32_t ambience_action,
+                            int32_t hero_proximity);
 
 struct sound_procs sample_procs = {
     SOUNDID(sample),
     SOUND_TRIGGER_USERSOUNDS | SOUND_TRIGGER_HEROMUSIC
-        | SOUND_TRIGGER_ACHIEVEMENTS |SOUND_TRIGGER_SOUNDEFFECTS,
+        | SOUND_TRIGGER_ACHIEVEMENTS |SOUND_TRIGGER_SOUNDEFFECTS
+        | SOUND_TRIGGER_AMBIENCE
     sample_init_nhsound,
     sample_exit_nhsound,
     sample_achievement,
     sample_soundeffect,
     sample_hero_playnotes,
     sample_play_usersound,
+    sample_ambience,
 };
 
 static void
@@ -539,5 +581,11 @@ sample_play_usersound(char *filename, int volume, int usidx)
 
 }
 
+static void
+sample_ambience(int32_t ambienceid, int32_t ambience_action,
+                int32_t hero_proximity)
+{
+}
+
 /* end of sample.c */
 -- >8 --

include/sndprocs.h

@@ -48,8 +48,11 @@ struct sound_procs {
     void (*sound_exit_nhsound)(const char *);
     void (*sound_achievement)(schar, schar, int32_t);
     void (*sound_soundeffect)(char *desc, int32_t, int32_t volume);
-    void (*sound_hero_playnotes)(int32_t instrument, const char *str, int32_t volume);
+    void (*sound_hero_playnotes)(int32_t instrument, const char *str,
+                                 int32_t volume);
     void (*sound_play_usersound)(char *filename, int32_t volume, int32_t idx);
+    void (*sound_ambience)(int32_t ambience_action, int32_t ambienceid,
+                           int32_t volume);
 };
 
 extern struct sound_procs sndprocs;
@@ -63,7 +66,8 @@ extern struct sound_procs sndprocs;
 #define SOUND_TRIGGER_HEROMUSIC    0x0002L
 #define SOUND_TRIGGER_ACHIEVEMENTS 0x0004L
 #define SOUND_TRIGGER_SOUNDEFFECTS 0x0008L
-                            /* 28 free bits */
+#define SOUND_TRIGGER_AMBIENCE     0x0010L
+                            /* 27 free bits */
 
 extern struct sound_procs soundprocs;
 
@@ -322,6 +326,14 @@ enum sound_effect_entries {
     number_of_se_entries
 };
 
+enum ambience_actions {
+    ambience_nothing, ambience_begin, ambience_end, ambience_update
+};
+
+enum ambiences {
+    amb_noambience,
+};
+
 enum achievements_arg2 {
     sa2_splashscreen, sa2_newgame_nosplash, sa2_restoregame,
     sa2_xplevelup, sa2_xpleveldown

sound/macsound/macsound.m

@@ -26,12 +26,15 @@ static void macsound_achievement(schar, schar, int32_t);
 static void macsound_soundeffect(char *, int32_t, int32_t);
 static void macsound_hero_playnotes(int32_t, const char *, int32_t);
 static void macsound_play_usersound(char *, int32_t, int32_t);
+static void macsounde_ambience(int32_t, int32_t, int32_t);
+
 static int affiliate(int32_t seid, const char *soundname);
 
 /*
  * Sound capabilities that can be enabled:
  *    SOUND_TRIGGER_USERSOUNDS | SOUND_TRIGGER_HEROMUSIC
- *        | SOUND_TRIGGER_ACHIEVEMENTS | SOUND_TRIGGER_SOUNDEFFECTS,
+ *        | SOUND_TRIGGER_ACHIEVEMENTS | SOUND_TRIGGER_SOUNDEFFECTS
+ *        | SOUND_TRIGGER_AMBIENCE,
  */
 
 struct sound_procs macsound_procs = {
@@ -43,6 +46,7 @@ struct sound_procs macsound_procs = {
     macsound_soundeffect,
     macsound_hero_playnotes,
     macsound_play_usersound,
+    macsound_ambience,
 };
 
 static void
@@ -66,6 +70,12 @@ macsound_achievement(schar ach1 UNUSED, schar ach2 UNUSED, int32_t repeat UNUSED
 
 }
 
+static void
+macsound_ambience(int32_t ambienceid, int32_t ambience_action,
+                int32_t hero_proximity)
+{
+}
+
 /* magic number 47 is the current number of sound_ files to include */
 #define EXTRA_SOUNDS 47
 

sound/windsound/windsound.c

@@ -23,6 +23,8 @@ static void windsound_achievement(schar, schar, int32_t);
 static void windsound_soundeffect(char *, int32_t, int32_t);
 static void windsound_hero_playnotes(int32_t instrument, const char *str, int32_t volume);
 static void windsound_play_usersound(char *, int32_t, int32_t);
+static void windsound_ambience(int32_t ambienceid, int32_t ambience_action,
+                               int32_t hero_proximity);
 
 /* supporting routines */
 static void adjust_soundargs_for_compiler(int32_t *, DWORD *, char **);
@@ -31,32 +33,39 @@ static void maybe_preinsert_directory(int32_t, char *, char *, size_t);
 struct sound_procs windsound_procs = {
     SOUNDID(windsound),
     SOUND_TRIGGER_USERSOUNDS | SOUND_TRIGGER_SOUNDEFFECTS
-        | SOUND_TRIGGER_HEROMUSIC,
+        | SOUND_TRIGGER_HEROMUSIC | SOUND_TRIGGER_AMBIENCE,
     windsound_init_nhsound,
     windsound_exit_nhsound,
     windsound_achievement,
     windsound_soundeffect,
     windsound_hero_playnotes,
     windsound_play_usersound,
+    windsound_ambience,
 };
 
-void
+static void
 windsound_init_nhsound(void)
 {
     /* No steps required */
 }
 
-void
+static void
 windsound_exit_nhsound(const char *reason)
 {
 }
 
-void
+static void
 windsound_achievement(schar ach1, schar ach2, int32_t repeat)
 {
 }
 
-void
+static void
+windsound_ambience(int32_t ambienceid, int32_t ambience_action,
+                int32_t hero_proximity)
+{
+}
+
+static void
 windsound_soundeffect(char *desc, int32_t seid, int32_t volume)
 {
 #ifdef SND_SOUNDEFFECTS_AUTOMAP
@@ -86,7 +95,7 @@ windsound_soundeffect(char *desc, int32_t seid, int32_t volume)
 
 #define WAVEMUSIC_SOUNDS
 
-void
+static void
 windsound_hero_playnotes(int32_t instrument, const char *str, int32_t volume)
 {
 #ifdef WAVEMUSIC_SOUNDS
@@ -174,14 +183,15 @@ windsound_hero_playnotes(int32_t instrument, const char *str, int32_t volume)
 #endif
 }
 
-void
+static void
 windsound_play_usersound(char *filename, int32_t volume UNUSED, int32_t idx UNUSED)
 {
     /*    pline("play_usersound: %s (%d).", filename, volume); */
     (void) sndPlaySound(filename, SND_ASYNC | SND_NODEFAULT | SND_FILENAME);
 }
 
-static void adjust_soundargs_for_compiler(
+static void
+adjust_soundargs_for_compiler(
     int32_t *sefilename_flags,
     DWORD *fdwsound,
     char **dirbuf)

src/sounds.c

@@ -1645,12 +1645,13 @@ extern struct sound_procs qtsound_procs;
 struct sound_procs nosound_procs = {
     SOUNDID(nosound),
     0L,
-    (void (*)(void)) 0,                     /* init_nhsound    */
+    (void (*)(void)) 0,                           /* init_nhsound   */
-    (void (*)(const char *)) 0,             /* exit_nhsound    */
+    (void (*)(const char *)) 0,                   /* exit_nhsound   */
-    (void (*)(schar, schar, int32_t)) 0,    /* achievement     */
+    (void (*)(schar, schar, int32_t)) 0,          /* achievement    */
-    (void (*)(char *, int32_t, int32_t)) 0, /* sound effect    */
+    (void (*)(char *, int32_t, int32_t)) 0,       /* sound effect   */
-    (void (*)(int32_t, const char *, int32_t)) 0, /* hero_playnotes  */
+    (void (*)(int32_t, const char *, int32_t)) 0, /* hero_playnotes */
-    (void (*)(char *, int32_t, int32_t)) 0, /* play_usersound  */
+    (void (*)(char *, int32_t, int32_t)) 0,       /* play_usersound */
+    (void (*)(int32_t, int32_t, int32_t)) 0,      /* ambience       */
 };
 
 /* The order of these array entries must match the
@@ -1811,6 +1812,9 @@ static void nosound_resume_nhsound(void);
 static void nosound_achievement(schar, schar, int32_t);
 static void nosound_soundeffect(int32_t, int32_t);
 static void nosound_play_usersound(char *, int32_t, int32_t);
+static void nosound_ambience(int32_t, int32_t, int32_t);
+{
+}
 
 static void
 nosound_init_nhsound(void)
@@ -1841,6 +1845,12 @@ static void
 nosound_play_usersound(char *filename, int volume, int idx)
 {
 }
+
+static void
+nosound_ambience(int32_t ambienceid, int32_t ambience_action,
+                int32_t hero_proximity)
+{
+}
 #endif
 
 #ifdef SND_SOUNDEFFECTS_AUTOMAP

win/Qt/qt_bind.cpp

@@ -1062,6 +1062,9 @@ void NetHackQtBind::qtsound_soundeffect(char *desc UNUSED, int32_t seid UNUSED,
 void NetHackQtBind::qtsound_hero_playnotes(int32_t instrument UNUSED, const char *str UNUSED, int32_t volume UNUSED)
 {
 }
+void NetHackQtBind::qtsound_ambience(int32_t ambienceid UNUSED, int32_t ambience_action UNUSED, int32_t proximity UNUSED)
+{
+}
 #endif
 
 #if defined(USER_SOUNDS) && !defined(QT_NO_SOUND)
@@ -1182,6 +1185,7 @@ struct sound_procs qtsound_procs = {
     nethack_qt_::NetHackQtBind::qtsound_soundeffect,
     nethack_qt_::NetHackQtBind::qtsound_hero_playnotes,
     nethack_qt_::NetHackQtBind::qtsound_play_usersound,
+    nethack_qt_::NetHackQtBind::qtsound_ambience,
 };
 #endif /* SND_LIB_QTSOUND and !QT_NO_SOUND */
 

win/Qt/qt_bind.h

@@ -102,6 +102,7 @@ public:
         static void qtsound_soundeffect(char *, int32_t, int32_t);
         static void qtsound_hero_playnotes(int32_t instrument, const char *str, int32_t volume);
         static void qtsound_play_usersound(char *, int32_t, int32_t);
+        static void qtsound_ambience(int32_t, int32_t, int32_t);
 #endif
 
 private: