Clean up comments and some defines.

src/opcodes/arithmetic.asm

@@ -1,8 +1,10 @@
 SECT_TEXT(suarithm)
 
 ;-------------------------------------------------------------------------------
-;   op_pop function: a -> (empty)
+;   POP opcode: remove (discard) the topmost signal from the stack
-;            stereo: a b -> (empty)
+;-------------------------------------------------------------------------------
+;   Mono:   a -> (empty)
+;   Stereo: a b -> (empty)
 ;-------------------------------------------------------------------------------
 %if POP_ID > -1
 
@@ -18,8 +20,10 @@ su_op_pop_mono:
 %endif
 
 ;-------------------------------------------------------------------------------
-;   op_add function: a b -> a+b b
+;   ADD opcode: add the two top most signals on the stack
-;            stereo: a b c d -> a+c b+d c d
+;-------------------------------------------------------------------------------
+;   Mono:   a b -> a+b b
+;   Stereo: a b c d -> a+c b+d c d
 ;-------------------------------------------------------------------------------
 %if ADD_ID > -1
 
@@ -38,9 +42,12 @@ su_op_add_mono:
 
 %endif
 
+
 ;-------------------------------------------------------------------------------
-;   op_addp function: a b -> a+b
+;   ADDP opcode: add the two top most signals on the stack and pop
-;             stereo: a b c d -> a+c b+d
+;-------------------------------------------------------------------------------
+;   Mono:   a b -> a+b
+;   Stereo: a b c d -> a+c b+d
 ;-------------------------------------------------------------------------------
 %if ADDP_ID > -1
 
@@ -58,9 +65,10 @@ su_op_addp_mono:
 %endif
 
 ;-------------------------------------------------------------------------------
-;   op_loadnote function: (empty) -> n
+;   LOADNOTE opcode: load the current note, scaled to [0,1]
-;                 stereo: (empty) -> n n
+;-------------------------------------------------------------------------------
-;   ecx should point to the workspace (slightly offset)
+;   Mono:   (empty) -> n, where n is the note
+;   Stereo: (empty) -> n n
 ;-------------------------------------------------------------------------------
 %if LOADNOTE_ID > -1
 
@@ -77,8 +85,10 @@ su_op_loadnote_mono:
 %endif
 
 ;-------------------------------------------------------------------------------
-;   op_mul function: a b -> a*b a
+;   MUL opcode: multiply the two top most signals on the stack
-;            stereo: a b c d -> a*c b*d c d
+;-------------------------------------------------------------------------------
+;   Mono:   a b -> a*b a
+;   Stereo: a b c d -> a*c b*d c d
 ;-------------------------------------------------------------------------------
 %if MUL_ID > -1
 
@@ -98,8 +108,10 @@ su_op_mul_mono:
 %endif
 
 ;-------------------------------------------------------------------------------
-;   op_mulp function: a b -> a*b
+;   MULP opcode: multiply the two top most signals on the stack and pop
-;             stereo: a b c d -> a*c b*d
+;-------------------------------------------------------------------------------
+;   Mono:   a b -> a*b
+;   Stereo: a b c d -> a*c b*d
 ;-------------------------------------------------------------------------------
 %if MULP_ID > -1
 
@@ -117,8 +129,10 @@ su_op_mulp_mono:
 %endif
 
 ;-------------------------------------------------------------------------------
-;   op_push function: a -> a a
+;   PUSH opcode: push the topmost signal on the stack
-;             stereo: a b -> a b a b
+;-------------------------------------------------------------------------------
+;   Mono:   a -> a a
+;   Stereo: a b -> a b a b
 ;-------------------------------------------------------------------------------
 %if PUSH_ID > -1
 
@@ -136,7 +150,9 @@ su_op_push_mono:
 %endif
 
 ;-------------------------------------------------------------------------------
-;   op_xch function: a b -> b a
+;   XCH opcode: exchange the signals on the stack
+;-------------------------------------------------------------------------------
+;   Mono:   a b -> b a
 ;   stereo: a b c d -> c d a b
 ;-------------------------------------------------------------------------------
 %if XCH_ID > -1

src/opcodes/effects.asm

