Merge pull request #1254 from ElectricKeet/doc-general

Expanded wavetable info.

doc/4-instrument/scc.md

@@ -4,5 +4,5 @@ The SCC/Bubble System WSG instrument editor consists of these macros:
 
 - **Volume**: volume sequence
 - **Arpeggio**: pitch sequence
-- **Waveform**: spicifies wavetables sequence
+- **Waveform**: specifies wavetable sequence
 - **Pitch**: fine pitch

doc/5-wave/README.md

@@ -1,23 +1,122 @@
+# wavetables
+
+Wavetable synthesizers, in context of Furnace, are sound sources that operate on extremely short n-bit PCM streams. By extremely short, no more than 256 bytes. This amount of space is nowhere near enough to store an actual sampled sound, it allows certain amount of freedom to define a waveform shape.
+
+Maximum wave width (length) is 256 bytes, and maximum wave height (depth) is 256 steps.
+
+Each chip has its own maximum size, shown in the following table. If a larger wave is defined for these chips, it will be squashed to fit within the constraints of the chips. Some hardware doesn't work well with the wavetable synthesizer (described below); these systems are marked in the "synth?" column.
+
+system              | width | height | synth?
+--------------------|------:|:-------|:-----:
+Bubble System       |    32 | 16     | 
+Game Boy            |    32 | 16     | 
+Game.com            |    32 | 16     | 
+Namco WSG           |    32 | 16     | 
+WonderSwan          |    32 | 16     | 
+Namco N163          |  ≤128 | 16     | 
+Super Nintendo      |  ≤256 | 16     | 
+PC Engine           |    32 | 32     | 
+Virtual Boy         |    32 | 64     | no
+Famicom Disk System |    64 | 64     | 
+Konami SCC          |    32 | 256    | 
+Seta X1-010         |   128 | 256    | 
+
+
 # wavetable editor
 
-Wavetable synthesizers, in context of Furnace, are sound sources that operate on extremely short n-bit PCM streams. By extremely short, no more than 256 bytes. This amount of space is nowhere near enough to store an actual sampled sound, it allows certain amount of freedom to define a waveform shape. As of Furnace 0.6pre4, wavetable editor affects PC Engine, WonderSwan, Namco WSGs, Virtual Boy, Game.com, SCC, FDS, Seta X1-010, Konami Bubble System WSG, SNES, Amiga and channel 3 of Game Boy.
+![wavetable editor](wave-editor.png)
 
-Furnace's wavetable editor is rather simple, you can draw the waveform using mouse or by pasting an MML bit stream in the input field. Maximum wave width (length) is 256 bytes, and maximum wave height (depth) is 256. NOTE: Game Boy, PCE, WonderSwan, Namco WSG, N163, Game.com, Virtual Boy and Bubble System can handle max 32 byte waveforms, X1-010 can handle max 128 byte waveforms as of now, with 16-level height for GB, X1-010 Envelope, WS, Bubble System, SNES, Namco WSG and N163, 32-level height for PCE and 64-level height for Virtual Boy. If a larger wave is defined for these chips, it will be squashed to fit within the constraints of the chips.
+controls across the top line:
+- waveform number. the `-` and `+` buttons step through the list.
+- open.
+- save.
+- **Steps**: view waveform as discrete blocks.
+- **Lines**: view waveform as a continuous line.
+- **Width**: length of the waveform data. maximum is 256.
+- **Height**: depth of the waveform. maximum is 256.
+- `<` / `>`: toggle tabs (described below).
 
-Furnace's wavetable editor features multiple ways of creating desired waveform shape:
+waveform display:
+- the waveform is directly editable with the mouse.
+- hovering will display a tooltip with the waveform position and value.
 
-- **Shape** tab allows you to select a few predefined basic shapes and indirectly edit it via "Duty", "Exponent" and "XOR Point" sliders:
-  - **Duty**: Affects mainly pulse waves, determining its wisth, like on C64/VRC6
-  - **Exponent**: Powers the waveform in the mathematical sense of the word (^2, ^3 and so on)
-  - **XOR Point**: Determines the point where the waveform gets negated.
-  - _TODO:_ amplitude/phase part
-- **FM** for creating the waveform with frequency modulation synthesis principles: One can set carrier/modulation levels, frquency multiplier, connection between operators and FM waveforms of these operators.
-- **WaveTools**: Allows user to fine-tune the waveform: scale said waveform in both X and Y axes, smoothen, amplify, normalize, convert to signed/unisgned, invert or even randomize the wavetable.
+controls across the bottom line:
+- **Dec**: view MML stream as decimal.
+- **Hex**: view MML stream as hexadecimal.
+- `+` / `±`: toggle MML stream as unsigned/signed. also adjusts waveform display.
+- MML stream: waveform data as an editable numeric sequence.
 
