WIP

Author: dciabrin

nullsound/nss-adpcm-a.s

@@ -56,18 +56,21 @@ _state_adpcm_start:
 
 ;;; ADPCM-A1
 state_a1:
-;;; state
+;;; { ...
 state_a_start:
-;;; stream pipeline
-state_a:
-state_a_pipeline:               .blkb   1       ; actions to run at every tick (load note, vol, other regs)
-state_a_fx:                     .blkb   1       ; enabled FX for this channel
-;;; volume state tracker
-state_a_vol_cfg:                .blkb   1       ; configured volume
-state_a_vol16:                  .blkb   2       ; current decimal volume
+        
 ;;; FX state trackers
 state_a_fx_vol_slide:           .blkb   SLIDE_SIZE
 state_a_fx_trigger:             .blkb   TRIGGER_SIZE
+;;; volume state tracker
+state_a_fx:                     .blkb   1       ; enabled FX for this channel
+state_a_vol_cfg:                .blkb   1       ; configured volume
+state_a_vol16:                  .blkb   2       ; current decimal volume
+
+;;; actions to run at the end of every tick
+state_a:
+state_a_pipeline:               .blkb   1       ; action: load note, load vol, load other regs
+
 ;;; ADPCM-A-specific state
 state_a_out_vol:                .blkb   1       ; ym2610 volume after the FX pipeline
 ;;; pan
@@ -89,6 +92,8 @@ state_a5:
 ;;; ADPCM-A6
 state_a6:
 .blkb   ADPCM_A_STATE_SIZE
+
+;;; ... }
 state_a6_end:
 
 ;;; context: current adpcm channel for opcode actions

nullsound/nss-adpcm-b.s

@@ -59,26 +59,31 @@
 _state_adpcm_b_start:
 
 ;;; ADPCM-B mirrored state
-;;; state
+;;; { ...
 state_b_start:
-;;; additional note and FX state tracker
-state_b_note_fx:                .blkb   1       ; enabled note FX for this channel
-state_b_note_cfg:               .blkb   1       ; configured note
-state_b_note16:                 .blkb   2       ; current decimal note
+
+;;; note FX state tracker
 state_b_fx_note_slide:          .blkb   SLIDE_SIZE
 state_b_fx_vibrato:             .blkb   VIBRATO_SIZE
 state_b_fx_arpeggio:            .blkb   ARPEGGIO_SIZE
 state_b_fx_legato:              .blkb   LEGATO_SIZE
-;;; stream pipeline
-state_b:
-state_b_pipeline:               .blkb   1       ; actions to run at every tick (load note, vol, other regs)
-state_b_fx:                     .blkb   1       ; enabled FX for this channel
-;;; volume state tracker
-state_b_vol_cfg:                .blkb   1       ; configured volume
-state_b_vol16:                  .blkb   2       ; current decimal volume
+;;; note state tracker
+state_b_note_fx:                .blkb   1       ; enabled note FX for this channel
+state_b_note_cfg:               .blkb   1       ; configured note
+state_b_note16:                 .blkb   2       ; current decimal note
+
 ;;; FX state trackers
 state_b_fx_vol_slide:           .blkb   SLIDE_SIZE
 state_b_trigger:                .blkb   TRIGGER_SIZE
+;;; volume state tracker
+state_b_fx:                     .blkb   1       ; enabled FX for this channel
+state_b_vol_cfg:                .blkb   1       ; configured volume
+state_b_vol16:                  .blkb   2       ; current decimal volume
+
+;;; actions to run at the end of every tick
+state_b:
+state_b_pipeline:               .blkb   1       ; action: load note, load vol, load other regs
+
 ;;; ADPCM-B-specific state
 ;;; Note
 state_b_note:
@@ -94,6 +99,8 @@ state_b_out_vol:                .blkb   1       ; ym2610 volume after the FX pip
 ;;; pan
 state_b_pan:                    .blkb   1       ; configured pan (b7: left, b6: right)
 ;;;
+
+;;; ... }
 state_b_end:
 
 
@@ -388,6 +395,7 @@ adpcm_b_instrument::
 
         ;; a: start of ADPCM-B property registers
         ld      a, #REG_ADPCM_B_ADDR_START_LSB
+        ;; TODO remove useless +0?
         add     b
 
 _adpcm_b_loop:

nullsound/nss-fm.s

@@ -92,27 +92,32 @@ state_fm_ym2610_channel::
 
 ;;; FM1
 state_fm1:
