ESFM: cherry-pick new documentation

doc/4-instrument/fm-esfm.md

@@ -7,13 +7,13 @@ the ESFM editor is divided into 6 tabs:
 - **Macros (OP2)**: for macros controlling FM parameters of operator 2.
 - **Macros (OP3)**: for macros controlling FM parameters of operator 3.
 - **Macros (OP4)**: for macros controlling FM parameters of operator 4.
-- **Macros**: for other macros (volume/arp/pitch/pan/noise mode).
+- **Macros**: for other macros (volume/arp/pitch/pan/operator 4 noise mode).
 
 ## FM
 
-ESFM is four-operator, but it is different from the rest of FM chips.
+ESFM is four-operator, meaning it takes four oscillators to produce a single sound.
 
-the concept of an algorithm does not exist in ESFM. instead, modulation routing is arbitrary, with each operator having output level and modulation input parameters.
+unlike most four-operator FM synthesizers, however, ESFM does not have an algorithm selection. instead, it uses a fixed operator arrangement, but allows you to independently control the output and modulation input levels of each operator. this allows it to reproduce a few common four-operator algorithms, as well as unique combinations where operators act as modulators and carriers at the same time.
 
 these apply to the instrument as a whole:
 - **OP4 Noise Mode**: determines the mode used to produce noise in operator 4.
@@ -21,57 +21,114 @@ these apply to the instrument as a whole:
   - Snare: takes the snare noise generation mode from OPL. square + noise.
   - HiHat: ring modulates with operator 3 and adds noise.
   - Top: ring modulates with operator 3 and double pitch modulation input.
-    - this mode is not emulated correctly. subject to change!
+  - these are normally used for the drum channels in ESFM's OPL3 compatibility mode.
+    - however, in ESFM, operator 4 can be modulated by operator 3, whereas in OPL3 drum mode the rhythm channels cannot be modulated.
+  - __note__: usage of noise mode "Top" is discouraged for now as it is not properly emulated yet, and results may change when the emulation gets fixed in the future.
+- **operator routing preview**: shows how operators are connected with each other and with the audio output (at the bottom).
+  - left-click pops up a small "operators changes with volume?" dialog where each operator can be toggled to scale with volume level.
+  - right-click switches to a preview display of the waveform generated on a new note:
+    - left-click restarts the preview.
+    - middle-click pauses and unpauses the preview.
+    - right-click returns to algorithm view.
 
 these apply to each operator:
 - the crossed-arrows button can be dragged to rearrange operators.
 - **Amplitude Modulation (AM)**: makes the operator affected by LFO tremolo.
-- **Sustain flag (SUS)**: when enabled, value of Sustain Level is in effect.
+- **AM Depth (DAM/AMD)**: when enabled, LFO tremolo is deeper (1dB off; 4.8dB on).
-- **AM Depth (AMD)**: when enabled, LFO tremolo is deeper.
+- **Sustain flag (SUS)**: when enabled, the envelope pauses ("sustains") once it reaches the Sustain Level and does not proceed to the release phase until note off.
+- **Envelope Delay (DL)**: determines the delay time before the envelope is triggered. the bigger the value, the longer the delay (0 to 7).
+  - a change of one unit doubles or halves the delay time.
+  - a value of 0 results in no delay.
 - **Attack Rate (AR)**: determines the rising time for the sound. the bigger the value, the faster the attack (0 to 15).
 - **Decay Rate (DR)**: determines the diminishing time for the sound. the higher the value, the shorter the decay. it's the initial amplitude decay rate (0 to 15).
 - **Sustain Level (SL)**: determines the point at which the sound ceases to decay and changes to a sound having a constant level. the sustain level is expressed as a fraction of the maximum level (0 to 15).
 - **Release Rate (RR)**: determines the rate at which the sound disappears after note off. the higher the value, the shorter the release (0 to 15).
-
 - **Total Level (TL)**: represents the envelope’s highest amplitude, with 0 being the largest and 63 (decimal) the smallest. a change of one unit is about 0.75 dB.
-- **Output Level (OL)**: determines the volume at which the operator will be output.
-- **Modulation Input (MI)**: determines how much to take from the previous operator for modulation.
-  - this controls feedback level in the case of operator 1.
 - **Key Scale Level (KSL)**: also known as "Level Scale". determines the degree to which the amplitude decreases according to the pitch.
 
 ![FM ADSR chart](FM-ADSRchart.png)
 
 - **Key Scale Rate (KSR)**: also known as "Rate Scale". determines the degree to which the envelope execution speed increases according to the pitch.
 - **Frequency Multiplier (MULT)**: sets the coarse pitch offset in relation to the note (0 to 15). 0 is -1 octave, 1 is 0 octaves, 2 is 1 octave, 3 is 1 octave 7 semitones, and so on.
-  - note that values 11, 13 and 14 behave as 10, 12 and 12 respectively.
+  - note that values 11, 13 and 14 behave as 10, 12 and 15 respectively.
+- **Tune (CT)**: sets the semitone offset in relation to the note (-24 to 24).
+  - this is a software effect.
+- **Fine Detune (DT)**: shifts the pitch in fine steps (-128 to 127). 0 is the base pitch, -128 is -1 semitone, 127 is nearly +1 semitone.
+  - this is a software effect.
+- **Left (L)**: toggles output to the left channel from the operator to the audio output.
+- **Right (R)**: toggles output to the right channel from the operator to the audio output.
 - **Waveform Select (WS)**: changes the waveform of the operator (0 to 7).
 - **Vibrato (VIB)**: makes the operator affected by LFO vibrato.
-- **FM Depth (FMD)**: when enabled, vibrato is deeper.
+- **Vibrato Depth (DVB/FMD)**: when enabled, vibrato is deeper.
 
-- **Tune**: sets the coarse tune of the operator.
+### routing controls
-- **Detune**: sets the fine tune of the operator.
 
-- **Left (L)**: output on the left channel.
+- **Output Level (OL)**: sets the output level from this operator to the audio output (0 to 7).
-- **Right (R)**: output on the right channel.
+  - 7 is the loudest level and 1 is the softest, while 0 disables audio output.
+  - a change of one unit is about 6 dB.
+  - this output scaling factor is applied after TL and envelope scaling have been performed.
+- **Modulation Input Level (MI)**: sets the modulation level from the previous operator to this operator (0 to 7).
+  - 7 is the strongest level and 1 is the weakest, while 0 disables modulation.
+  - a change of one unit is about 6 dB.
+  - for operator 1 this controls the **feedback level**.
+  - this modulation scaling factor is applied after the previous operator's TL and envelope scaling have been performed, but is unaffected by OL above.
+
+### common algorithms
+
+this table contains a list of modulation input/output level values which resemble common algorithms in Yamaha FM chips.
+
+__note__: MI1 is not included as it is the feedback level.
+
+| algorithm                      | OL1 | MI2 | OL2 | MI3 | OL3 | MI4 | OL4 |
+|--------------------------------|:---:|:---:|:---:|:---:|:---:|:---:|:---:|
+| OPN algorithm **0**            |  0  |  7  |  0  |  7  |  0  |  7  |  7  |
+| OPN algorithm **4**            |  0  |  7  |  7  |  0  |  0  |  7  |  7  |
+| OPN algorithm **6**            |  0  |  7  |  7  |  0  |  7  |  0  |  7  |
+| OPN algorithm **7**            |  7  |  0  |  7  |  0  |  7  |  0  |  7  |
+| OPL3 algorithm **1**           |  7  |  0  |  0  |  7  |  0  |  7  |  7  |
+| OPL3 algorithm **3**           |  7  |  0  |  0  |  7  |  7  |  0  |  7  |
+| OPL3 algorithm **1** (variant) |  0  |  7  |  0  |  7  |  7  |  0  |  7  |
 
 ### fixed frequency mode
 
 each operator has a Fixed Frequency mode. once enabled, the operator runs at the specified frequency regardless of the note.
 
