Merge branch 'master' of https://github.com/tildearrow/furnace into command-palette

.github/issue_template.md

@@ -1 +1,39 @@
-<!-- NOTICE: if you are going to write a suggestion, see the Discussions section instead. any suggestions posted in Issues will be closed. -->
+# IMPORTANT NOTICE
+
+1. this section is exclusively for ISSUES related to Furnace (bugs, major annoyances and others).
+2. this section is NOT for Suggestions, Questions, Showcase or any other Discussions that do not meet the criteria and definition of an ISSUE.
+  - see the Discussions section if you wish to submit these.
+3. check whether your issue has been reported already.
+  - go to the Issues section, and use the search bar that appears on top of the Issues list.
+4. include the following information:
+  - version of Furnace (help > about)
+  - operating system (and version)
+  - whether you have downloaded Furnace, or built it from source.
+5. provide these details if you believe the issue is operating system and/or computer-specific:
+  - CPU model
+    - Windows: go to Control Panel > System.
+    - macOS: go to the Apple menu and select About This Mac...
+    - Linux: use `lscpu` or `cat /proc/cpuinfo`.
+  - graphics card (and driver version)
+    - Windows: open `dxdiag` and observe the Render tab.
+    - macOS: go to the Apple menu and select About This Mac...
+      - this information is not always shown.
+      - this information is not necessary if you use an Apple silicon Mac.
+    - Linux: use `glxinfo | grep OpenGL`.
+6. if your issue is an abnormal program termination (a "Crash"), you must provide additional details:
+  - the furnace_crash.txt file that is created by Furnace after a Crash. this file is located in the following paths:
+    - Windows: `C:\Users\<username>\furnace_crash.txt`
+    - Linux/other: `/tmp/furnace_crash.txt`
+    - on macOS this file is not generated. you may retrieve information about the Crash by clicking on "Report..." or "Show Details" in the "quit unexpectedly" dialog that appears following the Crash.
+      - make sure to remove any personal information for privacy reasons.
+      - be sure to select "Don't Send" afterwards.
+  - the furnace.log file located in:
+    - Windows: `C:\Users\<username>\AppData\Roaming\furnace\furnace.log`
+    - macOS: `~/Library/Application Support/furnace/furnace.log`
+    - Linux: `~/.config/furnace/furnace.log`
+    - make sure to remove any personal information for privacy reasons.
+
+BY SUBMITTING A TICKET, YOU HEREBY AGREE TO COMPLY WITH THESE TERMS.
+FAILURE TO DO SO MAY RESULT IN YOUR TICKET BEING DECLARED VOID.
+
+***END OF NOTICE*** --- REMOVE THIS NOTICE AFTER READING!

.gitignore