-;;; state
+;;; { ...
 state_fm_start:
-;;; additional note and FX state tracker
-state_fm_note_fx:               .blkb   1      ; enabled note FX for this channel
-state_fm_note_cfg:              .blkb   1      ; configured note
-state_fm_note16:                .blkb   2      ; current decimal note
+        
+;;; note FX state tracker
 state_fm_fx_note_slide:         .blkb   SLIDE_SIZE
 state_fm_fx_vibrato:            .blkb   VIBRATO_SIZE
 state_fm_fx_arpeggio:           .blkb   ARPEGGIO_SIZE
 state_fm_fx_legato:             .blkb   LEGATO_SIZE
-;;; stream pipeline
-state_fm:
-state_fm_pipeline:              .blkb   1      ; actions to run at every tick (load note, vol, other regs)
-state_fm_fx:                    .blkb   1      ; enabled FX for this channel
+;;; note state tracker
+state_fm_note_fx:               .blkb   1      ; enabled note FX
+state_fm_note_cfg:              .blkb   1      ; configured note
+state_fm_note16:                .blkb   2      ; current decimal note
+
+;;; common FX state tracker
+state_fm_fx_vol_slide:          .blkb   SLIDE_SIZE
+state_fm_fx_trigger:            .blkb   TRIGGER_SIZE
 ;;; volume state tracker
+state_fm_fx:                    .blkb   1      ; enabled FX
 state_fm_vol_cfg:               .blkb   1      ; configured volume
 state_fm_vol16:                 .blkb   2      ; current decimal volume
-;;; FX state trackers
-state_fm_fx_vol_slide:          .blkb   SLIDE_SIZE
-state_fm_fx_trigger:            .blkb   TRIGGER_SIZE
-;;; FM-specific state
+        
+;;; actions to run at the end of every tick
+state_fm:
+state_fm_pipeline:              .blkb   1      ; action: load note, load vol, load other regs
+
+;;; FM-specific YM2610 state tracker
 ;;; Note
 state_fm_note:
 state_fm_instrument:            .blkb    1      ; instrument
@@ -130,8 +135,10 @@ state_fm_out_op1:               .blkb    1      ; ym2610 volume for OP1 after th
 state_fm_out_op2:               .blkb    1      ; ym2610 volume for OP2 after the FX pipeline
 state_fm_out_op3:               .blkb    1      ; ym2610 volume for OP3 after the FX pipeline
 state_fm_out_op4:               .blkb    1      ; ym2610 volume for OP4 after the FX pipeline
-;;;
+
+;;; ... }
 state_fm_end:
+
 ;;; FM2
 state_fm2:
 .blkb   FM_STATE_SIZE

nullsound/nss-ssg.s

@@ -75,26 +75,32 @@ state_mirrored_enabled:
 
 ;;; SSG A
 state_mirrored_ssg_a:
+;;; { ...
 ;;; state
+
+;;; note FX state tracker
 state_mirrored_ssg_start:
-;;; additional note and FX state tracker
-state_ssg_note_fx:              .blkb   1       ; enabled note FX for this channel
-state_ssg_note_cfg:             .blkb   1       ; configured note
-state_ssg_note16:               .blkb   2       ; current decimal note
 state_ssg_fx_note_slide:        .blkb   SLIDE_SIZE
 state_ssg_fx_vibrato:           .blkb   VIBRATO_SIZE
 state_ssg_fx_arpeggio:          .blkb   ARPEGGIO_SIZE
 state_ssg_fx_legato:            .blkb   LEGATO_SIZE
-;;; stream pipeline
-state_mirrored_ssg:
-state_ssg_pipeline:             .blkb   1       ; actions to run at every tick (eval macro, load note, vol, other regs)
-state_ssg_fx:                   .blkb   1       ; enabled FX for this channel
+;;; note state tracker
+state_ssg_note_fx:              .blkb   1       ; enabled note FX for this channel
+state_ssg_note_cfg:             .blkb   1       ; configured note
+state_ssg_note16:               .blkb   2       ; current decimal note
+
+;;; common FX state tracker
+state_ssg_fx_vol_slide:         .blkb   SLIDE_SIZE
+state_ssg_trigger:              .blkb   TRIGGER_SIZE
 ;;; volume state tracker
+state_ssg_fx:                   .blkb   1       ; enabled FX for this channel
 state_ssg_vol_cfg:              .blkb   1       ; configured volume
 state_ssg_vol16:                .blkb   2       ; current decimal volume
-;;; FX state trackers
-state_ssg_fx_vol_slide:         .blkb   SLIDE_SIZE
-state_ssg_trigger:              .blkb   TRIGGER_SIZE
+
+;;; actions to run at the end of every tick
+state_mirrored_ssg:
+state_ssg_pipeline:             .blkb   1       ; actions: eval macro, load note, load vol, load other regs
+
 ;;; SSG-specific state
 ;;; Note
 state_ssg_note_pos16:           .blkb   2       ; fixed-point note after the FX pipeline
@@ -111,10 +117,14 @@ state_ssg_macro_data:           .blkb   2       ; address of the start of the ma
 state_ssg_macro_pos:            .blkb   2       ; address of the current position in the macro program
 state_ssg_macro_load:           .blkb   2       ; function to load the SSG registers modified by the macro program
 state_ssg_out_vol:              .blkb   1       ; ym2610 volume for SSG channel after the FX pipeline
+
+;;; ... }
 state_mirrored_ssg_end:
