nullsound massive refactoring of FX processing

- slides and vibrato FX have ben updated to work on both note and volume
  with a single codebase.
- semantics of all FX hae been updated to match Furnace while changing
  note/volume/FX while an FX is ongoing
- general cleanup to avoid duplicating NSS bytecodes for each channel

Author: dciabrin

nullsound/Makefile.in

@@ -19,7 +19,7 @@ all: nullsound.lib linkcheck.map
 -include ../Makefile.config
 
 INCLUDE_FILES=helpers ports ym2610
-OBJS=entrypoint memory bios-commands adpcm ym2610 stream timer utils nss-fm nss-ssg nss-adpcm-a nss-adpcm-b fx-vibrato fx-slide fx-vol-slide fx-trigger fx-arpeggio fx-legato volume
+OBJS=entrypoint memory bios-commands adpcm ym2610 stream timer utils nss-fm nss-ssg nss-adpcm-a nss-adpcm-b fx-vibrato fx-slide fx-trigger fx-arpeggio fx-legato volume
 LIB=nullsound.lib
 
 VERSION=@version@

nullsound/align.inc

@@ -27,6 +27,6 @@
         ;; to tune the constants below to achieve our desired alignment.
 
         .lclequ ALIGN_OFFSET_FM,        0xbc
-        .lclequ ALIGN_OFFSET_SSG,       0x50
+        .lclequ ALIGN_OFFSET_SSG,       0x4b
         .lclequ ALIGN_OFFSET_ADPCM_A,   0x52
-        .lclequ ALIGN_OFFSET_ADPCM_B,   0x1a
+        .lclequ ALIGN_OFFSET_ADPCM_B,   0x10

nullsound/doc/nss.md

@@ -22,11 +22,12 @@ This document details the current level of support for Furnace features in NSS.
   - Only the `sequence` macro type can used to configure SSG properties. Macro types `ADSR` and `LFO` are not supported and there is no plan to support them.
 
   - Within a sequence macro, each step is 1 tick long. That is, each time the YM2610 triggers an IRQ during music playback, a step of the macro is being evaluated. Unlike in Furnace, there is no native support in NSS for step length or step delay.
+
   - Macro looping is currently different from what Furnace allows. Currently, NSS groups property updates by steps. When the loop is reached, it starts again from the configured step, which means all properties are re-evaluated from this step. This means you can't have loops for two different properties. This is going to improve in the future to match Furnace's semantics.
 
   - SSG Auto-envelope feature is currently broken, SSG instruments using that feature can be processed by `nsstool`, but the resulting playback is invalid. Do not use it.
 
-* If you use SSG in your Furnace module, and SSG instruments use the SSG noise channel, be aware that this will prevent you from fading out your module while it's playing. This is because the YM2610 has no support in hardware to change the volume of the noise channel.
+* If you use SSG in your Furnace module, and SSG instruments uses the volume envelope bit for the channel, be aware that this will prevent you from fading out your module while it's playing. This is because the YM2610 has no support in hardware to change the volume of the envelope generator.
 
 
 ## Currently supported Furnace FX
@@ -39,15 +40,15 @@ This document details the current level of support for Furnace features in NSS.
 
 ## Volume
 
-| FX   | Description                   | Status | Note                           |
-|------|-------------------------------|--------|--------------------------------|
-| `0A` | Volume slide                  | ⚠️      | Only volume down. No ADPCM yet |
-| `FA` | Fast volume slide             | 💜     |                                |
-| `F3` | Fine volume slide up          | 💜     |                                |
-| `F4` | Fine volume slide down        | 💜     |                                |
-| `F8` | Single tick volume slide up   | 💜     |                                |
-| `F9` | Single tick volume slide down | 💜     |                                |
-| `07` | Tremolo                       | 💜     |                                |
+| FX   | Description                   | Status | Note |
+|------|-------------------------------|--------|------|
+| `0A` | Volume slide                  | 💚️     |      |
+| `FA` | Fast volume slide             | 💜     |      |
+| `F3` | Fine volume slide up          | 💜     |      |
+| `F4` | Fine volume slide down        | 💜     |      |
+| `F8` | Single tick volume slide up   | 💜     |      |
+| `F9` | Single tick volume slide down | 💜     |      |
+| `07` | Tremolo                       | 💜     |      |
 
 
 ## Pitch
