Echo 1.6 release... kind of a mess, will clean up in further commits I guess

4 files changed, 105 insertions, 30 deletions

diff --git a/doc/api-asm.68k b/doc/api-asm.68k
index 3293b9e..8cbbdba 100644
--- a/doc/api-asm.68k
+++ b/doc/api-asm.68k
@@ -132,7 +132,9 @@ Echo_SetVolumeEx
    Sets the global volume for each channel separately. Register a0 points to
    a list of 16 bytes (one for each Echo channel). Values for FM and PSG
    channels are given in the same way as in events, that is: logarithmic
-   scale, 0..127 for FM, 0..15 for PSG, lower = louder.
+   scale, 0..127 for FM, 0..15 for PSG, lower = louder. You can use the
+   look-up tables described below (Echo_FMVolTable and Echo_PSGVolTable) to
+   convert from linear to .
    
    The last byte (the one belonging to the PCM channel) is used to toggle
    whether PCM plays, either 0 (disabled) or 1 (enabled).
@@ -141,6 +143,17 @@ Echo_SetVolumeEx
    been changed for the sake of expansion. Currently the extra bytes are
    ignored, but consider adapting your code (just set them to zero).
 
+Echo_FMVolTable
+Echo_PSGVolTable
+    These two are not subroutines but rather look-up tables. They have 64
+    byte-sized entries and they're used to convert a linear volume value into
+    a hardware volume value (e.g. for Echo_SetVolumeEx).
+    
+    To give an idea of how to use these: take what you'd pass in d0 to
+    Echo_SetVolume divided by 4 (shift right by 2), then use it as an offset
+    to these tables. The byte will be the volume as the hardware (or
+    Echo_SetVolumeEx) wants it.
+
 =============================================================================
 
 *** Settings ***