+
 ;;; SSG B
 state_mirrored_ssg_b:
         .blkb   SSG_STATE_SIZE
+
 ;;; SSG C
 state_mirrored_ssg_c:
         .blkb   SSG_STATE_SIZE

nullsound/stream.s

@@ -266,9 +266,9 @@ _post_process_nss_opcodes:
         ;; process the current stream pipeline
         ;; the next processing will take place once a new tick is reached
         call    run_fm_pipeline
-        call    run_ssg_pipeline
-        call    run_adpcm_a_pipeline
-        call    run_adpcm_b_pipeline
+        ;; call    run_ssg_pipeline
+        ;; call    run_adpcm_a_pipeline
+        ;; call    run_adpcm_b_pipeline
         ld      a, (state_timer_tick_reached)
         res     TIMER_CONSUMER_STREAM_BIT, a
         ld      (state_timer_tick_reached), a
@@ -562,11 +562,12 @@ nss_opcodes:
         .nss_op_unused
         .nss_op ssg_pitch
         ;; 0x40
+        .nss_op_unused 
         .nss_op_unused
+        ;; .nss_op ext_note_op2
         .nss_op_unused
         .nss_op_unused
-        .nss_op_unused
-        .nss_op_unused
+        .nss_op set_2ch
         .nss_op fm_cut
         .nss_op ssg_cut
         .nss_op adpcm_a_cut

nullsound/struct-fx.inc

@@ -1,6 +1,6 @@
 ;;;
 ;;; nullsound - modular sound driver
-;;; Copyright (c) 2024 Damien Ciabrini
+;;; Copyright (c) 2024-2025 Damien Ciabrini
 ;;; This file is part of ngdevkit
 ;;;
 ;;; ngdevkit is free software: you can redistribute it and/or modify
@@ -37,33 +37,58 @@
         .local  fx_trigger
 
 
-;;; The pipeline structure holds properties and state trackers common to all channels
-;;; fields before field `pipeline` are optional based on the type of channel
-
-;;; optional note and FX state tracker
-note_fx:                .blkb 1         ; enabled note FX
+;;; The channel state tracker holds properties of volume and configured FX, as
+;;; well as their current state at every moment of the playback.
+;;; 
+;;; The channel state tracker structure is split into three separate parts
+;;;   - all NSS state that are common to all type of channels (e.g. volume, trigger FX)
+;;;     some channels have a note state (FM/SSG/ADPCM-B), this comes before every other
+;;;     field in the state tracker
+;;;   - the pipeline state, i.e. what are the actions to perform at the next tick,
+;;;     e.g. load a note/volume/custom-register into the YM2610
+;;;   - every other field, usually YM2610-specific fields for a given type of
+;;;     channel (e.g. OPx for FM channels, Delta-N factor for ADPCM-B...)
+;;;
+;;; At runtime, the channel state tracker is always referenced from the pipeline field,
+;;; which means other field are accessed via either a negative of postive offset
+;;; 
+
+;;; 
+;;; Common layout of a channel state tracker
+;;; 
+        
+;;; note state tracker
 cfg_note:               .blkb 1         ; configured note
 note16:                 .blkb 2         ; current decimal note
+;;; optional note FX state tracker
+note_fx:                .blkb 1         ; enabled note FX
 fx_note_slide:          .blkb SLIDE_SIZE
 fx_vibrato:             .blkb VIBRATO_SIZE
 fx_arpeggio:            .blkb ARPEGGIO_SIZE
 fx_legato:              .blkb LEGATO_SIZE
-;;; strean pipeline
-pipeline:               .blkb 1         ; actions to run at every tick (load note, vol, other regs)
-fx_fx:                  .blkb 1         ; enabled FX. This must be the second field of a channel's state
+
 ;;; volume state tracker
 cfg_vol:                .blkb 1         ; configured volume
 vol16:                  .blkb 2         ; current decimal volume
-;;; misc fx state tracker
+;;; common FX state tracker
+fx_fx:                  .blkb 1         ; enabled FX
 fx_vol_slide:           .blkb SLIDE_SIZE
 fx_trigger:             .blkb TRIGGER_SIZE
 
+;;; strean pipeline
+;;; actions to run at the end of every tick
+pipeline:               .blkb 1         ; action: load note, load vol, load other regs
+
 