@@ -1,9 +1,8 @@
 ;-------------------------------------------------------------------------------
-;   DISTORT Tick
+;   DISTORT opcode: apply distortion on the signal
 ;-------------------------------------------------------------------------------
-;   Input:      st0     :   x - input value
+;   Mono:   x   ->  x*a/(1-a+(2*a-1)*abs(x))            where x is clamped first
-;   Output:     st0     :  x*a/(1-a+(2*a-1)*abs(x))
+;   Stereo: l r ->  l*a/(1-a+(2*a-1)*abs(l)) r*a/(1-a+(2*a-1)*abs(r))
-;                          where x is clamped first
 ;-------------------------------------------------------------------------------
 %if DISTORT_ID > -1
 
@@ -42,7 +41,10 @@ su_waveshaper:
 %endif ; SU_USE_DST
 
 ;-------------------------------------------------------------------------------
-;   HOLD Tick
+;   HOLD opcode: sample and hold the signal, reducing sample rate
+;-------------------------------------------------------------------------------
+;   Mono version:   holds the signal at a rate defined by the freq parameter
+;   Stereo version: holds both channels
 ;-------------------------------------------------------------------------------
 %if HOLD_ID > -1
 
@@ -75,7 +77,10 @@ su_op_hold_holding:
 %endif ; HOLD_ID > -1
 
 ;-------------------------------------------------------------------------------
-;   CRUSH Tick
+;   CRUSH opcode: quantize the signal to finite number of levels
+;-------------------------------------------------------------------------------
+;   Mono:   x   ->  e*int(x/e)
+;   Stereo: l r ->  e*int(l/e) e*int(r/e)
 ;-------------------------------------------------------------------------------
 %if CRUSH_ID > -1
 
@@ -94,7 +99,10 @@ EXPORT MANGLE_FUNC(su_op_crush,0)
 %endif ; CRUSH_ID > -1
 
 ;-------------------------------------------------------------------------------
-;   GAIN Tick
+;   GAIN opcode: apply gain on the signal
+;-------------------------------------------------------------------------------
+;   Mono:   x   ->  x*g
+;   Stereo: l r ->  l*g r*g
 ;-------------------------------------------------------------------------------
 %if GAIN_ID > -1
 
@@ -115,7 +123,10 @@ SECT_TEXT(sugain)
 %endif ; GAIN_ID > -1
 
 ;-------------------------------------------------------------------------------
-;   INVGAIN Tick
+;   INVGAIN opcode: apply inverse gain on the signal
+;-------------------------------------------------------------------------------
+;   Mono:   x   ->  x/g
+;   Stereo: l r ->  l/g r/g
 ;-------------------------------------------------------------------------------
 %if INVGAIN_ID > -1
 
@@ -136,14 +147,10 @@ SECT_TEXT(suingain)
 %endif ; INVGAIN_ID > -1
 
 ;-------------------------------------------------------------------------------
-;   su_op_filter: perform low/high/band-pass filtering on the signal
+;   FILTER opcode: perform low/high/band-pass/notch etc. filtering on the signal
 ;-------------------------------------------------------------------------------
-;   Input:      WRK     :   pointer to unit workspace
+;   Mono:   x   ->  filtered(x)
-;               VAL     :   pointer to unit values as bytes
+;   Stereo: l r ->  filtered(l) filtered(r)
-;               ecx     :   pointer to global workspace
-;               st0     :   signal
-;   Output:     st0     :   filtered signal
-;   Dirty:      eax, edx
 ;-------------------------------------------------------------------------------
 %if FILTER_ID > -1
 SECT_TEXT(sufilter)
@@ -203,10 +210,10 @@ su_op_filter_skipneghighpass:
 %endif ; SU_INCLUDE_FILTER
 
 ;-------------------------------------------------------------------------------
-;   su_clip function
+;   CLIP opcode: clips the signal into [-1,1] range
 ;-------------------------------------------------------------------------------
-;   Input:      st0     :   x
+;   Mono:   x   ->  min(max(x,-1),1)
-;   Output:     st0     :   min(max(x,-1),1)
+;   Stereo: l r ->  min(max(l,-1),1) min(max(r,-1),1)
 ;-------------------------------------------------------------------------------
 SECT_TEXT(suclip)
 
