Updated Sound Engine Commands (markdown)

1 files changed, 113 insertions, 4 deletions

diff --git a/Sound-Engine-Commands.md b/Sound-Engine-Commands.md
index d953efc..b2e4fc2 100644
--- a/Sound-Engine-Commands.md
+++ b/Sound-Engine-Commands.md
@@ -10,7 +10,7 @@ db $d8 - (\1)
 Sets the octave for the folloing notes  
   
 # $d8: notetype byte (byte)  
-\1: Note length  
+\1: Note length (# frames per 16th note, shouldn't be greater than 16)  
 \2: Initial Volume of envelope (0-0Fh) (0=No Sound)  
 \3: Envelope Direction (0=Decrease, 1=Increase)  
 \4: Number of envelope sweep (n: 0-7) (If zero, stop envelope operation.)  
@@ -24,6 +24,7 @@ db $d8, (\1), (\2 << 4) | (\3 << 3) | (\4)
     * following notes have length $a (channel 4 has no volume envelope setting)
   
 Sets the note length and (if we're not in channel 4) the volume envelope setting (see the command 'volenvelope') for the following notes.  
+The note length shouldn't be greater than 16, because it gets multiplied with the note duration (which is set with the note command, i.e. C_, 12) and of the result only the lower 8-Bits are taken into further calculation.  
   
 # $d9: forceoctave byte (or setabsnote)  
 \1: octave (0 - 15)  
@@ -36,13 +37,26 @@ Sets an absolute starting octave and pitch for all notes.
 This forces all notes up by the starting pitch and octave.  
   
 # $da: tempo word  
-\1: number (0 - (2^16-1))  
+\1: 8.8 fixed point number (with 8bit fractional part) (higher value = slower tempo)  
 db $da  
 dw (\1)  
 * usage:  
   * tempo 140  
   
-Sets the tempo of all channels to the chosen value  
+Sets the tempo of all channels to the chosen value.  
+The audio engine initialise this with $100.  
+  
+Corresponds to bpm (beats per minute):  
+You also have to set the note length with the Cmd 'notetype', which corresponds to 'Ticks/Row'.  
+* **240 beats per minute**  
+  3600 frames per minute / (6 tickets per row * 4 row per beat) / 240 bpm = 0.625 frames per tick  
+  0.625 frames per tick * 256 = 160 (this step is to convert to a fixed point value)  
+  240 bpm = tempo 160  
+  
+* **170 beats per minute**  
+  3600 frames per minute / (6 tickets per row * 4 rows per beat) / 170 bpm = 0.882 frames per tick  
+  0.882 frames per tick * 256 = ~226  
+  170 bpm = tempo 226  
   
 # $db: dutycycle byte (or setwaveduty)  
 \1: Wave pattern duty setting (0-3)  
@@ -144,6 +158,34 @@ db $e1, \1, (\2 << 4) | \3
 Parameter is saved into the channel structure, but never used again.  
 The command is also never used by any song or sound effect.  
   
+# $e3: togglenoise byte (or setdrumkit)  
+\1:  
+db $e3, (\1)  
+* usage:  
+  * togglenoise $05  
+  
+The command is used for channel 4 to set the drumkit and with it the available drumsounds.  
+If noise sampling is off (is the initial state) then it gets turned on, if noise sampling is on it gets turned off and no drumkit is set.  
+The Cmd is only used once per song in PokeCrystal so it's only used to set the drumkit.  
+  
+# $e4: panning byte  
+\1:  
+db $e4, (\1)  
+* usage:  
+  * panning $f0  
+  
+The parameter acts like a BitMask for register NR51.  
+  
+    FF25 - NR51 - Selection of Sound output terminal (R/W)
+    Bit 7 - Output sound 4 to SO2 terminal
+    Bit 6 - Output sound 3 to SO2 terminal
+    Bit 5 - Output sound 2 to SO2 terminal
+    Bit 4 - Output sound 1 to SO2 terminal
+    Bit 3 - Output sound 4 to SO1 terminal
+    Bit 2 - Output sound 3 to SO1 terminal
+    Bit 1 - Output sound 2 to SO1 terminal
+    Bit 0 - Output sound 1 to SO1 terminal
+  
 # $e5: volume byte  
 \1: SO2 output level (volume)  (0-7)  
 \2: SO1 output level (volume)  (0-7)  
@@ -163,6 +205,18 @@ parameter is directly written in hardware register [NR50](http://bgb.bircd.org/p
     in the cartridge to supply a fifth sound channel, additionally to the gameboys  
     internal four channels. As far as I know this feature isn't used by any existing games.  
   
+# $e6: tone word (setpitchoffset)  
+\1: 11bit frequency  
+db $e6  
+dw (\1)   
+* usage:  
+  * tone 0  
+  
+The frequency gets added to the intern NRX3 and NRX4 register of the corresponding channel, so that every note gets shifted by the frequency that is set with this command.  
+The frequency is calculated with following formula.  
+  
+    Frequency = 131072/(2048-x) Hz
+  
 # $e7: unknownmusic0xe7 byte  
   
 Parameter is saved into the channel structure, but never used again.  
@@ -190,7 +244,49 @@ dw (\1)
 * usage:  
   * unknownmusic0xee Label
   
-The command checks a byte that corresponds to the channel and decides to jump or not, but the byte that gets checked is never set.
+The command checks a byte that corresponds to the channel and decides to jump or not, but the byte that gets checked is never set.  
+  
+# $ef: stereopanning byte  
+\1:  
+db $ef, (\1)  
+* usage:  
+  * stereopanning $f0  
+  
+The command is only executed if stereo is activated in the options and then it acts the same as Cmd $e4.  
+  
+# $f0: sfxtogglenoise byte (or setsfxdrumkit)  
+\1:  
+db $f0, (\1)  
+* usage:  
+  * sfxtogglenoise $05  
+  
+Does the same as Cmd $e3 just for the SFX Channel.  
+  
+# $f1 - $f8:  
+  
+Commands don't do anything.
+  
+# $f9: unknownmusic0xf9  
+db $f9  
+  
+Sets a flag which is never used.  
+  
+# $fa: setcondition byte  
+\1: condition  
+db $fa, \1  
+* usage:  
+  * setcondition condition  
+  
+Sets the condition read by Cmd $fb.
+  
+# $fb: jumpif byte byte  
+\1: condition  
+\2: address  
+db $fb, \1, \2  
+* usage:  
+  * jumpif condition Label  
+  
+Reads and Compares the condition set by Cmd $fa. If it's equa to the condition in this Cmd the jump is executed.  
   
 # $fc: jumpchannel word  
 \1: 16bit-pointer  
@@ -201,6 +297,19 @@ dw (\1)
   
 The engine of the channel jumps to the given adress. MusicAdress of the corresponding channel is set to the paramter.  
   
+# $fd: loopchannel byte word  
+\1: count (0:infinite)  
+\2: address  
+db $fd, \1  
+dw (\2)  
+* usage:  
+  * loopchannel 1, Label  
+  
+# $fe: callchannel word  
+\1: address  
+db $fe  
+dw (\1)  
+  
 # $ff: endchannel  
 * usage:  
   * endchannel