add n-spc vcmd documentation to music_macros

Core/music_macros.asm

@@ -22,12 +22,20 @@
 !16thD = $1B
 !32nd  = $09
 
-macro SetDuration(v) 
+; Note Parameters ($01-$7F)
+; [xy]
+; When $xy < $80
+;   $x = Duration Rate (0-7)
+;   $y = Velocity Rate (0-15)
+; VByte itself means the length of the following note 
+; (48 = quarter note, usually).
+
+macro SetDuration(v)
 db <v>
 endmacro
 
 ; n default is $7F
-macro SetDurationN(v, n) 
+macro SetDurationN(v, n)
 db <v>, <n>
 endmacro
 
@@ -138,20 +146,33 @@ macro SetTempo(v)
 db $E7, <v>
 endmacro
 
+; - Play block $yyxx for $zz+1 times.
+; - Subroutine call cannot be nested.
+; - See also $00
+; The block $yyxx is played zz + 1 times. Subroutines cannot be nested.
 macro CallSubroutine(addr, repeat)
 db $EF
 dw <addr>
 db <repeat>
 endmacro
 
+; Set the left and right position of the sound. 
+; The range of values is as narrow as 0 to 20 
+; (the actual setting ratio is defined in the internal table). 
+; Depending on the version, it depends on whether the large value is left or right. 
+; The upper 2 bits are used for phase inversion.
+; Lower-5bit for pan value (0-20), higher-2bit is used for phase reverse switch.
 macro SetPan(v)
 db $E1, <v>
 endmacro
 
+; The position of the sound fades from the current value to yy over xx time.
 macro PanFade(length, dest)
 db $E2, <length>, <dest>
 endmacro
 
+; Enables vibrato (pitch fluctuation / pitch swing). 
+; Set zz-sized vibrato at yy speed after xx time.
 macro VibratoOn(delay, rate, depth)
 db $E3, <delay>, <rate>, <depth>
 endmacro
@@ -160,22 +181,31 @@ macro VibratoOff()
 db $E4
 endmacro
 
+; The volume of the entire song fades from the current value to yy over xx time.
 macro MasterVolumeFade(length, dest)
 db $E6, <length>, <dest>
 endmacro
 
+; Specifies the playing speed of the song.
+; Value of about 24/60 is written. 
 macro TempoFade(length, dest)
 db $E8, <length>, <dest>
 endmacro
 
+; Raises the playing pitch of all channels by xx 
+; (negative numbers can be specified).
 macro GlobalTranspose(tone)
 db $E9, <tone>
 endmacro
 
+; Raises the playing pitch of a single channel by xx 
+; (negative numbers can also be specified).
 macro ChannelTranspose(tone)
 db $EA, <tone>
 endmacro
 
+; Enable tremolo (volume fluctuation). 
+; Set the tremolo of the size of zz to be applied at the speed of yy after xx time.
 macro TremoloOn(delay, rate, depth)
 db $EB, <delay>, <rate>, <depth>
 endmacro
@@ -188,14 +218,23 @@ macro ChannelVolumeFade(length, dest)
 db $EE, <length>, <dest>
 endmacro
 
+; After temporarily setting the vibrato depth to 0, 
+; it will smoothly return to the original value over xx time.
 macro VibratoFade(length)
 db $F0, <length>
 endmacro
 
+; Specifies that subsequent sounds will be 
+; "higher by zz over yy time after xx time." 
+; zz is a semitone unit, and you can specify a negative number.
 macro PitchEnvelopeTo(delay, length, key)
 db $F1, <delay>, <length>, <key>
 endmacro
 
+; Specifies that subsequent notes will be 
+; "played at a pitch that is zz higher than normal, 
+;  and will return to normal pitch over yy time after xx time." 
+; zz is a semitone unit, and you can specify a negative number.
 macro PitchEnvelopeFrom(delay, length, key)
 db $F2, <delay>, <length>, <key>
 endmacro
@@ -204,10 +243,18 @@ macro PitchEnvelopeOff()
 db $F3
 endmacro
 
+; Change the pitch slightly. 
+; Only positive numbers can be specified, so the pitch cannot be lowered.
+; xx = Unsigned. Make the pitch xx/256 semitones higher.
 macro Tuning(v)
 db $F4, <v>
 endmacro
 
+; Specifies the channel and volume at which echo is enabled. 
+; The value set in the register remains the same.
+; xx = Echo Switch (EON)
+; yy = Echo Left Volume (EVOL (L))
+; zz = Echo Right Volume (EVOL (R))
 macro EchoVBits(switch, left, right)
 db $F5, <switch>, <left>, <right>
 endmacro
@@ -224,10 +271,34 @@ macro EchoVolumeFade(length, left, right)
 db $F8, <length>, <left>, <right>
 endmacro
 
+; This VCMD is handled at different timing than other VCMDs.
+; utter note $90, (wait), set instrument to $01, utter note $92
+; $90, $e0 $01, $92
+; utter note $90 then change the key immediately to note $91, (wait),
+; utter note $92.
+; $90, $f9 $00 $01 $91, $92
+; utter note $90 then change the key immediately to note $91, (wait),
+; set instrument to $01, utter note $92.
+; $90, $f9 $00 $01 $91, $e0 01, $92
+; <weird example> utter note $90, (wait), set instrument to $01,
+; (pitch slide vcmd appears but note $90 has been end), utter note $92.
+; $90, $e0 01, $f9 $00 $01 $91, $92
+
+; Smoothly changes the pitch of the sound being pronounced. 
+; After xx time from play, it will be changed to the zz pitch
+; (absolute designation) over yy time. 
+; If you want to raise or lower the sound in the middle of one note, 
+; write this command continuously. 
+; If the pronunciation time is long, you can write it with Thai.
+
+; Normally, after one Note, it waits for the length of the note 
+; and then processes the next byte, but only this command 
+; is read and processed immediately.
 macro PitchSlide(delay, length, note)
 db $F9, <delay>, <length>, <note>
 endmacro
 