@@ -235,15 +242,12 @@ su_clip_do:
 %endif ; SU_INCLUDE_CLIP
 
 ;-------------------------------------------------------------------------------
-;   PAN Tick
+;   PAN opcode: pan the signal
 ;-------------------------------------------------------------------------------
-;   Input:      WRK     :   pointer to unit workspace
+;   Mono:   s   ->  s*(1-p) s*p
-;               VAL     :   pointer to unit values as bytes
+;   Stereo: l r ->  l*(1-p) r*p
-;               ecx     :   pointer to global workspace
+;
-;               st0     :   s, the signal
+;   where p is the panning in [0,1] range
-;   Output:     st0     :   s*(1-p), where p is the panning in [0,1] range
-;               st1     :   s*p
-;   Dirty:      eax, edx
 ;-------------------------------------------------------------------------------
 %if PAN_ID > -1
 
@@ -297,16 +301,13 @@ su_effects_stereohelper_mono:
 %endif
 
 ;-------------------------------------------------------------------------------
-;   Delay Tick
+;   DELAY opcode: adds delay effect to the signal
 ;-------------------------------------------------------------------------------
-;   Pseudocode:
+;   Mono:   perform delay on ST0, using delaycount delaylines starting
-;   q = dr*x
+;           at delayindex from the delaytable
-;   for (i = 0;i < count;i++)
+;   Stereo: perform delay on ST1, using delaycount delaylines starting
-;     s = b[(t-delaytime[i+offset])&65535]
+;           at delayindex + delaycount from the delaytable (so the right delays
-;     q += s
+;           can be different)
-;     o[i] = o[i]*da+s*(1-da)
-;     b[t] = f*o[i] +p^2*x
-;  Perform dc-filtering q and output
 ;-------------------------------------------------------------------------------
 %if DELAY_ID > -1
 
@@ -348,6 +349,15 @@ su_op_delay_mono:               ; flow into mono delay
 ;-------------------------------------------------------------------------------
 ;   su_op_delay_do: executes the actual delay
 ;-------------------------------------------------------------------------------
+;   Pseudocode:
+;   q = dr*x
+;   for (i = 0;i < count;i++)
+;     s = b[(t-delaytime[i+offset])&65535]
+;     q += s
+;     o[i] = o[i]*da+s*(1-da)
+;     b[t] = f*o[i] +p^2*x
+;  Perform dc-filtering q and output q
+;-------------------------------------------------------------------------------
 su_op_delay_do:                                 ; x y
     fld     st0
     fmul    dword [INP+su_delay_ports.pregain]  ; p*x y
@@ -433,7 +443,12 @@ SECT_DATA(suconst)
 %endif ; DELAY_ID > -1
 
 ;-------------------------------------------------------------------------------
-;   Compressor Tick
+;   COMPRES opcode: push compressor gain to stack
+;-------------------------------------------------------------------------------
+;   Mono:   push g on stack, where g is a suitable gain for the signal
+;           you can either MULP to compress the signal or SEND it to a GAIN
+;           somewhere else for compressor side-chaining.
+;   Stereo: push g g on stack, where g is calculated using l^2 + r^2
 ;-------------------------------------------------------------------------------
 %if COMPRES_ID > -1
 

src/opcodes/flowcontrol.asm

@@ -1,20 +1,12 @@
 ;-------------------------------------------------------------------------------
-;   su_op_advance function: opcode to advance from one instrument to next
+;   ADVANCE opcode: advances from one voice to next
 ;-------------------------------------------------------------------------------
-;   Stack:      voice wrkptr valptr comptr
-;               voice   :   the number of voice we are currently processing
-;               wrkptr  :   pointer to the first unit of current voice - su_unit.size
-;               valptr  :   pointer to the first unit's value of current voice
-;               comptr  :   pointer to the first command of current voice
-;               COM     :   pointer to the command after current command
-;   Output:     WRK     :   pointer to the next unit to be processed
-;               VAL     :   pointer to the values of the next to be processed
-;               COM     :   pointer to the next command to be executed
-;
 ;   Checks if this was the last voice of current instrument. If so, moves to
 ;   next opcodes and updates the stack to reflect the instrument change.
 ;   If this instrument has more voices to process, rolls back the COM and VAL
 ;   pointers to where they were when this instrument started.