@@ -167,6 +180,15 @@ Echo_SetPCMRate
    (which can hamper Echo's ability to process complex streams). Be careful
    if you increase the sample rate.
 
+Echo_SetStereo
+   in d0 = $00 to use mono, otherwise to use stereo
+   
+   Toggles whether sound is forced to mono (d0 == $00) or if stereo panning
+   works (d0 != $00). Will take effect for all following panning events. Can
+   be used to implement a mono/stereo toggle in games.
+   
+   By default Echo is in stereo mode.
+
 =============================================================================
 
 *** Raw access ***
diff --git a/doc/api-c.txt b/doc/api-c.txt
index 8e5c61c..2c879ef 100644
--- a/doc/api-c.txt
+++ b/doc/api-c.txt
@@ -138,6 +138,17 @@ void echo_set_volume_ex(const uint8_t *ptr)
    been changed for the sake of expansion. Currently the extra bytes are
    ignored, but consider adapting your code (just set them to zero).
 
+const uint8_t echo_fm_vol_table[]
+const uint8_t echo_psg_vol_table[]
+    These two are not subroutines but rather look-up tables. They have 64
+    byte-sized entries and they're used to convert a linear volume value into
+    a hardware volume value (e.g. for echo_set_volume_ex).
+    
+    To give an idea of how to use these: take what you'd pass as argument to
+    echo_set_volume divided by 4 (shift right by 2), then use it as an index
+    to these arrays. The byte will be the volume as the hardware (or
+    echo_set_volume_ex) wants it.
+
 =============================================================================
 
 *** Settings ***
@@ -163,6 +174,14 @@ void echo_set_pcm_rate(uint8_t rate)
    (which can hamper Echo's ability to process complex streams). Be careful
    if you increase the sample rate.
 
+void echo_set_stereo(int enable)
+
+   Toggles whether sound is forced to mono (enable == 0) or if stereo panning
+   works (enable != 0). Will take effect for all following panning events.
+   Can be used to implement a mono/stereo toggle in games.
+   
+   By default Echo is in stereo mode.
+
 =============================================================================
 
 *** Raw access ***
diff --git a/doc/eef.txt b/doc/eef.txt
index c3ab92e..57eeb1d 100644
--- a/doc/eef.txt
+++ b/doc/eef.txt
@@ -7,13 +7,25 @@ OVERVIEW
 
 FORMAT
 
-    EEF instruments consist of a list of volume levels. Each byte represents
-    a different volume level, and the value ranges from $00 (loudest) to $0F
-    (quietest). Each byte represents one tick (i.e. 1/60th of a second).
+    EEF instruments consist of a byte per tick (1/60th of a second). The
+    bottom nibble is the volume level (relative to the note's volume),
+    ranging from $x0 (loudest) to $xF (quietest).
+    
+    The upper nibble is a "semitone shift", which is added to the current
+    note's semitone. These can be useful for things like vibrato (e.g. for
+    whistles) and such. The amount the semitone is shifted is as follows:
+    
+        $0x ... 0 | $1x ... +1  | $8x ... -1
+                  | $2x ... +2  | $9x ... -2
+                  | $3x ... +3  | $Ax ... -3
+                  | $4x ... +4  | $Bx ... -4
+                  | $5x ... +6  | $Cx ... -6
+                  | $6x ... +8  | $Dx ... -8
+                  | $7x ... +12 | $Ex ... -12
     
     Looping is possible. The start of the loop is marked by a byte with value
     $FE, while the end of the loop is marked by a byte with value $FF. There
-    must be at least one volume byte between them or Echo will hang.
+    must be at least one tick byte between them or Echo will hang.
     
     To make a non-looping PSG instrument, just put the last volume value
     inside the loop.
@@ -22,14 +34,14 @@ FORMAT
 
 NOTES
 
-    Yes, this format was kind of an afterthought. Later I may improve it to
-    provide at least some kind of RLE-like compression, but for now you'll
-    have to stick with this :P
-    
-    Also, since PSG instruments are required to use PSG channels and I know
-    many of you don't want to mess with them at all, here's a flat PSG
-    instrument (i.e. no envelope):
+    Since PSG instruments are required to use PSG channels and I know many of
+    you don't want to mess with them at all, here's a flat PSG instrument
+    (i.e. no envelope):
     
         $FE,$00,$FF
+    
+    There's a flavor of the Set Frequency event that doesn't play nice with
+    semitone shifting (in which case it'll just act as if it was always $0x).
+    It will work again once a new note starts or the other flavor is used.
 
 =============================================================================
diff --git a/doc/esf.txt b/doc/esf.txt
index 7fbe73e..ab74399 100644
--- a/doc/esf.txt
+++ b/doc/esf.txt
@@ -217,34 +217,56 @@ $2Bnn: Set volume PSG channel #4
 
 =============================================================================
 
-$30nnnn: Set frequency FM channel #1
-$31nnnn: Set frequency FM channel #2
-$32nnnn: Set frequency FM channel #3
-$34nnnn: Set frequency FM channel #4
-$35nnnn: Set frequency FM channel #5
-$36nnnn: Set frequency FM channel #6
+$30nn/$30nnnn: Set frequency FM channel #1
+$31nn/$31nnnn: Set frequency FM channel #2
+$32nn/$32nnnn: Set frequency FM channel #3
+$34nn/$34nnnn: Set frequency FM channel #4
+$35nn/$35nnnn: Set frequency FM channel #5
+$36nn/$36nnnn: Set frequency FM channel #6
 
     These events set the raw frequency of a specific FM channel, without
-    triggering a new note. Meant for note slides. The following two bytes
-    specify the new frequency in the same format as the YM2612 expects. The
-    first byte is register +$A4, the second byte is register +$A0.
-    
+    triggering a new note. Meant for note slides. The format of this event
+    depends on whether the second byte has its MSB set or not.
+
+    If the 2nd byte's MSB is set, the event is two bytes long. The 2nd byte
+    is the semitone in this format (where "octave" is from 0 to 7 and
+    "semitone" is from 0 to 11):
+
+        octave * 16 + semitone + 128
+
+    If the 2nd byte's MSB is clear, the event is three bytes long. The 2nd
+    and 3rd bytes specify the new frequency in the same format as the YM2612
+    expects. The 2nd byte is register $A4+, the 3rd byte is register $A0+.
+
     Echo uses the following frequency values for each semitone:
-    
+
         C  - 644 | E  - 810 | G# - 1021
         C# - 681 | F  - 858 | A  - 1081
         D  - 722 | F# - 910 | A# - 1146
         D# - 765 | G  - 964 | B  - 1214
 
-$38nnnn: Set frequency PSG channel #1
-$39nnnn: Set frequency PSG channel #2
-$3Annnn: Set frequency PSG channel #3
+$38nn/$38nnnn: Set frequency PSG channel #1
+$39nn/$39nnnn: Set frequency PSG channel #2
+$3Ann/$3Annnn: Set frequency PSG channel #3
 
     These events set the raw frequency of a specific square wave PSG channel,
-    without triggering a new note. Meant for note slides. The following two
-    bytes specify the new frequency, the first byte containing the four least
-    significant bits (LSB aligned), and the next byte containing the six most
-    significant bits (LSB aligned too).
+    without triggering a new note. Meant for note slides. The format of this
+    event depends on whether the second byte has its MSB set or not.
+
+    If the 2nd byte's MSB is set, the event is two bytes long. The 2nd byte
+    is the semitone in this format (where "octave" is from 0 to 5 and
+    "semitone" is from 0 to 11):
+
+        octave * 12 + semitone + 128
+
+    If the 2nd byte's MSB is clear, the event is three bytes long. The 2nd
+    and 3rd bytes specify the new frequency, the 2nd byte containing the
+    four least significant bits (LSB aligned), and the 3rd byte containing
+    the six most significant bits (LSB aligned too).
+
+    IMPORTANT: using the 3-byte event prevents semitone shifting in PSG
+    instruments from working. It will start working again whenever a new note
+    or the 2-byte version of this event is used.
 
     Echo uses the following frequency values for each semitone: