Instrument macro docs & images.

doc/4-instrument/8930.md

@@ -1,14 +1,16 @@
 # AY8930 instrument editor
 
-AY8930 instrument editor consists of 10 macros.
+AY8930 instrument editor consists of these macros.
 
 - [Volume] - volume levels sequence
 - [Arpeggio]- pitch sequence
-- [Noise frequency] - AY8930 noise generator frequency sequence
+- [Noise Freq] - AY8930 noise generator frequency sequence
 - [Waveform] - selector of sound type - pulse wave tone, noise or envelope generator
-- [Duty cycle] - duty cycle of a pulse wave sequence
+- [Pitch] - fine pitch
+- [Phase Reset] - trigger restart of waveform
+- [Duty] - duty cycle of a pulse wave sequence
 - [Envelope] - allows shaping an envelope
-- [Auto envelope numerator] - sets the envelope to the channel's frequency multiplied by numerator
-- [Auto envelope denominator] - sets the envelope to the channel's frequency multiplied by denominator
-- [Noise AND mask] - alters the shape/frequency of the noise generator, allowing to produce various interesting sound effects and even PWM phasing
-- [Noise OR mask] - see above
+- [AutoEnv Num] - sets the envelope to the channel's frequency multiplied by numerator
+- [AutoEnv Den] - sets the envelope to the channel's frequency multiplied by denominator
+- [Noise AND Mask] - alters the shape/frequency of the noise generator, allowing to produce various interesting sound effects and even PWM phasing
+- [Noise OR Mask] - see above

doc/4-instrument/README.md

@@ -30,16 +30,69 @@ depending on the instrument type, there are currently 13 different types of an i
 - [Namco 163](n163.md) - for use with Namco 163.
 - [Konami VRC6](vrc6.md) - for use with VRC6's PSG sound source.
 
+
+
 # macros
 
-one common feature to instruments is macros (also known as sequences).
+Macros are incredibly versatile tools for automating instrument effects.
 
-these run on every tick and are useful for controlling parameters automatically.
+After creating an instrument, open the Instrument Editor and select the "Macros" tab. There may be multiple macro tabs to control individual FM operators and such.
 
-![macro view](macro.png)
+![macro view](macroview.png)
 
-to change the loop portion/point, click on the bar under the macro.
-right click on it to disable macro loop.
+The very first numeric entry sets the visible width of the bars in sequence-type macros. The scrollbar affects the view of all macros at once. There's a matching scrollbar at the bottom underneath all the macros.
 
-to change the release point, shift-click the bar under the macro.
-shift-right click on it to remove the release point.
+Each macro has two buttons on the left.
+- Macro type (explained below).
+- Timing editor, which pops up a small dialog:
+  - Step Length (ticks): Determines how many ticks pass before each change of value.
+  - Delay: Delays the start of the macro until this many ticks have passed.
+
+## macro types
+
+Every macro can be defined though one of three methods, selectable by the leftmost button under the macro type label:
+
+- ![](macro-button-seq.png) **Sequence:** Displayed as a bar graph, this is a sequence of numeric values.
+- ![](macro-button-ADSR.png) **ADSR:** This is a traditional ADSR envelope, defined by the rate of increase and decrease of value over time.
+- ![](macro-button-LFO.png) **LFO:** The Low Frequency Oscillator generates a repeating wave of values.
+
+Some macros are "bitmap" style. They represent a number of "bits" that can be toggled individually, and the values listed represent the sum of which bits are turned on.
+
+### sequence
+
+![sequence macro editor](macro-seq.png)
+
+The number between the macro type label and the macro type button is the macro length in steps. The `-` and `+` buttons change the length of the macro. Start out by adding at least a few steps.
+
+The values of the macro can be drawn in the "bar graph box". Just beneath the box is shorter bar graph.
+- Click to set the start point of a loop; the end point is the last value unless a release point is set.
+- Shift-click to set the release point. When played, the macro will hold here until the note is released.
+
+Finally, the sequence of values can be directly edited in the text box at the bottom.
+- The loop start is entered as a `|`.
+- The release point is entered as a `/`.
+- In arpeggio macros, a value starting with a `@` is an absolute note (instead of a relative shift). No matter the note played, `@` values will be played at that exact note. This is especially useful for noise instruments with preset periods.
+
+### ADSR
+
+![ADSR macro editor](macro-ADSR.png)
+
+![macro ADSR chart](macro-ADSRchart.png)
+
+- **Bottom** and **Top** determine the range of values generated by the macro. (Bottom can be larger than Top to invert the envelope!) All generated values will fall between these two points.
+- **Attack** is how quickly the value goes from Bottom to Top. A 0 means nothing will change; a 255 instantly jumps to the Top value.
+- **Hold** sets how many ticks the note will wait at Top before decay.
+- **Decay** is how quickly the value moves to the Sustain level.
+- **Sustain** is the where the value will stay while the note is held until SusTime has passed.
+- **SusTime** is how many ticks until SusDecay.
+- **SusDecay** is the rate at which the value moves toward Bottom while the note is held.
+- **Release** is the rate at which the note changes once the note is released.
+
+### LFO
+
+![LFO macro editor](macro-LFO.png)
+
+- **Bottom** and **Top** determine the range of values generated by the macro. (Bottom can be larger than Top to invert the waveform!)
+- **Speed** is how quickly the values change – the frequency of the oscillator.
+- **Phase** is which part of the waveform the macro will start at, measured in 1/1024 increments.
+- **Shape** is the waveform used. Triangle is the default, and Saw and Square are exactly as they say.