@@ -26,3 +26,4 @@ CMakePresets.json
 extern/imgui_patched/examples/
 src/asm/68k/amigatest/*.bin
 src/asm/68k/amigatest/player
+res/binary_to_compressed_c

CMakeLists.txt

@@ -507,6 +507,8 @@ src/engine/platform/sound/d65modified.c
 
 src/engine/platform/sound/ted-sound.c
 
+src/engine/platform/sound/c140.c
+
 src/engine/platform/oplAInterface.cpp
 src/engine/platform/ym2608Interface.cpp
 src/engine/platform/ym2610Interface.cpp
@@ -599,6 +601,7 @@ src/engine/platform/sm8521.cpp
 src/engine/platform/pv1000.cpp
 src/engine/platform/k053260.cpp
 src/engine/platform/ted.cpp
+src/engine/platform/c140.cpp
 src/engine/platform/pcmdac.cpp
 src/engine/platform/dummy.cpp
 
@@ -646,6 +649,7 @@ src/gui/font_proggyClean.cpp
 src/gui/font_ptMono.cpp
 src/gui/font_unifont.cpp
 src/gui/font_icon.cpp
+src/gui/font_furicon.cpp
 src/gui/fonts.cpp
 
 src/gui/image_icon.cpp

doc/1-intro/README.md

@@ -21,3 +21,9 @@ it also has a flexible windowing system which you may move around and organize.
 see [2-interface](../2-interface/README.md) and [3-pattern](../3-pattern/README.md) for more information.
 
 once familiar with the tracker, look to [9-guides](../9-guides/README.md) for useful techniques.
+
+
+
+# links
+
+[Furnace Tutorials](https://youtube.com/playlist?list=PLCELB6AsTZUnwv0PC5AAGHjvg47F44YQ1): video tutorials created by Spinning Square Waves.

doc/2-interface/README.md

@@ -13,6 +13,7 @@ primary topics:
 - [play/edit controls](play-edit-controls.md)
 - [instrument/wavetable/sample list](asset-list.md)
 - [song information](song-info.md)
+- [effect list window](effect-list-window.md)
 - [pattern view](../3-pattern/README.md)
 - [instrument editor](../4-instrument/README.md)
 - [wavetable editor](../5-wave/README.md)

doc/2-interface/effect-list-window.md

@@ -0,0 +1,10 @@
+# effect list window
+
+(for more details about these effects, see [the effects page](../3-pattern/effects.md))
+
+![effect list window](effect-list.png)
+
+this window provides a list of the effects that are available.
+
+- **Chip at cursor**: the currently selected chip. the list only shows available effects for this chip.
+- menu button: opens a small list of effect categories. toggle each to change whether they're shown in the list.

doc/2-interface/settings.md

@@ -11,21 +11,19 @@ settings are saved when clicking the **OK** button at the bottom of the dialog.
 - **Render backend**
   - changing this may help with performace issues.
 - **Late render clear**
-- **Power-saving mode**
+- **Power-saving mode**: saves power by lowering the frame rate to 2fps when idle.
-  - saves power by lowering the frame rate to 2fps when idle.
   - may cause issues under Mesa drivers!
-- **Disable threaded input (restart after changing!)**
+- **Disable threaded input (restart after changing!)**: processes key presses for note preview on a separate thread (on supported platforms), which reduces latency.
-  - threaded input processes key presses for note preview on a separate thread (on supported platforms), which reduces latency.
   - however, crashes have been reported when threaded input is on. enable this option if that is the case.
 - **Enable event delay**
   - may cause issues with high-polling-rate mice when previewing notes.
 
 ### File
 
-- **Use system file picker**: use native OS file dialog instead of Furnace's.
+- **Use system file picker**: uses native OS file dialog instead of Furnace's.
-- **Number of recent files**
+- **Number of recent files**: number of files to show in the _open recent..._ menu.
 - **Compress when saving**
-  - use zlib to compress saved songs.
+  - uses zlib to compress saved songs.
 - **Save unused patterns**
 - **Use new pattern format when saving**
 - **Don't apply compatibility flags when loading .dmf**
@@ -39,11 +37,11 @@ settings are saved when clicking the **OK** button at the bottom of the dialog.
 
 - **Initial system**: the system of chips loaded on starting Furnace.
   - **Current system**: sets current chips as default.
-  - **Randomize**: set default to a random system.
+  - **Randomize**: sets default to a random system.
     - this will not choose a random system at each start.
   - **Reset to defaults**: sets default to "Sega Genesis/Mega Drive".
   - **Name**: name for the default system. may be set to any text.
-  - system configuration: same as in the [chip manager](../8-advanced/chip-manager.md) and [mixer](../8-advanced/mixer.md).
+  - **Configure:**: same as in the [chip manager](../8-advanced/chip-manager.md) and [mixer](../8-advanced/mixer.md).
 - **When creating new song**:
   - **Display system preset selector**
   - **Start with initial system**
@@ -70,12 +68,12 @@ settings are saved when clicking the **OK** button at the bottom of the dialog.
 
 ### Output
 
-- **Backend**: select SDL or JACK for audio output.
+- **Backend**: selects SDL or JACK for audio output.
   - only appears on Linux, or MacOS compiled with JACK support
 - **Driver**
 - **Device**: audio device for playback.
 - **Sample rate**
-- **Outputs**: select number of audio outputs created, up to 16.
+- **Outputs**: number of audio outputs created, up to 16.
   - only appears when Backend is JACK.
 - **Channels**: number of output channels to use.
 - **Buffer size**: size of buffer in both samples and milliseconds.
@@ -209,8 +207,7 @@ settings are saved when clicking the **OK** button at the bottom of the dialog.
   - **Export**: writes current layout to a .ini file.
   - **Reset**: resets layout to default.
 - **Allow docking editors**
-- **Remember window position**
+- **Remember window position**: remembers the window's last position on start-up.
-  - remembers the window's last position on start-up.
 - **Only allow window movement when clicking on title bar**
 - **Play/edit controls layout:**
   - **Classic**
@@ -236,7 +233,7 @@ settings are saved when clicking the **OK** button at the bottom of the dialog.
   - **No**
   - **Yes**
   - **Yes (while holding Ctrl only)**
-- **Toggle channel solo on:** select which interactions with a channel header will toggle solo for that channel.
+- **Toggle channel solo on:** selects which interactions with a channel header will toggle solo for that channel.
   - Right-click or double click
   - Right-click
   - Double-click
@@ -248,13 +245,15 @@ settings are saved when clicking the **OK** button at the bottom of the dialog.
 - **Pull delete affects entire channel row**
 - **Push value when overwriting instead of clearing it**: in the order list and pattern editors, typing into an already-filled value will shift digits instead of starting fresh.
   - if off: moving the cursor onto the value `A5` and typing a "B" results in `0B`.
-  - if on: with the cursor on the value `A5` and typing a "B" results in `5B`.
+  - if on: moving the cursor onto the value `A5` and typing a "B" results in `5B`.
 - **Effect input behavior:**
   - **Move down**
   - **Move to effect value (otherwise move down)**
   - **Move to effect value/next effect and wrap around**
 - **Delete effect value when deleting effect**
 - **Change current instrument when changing instrument column (absorb)**
+- **Remove instrument value when inserting note off/release**
+- **Remove volume value when inserting note off/release**
 
 
 ### Cursor movement
@@ -293,16 +292,17 @@ settings are saved when clicking the **OK** button at the bottom of the dialog.
 
 ### Scaling
 
-- **Automatic UI scaling factor**: automatically match the OS's UI scaling.
+- **Automatic UI scaling factor**: automatically matches the OS's UI scaling.
-- **UI scaling factor**: only if "Automatic UI scaling factor" is off.
+- **UI scaling factor**: only appears if "Automatic UI scaling factor" is off.
 - **Icon size**
 
 ### Text
 
-- **Main font**: if "Custom...", a file path selector will appear beneath.
+- **Main font**: overall interface font.\
-- **Size**
+  **Header font**: font for section headers.\
-- **Pattern font**: if "Custom...", a file path selector will appear beneath.
+  **Pattern font** font for the pattern view, the order list, and related.
-- **Size**
+  - if "Custom...", a file path selector will appear.
+  - **Size**: font size.
 - **Display Japanese characters**\
   **Display Chinese (Simplified) characters**\
   **Display Chinese (Traditional) characters**\
@@ -358,7 +358,7 @@ settings are saved when clicking the **OK** button at the bottom of the dialog.
 
 ### Channel
 
-- **Channel style:**
+- **Channel style:** sets the appearance of channel headers in pattern view.
   - **Classic**
   - **Line**
   - **Round**
@@ -391,9 +391,18 @@ settings are saved when clicking the **OK** button at the bottom of the dialog.
 
 ### Assets
 
-- **Unified instrument/wavetable/sample list**
+- **Unified instrument/wavetable/sample list**: combines all three types of assets into one list.
-- **Horizontal instrument list**
+  - the buttons act as appropriate to the currently selected asset or header.
+- **Horizontal instrument list**: when there are more instruments than there is room to display them...
+  - if on, scroll horizontally through multiple columns.
+  - if off, scroll vertically in one long column.
+- **Instrument list icon style:**
+  - **None**
+  - **Graphical icons**
+  - **Letter icons**
 - **Colorize instrument editor using instrument type**
+- **Display instrument type menu when adding instrument**
+  - if turned off, the menu can still be opened by right-clicking the add button.
 
 ### Macro Editor
 
@@ -428,11 +437,11 @@ settings are saved when clicking the **OK** button at the bottom of the dialog.
   - **Between Decay and Sustain Rate**
   - **After Release Rate**
 - **Use separate colors for carriers/modulators in FM editor**
-- **Unsigned FM detune values**
+- **Unsigned FM detune values**: uses the internal representation of detune values, such that detune amounts of -1, -2, and -3 are shown as 5, 6, and 7.
 
 ### Statistics
 
-- **Chip memory usage unit:**
+- **Chip memory usage unit:** unit for displaying memory usage in the Statistics window.
   - **Bytes**
   - **Kilobytes**
 
@@ -440,15 +449,20 @@ settings are saved when clicking the **OK** button at the bottom of the dialog.
 
 - **Rounded corners**
 - **Border**
-- **Fill entire window**
+- **Mono**: displays a single monaural waveform of all sound mixed together.
-- **Waveform goes out of bounds**
+  - if turned off, waves will be drawn on top of each other for each output channel. 
+  - all colors are configurable via _Settings > Color > Color scheme > Oscilloscope > Wave (non-mono)._
+- **Anti-aliased**: smoothes the lines of the waveform.
+  - slight performance cost and slightly buggy.
+- **Fill entire window**: removes the gap between the waveform and the edge of the window.
+- **Waveform goes out of bounds**: allows the waveform to draw past the top and bottom of the oscilloscope.
 
 ### Windows
 
 - **Rounded window corners**
 - **Rounded buttons**
 - **Rounded menu corners**
-- **Borders around widgets**
+- **Borders around widgets**: draws thin borders on buttons, checkboxes, text widgets, and the like.
 
 
 

doc/3-pattern/effects.md

@@ -14,7 +14,7 @@ however, effects are continuous, which means you only need to type it once and t
 - `F4xx`: **Fine volume slide down.** same as `0A0x` but 64× slower.
 - `F8xx`: **Single tick volume slide up.** adds `x` to volume on first tick only.
 - `F9xx`: **Single tick volume slide down.** subtracts `x` from volume on first tick only.
-
+  - ---
 - `07xy`: **Tremolo.** changes volume to be "wavy" with a sine LFO. `x` is the speed. `y` is the depth.
   - Tremolo is downward only.
   - Maximum tremolo depth is -60 volume steps.
@@ -26,16 +26,17 @@ however, effects are continuous, which means you only need to type it once and t
 - `02xx`: **Pitch slide down.**
 - `F1xx`: **Single tick pitch slide up.**
 - `F2xx`: **Single tick pitch slide down.**
-
+  - ---
-- `03xx`: **Portamento.** slides the current note's pitch to the specified note.  `x` is the slide speed.
+- `03xx`: **Portamento.** slides the currently playing note's pitch toward the new note. `x` is the slide speed.
-  - A note _must_ be present for this effect to work.
+  - a note _must_ be present with this effect for it to work.
+  - the effect stops automatically when it reaches the new note.
 - `E1xy`: **Note slide up.** `x` is the speed, while `y` is how many semitones to slide up.
 - `E2xy`: **Note slide down.** `x` is the speed, while `y` is how many semitones to slide down.
-
+  - ---
-- `EAxx`: **Toggle legato.** while on, notes instantly change the pitch of the currrently playing sound instead of starting it over.
+- `EAxx`: **Toggle legato.** while on, new notes instantly change the pitch of the currently playing sound instead of starting it over.
 - `00xy`: **Arpeggio.** after using this effect the channel will rapidly switch between semitone values of `note`, `note + x` and `note + y`.
 - `E0xx`: **Set arpeggio speed.** this sets the number of ticks between arpeggio values. default is 1.
-
+  - ---
 - `04xy`: **Vibrato.** changes pitch to be "wavy" with a sine LFO. `x` is the speed, while `y` is the depth.
   - Maximum vibrato depth is ±1 semitone.
 - `E3xx`: **Set vibrato direction.** `xx` may be one of the following:
@@ -54,7 +55,7 @@ not all chips support these effects.
 - `82xx`: **Set volume of right channel** (from `00` to `FF`).
 - `89xx`: **Set volume of rear left channel** (from `00` to `FF`).
 - `8Axx`: **Set volume of rear right channel** (from `00` to `FF`).
-
+  - ---
 - `80xx`: **Set panning (linear).** this effect behaves more like other trackers:
   - `00` is left.
   - `80` is center.
@@ -64,15 +65,15 @@ not all chips support these effects.
 
 - `09xx`: **Set speed/groove.** if no grooves are defined, this sets speed. If alternating speeds are active, this sets the first speed.
 - `0Fxx`: **Set speed 2.** during alternating speeds or a groove, this sets the second speed.
-
+  - ---
 - `Cxxx`: **Set tick rate.** changes tick rate to `xxx` Hz (ticks per second).
   - `xxx` may be from `000` to `3FF`.
 - `F0xx`: **Set BPM.** changes tick rate according to beats per minute. range is `01` to `FF`.
-
+  - ---
 - `0Bxx`: **Jump to order.** `x` is the order to play after the current row.
   - this marks the end of a loop with order `x` as the loop start.
-- `0Dxx`: **Jump to next pattern.** skips the current row and remainder of current order.
+- `0Dxx`: **Jump to next pattern.** skips the current row and remainder of current order. `x` is the row at which to start playing the next pattern.
-  - this can be used to shorten the current order.
+  - this can be used to shorten the current order as though it had a different pattern length.
 - `FFxx`: **Stop song.** stops playback and ends the song. `x` is ignored.
 
 ## note
@@ -86,12 +87,12 @@ not all chips support these effects.
 
 - `9xxx`: **Set sample position.** jumps current sample to position `xxx * 0x100`.
   - Not all chips support this effect.
-- `EBxx`: **Set sample bank.**
+- `EBxx`: **Set LEGACY sample mode bank.** selects sample bank. used only for compatibility.
-  - Does not apply on Amiga.
+  - does not apply on Amiga.
 - `EExx`: **Send external command.**
-  - This effect is currently incomplete.
+  - this effect is currently incomplete.
-- `F5xx`: **Disable macro.** see macro table at the end of this document for possible values.
+- `F5xx`: **Disable macro.**\
-- `F6xx`: **Enable macro.**
+  `F6xx`: **Enable macro.** see macro table at the end of this document for possible values.
 
 additionally, [each chip has its own effects](../7-systems/README.md).
 

doc/4-instrument/README.md

@@ -15,7 +15,7 @@ depending on the instrument type, there are many different types of instrument e
 - [SAA1099](saa.md) - for use with Philips SAA1099 PSG sound source.
 - [TIA](tia.md) - for use with Atari 2600 chip.
 - [AY-3-8910](ay8910.md) - for use with AY-3-8910 PSG sound source and SSG portion in YM2610.
-- [Amiga / sample](amiga.md) for controlling Amiga and other sample based synthsizers like YM2612's Channel 6 PCM mode, NES channel 5, Sega PCM, X1-010 and PC Engine's sample playback mode.
+- [Generic Sample](amiga.md) for controlling Amiga and other sample channels/chips like YM2612's Channel 6 PCM mode, NES channel 5, Sega PCM, X1-010 and PC Engine's sample playback mode.
 - [Atari Lynx](lynx.md) - for use with Atari Lynx handheld console.
 - [VERA](vera.md) - for use with Commander X16 VERA.
 - [Seta/Allumer X1-010](x1_010.md) - for use with Wavetable portion in Seta/Allumer X1-010.
@@ -24,6 +24,7 @@ depending on the instrument type, there are many different types of instrument e
 - [Konami VRC6](vrc6.md) - for use with VRC6's PSG sound source.
 - [SNES](snes.md) - for use with SNES S-APU.
 - [Casio PV-1000](pv1000.md) - for use with Casio PV-1000.
+- [C140](c140.md) for use with Namco C140.
 
 
 # macros

doc/4-instrument/amiga.md

@@ -1,17 +1,18 @@
 # Amiga/PCM sound source instrument editor
 
-The PCM instrument editor consists of a sample selector and several macros:
+The Generic Sample instrument editor consists of a sample selector and several macros:
 
-# Amiga/sample
+# Sample
 
 - **Initial sample**: specifies which sample should be assigned to the instrument, or the first one in the sequence
+- **Use sample map**: enables mapping different samples to notes.
 
 # Macros
 
-- **Volume**: volume sequence. _warning:_ it works only on Amiga system, as of version 0.5.5!
+- **Volume**: volume sequence. does not apply to some chips.
-- **Arpeggio**: pitch sequence
+- **Arpeggio**: pitch sequence.
-- **Waveform**: sample sequence
+- **Waveform**: waveform sequence.
-- **Panning (left)**: output level for left channel
+- **Panning (left)**: output level for left channel.
-- **Panning (right)**: output level for right channel
+- **Panning (right)**: output level for right channel.
-- **Pitch**: fine pitch
+- **Pitch**: fine pitch.
-- **Phase Reset**: trigger restart of waveform
+- **Phase Reset**: trigger restart of waveform.

doc/4-instrument/c140.md

@@ -0,0 +1,17 @@
+# Namco C140 instrument editor
+
+the Namco C140 instrument editor consists of a sample selector and several macros:
+
+# Sample
+
+- **Initial sample**: specifies which sample should be assigned to the instrument, or the first one in the sequence.
+- **Use sample map**: enables mapping different samples to notes.
+
+# Macros
+
+- **Volume**: volume sequence.
+- **Arpeggio**: pitch sequence.
+- **Panning (left)**: output level for left channel.
+- **Panning (right)**: output level for right channel.
+- **Pitch**: fine pitch.
+- **Phase Reset**: trigger restart of sample.

doc/4-instrument/fmopl.md

@@ -0,0 +1,70 @@
+# OPL FM synthesis instrument editor
+
+The OPL FM editor is divided into 7 tabs:
+
+- **FM**: for controlling the basic parameters of FM sound source.
+- **Macros (FM)**: for macros controlling algorithm and feedback
+- **Macros (OP1)**: for macros controlling FM parameters of operator 1
+- **Macros (OP2)**: for macros controlling FM parameters of operator 2
+- **Macros (OP3)**: for macros controlling FM parameters of operator 3 (Warning: only when 4-op flag is set, only on OPL3!)
+- **Macros (OP4)**: for macros controlling FM parameters of operator 4 (Warning: only when 4-op flag is set, only on OPL3!)
+- **Macros**: for miscellaneous macros controlling volume, arpeggio, and YMF262 panning.
+
+## FM
+
+The OPL synthesizers are nominally two-operator (OPL3 supports limited 4-operator mode), meaning it takes two oscillators to produce a single sound.
+
+These apply to the instrument as a whole:
+- **Feedback (FB)**: Determines how many times operator 1 returns its output to itself. (0-7 range)
+- **Algorithm (AL)**: Determines how operators are connected to each other. (0-1 range and OPL1 and OPL2, 0-3 range on OPL3 4op mode)
+  - Left-click pops up a small "operators changes with volume?" dialog where each operator can be toggled to scale with volume level.
+  - Right-click to switch 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.
+
+- **4-op**: Enables 4-operator FM instrument editor mode (ONLY ON OPL3)
+- **Drums**: Enables OPL drum mode editor
+
+These apply to each operator:
+- The crossed-arrows button can be dragged to rearrange operators.
+- The **OP1**, **OP2**, **OP3**, and **OP4** buttons enable or disable those operators.
+- **Amplitude Modulation (AM)**: Makes the operator affected by LFO tremolo.
+- **Sustain flag (SUS)**: When enabled, value of Sustain Level is in effect.
+- **Attack Rate (AR)**: determines the rising time for the sound. The bigger the value, the faster the attack. (0-15 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-315 range)
+- **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-15 range)
+- **Release Rate (RR)**: Determines the rate at which the sound disappears after KEY-OFF. The higher the value, the shorter the release. (0-15 range)
+- **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.
+
+![FM ADSR chart](FM-ADSRchart.png)
+
+- **Envelope Scale (KSR)**: Also known as "Key Scale". Determines the degree to which the envelope execution speed increases according to the pitch.
+- **Frequency Multiplier (MULT)**: Determines the operator frequency in relation to the pitch. (0-10, 12, 15 range)
+- **Waveform select (WS)**: Changes the waveform generated by oscillator (OPL2 and OPL3 only, 0-7 range)
+- **Pitch Modulation (VIB)**: Makes the operator affected by LFO vibrato.
+
+## macros
+
+Macros define the sequence of values passed to the given parameter. Via macro, along with the previously mentioned parameters, the following can be controlled:
+
+## FM Macros
+
+All parameters are listed above.
+
+## OP1-OP4 Macros
+
+All parameters are listed above.
+
+## Macros
+
+- **Arpeggio**: Pitch change sequence in semitones.
+- **Panning**: toggles output on left and right channels. (OPL3 only!)
+- **Pitch**: fine pitch.
+  - **Relative**: pitch changes are relative to the current pitch, not the note's base pitch.
+- **Phase Reset**: Restarts all operators and resets the waveform to its start. Effectively the same as a `0Cxx` retrigger.
+
+
+# links
+
+[FM instrument tutorial](https://www.youtube.com/watch?v=wS8edjurjDw): A great starting point to learn how create and work with FM sounds. This was made for DefleMask, but all the same principles apply.

doc/4-instrument/fmopll.md

@@ -0,0 +1,63 @@
+# OPLL FM synthesis instrument editor
+
+The OPLL FM editor is divided into 5 tabs:
+
+- **FM**: for controlling the basic parameters of FM sound source.
+- **Macros (FM)**: for macros controlling algorithm, waveform and feedback
+- **Macros (OP1)**: for macros controlling FM parameters of operator 1
+- **Macros (OP2)**: for macros controlling FM parameters of operator 2
+- **Macros**: for miscellaneous macros controlling volume, arpeggio, and preset.
+
+## FM
+
+The OPLL synthesizer is two-operator, meaning it takes two oscillators to produce a single sound.
+
+These apply to the instrument as a whole:
+- **Feedback (FB)**: Determines how many times operator 1 returns its output to itself. (0-7 range)
+- **Sustain (SUS)**: enables the sustain flag (sets the release rate to 5) 
+- **DC (half-sine carrier)**: Sets the waveform produced by carrier operator to half-sine
+- **DM (half-sine modulator)**: Sets the waveform produced by modulator operator to half-sine
+
+To the right, there is a drop down menu for OPLL preset instrument selection.
+
+These apply to each operator:
+- The crossed-arrows button can be dragged to rearrange operators.
+- The **OP1**, **OP2** buttons enable or disable those operators.
+- **Amplitude Modulation (AM)**: Makes the operator affected by LFO tremolo.
+- **Envelope generator sustain flag (EGS)**: When enabled, value of Sustain Level is in effect.
+- **Attack Rate (AR)**: determines the rising time for the sound. The bigger the value, the faster the attack. (0-15 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-15 range)
+- **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-15 range)
+- **Release Rate (RR)**: Determines the rate at which the sound disappears after KEY-OFF. The higher the value, the shorter the release. (0-15 range)
+- **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.
+
+![FM ADSR chart](FM-ADSRchart.png)
+
+- **Envelope Scale (KSR)**: Also known as "Key Scale". Determines the degree to which the envelope execution speed increases according to the pitch.
+- **Frequency Multiplier (MULT)**: Determines the operator frequency in relation to the pitch. (0-10, 12, 15 range)
+- **Pitch Modulation (VIB)**: Makes the operator affected by LFO vibrato.
+
+## macros
+
+Macros define the sequence of values passed to the given parameter. Via macro, along with the previously mentioned parameters, the following can be controlled:
+
+## FM Macros
+
+All parameters are listed above.
+
+## OP1-OP4 Macros
+
+All parameters are listed above.
+
+## Macros
+
+- **Arpeggio**: Pitch change sequence in semitones.
+- **Patch**: changes the playing preset mid-note
+- **Pitch**: fine pitch.
+  - **Relative**: pitch changes are relative to the current pitch, not the note's base pitch.
+- **Phase Reset**: Restarts all operators and resets the waveform to its start. Effectively the same as a `0Cxx` retrigger.
+
+
+# links
+
+[FM instrument tutorial](https://www.youtube.com/watch?v=wS8edjurjDw): A great starting point to learn how create and work with FM sounds. This was made for DefleMask, but all the same principles apply.

doc/4-instrument/psg.md

@@ -1,6 +1,6 @@
-# PSG instrument editor
+# Sega PSG instrument editor
 
-The instrument editor for PSG (SMS, MSX, and other TI SN76489 derivatives) consists of these macros:
+The instrument editor for Sega PSG (SMS, and other TI SN76489 derivatives) consists of these macros:
 
 - **Volume**: volume.
 - **Arpeggio**: pitch in half-steps.

doc/4-instrument/saa.md

@@ -9,4 +9,12 @@ The SAA1099 instrument editor consists of these macros:
 - **Panning (left)**: output level for left channel
 - **Panning (right)**: output level for right channel
 - **Pitch**: fine pitch
-- **Envelope**: envelope generator shape
+- **Envelope**: envelope generator settings:
+  enable: enables the envelope generator
+  N/A: has no effect
+  fixed: toggles whether to use a fixed frequency or lock to the frequency of channel 2 or 5
+  resolution: increases the envelope generator pitch resolution
+  direction: inverts the waveform around Y axis
+  cut: cuts the waveform (producing saw wave out of tri wave)
+  loop: toggles wheteher evelope is one-off or constantly looping
+  mirror: sets whether the right output will mirror the left one

doc/6-sample/README.md

@@ -33,15 +33,15 @@ the following sound chips have sample support:
 - Yamaha PCMD8/YMZ280B
 - MMC5 (last channel only)
 
-## compatible sample mode
+## compatible sample mode (LEGACY)
 
-effect `17xx` enables/disables compatible sample mode whether supported (e.g. on Sega Genesis or PC Engine).
+**use of this mode is discouraged in favor of Sample type instruments.**
+
+effect `17xx` enables/disables compatible sample mode where supported (e.g. on Sega Genesis or PC Engine).
 
 in this mode, samples are mapped to notes in an octave from C to B, allowing you to use up to 12 samples.
 if you need to use more samples, you may change the sample bank using effect `EBxx`.
 
-use of this mode is discouraged in favor of Sample type instruments.
-
 ## notes
 
 due to limitations in some of those sound chips, some restrictions exist:

doc/7-systems/README.md

@@ -1,56 +1,123 @@
-# sound chips
+# systems
 
-this is a list of sound chips that Furnace supports, including effects.
+this is a list of some of the systems that Furnace supports, as shown in the new file dialog. each chip links to a page with information and a list of supported effects.
 
+some systems have alternate chips, such as the Sega Genesis having a YM2612, a YM3438, or YMF276 depending on the model. this list shows the default configuration.
+
+- **Sega Genesis**: [YM3438](ym2612.md), [SN76489](sms.md)
+- **Sega Genesis (with Sega CD)**: [YM3438](ym2612.md), [SN76489](sms.md), [RF5C164](ricoh.md)
+<!-- -->
+- **Sega Master System**: [SN76489](sms.md)
+- **Sega Master System (with FM expansion)**: [SN76489](sms.md), [YM2413](opll.md)
+<!-- -->
+- **NES**: [2A03](nes.md)
+- **Famicom with Konami VRC6**: [2A03](nes.md), [VRC6](vrc6.md)
+- **Famicom with Konami VRC7**: [2A03](nes.md), [VRC7](opl.md)
+- **Famicom with MMC5**: [2A03](nes.md), [MMC5](mmc5.md)
+- **Famicom with Sunsoft 5B**: [2A03](nes.md), [5B](ay8910.md)
+- **Famicom with Namco 163**: [2A03](nes.md), [N163](n163.md)
+- **Famicom Disk System**: [2A03](nes.md), [FDS](fds.md)
+<!-- -->
+- **Game Boy**: [Game Boy](game-boy.md)
+<!-- -->
+- **SNES**: [SNES](snes.md)
+<!-- -->
+- **NEC PC Engine/TurboGrafx-16**: [HuC6280](pce.md)
+<!-- -->
+- **Commodore VIC-20**: [VIC](vic20.md)
+<!-- -->
+- **Commodore 64 (6581 SID)**: [MOS 6581](c64.md)
+- **Commodore 64 (8580 SID)**: [MOS 8580](c64.md)
+<!-- -->
+- **Amiga**: [Amiga](amiga.md)
+<!-- -->
+- **Arcade (YM2151 and SegaPCM)**: [YM2151](ym2152.md), [SegaPCM](segapcm.md)
+<!-- -->
+- **Capcom CPS-1**: [YM2151](ym2152.md), [MSM6295](msm6295.md)
+- **Capcom CPS-2 (QSound)**: [QSound](qsound.md)
+<!-- -->
+- **Neo Geo CD**: [YM2610](ym2610.md)
+- **Neo Geo CD (extended channel 2)**: [YM2610](ym2610.md)
+<!-- -->
+- **Neo Geo Pocket**: [T6W28](t6w28.md), [DAC](dac.md)
+<!-- -->
+- **Atari 2600/7800**: [TIA](tia.md)
+- **Atari 800**: [POKEY](pokey.md)
+<!-- -->
+- **Konami Bubble System**: [AY-3-8910](ay8910.md) × 2, [Konami WSG](bubblesystem.md)
+<!-- -->
+- **Sharp X68000**: [YM2151](ym2152.md), [MSM6258](msm6258.md)
+<!-- -->
+- **PC + Sound Blaster Pro**: [YM3812](opl.md) × 2, [DAC](dac.md), [PC Speaker](pcspkr.md)
+<!-- -->
+- **MSX**: [AY-3-8910](ay8910.md)
+- **MSX + SCC**: [YM2149(F)](ay8910.md), [SCC](scc.md)
+<!-- -->
+- **Commander X16 (VERA only)**: [VERA](vera.md)
+<!-- -->
+- and many, many more!
+
+
+
+# chips
+
+this is the full list of chips that Furnace supports.
+
+- [2A03](nes.md)
 - [Amiga](amiga.md)
-- [AY-3-8910](ay8910.md)
+- [AY-3-8910/8914/YM2149(F)/Sunsoft 5B](ay8910.md)
-- [Microchip AY8930](ay8930.md)
+- [Microship AY8930](ay8930.md)
-- [Bubble System WSG](bubblesystem.md)
+- [MOS 6581/8580 (SID)](c64.md)
-- [Casio PV-1000](pv1000.md)
+- [Ensoniq ES5506](es5506.md)
-- [Commodore 64](c64.md)
-- [Commodore PET](pet.md)
-- [Commodore VIC-20](vic20.md)
-- [Generic PCM DAC](dac.md)
-- [Famicom Disk System](fds.md)
-- [Game Boy](game-boy.md)
-- [Konami K007232](k007232.md)
-- [Konami K056320](k056320.md)
 - [Konami SCC](scc.md)
-- [Konami VRC6](vrc6.md)
+- [FDS](fds.md)
-- [Atari Lynx](lynx.md)
+- [Game Boy](game-boy.md)
+- [Generic PCM DAC](dac.md)
+- [Irem GA20](ga20.md)
+- [Bubble System WSG](bubblesystem.md)
+- [K007232](k007232.md)
+- [K053260](k056320.md)
+- [Lynx](lynx.md)
+- [MMC5](mmc5.md)
+- [MSM5232](msm5232.md)
+- [MSM6258](msm6258.md)
+- [MSM6295](msm6295.md)
 - [Namco 163](n163.md)
-- [Namco WSG](namco.md)
+- [Namco C140](c140.md)
-- [NES](nes.md)
+- [Namco WSG/C15/C30](namco.md)
-- [Nintendo MMC5](mmc5.md)
+- [HuC6280](pce.md)
-- [OKI MSM5232](msm5232.md)
-- [OKI MSM6258](msm6258.md)
-- [OKI MSM6295](msm6295.md)
-- [PC Engine/TurboGrafx-16](pce.md)
 - [PC Speaker](pcspkr.md)
-- [Philips SAA1099](saa1099.md)
+- [PET](pet.md)
-- [Pokémon mini](pokemini.md)
+- [Pokémon Mini](pokemini.md)
-- [Capcom QSound](qsound.md)
+- [POKEY](pokey.md)
-- [Ricoh RF5C68](ricoh.md)
+- [PV-1000](pv1000.md)
+- [QSound](qsound.md)
+- [RF5C68/RF5C164](ricoh.md)
+- [SAA1099](saa1099.md)
 - [SegaPCM](segapcm.md)
-- [Seta/Allumer X1-010](x1-010.md)
+- [SM8521](sm8521.md)
+- [SN76489/Sega PSG](sms.md)
 - [SNES](snes.md)
-- [Atari 2600 (TIA)](tia.md)
 - [tildearrow Sound Unit](soundunit.md)
-- [TI SN76489](sms.md)
+- [T6W28](t6w28.md)
-- [Toshiba T6W28](t6w28.md)
+- [TED](ted.md)
+- [TIA](tia.md)
 - [VERA](vera.md)
-- [WonderSwan](wonderswan.md)
+- [VIC](vic20.md)
 - [Virtual Boy](virtual-boy.md)
-- [Yamaha YM2413 (OPLL)](opll.md)
+- [VRC6](vrc6.md)
-- [Yamaha OPL](opl.md)
+- [WonderSwan](wonderswan.md)
-- [Yamaha YM2151](ym2151.md)
+- [X1-010](x1-010.md)
-- [Yamaha YM2203](ym2203.md)
+- [VRC7, Y8950, YM3526, YM3812 and YMF262 (OPL)](opl.md)
-- [Yamaha YM2414 (OPZ)](opz.md)
+- [YM2413 (OPLL)](opll.md)
-- [Yamaha YM2608](ym2608.md)
+- [YM2414 (OPZ)](opz.md)
-- [Neo Geo/YM2610](ym2610.md)
+- [YM2151 (OPM)](ym2152.md)
-- [Taito Arcade/YM2610B](ym2610b.md)
+- [YM2203 (OPN)](ym2203.md)
-- [Yamaha YM2612](ym2612.md)
+- [YM2608 (OPNA)](ym2608.md)
-- [Yamaha YMZ280B](ymz280b.md)
+- [YM2610 (OPNB)](ym2610.md)
+- [YM2610B (OPNB2)](ym2610b.md)
+- [YM2612/YM3438 (OPN2)](ym2612.md)
+- [YMZ280B](ymz280b.md)
 - [ZX Spectrum Beeper](zxbeep.md)
 
 Furnace also reads .dmf files with the [Yamaha YMU759](ymu759.md) system, but...

doc/7-systems/amiga.md

@@ -18,6 +18,8 @@ imported MOD files use this chip, and will set A-4 tuning to 436.
 
 # info
 
+this chip uses the [Generic Sample](../4-instrument/amiga.md) instrument editor.
+
 - the maximum rate for sample playback is technically 31469Hz but anything higher than 28867Hz will sound glitchy on hardware.
 - sample lengths and loop will be set to an even number.
 - samples can't be longer than 131070.

doc/7-systems/ay8910.md

@@ -47,7 +47,11 @@ as of Furnace 0.6pre7, AY-3-8910 supports software sample playback, where all 3
 - `2Fxx`: **write to I/O port B.**
   - this changes the port's mode to "write". make sure you have connected something to it.
 
-# chip config
+# info
+
+this chip uses the [AY-3-8910](../4-instrument/ay8910.md) instrument editor.
+
+
 ## AY derivative modes
 
 AY-3-810 was an absurdly popular chip that was blessed with many third-party clones, licensed or not.

doc/7-systems/ay8930.md

@@ -55,3 +55,7 @@ as of Furnace 0.6pre7, AY8930 supports software PCM, where all 3 channels can pl
   - `x` is the numerator.
   - `y` is the denominator.
   - if `x` or `y` are 0 this will disable auto-envelope mode.
+
+# info
+
+this chip uses the [AY8930](../4-instrument/8930.md) instrument editor.

doc/7-systems/bubblesystem.md

@@ -11,3 +11,7 @@ Furnace emulates this configuration as a "chip" with 32×16 wavetables.
 # effects
 
 - `10xx`: **change wave.**
+
+# info
+
+this chip uses the [Konami SCC/ Bubble System WSG](../4-instrument/scc.md) instrument editor.

doc/7-systems/c140.md

@@ -0,0 +1,19 @@
+# Namco C140
+
+Namco C140 is a 24-channel custom PCM sound chip manufactured jointly by Fujitsu and Namco. It was first used in Namco Sytem 2 arcade family starting in 1987.
+
+This chip features:
+
+- stereo soft panning
+- accepts either raw 12-bit PCM or proprietary 8-bit u-law compressed PCM samples
+- 21.4 kHz sampling rate
+
+# effects
+
+- `80xx`: set panning (`00: left, `80`: center, `FF`: right)
+- `81xx`: set left channel panning 
+- `82xx`: set right channel panning 
+
+# info
+
+this chip uses the [C140](../4-instrument/c140.md) instrument editor.

doc/7-systems/c64.md

@@ -57,3 +57,7 @@ two versions of aforementioned chip exist - 6581 (original chip) and 8580 (impro
     - `6`: disable channel 3 (`y` is `0` or `1`)
 - `3xxx`: **set duty cycle.** `xxx` range is `000` to `FFF`.
 - `4xxx`: **set cutoff.** `xxx` range is `000` to `7FF`.
+
+# info
+
+this chip uses the [C64](../4-instrument/c64.md) instrument editor.

doc/7-systems/dac.md

@@ -7,3 +7,7 @@ with it, you can emulate PCM DACs found in Williams arcade boards, Sound Blaster
 # effects
 
 none yet.
+
+# info
+
+this chip uses the [Generic Sample](../4-instrument/amiga.md) instrument editor.

doc/7-systems/es5506.md

@@ -39,3 +39,7 @@ it supports a whopping 32 channels of 16-bit PCM and:
 - `8Axx`: **set panning (rear right channel).**
 - `9xxx`: **set sample offset.** resets sample position to `xxx * 0x100`.
 - `DFxx`: **set sample playback direction.**
+
+# info
+
+this chip uses the [ES5506](../4-instrument/es5506.md) instrument editor.

doc/7-systems/fds.md

@@ -25,3 +25,7 @@ it also offers an additional 6-bit, 64-byte wavetable sound channel with (somewh
     - 6: -2
     - 7: -1
   - why is this mapping so unnatural? because that's how DefleMask does it (yeah, as you may have guessed this effect is mostly for compatibility reasons)...
+
+# info
+
+this chip uses the [FDS](../4-instrument/fds.md) instrument editor.

doc/7-systems/ga20.md

@@ -0,0 +1,8 @@
+# Irem GA20
+
+ga20 is a 4 channel PCM sound source used by Irem in their arcades in late 1980s and eraly 1990s, often paired with [Yamaha YM2151](ym2151.md). Soundchip itself is rather unremarkable, having 8-bit volume and pitch control, no stereo panning
+
+
+# effects
+
+none

doc/7-systems/game-boy.md

@@ -21,6 +21,11 @@ with stereo sound, two pulse channels, a wave channel and a noise channel, it pa
   - set to `0` to disable it.
 - `14xx`: **set sweep direction.** `0` is up and `1` is down.
 
+# info
+
+this chip uses the [Game Boy](../4-instrument/game-boy.md) instrument editor.
+
+
 # links
 
 - [Gameboy sound hardware](https://gbdev.gg8.se/wiki/articles/Gameboy_sound_hardware) - detailed technical information

doc/7-systems/k007232.md

@@ -9,3 +9,7 @@ it has 7 bit digital output per each channel and no volume register on chip, so
 # effects
 
 - nothing for now.
+
+# info
+
+this chip uses the [K007232](../4-instrument/k007232.md) instrument editor.

doc/7-systems/k056320.md

@@ -1,9 +1,13 @@
 # Konami 056320
 
-the 056320 is a sample-based chip that featured in a number of Konami arcade games, notably _Sunset Riders_ and _Teenage Mutant Ninja Turtles: Turtles in Time_. it has four channels of audio and stereo output, and can access up to 2MB of samples in 8-bit PCM or 4-bit ADPCM formats.
+the 056320 is a sample-based chip that featured in a number of Konami arcade games, notably _Sunset Riders_ and _Teenage Mutant Ninja Turtles: Turtles in Time_. it has four channels of audio, 12-bit pitch resolution and stereo output, and can access up to 2MB of samples in 8-bit PCM or 4-bit ADPCM formats.
 
 
 
 # effects
 
 - `DFxx`: Set sample playback direction. `0` is normal; `1` is reverse.
+
+# info
+
+this chip uses the [C140](../4-instrument/c140.md) instrument editor.

doc/7-systems/lynx.md

@@ -17,3 +17,7 @@ the Atari Lynx has a 6502-based CPU with a sound part (this chip is known as MIK
 
 - `3xxx`: **load LFSR.** this is a bitmask with values ranging from `000` to `FFF`.
   - for it to work, duty macro in instrument editor must be set to some value. without it LFSR will not be fed with any bits.
+
+# info
+
+this chip uses the [Atari Lynx](../4-instrument/lynx.md) instrument editor.

doc/7-systems/mmc5.md

@@ -10,3 +10,7 @@ additionally, it offers an 8-bit DAC which can be used to play samples. only one
 
 - `12xx`: **set duty cycle or noise mode of channel.**
   - may be `0` through `3` for the pulse channels.
+
+# info
+
+this chip uses the [NES](../4-instrument/nes.md) and [Generic Sample](../4-instrument/amiga.md) instrument editors.

doc/7-systems/msm5232.md

@@ -24,3 +24,7 @@ Furnace implements this chip in a way that allows the following features:
   - only in internal (capacitor-based) envelope mode.
 - `13xx`: **set group decay.** range is `0` to `11`.
   - only in internal (capacitor-based) envelope mode.
+
+# info
+
+this chip uses the [MSM5232](../4-instrument/msm5232.md) instrument editor.

doc/7-systems/msm6258.md

@@ -18,3 +18,7 @@ MSM6258 is an extremely basic ADPCM sound codec. it has no variable frequency ra
 | 4.096 MHz          | 8000 Hz       |
 | 8 MHz              | 15625 Hz      |
 | 8.192 MHz          | 16000 Hz      |
+
+# info
+
+this chip uses the [MSM6258](../4-instrument/msm6258.md) and [Generic Sample](../4-instrument/amiga.md) instrument editors.

doc/7-systems/msm6295.md

@@ -6,9 +6,15 @@ an upgrade from 6258 - it provides 4 ADPCM channels, at max 32 KHz (still no var
 
 - `20xx`: **set chip output rate.**
   
-# chip config
+
+# info
+
+this chip uses the [MSM6295](../4-instrument/msm6295.md) and [Generic Sample](../4-instrument/amiga.md) instrument editors.
+
+
 ## chip clock rates
-like MSM6258, MSM295 is an extremely basic ADPCM sound codec. it has no variable frequency rate, it depends on clock rate of a chip itself. Furnace supports following rates:
+
+like MSM6258, MSM6295 is an extremely basic ADPCM sound codec. it has no variable frequency rate, it depends on clock rate of a chip itself. Furnace supports following rates:
 
 | clock rate         | sampling rate |
 |--------------------|---------------|

doc/7-systems/n163.md

@@ -38,3 +38,7 @@ if the waveform changes (e.g. ins change, wave macro or wave synth), or the **lo
   - the length is determined by the wave's width (it will be snapped to a multiple of 4 if it isn't).
   - make sure to use `21xx` first!
 - `21xx`: **set position for 20xx.**
+
+# info
+
+this chip uses the [Namco 163](../4-instrument/n163.md) instrument editor.

doc/7-systems/namco.md

@@ -8,3 +8,7 @@ everything starts with Namco WSG, which is a simple 3-channel wavetable with no
 
 - `10xx`: **change waveform.**
 - `11xx`: **toggle noise mode.** _warning:_ only on C30.
+
+# info
+
+this chip uses the [Namco WSG](../4-instrument/namco.md) instrument editor.

doc/7-systems/nes.md

@@ -56,7 +56,11 @@ also known as Famicom. it is a five-channel sound generator: first two channels
   - only works in DPCM mode.
   - see table below for possible values.
 
-# tables
+
+# info
+
+this chip uses the [NES](../4-instrument/nes.md) and [Generic Sample](../4-instrument/amiga.md) instrument editors.
+
 
 ## short noise frequencies (NTSC)
 

doc/7-systems/opl.md

@@ -78,3 +78,7 @@ afterwards everyone moved to Windows and software mixed PCM streaming...
 - `5Bxy`: **set KSR of operator.**
   - `x` is the operator from 1 to 4; the last 2 operators only work in 4-op mode. a value of `0` means "all operators".
   - `y` determines whether KSR is on.
+
+# info
+
+this chip uses the [FM (OPL)](../4-instrument/fm-opl.md) instrument editor.

doc/7-systems/opll.md

@@ -65,3 +65,7 @@ the YM2413 is equipped with the following features:
 - `5Bxy`: **set KSR of operator.**
   - `x` is the operator, either 1 or 2. a value of `0` means "all operators".
   - `y` determines whether KSR is on.
+
+# info
+
+this chip uses the [FM (OPLL)](../4-instrument/fm-opll.md) instrument editor.

doc/7-systems/opz.md

@@ -113,3 +113,7 @@ no plans have been made for TX81Z MIDI passthrough, because:
 - `5Dxx`: **set D2R/SR of operator 2.**
 - `5Exx`: **set D2R/SR of operator 3.**
 - `5Fxx`: **set D2R/SR of operator 4.**
+
+# info
+
+this chip uses the [FM (OPZ)](../4-instrument/opz.md) instrument editor.

doc/7-systems/pce.md

@@ -18,5 +18,9 @@ furthermore, it has some PCM and LFO!
   - `03`: LFO enabled, shift 8.
   - when LFO is enabled, channel 2 is muted and its output is passed to channel 1's frequency.
 - `13xx`: **set LFO speed.**
-- `17xx`: **toggle PCM mode.**
+- `17xx`: **toggle LEGACY sample mode.**
-  - _this effect is here for compatibility reasons_; it is otherwise recommended to use Sample type instruments (which automatically enable PCM mode when used).
+  - **this effect exists only for compatibility reasons! its use is NOT recommented. use Sample type instruments instead.**
+
+# info
+
+this chip uses the [PC Engine](../4-instrument/pce.md) and [Generic Sample](../4-instrument/amiga.md) instrument editors.

doc/7-systems/pcspkr.md

@@ -29,3 +29,7 @@ oh, and of course you also need the beeper to be present in your machine. some l
 # effects
 
 ha! effects...
+
+# info
+
+this chip uses the [Beeper](../4-instrument/beeper.md) instrument editor.

doc/7-systems/pet.md

@@ -9,3 +9,7 @@ some of these didn't even have sound...
 # effects
 
 - `10xx`: **set waveform.** `xx` is a bitmask.
+
+# info
+
+this chip uses the [PET](../4-instrument/pet.md) instrument editor.

doc/7-systems/pokemini.md

@@ -5,3 +5,7 @@ the Pokémon Mini is a ridiculously small handheld system from 2001. its single
 # effects
 
 none.
+
+# info
+
+this chip uses the [Pokémon Mini/QuadTone](../4-instrument/quadtone.md) instrument editor.

doc/7-systems/pokey.md

@@ -35,3 +35,7 @@ a sound and input chip developed by Atari for their 8-bit computers (Atari 400,
 - `12xx`: **toggle two-tone mode.**
   - when enabled, channel 2 modulates channel 1. I don't know how, but it does.
   - only on ASAP core.
+
+# info
+
+this chip uses the [POKEY](../4-instrument/pokey.md) instrument editor.

doc/7-systems/pv1000.md

@@ -5,3 +5,7 @@ released only in Japan, this console was pulled after only a few weeks on the ma
 # effects
 
 - `10xx`: **set ring modulation.** amplitude modulation by the previous channel's output. `0` turns it off and `1` turns it on.
+
+# info
+
+this chip uses the [PV-1000](../4-instrument/pv1000.md) instrument editor.

doc/7-systems/qsound.md

@@ -17,3 +17,7 @@ there are also 3 ADPCM channels. ADPCM samples are fixed to 8012 Hz.
 - `11xx`: **set echo level.**
 - `12xx`: **toggle QSound algorithm.** on by default.
 - `3xxx`: **set echo delay buffer length.**
+
+# info
+
+this chip uses the [QSound](../4-instrument/qsound.md) and [Generic Sample](../4-instrument/amiga.md) instrument editors.

doc/7-systems/ricoh.md

@@ -6,3 +6,6 @@ YM2612's sidekick - poor man's SNES DSP. 8-channel PCM sample-based synthesizer
 
 none so far.
 
+# info
+
+this chip uses the [RF5C68](../4-instrument/ricoh.md) and [Generic Sample](../4-instrument/amiga.md) instrument editors.

doc/7-systems/saa1099.md

@@ -27,3 +27,7 @@ this was used by the Game Blaster and SAM Coupé. it's pretty similar to the AY-
     - `111`: up loop (reverse saw)
   - bit 0 sets whether the right output will mirror the left one.
   - this effect affects either the first 3 or last 3 channels, depending on where it is placed.
+
+# info
+
+this chip uses the [SAA1099](../4-instrument/saa.md) instrument editor.

doc/7-systems/scc.md

@@ -9,3 +9,7 @@ the SCC+ fixes this issue though (while being compatible with SCC games).
 # effects
 
 - `10xx`: **change wave.**
+
+# info
+
+this chip uses the [Konami SCC/Bubble System WSG](../4-instrument/scc.md) instrument editor.

doc/7-systems/segapcm.md

@@ -15,3 +15,7 @@ Furnace also has a five channel version of this chip, but it only exists for Def
 - `20xx`: **set PCM frequency.**
   - `xx` is a 256th fraction of 31250Hz.
   - this effect exists mostly for DefleMask compatibility; it is otherwise recommended to use Sample type instruments.
+
+# info
+
+this chip uses the [SegaPCM](../4-instrument/segapcm.md) and [Generic Sample](../4-instrument/amiga.md) instrument editors.

doc/7-systems/sm8521.md

@@ -15,9 +15,13 @@ the sound-related features and quirks of the SM8521 are as follows:
 - a low bit-depth output (which means it distorts a lot). 
 - it phase resets when you switch waves
 - 12-bit pitch with a wide frequency range
-- a software-controlled D/A register that (potentially) requires all other registers to be stopped to play. due to this, it is currently, it is not implemented in Furnace as of version 0.6pre4.
+- a software-controlled D/A register that (potentially) requires all other registers to be stopped to play. due to this, it is currently not implemented in Furnace as of version 0.6pre4.
 
 ## effect commands
 
 - `10xx`: **set waveform.**
   - `xx` is a value between 0 and 255 that sets the waveform of the channel you place it on.
+
+# info
+
+this chip uses the [SM8521](../4-instrument/sm8521.md) instrument editor.

doc/7-systems/sms.md

@@ -1,4 +1,4 @@
-# TI SN76489 (e.g. sega Master System)
+# TI SN76489 (e.g. Sega Master System)
 
 a relatively simple sound chip made by Texas Instruments. a derivative of it is used in Sega's Master System, the predecessor to Genesis.
 
@@ -14,7 +14,12 @@ the original iteration of the SN76489 used in the TI-99/4A computer, the SN94624
     - `0`: thin pulse.
     - `1`: noise.
 
-# chip config
+
+# info
+
+this chip uses the [SN76489/Sega PSG](../4-instrument/psg.md) instrument editor.
+
+
 ## SN7 versions
 SN7 was extremely popular due to low cost. Therefore, it was cloned and copied to no end, often with minor differences between each other. Furnace supports several of these:
 - SN94624, can only produce tones as low as 100Hz, and is clocked at 447 KHz.

doc/7-systems/snes.md

@@ -67,7 +67,10 @@ Furnace also allows the SNES to use wavetables (and the wavetable synthesizer) i
   - _Note:_ Be sure the sum of all coefficients is between -128 and 127. sums outside that may result in overflow and therefore clicking.
   - see [SnesLab](https://sneslab.net/wiki/FIR_Filter) for a full explanation and examples.
 
-# tables
+# info
+
+this chip uses the [SNES](../4-instrument/snes.md) instrument editor.
+
 
 ## ADSR
 

doc/7-systems/soundunit.md

@@ -54,3 +54,7 @@ it has the following capabilities:
   - bit 0-6: speed
   - bit 7: up direction
 - `4xxx`: **set cutoff.** range is `0` to `FFF`.
+
+# info
+
+this chip uses the [Sound Unit](../4-instrument/soundunit.md) and [Generic Sample](../4-instrument/amiga.md) instrument editors.

doc/7-systems/t6w28.md

@@ -9,3 +9,7 @@ this chip was used in Neo Geo Pocket.
 - `20xx`: **set noise mode.**
   - `0`: thin pulse.
   - `1`: noise.
+
+# info
+
+this chip uses the [T6W28](../4-instrument/t6w28.md) instrument editor.

doc/7-systems/ted.md

@@ -8,3 +8,7 @@ pitch range is limited as well, akin to that of SN76489, and volume control is g
 # effects
 
 none so far.
+
+# info
+
+this chip uses the [TED](../4-instrument/ted.md) instrument editor.

doc/7-systems/tia.md

@@ -29,9 +29,12 @@ Furnace isn't complete without this one...
 
 
 
-# tables
+# info
 
-pitch number can be used for absolute notes in arpeggio macros.
+this chip uses the [TIA](../4-instrument/tia.md) instrument editor.
+
+
+- pitch number can be used for absolute notes in arpeggio macros.
 
 ## shape 1
 

doc/7-systems/vera.md

@@ -15,3 +15,7 @@ currently Furnace does not support the PCM channel's stereo mode, though (except
 - `22xx`: **set duty cycle.** range is `0` to `3F`.
 - `EExx`: **ZSM synchronization event.**
   - Where `xx` is the event payload. This has no effect in how the music is played in Furnace, but the ZSMKit library for the Commander X16 interprets these events inside ZSM files and optionally triggers a callback routine. This can be used, for instance, to cause game code to respond to beats or at certain points in the music.
+
+# info
+
+this chip uses the [VERA](../4-instrument/vera.md) and [Generic Sample](../4-instrument/amiga.md) instrument editors.

doc/7-systems/vic20.md

@@ -16,3 +16,7 @@ these channels are not referred as "square" wave channels since a technique to p
 ## effect commands
 
 - `10xx`: **switch waveform.** range is `00` to `0F`.
+
+# info
+
+this chip uses the [VIC](../4-instrument/vic.md) instrument editor.

doc/7-systems/virtual-boy.md

@@ -41,3 +41,7 @@ additionally, channel 5 offers a modulation/sweep unit. the former is similar to
 - `15xx`: **set modulation wave.**
   - `xx` points to a wavetable. range is `0` to `FF`.
   - this is an alternative to setting the modulation wave through the instrument.
+
+# info
+
+this chip uses the [Virtual Boy](../4-instrument/virtual-boy.md) instrument editor.

doc/7-systems/vrc6.md

@@ -15,4 +15,9 @@ Furnace supports this routine for PCM playback, but it consumes a lot of CPU tim
 these effects only are effective in the pulse channels.
 
 - `12xx`: **set duty cycle.** range is `0` to `7`.
-- `17xx`: **toggle PCM mode.**
+- `17xx`: **toggle LEGACY sample mode.**
+  - **this effect exists only for compatibility reasons! its use is NOT recommented. use Sample type instruments instead.**
+
+# info
+
+this chip uses the [VRC](../4-instrument/vrc6.md), [VRC (saw)](../4-instrument/vrc6.md), and [Generic Sample](../4-instrument/amiga.md) instrument editors.

doc/7-systems/wonderswan.md

@@ -19,3 +19,7 @@ it has 4 wavetable channels. some of them have additional capabilities:
   - 1-32: enable and set period.
 - `13xx`: **setup sweep amount.** channel 3 only.
 - `17xx`: **toggle PCM mode.** channel 2 only.
+
+# info
+
+this chip uses the [WonderSwan](../4-instrument/wonderswan.md) and [Generic Sample](../4-instrument/amiga.md) instrument editors.

doc/7-systems/x1-010.md

@@ -27,7 +27,8 @@ in Furnace, you can enable the envelope shape split mode. when it is set, its wa
 
 - `10xx`: **change wave.**
 - `11xx`: **change envelope shape.** also wavetable.
-- `17xx`: **toggle PCM mode.**
+- `17xx`: **toggle LEGACY sample mode.**
+  - **this effect exists only for compatibility reasons! its use is NOT recommented. use Sample type instruments instead.**
 - `20xx`: **set PCM frequency.** range is `1` to `FF`.
   - PCM frequency formula: `step * (clock / 8192)`.
   - range is 1.95KHz to 498KHz if the chip clock is 16MHz.
@@ -45,3 +46,7 @@ in Furnace, you can enable the envelope shape split mode. when it is set, its wa
   - `x` is the numerator.
   - `y` is the denominator.
   - if `x` or `y` are 0 this will disable auto-envelope mode.
+
+# info
+
+this chip uses the [X1-010](../4-instrument/x1_010.md) and [Generic Sample](../4-instrument/amiga.md) instrument editors.

doc/7-systems/ym2151.md

@@ -68,3 +68,7 @@ in most arcade boards the chip was used in combination with a PCM chip, like [Se
 - `5Dxx`: **set D2R/SR of operator 2.**
 - `5Exx`: **set D2R/SR of operator 3.**
 - `5Fxx`: **set D2R/SR of operator 4.**
+
+# info
+
+this chip uses the [FM (OPM)](../4-instrument/fm-opm.md) instrument editor.

doc/7-systems/ym2203.md

@@ -100,7 +100,12 @@ several variants of this chip were released as well, with more features.
 - `5Exx`: **set D2R/SR of operator 3.**
 - `5Fxx`: **set D2R/SR of operator 4.**
 
-# system modes
+
+# info
+
+this chip uses the [FM (OPN)](../4-instrument/fm-opn.md) and [AY-3-8910/SSG](../4-instrument/ay8910.md) instrument editor.
+
+
 ## extended channel 3
 in ExtCh mode, channel 3 is split into one column for each of its four operators and feedback are shared. the frequency of each operator may be controlled independently with notes and effects. this can be used for more polyphony or more complex sounds.
 

doc/7-systems/ym2608.md

@@ -100,7 +100,12 @@ the YM2610 (OPNB) and YM2610B chips are very similar to this one, but the built-
 - `5Exx`: **set D2R/SR of operator 3.**
 - `5Fxx`: **set D2R/SR of operator 4.**
   
-#  system modes
+
+# info
+
+this chip uses the [FM (OPN)](../4-instrument/fm-opn.md), [Generic Sample](../4-instrument/amiga.md), [AY-3-8910/SSG](../4-instrument/ay8910.md), [ADPCM-A](../4-instrument/adpcm-a.md), and [ADPCM-B](../4-instrument/adpcm-b.md) instrument editors.
+
+
 ## extended channel 3
 in ExtCh mode, channel 3 is split into one column for each of its four operators. feedback and LFO levels are shared. the frequency of each operator may be controlled independently with notes and effects. this can be used for more polyphony or more complex sounds.
 

doc/7-systems/ym2610.md

@@ -98,7 +98,11 @@ its soundchip is a 4-in-1: 4ch 4-op FM, YM2149 (AY-3-8910 clone) and [2 differen
 - `5Exx`: **set D2R/SR of operator 3.**
 - `5Fxx`: **set D2R/SR of operator 4.**
 
-# system modes
+# info
+
+this chip uses the [FM (OPN)](../4-instrument/fm-opn.md), [Generic Sample](../4-instrument/amiga.md), [AY-3-8910/SSG](../4-instrument/ay8910.md), [ADPCM-A](../4-instrument/adpcm-a.md), and [ADPCM-B](../4-instrument/adpcm-b.md) instrument editors.
+
+
 ## extended channel 2
 in ExtCh mode, channel 2 is split into one column for each of its four operators. feedback and LFO levels are shared. the frequency of each operator may be controlled independently with notes and effects. this can be used for more polyphony or more complex sounds.
 

doc/7-systems/ym2610b.md

@@ -97,8 +97,13 @@ it is backward compatible with the original chip.
 - `5Exx`: **set D2R/SR of operator 3.**
 - `5Fxx`: **set D2R/SR of operator 4.**
 
-# system modes
+# info
+
+this chip uses the [FM (OPN)](../4-instrument/fm-opn.md), [Generic Sample](../4-instrument/amiga.md), [AY-3-8910/SSG](../4-instrument/ay8910.md), [ADPCM-A](../4-instrument/adpcm-a.md), and [ADPCM-B](../4-instrument/adpcm-b.md) instrument editors.
+
+
 ## extended channel 3
+
 in ExtCh mode, channel 3 is split into one column for each of its four operators. feedback and LFO levels are shared. the frequency of each operator may be controlled independently with notes and effects. this can be used for more polyphony or more complex sounds.
 
 all four operators are still combined according to the algorithm in use. for example, algorithm 7 acts as four independent sine waves. algorithm 4 acts as two independent 2op sounds. even with algorithm 0, placing a note in any operator triggers that operator alone.

doc/7-systems/ym2612.md

@@ -16,8 +16,9 @@ as of Furnace 0.6pre5, Furnace offers DualPCM, a Z80 driver that splits channel
 - `16xy`: **set multiplier of operator.**
   - `x` is the operator (1-4).
   - `y` is the multiplier.
-- `17xx`: **enable PCM channel.**
+- `17xx`: **toggle LEGACY sample mode.**
   - this only works on channel 6.
+  - **this effect exists only for compatibility reasons! its use is NOT recommented. use Sample type instruments instead.**
 - `18xx`: **toggle extended channel 3 mode.**
   - 0 disables it and 1 enables it.
   - only in extended channel 3 chip.
@@ -66,3 +67,24 @@ as of Furnace 0.6pre5, Furnace offers DualPCM, a Z80 driver that splits channel
 - `5Dxx`: **set D2R/SR of operator 2.**
 - `5Exx`: **set D2R/SR of operator 3.**
 - `5Fxx`: **set D2R/SR of operator 4.**
+
+# info
+
+this chip uses the [FM (OPN)](../4-instrument/fm-opn.md) and [Generic Sample](../4-instrument/amiga.md) instrument editors.
+
+
+## extended channel 3
+
+in ExtCh mode, channel 3 is split into one column for each of its four operators. feedback and LFO levels are shared. the frequency of each operator may be controlled independently with notes and effects. this can be used for more polyphony or more complex sounds.
+
+all four operators are still combined according to the algorithm in use. for example, algorithm 7 acts as four independent sine waves. algorithm 4 acts as two independent 2op sounds. even with algorithm 0, placing a note in any operator triggers that operator alone.
+
+## CSM
+
+CSM is short for "Composite Sinusoidal Modeling". CSM works by sending key-on and key-off commands to channel 3 at a specific frequency, controlled by the added "CSM Timer" channel. this can be used to create vocal formants (speech synthesis!) or other complex effects.
+
+CSM is beyond the scope of this documentation. for more information, see this [brief SSG-EG and CSM video tutorial](https://www.youtube.com/watch?v=IKOR0TUlnWU).
+
+## DualPCM
+
+thanks to the Z80 sound CPU, DualPCM can play two samples at once! this mode splits channel 6 into two individual PCM channels with variable pitch. these are mixed together in software and streamed to channel 6 with a mix rate of 13750 Hz. VGM export requires the "direct stream mode" option to be enabled, and resulting files will be very large.

doc/7-systems/ymu759.md

@@ -15,3 +15,7 @@ even DefleMask dropped support for the chip in version 0.11, which just shows ho
 
 
 hey, at least it was the spark that ignited the idea of DefleMask.
+
+# info
+
+this chip uses the [FM (OPL)](../4-instrument/fm-opl.md) and [Generic Sample](../4-instrument/amiga.md) instrument editors.

doc/7-systems/ymz280b.md

@@ -7,3 +7,7 @@ it has 16-level stereo panning, up to 16-bit PCM and up to 16MB of external PCM
 # effects
 
 none so far.
+
+# info
+
+this chip uses the [YMZ280B](../4-instrument/ymz280b.md) and [Generic Sample](../4-instrument/amiga.md) instrument editors.

doc/7-systems/zxbeep.md

@@ -14,3 +14,7 @@ not really - very soon talented programmers found out ways to output much more t
   - `xx` is the sample number.
   - overlay drums are 1-bit and always play at 55930Hz (NTSC) or 55420Hz (PAL).
   - the maximum length is 2048!
+
+# info
+
+this chip uses the [Beeper](../4-instrument/beeper.md), [Generic Sample](../4-instrument/amiga.md), and [Pokémon Mini/QuadTone](../4-instrument/quadtone.md) instrument editors.

doc/8-advanced/chanosc.md

@@ -8,6 +8,11 @@ right-clicking within the view will change it to the configuration view shown ab
 - **Columns**: arranges oscilloscopes into this many columns.
 - **Size (ms)**: sets what length of audio is visible in each oscilloscope.
 - **Center waveform**: does its best to latch the waveform to the channel's note frequency and centers the display.
+- **Automatic columns**: sets the number of columns based on the number of channels.
+  - **Off**: use the Columns setting.
+  - **Mode 1**: always fewer columns than rows.
+  - **Mode 2**: bias slightly toward more columns.
+  - **Mode 3**: always more columns than rows.
 - **Amplitude**: scales amplitude for all oscilloscopes.
 - **Gradient**: see below.
 - the color selector sets the color for all waveforms. right-clicking on it pops up an option dialog:
@@ -19,6 +24,7 @@ right-clicking within the view will change it to the configuration view shown ab
   - `%C`: channel short name
   - `%d`: channel number (starting from 0)
   - `%D`: channel number (starting from 1)
+  - `%n`: channel note
   - `%i`: instrument name
   - `%I`: instrument number (decimal)
   - `%x`: instrument number (hex)

extern/igfd/ImGuiFileDialog.cpp

@@ -192,7 +192,7 @@ namespace IGFD
 #define OverWriteDialogTitleString "Warning"
 #endif // OverWriteDialogTitleString
 #ifndef OverWriteDialogMessageString
-#define OverWriteDialogMessageString "The file you selected already exists? Would you like to overwrite it?"
+#define OverWriteDialogMessageString "The file you selected already exists! Would you like to overwrite it?"
 #endif // OverWriteDialogMessageString
 #ifndef OverWriteDialogConfirmButtonString
 #define OverWriteDialogConfirmButtonString "Yes"
@@ -3814,6 +3814,66 @@ namespace IGFD
     return escape;
   }
 
+  int IGFD::FileDialog::isFileNameValid(const char* n) {
+#ifdef _WIN32
+    char lower[6];
+    int len=strlen(n);
+
+    for (int i=0; i<6; i++) {
+      lower[i]=0;
+    }
+
+    if (len>=3) {
+      if (len>5) len=5;
+      for (int i=0; i<len; i++) {
+        if (n[i]>='A' && n[i]<='Z') {
+          lower[i]=n[i]+('a'-'A');
+        } else {
+          lower[i]=n[i];
+        }
+      }
+      if ((memcmp(lower,"con",3)==0 ||
+           memcmp(lower,"prn",3)==0 ||
+           memcmp(lower,"aux",3)==0 ||
+           memcmp(lower,"nul",3)==0) &&
+          (len==3 || lower[3]=='.')) {
+        return 2;
+      }
+      if (len>=4) {
+        if ((memcmp(lower,"com",3) ||
+             memcmp(lower,"lpt",3)) &&
+            (lower[3]>='1' && lower[3]<='9') &&
+            (len==4 || lower[4]=='.')) {
+          return 2;
+        }
+      }
+    }
+#endif
+    for (const char* i=n; *i; i++) {
+#ifdef _WIN32
+      if (*i<32) {
+        return 3;
+      }
+#endif
+
+      switch (*i) {
+#ifdef _WIN32
+        case '<':
+        case '>':
+        case ':':
+        case '"':
+        case '\\':
+        case '|':
+        case '?':
+        case '*':
+#endif
+        case '/':
+          return 1;
+      }
+    }
+    return 0;
+  }
+
   bool IGFD::FileDialog::prDrawFooter()
   {
     auto& fdFile = prFileDialogInternal.puFileManager;
@@ -3844,16 +3904,44 @@ namespace IGFD
     bool res = false;
 
     // OK Button
-    if (prFileDialogInternal.puCanWeContinue && strlen(fdFile.puFileNameBuffer))
+    bool notEmpty=strlen(fdFile.puFileNameBuffer);
-    {
+    int fileValid=isFileNameValid(fdFile.puFileNameBuffer);
+    if (!(prFileDialogInternal.puDLGflags&ImGuiFileDialogFlags_ConfirmOverwrite)) fileValid=0;
+    ImGui::BeginDisabled(!(prFileDialogInternal.puCanWeContinue && notEmpty && fileValid==0));
     if (IMGUI_BUTTON(okButtonString "##validationdialog"))
     {
       prFileDialogInternal.puIsOk = true;
       res = true;
     }
+    if (!(prFileDialogInternal.puCanWeContinue && notEmpty && fileValid==0)) {
+      if (ImGui::IsItemHovered()) {
+        if (!notEmpty) {
+          if (prFileDialogInternal.puDLGflags&ImGuiFileDialogFlags_ConfirmOverwrite) {
+            ImGui::SetTooltip("file name is empty");
+          } else {
+            ImGui::SetTooltip("select a file");
+          }
+        } else if (!prFileDialogInternal.puCanWeContinue) {
+          ImGui::SetTooltip("we can't continue - this is most likely a bug!");
+        } else switch (fileValid) {
+          case 1:
+            ImGui::SetTooltip("invalid characters in file name\nmake sure there aren't any of these:\n  < > : \" / \\ | ? *");
+            break;
+          case 2:
+            ImGui::SetTooltip("this file name is reserved by the system");
+            break;
+          case 3:
+            ImGui::SetTooltip("non-printable characters in file name\nhow did you manage to type these?");
+            break;
+          default:
+            ImGui::SetTooltip("bug! how did you do this? please fill an issue report now...");
+            break;
+        }
+      }
+    }
+    ImGui::EndDisabled();
 
     ImGui::SameLine();
-    }
 
     // Cancel Button
     if (IMGUI_BUTTON(cancelButtonString "##validationdialog") || 

extern/igfd/ImGuiFileDialog.h

@@ -1261,6 +1261,11 @@ namespace IGFD
     bool IsOpened(const std::string& vKey) const;        // say if the key is opened
     bool IsOpened() const;                    // say if the dialog is opened somewhere
     std::string GetOpenedKey() const;              // return the dialog key who is opened, return nothing if not opened
+    // 0: valid
+    // 1: invalid chars
+    // 2: reserved name
+    // 3: non-printable chars
+    int isFileNameValid(const char* n);
 
     // get result
     bool IsOk() const;                      // true => Dialog Closed with Ok result / false : Dialog closed with cancel result

extern/imgui_patched/imconfig.h

@@ -97,7 +97,9 @@
 // Your renderer backend will need to support it (most example renderer backends support both 16/32-bit indices).
 // Another way to allow large meshes while keeping 16-bit indices is to handle ImDrawCmd::VtxOffset in your renderer.
 // Read about ImGuiBackendFlags_RendererHasVtxOffset for details.
-//#define ImDrawIdx unsigned int
+#ifndef IS_MOBILE
+#define ImDrawIdx unsigned int
+#endif
 
 //---- Override ImDrawCallback signature (will need to modify renderer backends accordingly)
 //struct ImDrawList;

extern/imgui_patched/imconfig_fur.h

@@ -96,7 +96,9 @@
 // Your renderer backend will need to support it (most example renderer backends support both 16/32-bit indices).
 // Another way to allow large meshes while keeping 16-bit indices is to handle ImDrawCmd::VtxOffset in your renderer.
 // Read about ImGuiBackendFlags_RendererHasVtxOffset for details.
-//#define ImDrawIdx unsigned int
+#ifndef IS_MOBILE
+#define ImDrawIdx unsigned int
+#endif
 
 //---- Override ImDrawCallback signature (will need to modify renderer backends accordingly)
 //struct ImDrawList;

extern/imgui_patched/imgui.cpp

@@ -9522,6 +9522,8 @@ void ImGui::UpdateInputEvents(bool trickle_fast_inputs)
         }
         else if (e->Type == ImGuiInputEventType_MouseButton)
         {
+            bool trickle_fast_inputs = true; // forcing trickle for MouseButton event
+
             // Trickling Rule: Stop processing queued events if we got multiple action on the same button
             const ImGuiMouseButton button = e->MouseButton.Button;
             IM_ASSERT(button >= 0 && button < ImGuiMouseButton_COUNT);
@@ -9549,6 +9551,8 @@ void ImGui::UpdateInputEvents(bool trickle_fast_inputs)
         }
         else if (e->Type == ImGuiInputEventType_Key)
         {
+            bool trickle_fast_inputs = true; // forcing trickle for Key event
+
             // Trickling Rule: Stop processing queued events if we got multiple action on the same button
             ImGuiKey key = e->Key.Key;
             IM_ASSERT(key != ImGuiKey_None);
@@ -9570,6 +9574,10 @@ void ImGui::UpdateInputEvents(bool trickle_fast_inputs)
         }
         else if (e->Type == ImGuiInputEventType_Text)
         {
+            // forcing trickle for Text event, but only when interacting with keydown or mouse button
+            if ((key_changed && trickle_interleaved_keys_and_text) || mouse_button_changed != 0)
+                break;
+
             // Trickling Rule: Stop processing queued events if keys/mouse have been interacted with
             if (trickle_fast_inputs && ((key_changed && trickle_interleaved_keys_and_text) || mouse_button_changed != 0 || mouse_moved || mouse_wheeled))
                 break;

extern/imgui_patched/imgui_draw.cpp

@@ -2224,10 +2224,22 @@ ImFont* ImFontAtlas::AddFontFromMemoryTTF(void* ttf_data, int ttf_size, float si
 
 ImFont* ImFontAtlas::AddFontFromMemoryCompressedTTF(const void* compressed_ttf_data, int compressed_ttf_size, float size_pixels, const ImFontConfig* font_cfg_template, const ImWchar* glyph_ranges)
 {
+    // workaround for big-endian
+#ifdef TA_BIG_ENDIAN
+    unsigned char* beData=(unsigned char*)IM_ALLOC(compressed_ttf_size);
+    for (int i=0; i<compressed_ttf_size; i++) {
+      beData[i]=compressed_ttf_data[i^3];
+    }
+    compressed_ttf_data=beData;
+#endif
     const unsigned int buf_decompressed_size = stb_decompress_length((const unsigned char*)compressed_ttf_data);
     unsigned char* buf_decompressed_data = (unsigned char*)IM_ALLOC(buf_decompressed_size);
     stb_decompress(buf_decompressed_data, (const unsigned char*)compressed_ttf_data, (unsigned int)compressed_ttf_size);
 
+#ifdef TA_BIG_ENDIAN
+    IM_FREE(beData);
+#endif
+
     ImFontConfig font_cfg = font_cfg_template ? *font_cfg_template : ImFontConfig();
     IM_ASSERT(font_cfg.FontData == NULL);
     font_cfg.FontDataOwnedByAtlas = true;

extern/nfd-modified/src/nfd_win.cpp

@@ -532,6 +532,9 @@ nfdresult_t NFD_OpenDialogMultiple( const std::vector<std::string>& filterList,
                                     nfdselcallback_t selCallback )
 {
     nfdresult_t nfdResult = NFD_ERROR;
+    NFDWinEvents* winEvents;
+    bool hasEvents=true;
+    DWORD eventID=0;
 
 
     HRESULT coResult = COMInit();
@@ -566,6 +569,16 @@ nfdresult_t NFD_OpenDialogMultiple( const std::vector<std::string>& filterList,
         goto end;
     }
 
+    // Pass the callback
+    winEvents=new NFDWinEvents(selCallback);
+    if ( !SUCCEEDED(fileOpenDialog->Advise(winEvents,&eventID)) ) {
+      // error... ignore
+      hasEvents=false;
+      winEvents->Release();
+    } else {
+      winEvents->Release();
+    }
+
     // Set a flag for multiple options
     DWORD dwFlags;
     result = fileOpenDialog->GetOptions(&dwFlags);
@@ -613,8 +626,12 @@ nfdresult_t NFD_OpenDialogMultiple( const std::vector<std::string>& filterList,
     }
 
 end:
-    if ( fileOpenDialog )
+    if (fileOpenDialog) {
+        if (hasEvents) {
+          fileOpenDialog->Unadvise(eventID);
+        }
         fileOpenDialog->Release();
+    }
 
     COMUninit(coResult);
     

extern/opl/MODIFIED.md

@@ -1,4 +1,4 @@
 # modification disclaimer
 
-this is a modified version of Nuked-OPL3 which implements channel muting in the core.
+this is a modified version of Nuked-OPL3 which implements channel muting in the core, and resampling function.
 see [this issue](https://github.com/tildearrow/furnace/issues/414) for more information.

extern/opl/opl3.c

@@ -1362,6 +1362,11 @@ void OPL3_Reset(opl3_chip *chip, uint32_t samplerate)
 #endif
 }
 
+void OPL3_Resample(opl3_chip *chip, uint32_t samplerate)
+{
+    chip->rateratio = (samplerate << RSM_FRAC) / 49716;
+}
+
 void OPL3_WriteReg(opl3_chip *chip, uint16_t reg, uint8_t v)
 {
     uint8_t high = (reg >> 8) & 0x01;

extern/opl/opl3.h

@@ -158,6 +158,7 @@ struct _opl3_chip {
 void OPL3_Generate(opl3_chip *chip, int16_t *buf);
 void OPL3_GenerateResampled(opl3_chip *chip, int16_t *buf);
 void OPL3_Reset(opl3_chip *chip, uint32_t samplerate);
+void OPL3_Resample(opl3_chip *chip, uint32_t samplerate);
 void OPL3_WriteReg(opl3_chip *chip, uint16_t reg, uint8_t v);
 void OPL3_WriteRegBuffered(opl3_chip *chip, uint16_t reg, uint8_t v);
 void OPL3_GenerateStream(opl3_chip *chip, int16_t *sndptr, uint32_t numsamples);

papers/format.md

@@ -143,8 +143,8 @@ size | description
      |   - 0x49: Neo Geo CD extended - 16 channels
      |   - 0x80: AY-3-8910 - 3 channels
      |   - 0x81: Amiga - 4 channels
-     |   - 0x82: YM2151 alone - 8 channels
+     |   - 0x82: YM2151 - 8 channels
-     |   - 0x83: YM2612 alone - 6 channels
+     |   - 0x83: YM2612 - 6 channels
      |   - 0x84: TIA - 2 channels
      |   - 0x85: VIC-20 - 4 channels
      |   - 0x86: PET - 1 channel
@@ -159,7 +159,7 @@ size | description
      |   - 0x8f: OPL (YM3526) - 9 channels
      |   - 0x90: OPL2 (YM3812) - 9 channels
      |   - 0x91: OPL3 (YMF262) - 18 channels
-     |   - 0x92: MultiPCM - 28 channels
+     |   - 0x92: MultiPCM - 28 channels (UNAVAILABLE)
      |   - 0x93: Intel 8253 (beeper) - 1 channel
      |   - 0x94: POKEY - 4 channels
      |   - 0x95: RF5C68 - 8 channels
@@ -187,8 +187,8 @@ size | description
      |   - 0xab: MSM6258 - 1 channel
      |   - 0xac: Commander X16 (VERA) - 17 channels
      |   - 0xad: Bubble System WSG - 2 channels
-     |   - 0xae: OPL4 (YMF278B) - 42 channels
+     |   - 0xae: OPL4 (YMF278B) - 42 channels (UNAVAILABLE)
-     |   - 0xaf: OPL4 drums (YMF278B) - 44 channels
+     |   - 0xaf: OPL4 drums (YMF278B) - 44 channels (UNAVAILABLE)
      |   - 0xb0: Seta/Allumer X1-010 - 16 channels
      |   - 0xb1: Ensoniq ES5506 - 32 channels
      |   - 0xb2: Yamaha Y8950 - 10 channels
@@ -199,26 +199,29 @@ size | description
      |   - 0xb7: YM2608 extended - 19 channels
      |   - 0xb8: YMZ280B - 8 channels
      |   - 0xb9: Namco WSG - 3 channels
-     |   - 0xba: Namco 15xx - 8 channels
+     |   - 0xba: Namco C15 - 8 channels
-     |   - 0xbb: Namco CUS30 - 8 channels
+     |   - 0xbb: Namco C30 - 8 channels
      |   - 0xbc: MSM5232 - 8 channels
-     |   - 0xbd: YM2612 extra features extended - 11 channels
+     |   - 0xbd: YM2612 DualPCM extended - 11 channels
-     |   - 0xbe: YM2612 extra features - 7 channels
+     |   - 0xbe: YM2612 DualPCM - 7 channels
      |   - 0xbf: T6W28 - 4 channels
      |   - 0xc0: PCM DAC - 1 channel
      |   - 0xc1: YM2612 CSM - 10 channels
-     |   - 0xc2: Neo Geo CSM (YM2610) - 18 channels
+     |   - 0xc2: Neo Geo CSM (YM2610) - 18 channels (UNAVAILABLE)
-     |   - 0xc3: YM2203 CSM - 10 channels
+     |   - 0xc3: YM2203 CSM - 10 channels (UNAVAILABLE)
-     |   - 0xc4: YM2608 CSM - 20 channels
+     |   - 0xc4: YM2608 CSM - 20 channels (UNAVAILABLE)
-     |   - 0xc5: YM2610B CSM - 20 channels
+     |   - 0xc5: YM2610B CSM - 20 channels (UNAVAILABLE)
      |   - 0xc6: K007232 - 2 channels
      |   - 0xc7: GA20 - 4 channels
      |   - 0xc8: SM8521 - 3 channels
-     |   - 0xc9: M114S - 16 channels
+     |   - 0xc9: M114S - 16 channels (UNAVAILABLE)
      |   - 0xca: ZX Spectrum (beeper, QuadTone engine) - 5 channels
      |   - 0xcb: Casio PV-1000 - 3 channels
      |   - 0xcc: K053260 - 4 channels
      |   - 0xcd: TED - 2 channels
+     |   - 0xce: Namco C140 - 24 channels
+     |   - 0xcf: Namco C219 - 16 channels (UNAVAILABLE)
+     |   - 0xd0: Namco C352 - 32 channels (UNAVAILABLE)
      |   - 0xde: YM2610B extended - 19 channels
      |   - 0xe0: QSound - 19 channels
      |   - 0xfc: Pong - 1 channel
@@ -227,6 +230,8 @@ size | description
      |   - 0xff: reserved for development
      | - (compound!) means that the system is composed of two or more chips,
      |   and has to be flattened.
+     | - (UNAVAILABLE) means that the chip hasn't been implemented in Furnace
+     |   yet.
  32  | sound chip volumes (<135) or reserved
      | - signed char, 64=1.0, 127=~2.0
      | - as of version 135 these fields only exist for compatibility reasons.