nullsound: rework exclusive ADPCM playback semantics

Update the ADPCM SFX playback functions:
  . snd_X_play now plays a ADPCM sample only if the current
    channel is not locked for uninterruptible playback.
  . snd_X_play_exclusive locks a channel to be uninterruptible,
    except if another snd_X_play_exclusive is run on the same
    channel.

Author: dciabrin

nullsound/adpcm.s

@@ -37,12 +37,18 @@
 state_adpcm_busy:
         .blkb   1
 
+;;; ADPCM channels currently held by an exclusive play action
+;;; | B  | __ | A6 | A5 | A4 | A3 | A2 | A1 |
+state_adpcm_exclusive:
+        .blkb   1
+
 
         .area  CODE
 
 init_adpcm_state_tracker::
         ld      a, #0
         ld      (state_adpcm_busy), a
+        ld      (state_adpcm_exclusive), a
         ret
 
 update_adpcm_state_tracker::
@@ -58,12 +64,15 @@ update_adpcm_state_tracker::
         ld      b, #REG_ADPCM_PLAYBACK_MASK
         ld      c, #0x00
         call    ym2610_write_port_a
-        ;; a <- busy state clear mask
+        ;; a <-  busy/exclusive states clear mask
         cpl
         ld      b, a
         ld      a, (state_adpcm_busy)
         and     b
         ld      (state_adpcm_busy), a
+        ld      a, (state_adpcm_exclusive)
+        and     b
+        ld      (state_adpcm_exclusive), a
 _adpcm_no_state_update:
         ret
 
@@ -97,7 +106,7 @@ _adpcm_no_state_update:
 ;;; ------
 ;;; ix: sample play config
 ;;; [a modified - other registers saved]
-snd_adpcm_a_play::
+snd_adpcm_a_play_common::
         push    bc
         ;; stop playback
         ld      b, #REG_ADPCM_A_START_STOP
@@ -152,23 +161,44 @@ _snd_adpcm_a_end:
         ret
 
 
-;;; Play a ROM sample on a ADPCM-A channel only if it's not in use
+;;; Play a ROM sample on a ADPCM-A channel
+;;; If the channel is currently locked by an ongoing play,
+;;; no action is taken and the ongoing play continues.
 ;;; ------
 ;;; ix: sample play config
 ;;; [a modified - other registers saved]
-snd_adpcm_a_play_exclusive::
+snd_adpcm_a_play::
         push    bc
-        ld      a, (state_adpcm_busy)
+        ld      a, (state_adpcm_exclusive)
         ld      b, A_CHANNEL_BIT(ix)
         and     b
         jp      nz, _snd_adpcm_a_busy
         ;; play sample (will mark the channel as busy)
-        call    snd_adpcm_a_play
+        call    snd_adpcm_a_play_common
 _snd_adpcm_a_busy:
         pop     bc
         ret
 
 
+;;; Play a ROM sample on a ADPCM-A channel
+;;; If the channel is currently locked by an ongoing play,
+;;; replace it and play the new sample while keeping this channel locked.
+;;; ------
+;;; ix: sample play config
+;;; [a modified - other registers saved]
+snd_adpcm_a_play_exclusive::
+        push    bc
+        ;; lock the channel
+        ld      a, (state_adpcm_exclusive)
+        ld      b, A_CHANNEL_BIT(ix)
+        or      b
+        ld      (state_adpcm_exclusive), a
+        ;; play sample (will mark the channel as busy)
+        call    snd_adpcm_a_play_common
+        pop     bc
+        ret
+
+
 ;;; Configure a ROM sample on the ADPCM-B channel for playback
 ;;; ------
 ;;; ix: sample play config
@@ -216,78 +246,99 @@ snd_adpcm_b_play_common::
         ld      b, #REG_ADPCM_B_VOLUME
         ld      c, B_VOLUME(ix)
         call    ym2610_write_port_a
+        ;; mark the channel as busy
+        ;; playback will be started by the caller
+        ld      a, (state_adpcm_busy)
+        ld      c, #0x80
+        or      c
+        ld      (state_adpcm_busy), a
         ret
 
 
 ;;; Play a ROM sample on the ADPCM-B channel
+;;; If the channel is currently locked by an ongoing play,
+;;; replace it and play the new sample while keeping this channel locked.
 ;;; ------
 ;;; ix: sample play config
 ;;; [a modified - other registers saved]
-snd_adpcm_b_play::
+snd_adpcm_b_play_exclusive::
         push    bc
-        call    snd_adpcm_b_play_common
+        ;; lock the channel
+        ld      a, (state_adpcm_exclusive)
+        ld      b, #0x80
+        or      b
+        ld      (state_adpcm_exclusive), a
         ;; play channel
+        call    snd_adpcm_b_play_common
         ld      b, #REG_ADPCM_B_START_STOP
         ld      c, #0x80
         call    ym2610_write_port_a
-        ;; mark the channel as busy
-        ld      a, (state_adpcm_busy)
-        ld      c, #0x80
-        or      c
-        ld      (state_adpcm_busy), a
         pop     bc
         ret
 
 
 ;;; Play and loop a ROM sample on the ADPCM-B channel