@@ -61,29 +62,29 @@ This document details the current level of support for Furnace features in NSS.
 | F2 | Single tick pitch slide down | 💜     |      |
 | 03 | Portamento                   | 💚     |      |
 | E1 | Note slide up                | 💚     |      |
-| E2 | Note slide down              | 💚     |      |
 | EA | Toggle legato                | 💜     |      |
+| E2 | Note slide down              | 💚     |      |
 | E6 | Quick legato (compatibility) | 🚫     |      |
-| E8 | Quick legato up              | 🚫     |      |
-| E9 | Quick legato down            | 🚫     |      |
-| 00 | Arpeggio                     | 💜     |      |
-| E0 | Set arpeggio speed           | 💜     |      |
+| E8 | Quick legato up              | 💚     |      |
+| E9 | Quick legato down            | 💚     |      |
+| 00 | Arpeggio                     | 💚     |      |
+| E0 | Set arpeggio speed           | 💚     |      |
 | 04 | Vibrato                      | 💚     |      |
 | E3 | Set vibrato direction        | 🚫     |      |
 | E4 | Set vibrato rang             | 🚫     |      |
 
 
 ## Panning
 
-| FX | Description                     | Status | Note |
-|----|---------------------------------|--------|------|
-| 08 | Set panning                     | 💚     |      |
-| 88 | Set rear panning                | 🚫     |      |
-| 81 | Set volume of left channe       | 🚫     |      |
-| 82 | Set volume of right channe      | 🚫     |      |
-| 89 | Set volume of rear left channe  | 🚫     |      |
-| 8A | Set volume of rear right channe | 🚫     |      |
-| 80 | Set panning (linear)            | 💚     |      |
+| FX | Description                      | Status | Note |
+|----|----------------------------------|--------|------|
+| 08 | Set panning                      | 💚     |      |
+| 88 | Set rear panning                 | 🚫     |      |
+| 81 | Set volume of left channel       | 🚫     |      |
+| 82 | Set volume of right channel      | 🚫     |      |
+| 89 | Set volume of rear left channel  | 🚫     |      |
+| 8A | Set volume of rear right channel | 🚫     |      |
+| 80 | Set panning (linear)             | 💚     |      |
 
 
 ## Time

nullsound/fx-arpeggio.s

@@ -16,7 +16,7 @@
 ;;; You should have received a copy of the GNU Lesser General Public License
 ;;; along with ngdevkit.  If not, see <http://www.gnu.org/licenses/>.
 
-;;; Trigger effect (delay, cut...), common functions for FM and SSG
+;;; Arpeggio effect for FM, SSG and ADPCM-B
 ;;;
 
         .module nullsound
@@ -29,26 +29,58 @@
         .area  CODE
 
 
+;;; Update the arpeggio state for the current channel
+;;; ------
+;;; ix: mirrored state of the current channel
+eval_arpeggio_step::
+        ;; assert: speed is always >=1, so count is never 0 here
+        dec     ARPEGGIO_COUNT(ix)
+        ld      a, ARPEGGIO_COUNT(ix)
+        cp      #0
+        jr      z, _arpeggio_update_pos
+        ret
+_arpeggio_update_pos:
+        ;; rearm countdown
+        ld      a, ARPEGGIO_SPEED(ix)
+        ld      ARPEGGIO_COUNT(ix), a
+
+        ;; update position in the arpeggio
+        ld      a, ARPEGGIO_POS(ix)
+        dec     a
+        jp      p, _arpeggio_post_pos
+        add     #3
+_arpeggio_post_pos:
+        ld      ARPEGGIO_POS(ix), a
+
+        ;; set semitone offset according to position
+        cp      #2
+        jr      nz, _arpeggio_not2
+        ;; pos == 2: 2nd note in chord
+        ld      a, ARPEGGIO_2ND(ix)
+        ld      ARPEGGIO_POS8(ix), a
+        jr      _arpeggio_eval_end
+_arpeggio_not2:
+        cp      #1
+        jr      nz, _arpeggio_not1
+        ;; pos == 2: 3rd note in chord
+        ld      a, ARPEGGIO_3RD(ix)
+        ld      ARPEGGIO_POS8(ix), a
+        jr      _arpeggio_eval_end
+_arpeggio_not1:
+        ;; 1st note in chord (0 displacement)
+        ld      ARPEGGIO_POS8(ix), #0
+
+_arpeggio_eval_end:
+        ret
+
+
 ;;; ARPEGGIO
 ;;; Enable arpeggio chord for note playback
 ;;; ------
 ;;;   ix  : state for channel
 ;;; [ hl ]: semitone:4 - semitone:4
 ;;; hl modified
 arpeggio::