-## wavetable synthesizer
+## tabs
 
-Furnace contains a mode for wavetable instruments that allows you to modulate or combine 1 or 2 waves to create unique "animated" sounds. Think of it like a VST or a plugin, as it's basically an extension of regular wavetable soundchips that still allow it to run on real hardware.
+each tab provides different ways of creating or altering a waveform.
+
+### Shapes
+
+![wavetable shape tab](wave-editor-shapes.png)
+
+this creates a waveform by adding together a few predefined basic wave shapes.
+- shape: select shape from sine, triangle, saw, and square.
+- **Duty**: only affects pulse waves, determining their width
+- **Exponent**: applies an exponent (power) to the waveform (^2, ^3 and so on).
+- **XOR Point**: determines the point where the waveform gets negated.
+- **Amplitude/Phase**: add together up to 16 instances of the shape.
+  - **Amplitude**: height of the shape.
+  - **Phase**: position along the shape. for example, 0.250 starts the shape a quarter of the way along.
+
+### FM
+
+![wavetable FM tab](wave-editor-FM.png)
+
+this creates a waveform using frequency modulation synthesis with up to four operators.
+
+one can set carrier/modulation levels, frequency multipliers, connections between operators and FM waveforms of these operators.
+
+### WaveTools
+
+![wavetable tools tab](wave-editor-tools.png)
+
+these are useful editing tools to fine-tune the waveform:
+- **Scale X**: stretches the waveform to a new length.
+- interpolation method: filters the waveform when stretching. choose from none, linear, cosine, and cubic interpolation.
+- **Scale Y**: resizes the waveform to a new height. it will clip at the top and bottom.
+- **Offset X**: slides the the waveform forward or back. it will wrap around.
+- **Offset Y**: slides the waveform up or down. it will clip at the top and bottom.
+- **Smooth**. smooths waveform.
+- **Amplify**. changes the volume of the waveform. it will clip at the top and bottom.
+- **Normalize**: stretches waveform to maximum within the wavetable height.
+- **Invert**: flips waveform vertically.
+- **Half**: halves the waveform's frequency by stretching its first half to fill the waveform length.
+- **Double**: doubles the waveform's frequency by squashing it to half length then repeating it.
+- **Convert Signed/Unsigned**. worth trying if an imported wave sounds corrupted.
+- **Randomize**: generate a completely random waveform.
+
+
+
+# wavetable synthesizer
+
+Within the "Wavetable" tab of the instrument editor, Furnace allows you to modulate or combine 1 or 2 waves to create unique "animated" sounds. Think of it like a VST or a plugin, as it's basically an extension of regular wavetable soundchips that still allow it to run on real hardware.
 
 This is accomplished by selecting a wave or two, a mode, and adjusting the settings as needed until you come up with a sound that you like, without taking up a load of space. This allows you to create unique sound effects or instruments, that, when used well, almost sound like they're Amiga samples.
 
-Unfortunately, on chips like the HuC6280, you cannot use the wavetable synth to animate waveforms and have them sound smooth, as the chip resets the channel's phase when a waveform is changed while the channel is playing. On certain frequencies, this can be avoided, but not on most, unfortunately.
+Unfortunately, on some chips like the HuC6280, you cannot use the wavetable synth to animate waveforms and have them sound smooth, as the chip resets the channel's phase when a waveform is changed while the channel is playing. On certain frequencies, this can be avoided, but not on most, unfortunately.
+
+![instrument wavetable tab](instrument-wavetable.png)
+
+input waveforms should match the size of the wavetable or unexpected results may occur.
+
+- **Enable synthesizer**: must be on for the rest of this to work.
+- synthesizer type: selects the synthesis algorithm.
+- waveform displays.
+- **Wave 1**: selects input waveform.
+- **Wave 2**: selects second input waveform. only appears when a dual-waveform synthesizer is selected.
+- **Pause preview**: toggles live waveform preview.
+- **Restart preview**: restarts preview from initial state.
+- **Copy to new wavetable**: copies the currently displayed output waveform into the wavetable as a new entry.
+- (width×height): size of wavetable.
+- **Update Rate**: time in ticks between waveform changes.
+- **Speed**: rate of change with each update.
+- **Amount**: strength of synthesizer function.
+- **Power**: only appears when synthesizer type is "Phase Modulation".
+- **Global**:
+  - if disabled, each note resets the synthesizer to the start.
+  - if enabled, synthesis continues unbroken from note to note.