-;;; ------
+;;; If the channel is currently locked by an ongoing play,
+;;; replace it and play the new sample while keeping this channel locked.
+;; ------
 ;;; ix: sample play config
 ;;; [a modified - other registers saved]
-snd_adpcm_b_play_loop::
+snd_adpcm_b_play_loop_exclusive::
         push    bc
-        call    snd_adpcm_b_play_common
+        ;; lock the channel
+        ld      a, (state_adpcm_exclusive)
+        ld      b, #0x80
+        or      b
+        ld      (state_adpcm_exclusive), a
         ;; play channel
+        call    snd_adpcm_b_play_common
         ld      b, #REG_ADPCM_B_START_STOP
         ld      c, #0x90
         call    ym2610_write_port_a
-        ;; mark the channel as busy
-        ld      a, (state_adpcm_busy)
-        ld      c, #0x80
-        or      c
-        ld      (state_adpcm_busy), a
         pop     bc
         ret
 
 
-;;; Play a ROM sample on the ADPCM-B channel only if it's not in use
+;;; Play a ROM sample on the ADPCM-B channel
+;;; If the channel is currently locked by an ongoing play,
+;;; no action is taken and the ongoing play continues.
 ;;; ------
 ;;; ix: sample play config
 ;;; [a modified - other registers saved]
-snd_adpcm_b_play_exclusive::
+snd_adpcm_b_play::
         push    bc
-        ld      a, (state_adpcm_busy)
+        ld      a, (state_adpcm_exclusive)
         ld      b, #0x80
         and     b
         jp      nz, _snd_adpcm_b_busy
         ;; play sample (will mark the channel as busy)
-        call    snd_adpcm_b_play
+        call    snd_adpcm_b_play_common
+        ld      b, #REG_ADPCM_B_START_STOP
+        ld      c, #0x80
+        call    ym2610_write_port_a
 _snd_adpcm_b_busy:
         pop     bc
         ret
 
 
-;;; Play and loop a ROM sample on the ADPCM-B channel only if it's not in use
+;;; Play and loop a ROM sample on the ADPCM-B channel
+;;; If the channel is currently locked by an ongoing play,
+;;; no action is taken and the ongoing play continues.
 ;;; ------
 ;;; ix: sample play config
 ;;; [a modified - other registers saved]
-snd_adpcm_b_play_loop_exclusive::
+snd_adpcm_b_play_loop::
         push    bc
-        ld      a, (state_adpcm_busy)
+        ld      a, (state_adpcm_exclusive)
         ld      b, #0x80
         and     b
         jp      nz, _snd_adpcm_b_loop_busy
         ;; play sample (will mark the channel as busy)
-        call    snd_adpcm_b_play_loop
+        call    snd_adpcm_b_play_common
+        call    snd_adpcm_b_play_common
+        ld      b, #REG_ADPCM_B_START_STOP
+        ld      c, #0x90
+        call    ym2610_write_port_a
 _snd_adpcm_b_loop_busy:
         pop     bc
         ret

tools/soundtool.py

@@ -23,6 +23,7 @@
 import glob
 import os
 import wave
+from operator import itemgetter
 
 # Special handling for YAML: try to import ruamel.yaml first,
 # because it's better at keeping comments in YAML files, and
@@ -131,8 +132,11 @@ def detect_adpcm_type(f):
                 name=mkid(os.path.splitext(os.path.basename(f))[0])
                 sfx = {'name': name, 'uri': uri}
                 sfxdir=os.path.basename(os.path.dirname(f))
-                if re.match(r'^[1-6]$',sfxdir):
-                    sfx['channel']=int(sfxdir)
+                m = re.match(r'^([1-6])(_x)?$',sfxdir)
+                if m:
+                    sfx['channel']=int(m[1])
+                    if m[2]:
+                        sfx['exclusive']=True
                 read_data.append([name, {sfxtype: sfx}])
 
     result_data = []
@@ -143,9 +147,15 @@ def detect_adpcm_type(f):
         else:
             result_data.append(data)
 
+    # sort result_data to get a consistent output on update
+    result_keys = [next(iter(x.keys())) for x in result_data]
+    decorated_data = [((type, data[type]['channel'], data[type]['name']), data) for type, data in zip(result_keys, result_data)]
+    decorated_data.sort(key=itemgetter(0))
+    sorted_data = [data for key, data in decorated_data]
+
     # save sound map description
     print(header, end='', file=output)
-    print(yaml_dump(result_data, end='', f=output))
+    yaml_dump(sorted_data, end='', f=output)
 
 
 
@@ -234,10 +244,14 @@ def print_music_cmd(stype, data, bank):
     def print_sfx_cmd(stype, data, bank):
         name=data['name']
         channel=data.get('channel', 6)-1
+        snd_func_name='snd_%s_play'%stype
+        exclusive=data.get('exclusive', False)
+        if exclusive:
+            snd_func_name+='_exclusive'
         ucname=name.upper()
         print('sfx_%s::'%name, file=f)
         print('        ld      ix, #sfx_%s_data'%name, file=f)
-        print('        call    snd_%s_play'%stype, file=f)
+        print('        call    %s'%snd_func_name, file=f)
         print('        ret', file=f)
         print('sfx_%s_data:'%name, file=f)
         print('        .db     %s_START_LSB, %s_START_MSB ; start>>8 in VROM'%(ucname,ucname), file=f)