-;;; common FX for note and volume are prefix with those common fields
+;;; 
+;;; common FX getters for all channels 
+;;; 
+        
+;;; common state getter shared by volume and (optional) note fields
 _data_ctx:
-_data_fx:                .blkb 1         ; enabled FX for this data
 _data_cfg:               .blkb 1         ; configured data
 _data16:                 .blkb 2         ; current decimal data
+_data_fx:                .blkb 1         ; enabled FX for this data
 
 ;;; FX: slide
 _vol_slide:
@@ -73,7 +98,7 @@ _vol_slide_end:         .blkw 1         ; volume slide end
 _vol_slide_max:         .blkb 1         ; volume slide max for channel
 _vol_slide_size:
 
-;;; FX: vibrato
+;;; FX: vibrato/tremolo
 _vibrato:
 _vibrato_speed:         .blkb 1         ; vibrato_speed
 _vibrato_depth:         .blkb 1         ; vibrato_depth
@@ -108,29 +133,34 @@ _trigger_cur:           .blkb 1         ; per-action current accumulator
 _trigger_size:
 
 
-        ;; FX getter for a channel's state
-        ;; The offset assumes that that the FX structure are located
-        ;; at the same location in reference to the pipeline field,
-        ;; and they are the same for all channels
+        ;; The offset of every field is the same for all channels, and is
+        ;; based on the common layout defined above, starting from the
+        ;; pipeline field (referenced by register ix)
         .lclequ PIPELINE,       (pipeline - pipeline)
-        .lclequ FX,             (fx_fx - pipeline)
-        ;; note and volume can both have a slide a vibrato/tremolo FX, so their
-        ;; attribute share the same alignement in memory.
-        .lclequ VOL_CTX,            FX
+
+        ;; volume and note properties are sometimes processed by a common code
+        ;; so they need to share the same alignment in memory
         .lclequ VOL,                (cfg_vol - pipeline)
         .lclequ VOL16,              (vol16   - pipeline)
-        .lclequ NOTE_CTX,           NOTE_FX
-        .lclequ NOTE_FX,            (note_fx  - pipeline)
+        .lclequ FX,                 (fx_fx - pipeline)
         .lclequ NOTE,               (cfg_note - pipeline)
         .lclequ NOTE16,             (note16   - pipeline)
-        ;; getter for accessing the pipeline from the start of a FM, SSG, ADPCM-B
-        .lclequ PIPELINE_FROM_NOTE, (pipeline - note_fx)
+        .lclequ NOTE_FX,            (note_fx  - pipeline)
+        ;; when the common code needs to access the fields above, it uses
+        ;; another set of getters, whose offset is relative to a volume
+        ;; or note context (referenced by register iy)
+        .lclequ VOL_CTX,            VOL
+        .lclequ NOTE_CTX,           NOTE
+        .lclequ DATA_CFG,           (_data_cfg - _data_ctx)
+        .lclequ DATA16,             (_data16   - _data_ctx)
+        .lclequ DATA_FX,            (_data_fx  - _data_ctx)
 
         ;; FX that are common to the volume and note properties have getters
-        ;; relative to the propertie. they are accessed with register iy
-        .lclequ DATA_FX,             (_data_fx  - _data_ctx)
+        ;; whose offset is relative to the volume context or note context
+        ;; (referenced by register iy)
         .lclequ DATA_CFG,            (_data_cfg - _data_ctx)
         .lclequ DATA16,              (_data16   - _data_ctx)
+        .lclequ DATA_FX,             (_data_fx  - _data_ctx)
         ;; FX slide
         .lclequ SLIDE_CFG,  (_vol_slide_cfg    - _data_ctx)
         .lclequ SLIDE_INC16, (_vol_slide_inc16 - _data_ctx)
@@ -167,6 +197,10 @@ _trigger_size:
         .lclequ TRIGGER_CUR,    (_trigger_cur    - _trigger + fx_trigger - pipeline)
         .lclequ TRIGGER_SIZE,   (_trigger_size   - _trigger)
 
+         ;; common getter for accessing the pipeline from the start of
+        ;; the FM, SSG or ADPCM-B channel
+        .lclequ PIPELINE_FROM_NOTE, (pipeline - note_fx)
+
         ;; Enabled FX
         .lclequ BIT_FX_TRIGGER,         0
         .lclequ BIT_FX_SLIDE,           1
@@ -179,6 +213,7 @@ _trigger_size:
         .lclequ TRIGGER_LOAD_NOTE_FUNC,         0
         .lclequ TRIGGER_LOAD_VOL_FUNC,          2
         .lclequ TRIGGER_STOP_NOTE_FUNC,         4
+        
         ;; Trigger FX configuration
         .lclequ BIT_TRIGGER_ACTION_DELAY,       0
         .lclequ BIT_TRIGGER_ACTION_CUT,         1