+; Determines the correspondence between the percussion value and the sound you hear.
 macro PercussionPatchBass(instrument)
 db $FA, <instrument>
 endmacro
@@ -267,84 +338,103 @@ macro SustainNoteN(note, num)
   endif
 endmacro
 
-End = $00
+End  = $00
+Tie  = $C8
 Rest = $C9
-Tie = $C8
 
-C1 = $80
+; Percussion Note ($CA-DF)
-C1s = $81
+; VByte itself means percussion note (#). 
-D1 = $82
+; Relations between percussion note and SRCN depends on $FA.
-D1s = $83
+; By default, percussion uses the same instrument set as the song, 
-E1 = $84
+; and all percussion is keyed on with a note of $A4. 
-F1 = $85
+; The starting ID to use for all channels can be redefined by VCMD $FA. 
-F1s = $86
-G1 = $87
-G1s = $88
-A1 = $89
-A1s = $8A
-B1 = $8B
 
-C2 = $8C
-C2s = $8D
-D2 = $8E
-D2s = $8F
-E2 = $90
-F2 = $91
-F2s = $92
-G2 = $93
-G2s = $94
-A2 = $95
-A2s = $96
-B2 = $97
 
-C3 = $98
+; =========================================================
-C3s = $99
+; Tone Map
-D3 = $9A
+; 
-D3s = $9B
+; 	    C 	C+ 	D 	D+ 	E 	F 	F+ 	G 	G+ 	A 	A+ 	B
-E3 = $9C
+; Oc1 	80 	81 	82 	83 	84 	85 	86 	87 	88 	89 	8A 	8B
-F3 = $9D
+; Oc2 	8C 	8D 	8E 	8F 	90 	91 	92 	93 	94 	95 	96 	97
-F3s = $9E
+; Oc3 	98 	99 	9A 	9B 	9C 	9D 	9E 	9F 	A0 	A1 	A2 	A3
-G3 = $9F
+; Oc4 	A4 	A5 	A6 	A7 	A8 	A9 	AA 	AB 	AC 	AD 	AE 	AF
-G3s = $A0
+; Oc5 	B0 	B1 	B2 	B3 	B4 	B5 	B6 	B7 	B8 	B9 	BA 	BB
-A3 = $A1
+; Oc6 	BC 	BD 	BE 	BF 	C0 	C1 	C2 	C3 	C4 	C5 	C6 	C7
-A3s = $A2
-B3 = $A3
 
-C4 = $A4
+C1   = $80
-C4s = $A5
+C1s  = $81
-D4 = $A6
+D1   = $82
-D4s = $A7
+D1s  = $83
-E4 = $A8
+E1   = $84
-F4 = $A9
+F1   = $85
-F4s = $AA
+F1s  = $86
-G4 = $AB
+G1   = $87
-G4s = $AC
+G1s  = $88
-A4 = $AD
+A1   = $89
-A4s = $AE
+A1s  = $8A
-B4 = $AF
+B1   = $8B
 
-C5 = $B0
+C2   = $8C
-C5s = $B1
+C2s  = $8D
-D5 = $B2
+D2   = $8E
-D5s = $B3
+D2s  = $8F
-E5 = $B4
+E2   = $90
-F5 = $B5
+F2   = $91
-F5s = $B6
+F2s  = $92
-G5 = $B7
+G2   = $93
-G5s = $B8
+G2s  = $94
-A5 = $B9
+A2   = $95
-A5s = $BA
+A2s  = $96
-B5 = $BB
+B2   = $97
 
-C6 = $BC
+C3   = $98
-C6s = $BD
+C3s  = $99
-D6 = $BE
+D3   = $9A
-D6s = $BF
+D3s  = $9B
-E6 = $C0
+E3   = $9C
-F6 = $C1
+F3   = $9D
-F6s = $C2
+F3s  = $9E
-G6 = $C3
+G3   = $9F
-G6s = $C4
+G3s  = $A0
-A6 = $C5
+A3   = $A1
-A6s = $C6
+A3s  = $A2
-B6 = $C7
+B3   = $A3
+
+C4   = $A4
+C4s  = $A5
+D4   = $A6
+D4s  = $A7
+E4   = $A8
+F4   = $A9
+F4s  = $AA
+G4   = $AB
+G4s  = $AC
+A4   = $AD
+A4s  = $AE
+B4   = $AF
+
+C5   = $B0
+C5s  = $B1
+D5   = $B2
+D5s  = $B3
+E5   = $B4
+F5   = $B5
+F5s  = $B6
+G5   = $B7
+G5s  = $B8
+A5   = $B9
+A5s  = $BA
+B5   = $BB
+
+C6   = $BC
+C6s  = $BD
+D6   = $BE
+D6s  = $BF
+E6   = $C0
+F6   = $C1
+F6s  = $C2
+G6   = $C3
+G6s  = $C4
+A6   = $C5
+A6s  = $C6
+B6   = $C7