+when fixed frequency mode is enabled, the Tune and Fine Detune sliders will be replaced by **Block (Blk)** and **FreqNum (F)**, which allow you to input a raw frequency value into the operator.
+the actual frequency is determined by the formula: `FreqNum*(2^Block)`.
+
+in other words, FreqNum defines the base frequency, while Block determines the scaling factor in octaves.
+
 ## macros
 
 these macros allow you to control several parameters of FM per tick.
 
 ## OP1-OP4 Macros
 
-all parameters are listed above.
+most parameters are listed above.
+
+### envelope delay macro tricks
+
+due to a quirk in how the envelope delay feature works, the **Envelope Delay** macro can control the operator's key-on status for a limited amount of time after a note is played. a value of 0 represents key-on, while a value of 7 represents key-off.
+
+note that the macro cannot exceed 659.1 ms in length - anything beyond that will be treated as a value of 0.
+
+### operator arpeggio and pitch macros
+
+among the available macros are **Op. Arpeggio** and **Op. Pitch**. these work like the **Arpeggio** and **Pitch** macros featured below, but are applied to the individual operator, overriding the **Arpeggio**/**Pitch** macros respectively.
+
+the **Tune** and **Fine Detune** FM parameters are still respected when using these macros.
+
+### fixed frequency macros
+
+when fixed frequency is enabled for an operator, the **Op. Arpeggio** and **Op. Pitch** macros will be replaced by the **Block** and **FreqNum** macros. these can be used to change the operator's fixed frequency over time.
 
 ## Macros
 
 - **Volume**: volume sequence.
 - **Arpeggio**: pitch sequence.
-- **OP4 Noise Mode**: noise mode sequence.
+- **OP4 Noise Mode**: operator 4 noise mode sequence.
 - **Panning**: enables output on left/right channels.
+  - note that each operator also has its own pan controls, which get masked by this global pan control.
 - **Pitch**: fine pitch.
   - **Relative**: when enabled, pitch changes are relative to the current pitch.
 - **Phase Reset**: restarts all operators and resets the waveform to its start.

doc/4-instrument/fm-opl.md

@@ -29,7 +29,7 @@ these apply to the instrument as a whole:
 these apply to each operator:
 - the crossed-arrows button can be dragged to rearrange operators.
 - **Amplitude Modulation (AM)**: makes the operator affected by LFO tremolo.
-- **Sustain flag (SUS)**: when enabled, value of Sustain Level is in effect.
+- **Sustain flag (SUS)**: when enabled, the envelope pauses ("sustains") once it reaches the Sustain Level and does not proceed to the release phase until note off.
 - **Attack Rate (AR)**: determines the rising time for the sound. the bigger the value, the faster the attack (0 to 15).
 - **Decay Rate (DR)**: determines the diminishing time for the sound. the higher the value, the shorter the decay. it's the initial amplitude decay rate (0 to 15).
 - **Sustain Level (SL)**: determines the point at which the sound ceases to decay and changes to a sound having a constant level. the sustain level is expressed as a fraction of the maximum level (0 to 15).

doc/7-systems/esfm.md

@@ -1,8 +1,12 @@
 # ESS ESFM
 
-an enhanced version of Yamaha's OPL3, adding many features which weren't present on the original chip, such as 4-op on all channels, coarse/fine detune, per-op panning, envelope delay, noise generator and advanced modulation routing (no more algorithms!).
+an FM synthesizer core included in a series of sound card chipsets made by ESS, which were mildly popular in the DOS days during the mid-late 90s.
 
-the technology was present in many of ESS' sound cards (the ES1xxx series in particular).
+at a cursory glance, it looks like just an [OPL3 clone](opl.md). but hidden under a veil of mystery is its exclusive "native mode", revealing an impressive superset of features, including 4-operator support on all 18 channels, semi-modular operator routing, per-operator pitch control, and even a few unique features.
+
+for a long time, not much was known about the inner workings of ESFM's native mode, since ESS did not release any documentation to developers on how to use it. this has thankfully changed in recent years thanks to reverse-engineering efforts from the community.
+
+thanks to ESS's decision to not release any documentation to developers and lock down usage of native mode behind a couple of General MIDI drivers shipping with rather lackluster patch sets, ESFM's native mode was unfortunately not very well used over its original lifespan.
 
 ## effects