+;
+;   There is no stereo version.
 ;-------------------------------------------------------------------------------
 SECT_TEXT(suopadvn)
 
@@ -47,7 +39,11 @@ su_op_advance_finish:
 %endif
 
 ;-------------------------------------------------------------------------------
-;   SPEED tick
+;   SPEED opcode: modulate the speed (bpm) of the song based on ST0
+;-------------------------------------------------------------------------------
+;   Mono: adds or subtracts the ticks, a value of 0.5 is neutral & will7
+;   result in no speed change.
+;   There is no STEREO version.
 ;-------------------------------------------------------------------------------
 %if SPEED_ID > -1
 

src/opcodes/sinks.asm

@@ -1,5 +1,8 @@
 ;-------------------------------------------------------------------------------
-;   OUT Tick
+;   OUT opcode: outputs and pops the signal
+;-------------------------------------------------------------------------------
+;   Mono: add ST0 to global left port
+;   Stereo: also add ST1 to global right port
 ;-------------------------------------------------------------------------------
 %if OUT_ID > -1
 
@@ -21,14 +24,10 @@ EXPORT MANGLE_FUNC(su_op_out,0) ; l r
 %endif ; SU_OUT_ID > -1
 
 ;-------------------------------------------------------------------------------
-;   Send Tick
+;   SEND opcode: adds the signal to a port
 ;-------------------------------------------------------------------------------
-;   Input:      WRK     :   pointer to unit workspace
+;   Mono: adds signal to a memory address, defined by a word in VAL stream
-;               VAL     :   pointer to unit values as bytes
+;   Stereo: also add right signal to the following address
-;               ecx     :   pointer to global workspace
-;               st0     :   signal
-;   Output:     (st0)   :   signal, unless popped
-;   Dirty:      eax, edx
 ;-------------------------------------------------------------------------------
 %if SEND_ID > -1
 

src/opcodes/sources.asm

@@ -1,13 +1,8 @@
 ;-------------------------------------------------------------------------------
-;   ENV Tick
+;   ENVELOPE opcode: pushes an ADSR envelope value on stack [0,1]
 ;-------------------------------------------------------------------------------
-;   Input:      WRK     :   pointer to unit workspace
+;   Mono:   push the envelope value on stack
-;               VAL     :   pointer to unit values as bytes
+;   Stereo: push the envelope valeu on stack twice
-;               ecx     :   pointer to global workspace
-;   Output:     st0     :   envelope value, [gain]*level. The slopes of
-;                           level is 2^(-24*p) per sample, where p is either
-;                           attack, decay or release in [0,1] range
-;   Dirty:      eax, edx
 ;-------------------------------------------------------------------------------
 %if ENVELOPE_ID > -1
 
@@ -70,7 +65,10 @@ kmENV_func_leave2:
 %endif ; SU_USE_ENVELOPE
 
 ;-------------------------------------------------------------------------------
-;   su_noise function: noise oscillators
+;   NOISE opcode: creates noise
+;-------------------------------------------------------------------------------
+;   Mono:   push a random value [-1,1] value on stack
+;   Stereo: push two (differeent) random values on stack
 ;-------------------------------------------------------------------------------
 %if NOISE_ID > -1
 
@@ -94,7 +92,10 @@ su_op_noise_mono:
 %endif
 
 ;-------------------------------------------------------------------------------
-;   su_op_oscillat function: oscillator, the heart of the synth
+;   OSCILLAT opcode: oscillator, the heart of the synth
+;-------------------------------------------------------------------------------
+;   Mono:   push oscillator value on stack
+;   Stereo: push l r on stack, where l has opposite detune compared to r
 ;-------------------------------------------------------------------------------
 %if OSCILLAT_ID > -1
 
@@ -354,17 +355,15 @@ SECT_DATA(suconst)
 ;-------------------------------------------------------------------------------
 ;   LOADVAL opcode
 ;-------------------------------------------------------------------------------
