Merge pull request #1156 from ElectricKeet/master

Document macros, update instrument macro listings.

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
-- [Waveform] - selector of sound type - pulse wave tone, noise or envelope generator
-- [Duty cycle] - duty cycle of a pulse wave sequence
+- [Volume] - volume sequence
+- [Arpeggio]- pitch in half-steps
+- [Noise Freq] - AY8930 noise generator frequency sequence
+- [Waveform] - selector of sound type: pulse wave tone, noise or envelope generator
+- [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 divided 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 parameters.
 
-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 with 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 or release point. Right-click to remove the loop.
+- Shift-click to set the release point. When played, the macro will hold here until the note is released. Right-click to remove the release point.
+
+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)
+
+- **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 value moves toward Bottom after the note is released.
+
+![macro ADSR chart](macro-ADSRchart.png)
+
+### 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:
+The 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.
+The 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,12 +1,13 @@
 # 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)
-- [Sustain] - Determines the diminishing time for the sound. The higher the value, the longer the decay. This is the long "tail" of the sound that continues as long as the key is depressed. (0-15 range)
+- [Sustain] - Sets the volume level at which the sound stops decaying and holds steady. (0-15 range)
 - [Release] - Determines the rate at which the sound disappears after KEY-OFF. The higher the value, the longer the release. (0-15 range)
 - [Ring Modulation] - enables the ring modulation affecting the instrument.
 - [Duty] - specifies the width of a pulse wave. (0-4095 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 definable.
+- [Don't test/gate before new note] - Don't reset the envelope to zero when a new note starts. (Read "Test/Gate" below for more info.)
 
 ## 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] - When on, the TEST bit resets and locks Oscillator 1 at zero until cleared. The GATE bit controls Oscillator 1's envelope: Gate on runs through the envelope's attack, delay, and sustain; Gate off is envelope release.

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, start at a lower volume!
+
+- [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

@@ -1,23 +1,30 @@
 # Namco 163 instrument editor
 
-Namco 163 instrument editor consists of two tabs: one controlling various parameters for waveform initialize and macro tab containing 10 macros.
+The Namco 163 instrument editor consists of two tabs: "Namco 163" for control of various waveform parameters, and "Macro" containing several 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:
+The 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:
+The 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:
+The 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:
+The 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
 

doc/8-advanced/channels.md

@@ -0,0 +1,11 @@
+# channels
+
+The "Channels" dialog allows manipulation of the song's channels.
+
+![channels dialog](channels.png)
+
+Each channel has the following options:
+- "Visible": uncheck the box to hide the channel from view. Pattern data will be kept.
+- Crossed-arrows button: Click and drag to rearrange pattern data throughout the song. _Note:_ This does **not** move channels around within a chip! It only affects pattern data.
+- "Name" is the name displayed at the top of each channel in the tracker view.
+- To the right of that is the abbreviation used above each channel in the order view.

doc/8-advanced/chanosc.md

@@ -0,0 +1,16 @@
+# oscilloscope (per channel)
+
+The "Oscilloscope (per channel)" dialog shows an individual oscilloscope for each channel during playback.
+
+![oscilloscope per-channel configuration view](chanosc.png)
+
+Right-clicking within the view will change it to the configuration view shown above:
+- "Columns" sets the number of columns the view will be split into.
+- "Size (ms)" sets what length of audio is visible in each oscilloscope.
+- "Center waveform" does its best to latch to the channel's note frequency and centers the display.
+- "Gradient" is presently unimplemented.
+- The color selector allows setting the waveform color. Right-clicking on it pops up an option dialog:
+  - Select between the square selector and the color wheel selector.
+  - "Alpha bar" adds a transparency selector.
+- The boxes below that are for selecting colors numerically by red-green-blue-alpha, hue-saturation-value-alpha, and HTML-style RGBA in hex.
+- The OK button returns from options view to regular.

doc/8-advanced/chip-manager.md

@@ -0,0 +1,15 @@
+# chip manager
+
+The **chip manager** window does exactly what it says.
+
+![chip manager](chip-manager.png)
+
+"Preserve channel order" will make existing pattern data stay in place even when chips are rearranged. If turned off, pattern data will rearrange to match (the default, and usually the desired behavior).
+
+To move a chip around, click and drag the ![crossed-arrows](chip-manager-move.png) button to its left.
+
+To replace a chip with a different one, click the ![down-angle](chip-manager-change.png) and select the replacement.
+
+To remove a chip entirely, click the ![X](chip-manager-remove.png) button.
+
+Click a chip's name to open its options, where one can set clock rate, chip variant, and other specifics.

doc/8-advanced/clock.md

@@ -0,0 +1,10 @@
+# clock
+
+![clock dialog](clock.png)
+
+The clock shows the current playback position relative to the start of the song:
+
+- order : row
+- measure : beat (as defined by row highlight settings)
+- beat
+- elapsed time in minutes:seconds.hundredths

doc/8-advanced/comments.md

@@ -0,0 +1,8 @@
+# comments
+
+![comments dialog](comments.png)
+
+Comments, credits, or any arbitrary text may be entered here.
+It has no effect on the song.
+
+There is no word wrap; long lines must be broken manually with the Enter key.

doc/8-advanced/compat-flags.md

@@ -0,0 +1,5 @@
+# compatibility flags
+
+The "Compatibility Flags" window contains several tabs full of settings that change aspects of tracking and playback. A new Furnace file will leave them all at their defaults (off), while opening a DefleMask, Amiga MOD, or earlier Furnace file will automatically set the appropriate options.
+
+Hovering over most options will bring up additional info about them. It's not recommended to change any of these without clear reason. _There be dragons here._

doc/8-advanced/log-viewer.md

@@ -0,0 +1,17 @@
+# log viewer
+
+The log viewer provides a look at Furnace's internal messages. This can be useful for chasing down problems.
+
+![log viewer dialog](log-viewer.png)
+
+If the "Follow" checkbox is enabled, the log will snap to the bottom and continually scroll to show the newest messages. If disabled, it will stay put on what's currently shown.
+
+The "Level" dropdown determines the minimum importance of the messages displayed.
+
+| level | message shown |
+|---|---|
+| ERROR | serious problem |
+| warning | may or may not be a problem |
+| info | significant information |
+| debug | general info about what Furnace is doing |
+| trace | detailed info useful only to developers |

doc/8-advanced/mixer.md

@@ -0,0 +1,25 @@
+# mixer
+
+The "Mixer" dialog provides options for overall sound mixing.
+
+## "Mixer" tab
+
+![mixer dialog on mixer tab](mixer-mixer.png)
+
+"Master Volume" controls the overall mix.
+
+Each chip has several options:
+- "Invert" flips the output wave.
+- "Volume" controls the chip's volume relative to other chips.
+- "Panning" is for left-right control.
+- "Front/Rear" does as it says, is only useful for setups with four or more speakers.
+
+## "Patchbay" tab
+
+![mixer dialog on patchbay tab](mixer-patchbay.png)
+
+- "Automatic patchbay" will make appropriate connections when adding, removing, or changing chips and chip settings.
+- "Display hidden ports" shows all available connection ports. The "System" unit actually has 16 ports; 1 maps to the left channel, and 2 maps to the right.
+- "Display internal" shows two additional units, one for sample previews and one for the metronome sound.
+
+The graph shows each existing unit along with their outputs, inputs, and the "patch cables" connecting them. Connections can be made by dragging between an output and an input. Right-clicking on a unit gives the option to disconnect all patches from that unit.

doc/8-advanced/osc.md

@@ -0,0 +1,9 @@
+# oscilloscope
+
+The Oscilloscope shows the waveform of the mix of all currently playing sounds.
+
+![oscilloscope view](osc.png)
+
+Right-clicking on the oscilloscope toggles the adjustment sliders:
+- waveform height zoom
+- width of viewed audio (window size) in milliseconds.

doc/8-advanced/pat-manager.md

@@ -0,0 +1,22 @@
+# pattern manager
+
+The pattern manager is useful for cleaning up stray patterns and as an overview of pattern usage.
+
+![pattern manager dialog](pattern-manager.png)
+
+"De-duplicate patterns" looks for matching patterns, eliminates all but the first instance, and changes all references in the order list to match.
+
+"Re-arrange patterns" renumbers patterns to be in sequence, along with changing all references in the order list to match.
+
+The pattern grid shows each channel and all its patterns. These are color-coded to show how much they're used in the song; these colors can be changed in Settings.
+
+| default color | name in Settings | meaning |
+| --- | --- | --- |
+| grey | Unallocated | pattern doesn't exist yet |
+| red | Unused | exists but isn't in order list |
+| green | Used | used only once in order list |
+| yellow | Overused | used multiple times |
+| orange | Really overused | used in half or more orders |
+| magenta | Combo Breaker | the only used pattern in this channel! |
+
+Right-clicking a pattern will permanently delete it.

doc/8-advanced/piano.md

@@ -0,0 +1,38 @@
+# piano / input pad
+
+The piano serves as a non-keyboard interface to input notes.
+
+![piano chart](piano.png)
+
+The buttons at the left do the following:
+
+|  |  |  |
+| :---: | :---: | :---: |
+| move one octave down | move one octave up | open options |
+| fewer visible octaves | more visible octaves | swap buttons |
+
+When swapped, the bottons do the following:
+
+|  |  |  |
+| :---: | :---: | :---: |
+| input note off | input note release | open options |
+| input macro release | delete | swap buttons |
+
+Every C key is labelled with its octave.
+
+Right-clicking on the piano keys will make the buttons disappear; right-clicking again brings them back.
+
+## options
+
+Key layout:
+- [Automatic]
+- [Standard]: Black keys are 2/3 length.
+- [Continuous]: Black keys are full length.
+
+Value input pad: (document this)
+- [Disabled]
+- [Replace piano]
+- [Split (automatic)]
+- [Split (always visible)]
+
+[Share play/edit offset/range]: (document this)

doc/8-advanced/regview.md

@@ -0,0 +1,5 @@
+# register view
+
+During playback, "Register View" shows the hex data involved with each chip's operation.
+
+![register view dialog](register.png)

doc/8-advanced/stats.md

@@ -0,0 +1,5 @@
+# statistics
+
+The Statistics dialog shows running stats such as overall audio processing load and per-chip sample memory.
+
+![statistics dialog](stats.png)