-        ;; check whether this disables FX
-        ld      a, (hl)
-        cp      #0
-        jr      nz, _arpeggio_init
-        inc     hl
-        res     BIT_FX_ARPEGGIO, FX(ix)
-        ;; To fully clear the state after the FX is disabled, we must remember
-        ;; to recompute the note and tune values without shift, so force it here
-        ld      ARPEGGIO_POS8(ix), a
-        set     BIT_LOAD_NOTE, PIPELINE(ix)
-        ld      a, #1
-        ret
-_arpeggio_init:
         ;; 2nd note in chord
         ld      a, (hl)
         rra
@@ -66,15 +98,15 @@ _arpeggio_init:
         inc     hl
 
         ;; init arpeggio state if it is not running already
-        bit     BIT_FX_ARPEGGIO, FX(ix)
+        bit     BIT_FX_ARPEGGIO, NOTE_FX(ix)
         jr      nz, _arpeggio_end
         ld      a, ARPEGGIO_SPEED(ix)
         ld      ARPEGGIO_COUNT(ix), a
         xor     a
         ld      ARPEGGIO_POS(ix), a
         ld      ARPEGGIO_POS8(ix), a
 
-        set     BIT_FX_ARPEGGIO, FX(ix)
+        set     BIT_FX_ARPEGGIO, NOTE_FX(ix)
 
 _arpeggio_end:
         ld      a, #1
@@ -90,55 +122,21 @@ _arpeggio_end:
 arpeggio_speed::
         ld      a, (hl)
         inc     hl
-
         ld      ARPEGGIO_SPEED(ix), a
-
         ld      a, #1
-
         ret
 
 
-;;; Update the arpeggio state for the current channel
+;;; ARPEGGIO_OFF
+;;; Disable arpeggio chord for note playback
 ;;; ------
-;;; ix: mirrored state of the current channel
-;;; [TODO modified]
-eval_arpeggio_step::
-        ;; assert: speed is always >=1, so count is never 0 here
-        dec     ARPEGGIO_COUNT(ix)
-        ld      a, ARPEGGIO_COUNT(ix)
-        cp      #0
-        jr      z, _arpeggio_update_pos
-        ret
-_arpeggio_update_pos:
-        ;; rearm countdown
-        ld      a, ARPEGGIO_SPEED(ix)
-        ld      ARPEGGIO_COUNT(ix), a
-
-        ;; update position in the arpeggio
-        ld      a, ARPEGGIO_POS(ix)
-        dec     a
-        jp      p, _arpeggio_post_pos
-        add     #3
-_arpeggio_post_pos:
-        ld      ARPEGGIO_POS(ix), a
-
-        ;; set semitone offset according to position
-        cp      #2
-        jr      nz, _arpeggio_not2
-        ;; pos == 2: 2nd note in chord
-        ld      a, ARPEGGIO_2ND(ix)
-        ld      ARPEGGIO_POS8(ix), a
-        jr      _arpeggio_eval_end
-_arpeggio_not2:
-        cp      #1
-        jr      nz, _arpeggio_not1
-        ;; pos == 2: 3rd note in chord
-        ld      a, ARPEGGIO_3RD(ix)
-        ld      ARPEGGIO_POS8(ix), a
-        jr      _arpeggio_eval_end
-_arpeggio_not1:
-        ;; 1st note in chord (0 displacement)
+;;;   ix  : state for channel
+arpeggio_off::
+        ;; disable FX
+        res     BIT_FX_ARPEGGIO, NOTE_FX(ix)
         ld      ARPEGGIO_POS8(ix), #0
-
-_arpeggio_eval_end:
+        ;; since we disable the FX outside of the pipeline process
+        ;; make sure to load this new note at next pipeline run
+        set     BIT_LOAD_NOTE, PIPELINE(ix)
+        ld      a, #1
         ret