doc/4-instrument/amiga.md

@@ -1,6 +1,6 @@
 # Amiga/PCM sound sourceinstrument editor
 
-PCM instrument editor consists of four macros and sample selector:
+PCM instrument editor consists of a sample selector and several macros:
 
 # Amiga/sample
 
@@ -11,3 +11,7 @@ PCM instrument editor consists of four macros and sample selector:
 - [Volume] - volume sequence WARNING: it works only on Amiga system, as of version 0.5.5!!
 - [Arpeggio] - pitch sequence
 - [Waveform] - sample sequence
+- [Panning (left)] - output level for left channel
+- [Panning (right)] - output level for right channel
+- [Pitch] - fine pitch
+- [Phase Reset] - trigger restart of waveform

doc/4-instrument/ay8910.md

@@ -1,11 +1,13 @@
 # AY-3-8910 instrument editor
 
-AY-3-8910 instrument editor consists of 7 macros.
+AY-3-8910 instrument editor consists of these macros.
 
 - [Volume] - volume levels sequence
 - [Arpeggio]- pitch sequence
-- [Noise frequency] - AY-3-8910 noise generator frequency sequence
+- [Noise Freq] - AY-3-8910 noise generator frequency sequence
 - [Waveform] - selector of sound type - square wave tone, noise or envelope generator
+- [Pitch] - fine pitch
+- [Phase Reset] - trigger restart of waveform
 - [Envelope] - allows shaping an envelope
-- [Auto envelope numerator] - sets the envelope to the channel's frequency multiplied by numerator
-- [Auto envelope denominator] - ets the envelope to the channel's frequency multiplied by denominator
+- [AutoEnv Num] - sets the envelope to the channel's frequency multiplied by numerator
+- [AutoEnv Den] - sets the envelope to the channel's frequency multiplied by denominator

doc/4-instrument/c64.md

@@ -1,8 +1,9 @@
 # C64 SID instrument editor
 
-C64 instrument editor consists of two tabs: one controlling various parameters of sound channels and macro tab containing seven macros:
+The C64 instrument editor consists of two tabs: "C64" to control various parameters of sound channels, and "Macros" containing several macros.
 
 ## C64
+
 - [Waveform] - allows selecting a waveform. NOTE: more than one waveform can be selected at once, logical AND mix of waves will be produced, with an exception of a noise waveform, it can't be mixed.
 - [Attack] - determines the rising time for the sound. The bigger the value, the slower the attack. (0-15 range)
 - [Decay]- Determines the diminishing time for the sound. The higher the value, the longer the decay. It's the initial amplitude decay rate. (0-15 range)