doc/7-systems/nes.md

@@ -83,45 +83,6 @@ reference: [NESdev](https://www.nesdev.org/wiki/APU_Noise)
 
 ## length counter table
 
-<!-- organized by input value... of little use -->
-<!--
-value | raw | NTSC  | PAL   | Dendy | NTSC 5-step | PAL 5-step | Dendy 5-step
------:|----:|------:|------:|------:|------------:|-----------:|-------------:
- `00` |  10 | 83ms  | 100ms | 84ms  | 104ms       | 125ms      | 105ms
- `01` | 254 | 2.1s  | 2.5s  | 2.1s  | 2.6s        | 3.2s       | 2.7s
- `02` |  20 | 166ms | 200ms | 168ms | 208ms       | 250ms      | 210ms
- `03` |   2 | 17ms  | 20ms  | 17ms  | 21ms        | 25ms       | 21ms
- `04` |  40 | 333ms | 400ms | 336ms | 417ms       | 500ms      | 421ms
- `05` |   4 | 33ms  | 40ms  | 34ms  | 42ms        | 50ms       | 42ms
- `06` |  80 | 667ms | 800ms | 673ms | 833ms       | 1.0s       | 841ms
- `07` |   6 | 50ms  | 60ms  | 50ms  | 63ms        | 75ms       | 63ms
- `08` | 160 | 1.3s  | 1.6s  | 1.3s  | 1.7s        | 2.0s       | 1.7s
- `09` |   8 | 67ms  | 80ms  | 67ms  | 83ms        | 100ms      | 84ms
- `0A` |  60 | 500ms | 600ms | 505ms | 625ms       | 750ms      | 631ms
- `0B` |  10 | 83ms  | 100ms | 84ms  | 104ms       | 125ms      | 105ms
- `0C` |  14 | 117ms | 140ms | 118ms | 146ms       | 175ms      | 147ms
- `0D` |  12 | 100ms | 120ms | 101ms | 125ms       | 150ms      | 126ms
- `0E` |  26 | 217ms | 260ms | 219ms | 271ms       | 325ms      | 273ms
- `0F` |  14 | 117ms | 140ms | 118ms | 145ms       | 175ms      | 147ms
- `10` |  12 | 100ms | 120ms | 101ms | 125ms       | 150ms      | 126ms
- `11` |  16 | 133ms | 160ms | 135ms | 167ms       | 200ms      | 168ms
- `12` |  24 | 200ms | 240ms | 202ms | 250ms       | 300ms      | 252ms
- `13` |  18 | 150ms | 180ms | 151ms | 188ms       | 225ms      | 189ms
- `14` |  48 | 400ms | 480ms | 404ms | 500ms       | 600ms      | 505ms
- `15` |  20 | 167ms | 200ms | 168ms | 208ms       | 250ms      | 210ms
- `16` |  96 | 800ms | 960ms | 807ms | 1.0s        | 1.2s       | 1.0s
- `17` |  22 | 183ms | 220ms | 185ms | 229ms       | 275ms      | 231ms
- `18` | 192 | 1.6s  | 1.9s  | 1.6s  | 2.0s        | 2.4s       | 2.0s
- `19` |  24 | 200ms | 240ms | 202ms | 250ms       | 300ms      | 252ms
- `1A` |  72 | 600ms | 720ms | 606ms | 750ms       | 900ms      | 757ms
- `1B` |  26 | 217ms | 260ms | 219ms | 271ms       | 325ms      | 273ms
- `1C` |  16 | 133ms | 160ms | 135ms | 167ms       | 200ms      | 168ms
- `1D` |  28 | 233ms | 280ms | 235ms | 292ms       | 350ms      | 294ms
- `1E` |  32 | 267ms | 320ms | 269ms | 333ms       | 400ms      | 336ms
- `1F` |  30 | 250ms | 300ms | 252ms | 313ms       | 375ms      | 315ms
--->
-
-<!-- organized by resulting times... more useful! -->
 value | raw | NTSC  | PAL   | Dendy | NTSC 5-step | PAL 5-step | Dendy 5-step
 -----:|----:|------:|------:|------:|------------:|-----------:|-------------:
  `03` |   2 | 17ms  | 20ms  | 17ms  | 21ms        | 25ms       | 21ms
@@ -161,21 +122,25 @@ reference: [NESdev](https://www.nesdev.org/wiki/APU_Length_Counter)
 
 ## DPCM frequency table
 
-value | NTSC      | PAL
-------|----------:|----------:
- `00` | 4181.7Hz  | 4177.4Hz
- `01` | 4709.9Hz  | 4696.6Hz
- `02` | 5264.0Hz  | 5261.4Hz
- `03` | 5593.0Hz  | 5579.2Hz
- `04` | 6257.9Hz  | 6023.9Hz
- `05` | 7046.3Hz  | 7044.9Hz
- `06` | 7919.3Hz  | 7917.2Hz
- `07` | 8363.4Hz  | 8397.0Hz
- `08` | 9419.9Hz  | 9446.6Hz
- `09` | 11186.1Hz | 11233.8Hz
- `0A` | 12604.0Hz | 12595.5Hz
- `0B` | 13982.6Hz | 14089.9Hz
- `0C` | 16884.6Hz | 16965.4Hz
- `0D` | 21306.8Hz | 21315.5Hz
- `0E` | 24858.0Hz | 25191.0Hz
- `0F` | 33143.9Hz | 33252.1Hz
+"value" is for DefleMask compatability.
+
+value | tracker | NTSC freq | NTSC pitch |  PAL freq | PAL pitch  
+-----:|:-------:|----------:|:----------:|----------:|:----------:
+ `00` |  `C-3`  |  4181.7Hz | C-8  -  2¢ |  4177.4Hz | C-8  -  4¢
+ `01` |  `D-3`  |  4709.9Hz | D-8  +  4¢ |  4696.6Hz | D-8  -  1¢
+ `02` |  `E-3`  |  5264.0Hz | E-8  -  3¢ |  5261.4Hz | E-8  -  4¢
+ `03` |  `F-3`  |  5593.0Hz | F-8  +  2¢ |  5579.2Hz | F-8  -  3¢
+ `04` |  `G-3`  |  6258.0Hz | G-8  -  4¢ |  6023.9Hz | G-8  - 70¢
+ `05` |  `A-3`  |  7046.4Hz | A-8  +  2¢ |  7044.9Hz | A-8  +  1¢
+ `06` |  `B-3`  |  7919.4Hz | B-8  +  4¢ |  7917.2Hz | B-8  +  3¢
+ `07` |  `C-4`  |  8363.4Hz | C-9  -  2¢ |  8397.0Hz | C-9  +  5¢
+ `08` |  `D-4`  |  9419.9Hz | D-9  +  4¢ |  9446.6Hz | D-9  +  9¢
+ `09` |  `F-4`  | 11186.1Hz | F-9  +  2¢ | 11233.8Hz | F-9  +  9¢
+ `0A` |  `G-4`  | 12604.0Hz | G-9  +  8¢ | 12595.5Hz | G-9  +  7¢
+ `0B` |  `A-4`  | 13982.6Hz | A-9  - 12¢ | 14089.9Hz | A-9  +  1¢
+ `0C` |  `C-5`  | 16884.6Hz | C-10 + 15¢ | 16965.4Hz | C-10 + 23¢
+ `0D` |  `E-5`  | 21306.8Hz | E-10 + 17¢ | 21315.5Hz | E-10 + 18¢
+ `0E` |  `G-5`  | 24858.0Hz | G-10 - 16¢ | 25191.0Hz | G-10 +  7¢
+ `0F` |  `C-6`  | 33143.9Hz | C-11 - 18¢ | 33252.1Hz | C-11 - 12¢
+
+reference: [NESdev](https://www.nesdev.org/wiki/APU_DMC#Pitch_table)