-;   Input:      edx     :   pointer to unit ports
+;   Mono: push 2*v-1 on stack, where v is the input to port "value"
-;
+;   Stereo: push 2*v-1 twice on stack
-;   Mono version: push 2*v-1 on stack, where v is the input to port "value"
-;   Stereo version: push 2*v-1 twice on stack
 ;-------------------------------------------------------------------------------
 %if LOADVAL_ID > -1
 
 SECT_TEXT(suloadvl)
 
 EXPORT MANGLE_FUNC(su_op_loadval,0)
-%ifdef INCLUDE_STEREO_LOAD_VAL
+%ifdef INCLUDE_STEREO_LOADVAL
     jnc     su_op_loadval_mono
     call    su_op_loadval_mono
 su_op_loadval_mono:
@@ -380,8 +379,8 @@ su_op_loadval_mono:
 ;-------------------------------------------------------------------------------
 ;   RECEIVE opcode
 ;-------------------------------------------------------------------------------
-;   Mono version:   push l on stack, where l is the left channel received
+;   Mono:   push l on stack, where l is the left channel received
-;   Stereo version: push l r on stack
+;   Stereo: push l r on stack
 ;-------------------------------------------------------------------------------
 %if RECEIVE_ID > -1
 

src/opcodes/sources.inc

@@ -209,7 +209,7 @@ endstruc
     USE_LOAD_VAL
     %xdefine CMDS CMDS LOADVAL_ID+%1,
     %if %1 == STEREO
-        %define INCLUDE_STEREO_LOAD_VAL
+        %define INCLUDE_STEREO_LOADVAL
     %endif
 %endmacro
 

src/sointu.inc

@@ -1,14 +1,8 @@
 %ifndef SOINTU_INC
 %define SOINTU_INC
 
-; Following defines have to be defined before this include:
+; You will have to define a BPM for your song, e.g.
-; MAX_TRACKS            e.g.         %define MAX_TRACKS 10
+; %define BPM 100
-; BPM                   e.g.         %define BPM 100
-; MAX_PATTERNS          e.g.         %define MAX_PATTERNS 1
-; MAX_VOICES            e.g.         %define MAX_VOICES 4 <- e.g. 4 instruments or 1 polyphonic instrument with 4 voices
-;
-; Optionally:
-; PATTERN_SIZE          e.g.         %define PATTERN_SIZE 16 <- this is the default
 
 %macro EXPORT 1
     global %1
@@ -73,64 +67,10 @@
     %endif
 %endif
 
-%ifdef SU_USE_ALL
-    ; SU_USE_ALL is convenience way to enable almost all features of the synth, for vsti plugins and such which
-    ; do not have any size constraints. However, SU_USE_ALL should only enable features that absolutely do not
-    ; change the functioning of the synth in any way, just add features. Clipping, 16 bit output etc. should still
-    ; be enabled only whent they are actually needed
-
-    ; Things that are NOT defined by SU_USE_ALL
-    ;%define SU_USE_16BIT_OUTPUT         ; // removing this will output to 32bit floating point buffer
-    ;%define SU_USE_GROOVE_PATTERN       ; // removing this skips groove pattern code
-    ;%define SU_USE_ENVELOPE_RECORDINGS  ; // removing this skips envelope recording code
-    ;%define SU_USE_NOTE_RECORDINGS      ; // removing this skips note recording code
-    ;%define SU_USE_UNDENORMALIZE        ; // removing this skips denormalization code in the units
-    ;%define SU_CLIP_OUTPUT              ; // removing this skips clipping code for the final output
-
-    %define SU_USE_DST                    ; // removing this will skip DST unit
-    %define SU_USE_DLL                    ; // removing this will   skip DLL unit
-    %define SU_USE_PAN                    ; // removing this will   skip PAN unit
-    %define SU_USE_GLOBAL_DLL             ; // removing this will   skip global dll processing
-    %define SU_USE_FSTG                   ; // removing this will   skip global store unit
-    %define SU_USE_FLD                    ; // removing this will   skip float load unit
-    %define SU_USE_GLITCH                 ; // removing this will   skip GLITCH unit
-    %define SU_USE_ENV_CHECK              ; // removing this skips checks   if processing is needed
-    %define SU_USE_VCO_CHECK              ; // removing this skips checks   if processing is needed
-    %define SU_USE_VCO_PHASE_OFFSET       ; // removing this will   skip initial phase offset code
-    %define SU_USE_VCO_SHAPE                ; // removing this skips waveshaping code
-    %define SU_USE_VCO_GATE             ; // removing this skips gate code
-    %define SU_USE_VCO_MOD_FM               ; // removing this skips frequency modulation code
-    %define SU_USE_VCO_MOD_DM               ; // removing this skips detune modulation code
-    %define SU_USE_VCO_STEREO               ; // removing this skips stereo code
-    %define SU_USE_VCF_CHECK                ; // removing this skips checks if processing is needed
-    %define SU_USE_VCF_HIGH             ; // removing this skips code for high output
-    %define SU_USE_VCF_BAND             ; // removing this skips code for band output
-    %define SU_USE_VCF_PEAK             ; // removing this skips code for peak output
-    %define SU_USE_VCF_STEREO               ; // removing this skips code for stereo filter output
-    %define SU_USE_DST_CHECK                ; // removing this skips checks if processing is needed
-    %define SU_USE_DST_SH                   ; // removing this skips sample and hold code
-    %define SU_USE_DST_STEREO             ; // removing this skips stereo processing
-    %define SU_USE_DLL_NOTE_SYNC          ; // removing this will   skip delay length adjusting code (karplus strong)
-    %define SU_USE_DLL_CHORUS             ; // removing this will   skip delay chorus/flanger code
-    %define SU_USE_DLL_CHORUS_CLAMP       ; // removing this will skip chorus lfo phase clamping
-    %define SU_USE_DLL_DAMP             ; // removing this will skip dll damping code
-    %define SU_USE_DLL_DC_FILTER            ; // removing this will skip dll dc offset removal code
-    %define SU_USE_FSTG_CHECK               ; // removing this skips checks if processing is needed
-    %define SU_USE_WAVESHAPER_CLIP      ; // removing this will skip clipping code
-%endif
-
-%ifdef SU_USE_VCO_SHAPE
-    %define INCLUDE_WAVESHAPER
-%endif
-%ifdef SU_USE_DST
-    %define INCLUDE_WAVESHAPER
-%endif
 %ifdef SU_USE_16BIT_OUTPUT
     %define SU_INCLUDE_CLIP
 %endif
 
-;%include "opcodes/flowcontrol.inc"
-
 %assign CUR_ID          2
 %define CMDS              ; CMDS is empty at first, no commands defined
 %define OPCODES         MANGLE_FUNC(su_op_advance,0),
@@ -145,9 +85,9 @@
 %include "opcodes/sources.inc"
 %include "opcodes/sinks.inc"
 
-; //----------------------------------------------------------------------------------------
+;-------------------------------------------------------------------------------
-; // synth defines
+;   synth defines
-; //----------------------------------------------------------------------------------------
+;-------------------------------------------------------------------------------
 
 %define MAX_DELAY           65536
 %assign MAX_UNITS_SHIFT     6
@@ -281,18 +221,18 @@
 
 %define SU_END_TRACKS
 
-; //----------------------------------------------------------------------------------------
+;-------------------------------------------------------------------------------
-; // Unit struct
+;   unit struct
-; //----------------------------------------------------------------------------------------
+;-------------------------------------------------------------------------------
 struc su_unit
     .state      resd    8
     .ports      resd    8
     .size
 endstruc
 
-; //----------------------------------------------------------------------------------------
+;-------------------------------------------------------------------------------
-; // Voice struct
+;   voice struct
-; //----------------------------------------------------------------------------------------
+;-------------------------------------------------------------------------------
 struc su_voice
     .note       resd    1
     .release    resd    1
@@ -300,9 +240,10 @@ struc su_voice
     .workspace  resb    MAX_UNITS * su_unit.size
     .size
 endstruc
-; //----------------------------------------------------------------------------------------
+
-; // Synth struct
+;-------------------------------------------------------------------------------
-; //----------------------------------------------------------------------------------------
+;   synth struct
+;-------------------------------------------------------------------------------
 struc su_synth
     .left       resd    1
     .right      resd    1