@@ -15,16 +16,20 @@ C64 instrument editor consists of two tabs: one controlling various parameters o
 - [Initialize filter] - initializes the filter with the specified parameters:
 - [Cutoff] - defines the "intensity" of a filter, to put in in layman terms (0-2047 range)
 - [Resonance] - defines an additional controlled amplification of that cutoff frequency, creating a secondary peak forms and colors the original pitch. (0-15 range)
-- [Filter mode] - determined the filter mode NOTE: SID's filter is muliti-mode, you can mix different modes together (like low and high-pass filters at once) CH3-OFF disables the channel 3, for no reason whatsoever lmao
-- [Volume Macrio is a Cutoff macro] - turns a volume macro in a macros tab into a filter cutoff macro.
-- [Absolute Cutoff macro] - changes the behaviour of a cutoff macro from the old-style, compatible to much more define-able.
-- [Absolute Duty macro] - changes the behaviour of a duty cycle macro from the old-style, compatible to much more define-able.
+- [Filter mode] - determined the filter mode NOTE: SID's filter is multi-mode, you can mix different modes together (like low and high-pass filters at once) CH3-OFF disables the channel 3, for no reason whatsoever lmao
+- [Volume Macro is Cutoff Macro] - turns a volume macro in a macros tab into a filter cutoff macro.
+- [Absolute Cutoff Macro] - changes the behaviour of a cutoff macro from the old-style, compatible to much more define-able.
+- [Absolute Duty Macro] - changes the behaviour of a duty cycle macro from the old-style, compatible to much more define-able.
+- [Don't test/gate before new note] - (document this)
 
 ## Macros
-- [Volume/Cutoff] - volume sequence (WARNING: Volume sequence is global for ALL three channels!!)
+
+- [Volume] - volume sequence (WARNING: Volume sequence is global for ALL three channels!!)
 - [Arpeggio] - pitch sequence
-- [Duty cycle] - pulse duty cycle sequence
+- [Duty] - pulse duty cycle sequence
 - [Waveform] - select the waveform used by instrument
+- [Pitch] - fine pitch
 - [Filter mode] - select the filter mode/sequence
 - [Resonance] - filter resonance sequence
 - [Special] - ring and oscillator sync selector
+- [Test/Gate] - (document this)

doc/4-instrument/fm.md

@@ -12,7 +12,7 @@ FM editor is divided into 7 tabs:
 
 ## FM
 
-FM synthesizers Furnace supports are for-operator, meaning it takes four oscillators to produce a single sound. Each operator is controlled by a dozen of sliders:
+FM synthesizers Furnace supports are four-operator, meaning it takes four oscillators to produce a single sound. Each operator is controlled by a dozen sliders:
 
 - [Attack Rate (AR)] - determines the rising time for the sound. The bigger the value, the faster the attack. (0-31 range)
 - [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-31 range)

doc/4-instrument/game-boy.md

@@ -1,17 +1,25 @@
 # Game Boy instrument editor
 
-GB instrument editor consists of two tabs: one controlling envelope of sound channels and macro tab containing only four macros:
+GB instrument editor consists of two tabs: one controlling envelope of sound channels and macro tab containing several macros.
 
 ## Game Boy
 
-- [Volume] - this slider affect the channel volume (range 0-15)
-- [Envelope length] - this slider specifies the envelope decay/attack (range 0-7)
-- [Sound length] - this slider cuts off the sound after specified length, overriding the previous slider's value
+- [Use software envelope] - switch to volume macro instead of envelope
+- [Initialize envelope on every note] - forces a volume reset on each new note
+- [Volume] - initial channel volume (range 0-15)
+- [Length] - envelope decay/attack duration (range 0-7)
+- [Sound Length] - cuts off sound after specified length, overriding the Length value
 
-- [UP an DOWN radio buttons] - these buttons alter the behaviour of a second slider. Up makes it specify the envelope attack, down the decay. WARNING: for envelope attack to have any effect, volume should be at the lower rates!
+- [Up and Down radio buttons] - Up makes the envelope an attack, down makes it decay. _Note:_ For envelope attack to have any effect, volume should start at a lower value!
+
+- [Hardware Sequence] - (document this)
 
 ## Macros
-- [Volume] - volume sequence
-- [Arpeggio] - pitch sequence
-- [Duty cycle] - pulse wave channels duty cycle sequence
+
+- [Volume] - volume sequence. _Note:_ This only appears if "Use software envelope" is checked.
+- [Arpeggio] - pitch in half-steps
+- [Duty/Noise] - pulse wave duty cycle or noise mode sequence
 - [Waveform] - ch3 wavetable sequence
+- [Panning] - output for left and right channels
+- [Pitch] - fine pitch
+- [Phase Reset] - trigger restart of waveform

doc/4-instrument/lynx.md

@@ -1,15 +1,18 @@
 # Atari Lynx instrument editor
 
-Atari Lynx instrument editor consists of only three macros:
+Atari Lynx instrument editor consists of these macros:
 
 - [Volume] - volume sequence
-- [Arpeggio] - pitch sequencer
-- [Duty/Int] - bit pattern for LFSR taps and integration.
+- [Arpeggio] - pitch in half-steps
+- [Duty/Int] - bit pattern for LFSR taps and integration
+- [Panning (left)] - output level for left channel
+- [Panning (right)] - output level for right channel
+- [Pitch] - fine pitch
+- [Phase Reset] - trigger restart of waveform
 
 ## Audio generation description
 
-Atari Lynx to generate sound uses 12-bit linear feedback shift register with configurable tap. Nine separate bits can be enable to be the source of feedback.
-Namely bits 0, 1, 2, 3, 4, 5, 7, 10 and 11. To generate ANY sound at least one bit MUST be enable.
+Atari Lynx generates sound using a 12-bit linear feedback shift register with configurable tap. Nine separate bits can be enabled to be the source of feedback: 0, 1, 2, 3, 4, 5, 7, 10 and 11. To generate _any_ sound at least one bit _must_ be enabled.
 
 ### Square wave
 

doc/4-instrument/n163.md

@@ -3,21 +3,28 @@
 Namco 163 instrument editor consists of two tabs: one controlling various parameters for waveform initialize and macro tab containing 10 macros.
 
 ## Namco 163
-- [Initial Waveform] - Determines the initial waveform for playing.
-- [Initial Waveform position in RAM] - Determines the initial waveform position will be load to RAM.
-- [Initial Waveform length in RAM] - Determines the initial waveform length will be load to RAM.
+
+- [Waveform] - Determines the initial waveform for playing.
+- [Offset] - Determines the initial waveform position will be load to RAM.
+- [Length] - Determines the initial waveform length will be load to RAM.
 - [Load waveform before playback] - Determines the load initial waveform into RAM before playback.
 - [Update waveforms into RAM when every waveform changes] - Determines the update every different waveform changes in playback.
 
 
 ## Macros
+
 - [Volume] - volume levels sequence
 - [Arpeggio]- pitch sequence
-- [Waveform pos.] - sets the waveform source address in RAM for playback (single nibble unit)
 - [Waveform] - sets waveform source for playback immediately or update later
+- [Panning] - output for left and right channels
+- [Pitch] - fine pitch
+- [Phase Reset] - trigger restart of waveform
+<!--
+- [Waveform pos.] - sets the waveform source address in RAM for playback (single nibble unit)
 - [Waveform len.] - sets the waveform source length for playback (4 nibble unit)
 - [Waveform update] - sets the waveform update trigger behavior for playback
 - [Waveform to load] - sets waveform source for load to RAM immediately or later
 - [Wave pos. to load] - sets address of waveform for load to RAM (single nibble unit)
 - [Wave len. to load] - sets length of waveform for load to RAM (4 nibble unit)
 - [Waveform load] - sets the waveform load trigger behavior
+-->

doc/4-instrument/pce.md

@@ -1,9 +1,14 @@
 # NEC PC Engine instrument editor
 
-PCE instrument editor consists of only three macros, almost like TIA:
+PCE instrument editor consists of these macros:
 
 - [Volume] - volume sequence
-- [Arpeggio] - pitch sequence
-- [Waveform] - spicifies wavetables sequence
+- [Arpeggio] - pitch in half-steps
+- [Noise] - enable noise mode (ch5 and ch6 only)
+- [Waveform] - wavetable sequence
+- [Panning (left)] - output level for left channel
+- [Panning (right)] - output level for right channel
+- [Pitch] - fine pitch
+- [Phase Reset] - trigger restart of waveform
 
 It also has wavetable synthesizer support, but unfortunately, it clicks a lot when in use on the HuC6280.

doc/4-instrument/saa.md

@@ -1,9 +1,12 @@
 # Philips SAA1099 instrument editor
 
-SAA1099 instrument editor consists of five macros:
+SAA1099 instrument editor consists of these macros:
 
 - [Volume] - volume sequence
 - [Arpeggio] - pitch sequence
-- [Duty cycle/ Noise] - noise generator frequency
+- [Duty/Noise] - noise generator frequency
 - [Waveform] - selector between tone and noise
-- [Envelope] - specifies the envelope generator shape
+- [Panning (left)] - output level for left channel
+- [Panning (right)] - output level for right channel
+- [Pitch] - fine pitch
+- [Envelope] - envelope generator shape

doc/4-instrument/scc.md

@@ -1,7 +1,8 @@
 # Konami SCC/Bubble System WSG instrument editor
 
-SCC/Bubble System WSG instrument editor consists of only three macros:
+SCC/Bubble System WSG instrument editor consists of these macros:
 
 - [Volume] - volume sequence
 - [Arpeggio] - pitch sequence
 - [Waveform] - spicifies wavetables sequence
+- [Pitch] - fine pitch

doc/4-instrument/standard.md

@@ -1,7 +1,10 @@
 # Standard instrument editor
 
-SMS and NES instrument editor consists of only three macros:
+The instrument editor for NES and PSG (SMS, MSX, and such) consists of these macros:
 
-- [Volume] - volume sequence
-- [Arpeggio] - pitch sequencr
-- [Duty cycle] - spicifies duty cycle and noise mode for NES channels NOTE: it obviously has no effect on Sega Master System
+- [Volume] - volume
+- [Arpeggio] - pitch in half-steps
+- [Duty] - duty cycle and noise mode for NES channels. _Note:_ This has no effect on Sega Master System.
+- [Panning] - output for left and right channels
+- [Pitch] - fine pitch
+- [Phase Reset] - trigger restart of waveform

doc/4-instrument/tia.md

@@ -1,7 +1,8 @@
 # Atari TIA instrument editor
 
-TIA instrument editor consists of only three macros:
+TIA instrument editor consists of these macros:
 
 - [Volume] - volume sequence
 - [Arpeggio] - pitch sequencr
 - [Waveform] - 1-bit polynomial pattern type sequence
+- [Pitch] - "fine" pitch

doc/4-instrument/vera.md

@@ -1,8 +1,10 @@
 # VERA instrument editor
 
-VERA instrument editor consists of only four macros:
+VERA instrument editor consists of these macros:
 
 - [Volume] - volume sequence
 - [Arpeggio] - pitch sequence
-- [Duty cycle] - pulse duty cycle sequence
+- [Duty] - pulse duty cycle sequence
 - [Waveform] - select the waveform used by instrument
+- [Panning] - output for left and right channels
+- [Pitch] - fine pitch

doc/4-instrument/vrc6.md

@@ -1,10 +1,11 @@
 # VRC6 instrument editor
 
-The VRC6 (regular) instrument editor consists of only three macros:
+The VRC6 (regular) instrument editor consists of these macros:
 
 - [Volume] - volume sequence
 - [Arpeggio] - pitch sequence
-- [Duty cycle] - specifies duty cycle for pulse wave channels
+- [Duty] - specifies duty cycle for pulse wave channels
+- [Pitch] - fine pitch
 
 ## VRC6 (saw) instrument editor