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

.github/workflows/build.yml

@@ -22,8 +22,8 @@ jobs:
           - { name: 'Windows MSVC x86_64', os: windows-latest, compiler: msvc, arch: x86_64 }
           #- { name: 'Windows MinGW x86', os: ubuntu-20.04, compiler: mingw, arch: x86 }
           #- { name: 'Windows MinGW x86_64', os: ubuntu-20.04, compiler: mingw, arch: x86_64 }
-          - { name: 'macOS x86_64', os: macos-latest, arch: x86_64 }
-          - { name: 'macOS ARM', os: macos-latest, arch: arm64 }
+          #- { name: 'macOS x86_64', os: macos-latest, arch: x86_64 }
+          #- { name: 'macOS ARM', os: macos-latest, arch: arm64 }
           - { name: 'Linux x86_64', os: ubuntu-20.04, arch: x86_64 }
           #- { name: 'Linux ARM', os: ubuntu-18.04, arch: armhf }
       fail-fast: false

CMakeLists.txt

@@ -143,7 +143,7 @@ if (WIN32)
   endif()
 endif()
 
-list(APPEND DEPENDENCIES_INCLUDE_DIRS "extern/SAASound/include")
+#list(APPEND DEPENDENCIES_INCLUDE_DIRS "extern/SAASound/include")
 list(APPEND DEPENDENCIES_INCLUDE_DIRS "extern/vgsound_emu-modified")
 
 find_package(Threads REQUIRED)
@@ -489,6 +489,9 @@ extern/Nuked-PSG/ympsg.c
 extern/opm/opm.c
 extern/Nuked-OPLL/opll.c
 extern/opl/opl3.c
+extern/YM3812-LLE/fmopl2.c
+extern/YMF262-LLE/fmopl3.c
+extern/YMF276-LLE/fmopn2.c
 
 src/pch.cpp
 
@@ -556,9 +559,11 @@ src/engine/platform/sound/tia/AudioChannel.cpp
 src/engine/platform/sound/tia/Audio.cpp
 
 src/engine/platform/sound/ymfm/ymfm_adpcm.cpp
+src/engine/platform/sound/ymfm/ymfm_opl.cpp
 src/engine/platform/sound/ymfm/ymfm_opm.cpp
 src/engine/platform/sound/ymfm/ymfm_opn.cpp
 src/engine/platform/sound/ymfm/ymfm_opz.cpp
+src/engine/platform/sound/ymfm/ymfm_pcm.cpp
 src/engine/platform/sound/ymfm/ymfm_ssg.cpp
 
 src/engine/platform/sound/lynx/Mikey.cpp
@@ -810,6 +815,7 @@ src/gui/tutorial.cpp
 src/gui/util.cpp
 src/gui/waveEdit.cpp
 src/gui/volMeter.cpp
+src/gui/xyOsc.cpp
 src/gui/gui.cpp
 )
 
@@ -1072,6 +1078,7 @@ if (NOT ANDROID OR TERMUX)
     set(CPACK_BUNDLE_PLIST ${CMAKE_SOURCE_DIR}/res/Info.plist)
     set(CPACK_BUNDLE_ICON ${CMAKE_SOURCE_DIR}/res/icon.icns)
     set(CPACK_BUNDLE_STARTUP_COMMAND "furnace")
+    set(CPACK_BUNDLE_APPLE_CERT_APP "-")
   endif()
   
   include(CPack)

CONTRIBUTING.md

@@ -35,6 +35,7 @@ the coding style is described here:
   - preprocessor directives not intended
   - if macro comprises more than one line, indent
   - no new line after `template<>`
+- do not use `_t` types, except for 64-bit integers and `size_t`.
 - prefer built-in types:
   - `bool`
   - `signed char` or `unsigned char` are 8-bit
@@ -48,6 +49,7 @@ the coding style is described here:
   - `long long int` or `unsigned long long int` are 64-bit
     - avoid using 64-bit numbers as I still build for 32-bit systems.
     - two `long`s are required to make Windows happy.
+    - prefer using `int64_t` or `uint64_t` for this specific case.
   - `size_t` are 32-bit or 64-bit, depending on architecture.
 - in float/double operations, always use decimal and `f` if single-precision.
   - e.g. `1.0f` or `1.0` instead of `1`.

TODO.md

@@ -4,14 +4,9 @@
 
 # THE REAL TO-DO LIST
 
-- Amiga's Period Modulation not working
-- Song is silent after playing an order after loop point
-- Select loaded instrument on open - rewrite because I want a setting...
-- re-engineer volume handling? Sound Unit cries at me
-- finish status view
 - finish auto-clone
 
-once you have done all of this (maybe not the first one) and merged the two or so pending pull requests, release 0.6.1
+once you have done all of this (maybe not the first one), release 0.6.1
 
 Furnace is like alcohol...
 

doc/1-intro/README.md

@@ -26,4 +26,6 @@ once familiar with the tracker, look to [9-guides](../9-guides/README.md) for us
 
 ## tutorial?
 
+[How to Learn Chiptune Trackers](https://www.youtube.com/watch?v=Q37XuOLz0jw): video tutorial created by Button Masher. covers the basic mechanics of chiptune tracking using Furnace for demonstration.
+
 [Furnace Tutorials](https://youtube.com/playlist?list=PLCELB6AsTZUnwv0PC5AAGHjvg47F44YQ1): video tutorials created by Spinning Square Waves. be noted that these may not apply to the current version.

doc/1-intro/concepts.md

@@ -23,7 +23,7 @@ the **order list** is a smaller spreadsheet showing the overall song structure.
 - patterns may be used multiple times in the order list. changing a pattern's data in one order will affect the same pattern used in other orders.
 - each pattern is made of the same number of rows as seen in the tracker view.
 - during playback, the **playhead** moves down as described previously. when it reaches the end of the pattern view, it will go to the next order.
-- if the last order is reached and the playhear reaches the end of the pattern view, it will go back to the beginning of the song.
+- if the last order is reached and the playhead reaches the end of the pattern view, it will go back to the beginning of the song.
 
 ## time
 

doc/2-interface/asset-list.md

@@ -55,5 +55,12 @@ everything from the wavetables list applies here also, with the addition of one
 
 samples are saved as standard wave (.wav) files.
 
-- right-clicking the Save button brings up a menu with the following options:
-  - **save raw sample...**: saves the selected sample as raw data.
+right-clicking the Save button brings up a menu with the following options:
+- **save raw sample...**: saves the selected sample as raw data.
+
+right-clicking a sample in the list brings up a menu:
+- **make instrument**: creates a new instrument which is set to use the selected sample.
+- **duplicate**: makes a copy of the selected sample.
+- **replace...**: opens a file dialog to choose a replacement sample.
+- **save**: opens a file dialog to choose where to save the sample.
+- **delete**: removes the sample.

doc/2-interface/components.md

@@ -21,7 +21,8 @@ the following keyboard shortcuts work while on a text field:
 
 these work similar to text fields, but you may only input numbers.
 
-they also usually have `+` and `-` buttons which allow you to increase/decrease the amount when clicked (and rapidly do so when click-holding).
+they also usually have `+` and `-` buttons which allow you to increase/decrease the value when clicked (and rapidly do so when holding).
+additionally, Ctrl-clicking these buttons may increase/decrease the value by a coarse amount.
 
 ## sliders
 
@@ -29,7 +30,8 @@ sliders are used for controlling values in a quick manner by being dragged.
 
 using the scroll wheel while holding Ctrl will change the slider's value by small amounts.
 
-right-clicking or Ctrl-clicking or a slider (Command-click on macOS) will turn it into a number input field for a short period of time, allowing you to input precise values.
+right-clicking or Ctrl-clicking or a slider (Command-click on macOS) will turn it into a number input field, allowing you to input precise values.
+once you click away it will become a slider again.
 
 ## windows
 
@@ -37,13 +39,13 @@ right-clicking or Ctrl-clicking or a slider (Command-click on macOS) will turn i
 
 windows may be moved, collapsed, closed or even docked around the workspace.
 
-to move a window, press and hold the mouse button while on title bar or any empty space on it.
+to move a window, press and hold the left mouse button while on the title bar or any empty space on it.
 then drag your mouse, and release it to stop moving.
 
 to resize a window, drag the bottom right corner (marked by a triangular tab) or the borders.
 
 to collapse a window, click on the triangle in the title bar.
-clicking again expands it.
+clicking again expands the window.
 
 to close a window, click on the `X` at the top right corner, or select it from the "window" menu.
 

doc/2-interface/menu-bar.md

@@ -35,6 +35,7 @@ items in _italic_ don't appear in basic mode and are only available in advanced
 
 - **export audio...**: opens the file picker, allowing you to export your song to a .wav file. see next section for more details.
 - **export VGM...**: opens the file picker, allowing you to export your song to a .vgm file. see next section for more details.
+- **export text...**: opens the file picker, allowing you to export your song to a .txt file.
 - **export ZSM...**: opens the file picker, allowing you to export your song to a .zsm file. see next section for more details.
   - only available when there's a YM2151 and/or VERA.
 - **export command stream...**: export song data to a command stream file. see next section for more details.
@@ -140,6 +141,7 @@ it's not really useful, unless you're a developer and want to use a command stre
 - **cut**: moves the current selection in the pattern view to clipboard.
 - **copy**: copies the current selection in the pattern view to clipboard.
 - **paste**: inserts the clipboard's contents in the cursor position.
+  - you may be able to paste from OpenMPT as well.
 - _**paste special...**:_ variants of the paste feature.
   - **paste mix**: inserts the clipboard's contents in the cursor position, but does not erase the occupied region.
   - **paste mix (background)**: does the same thing as paste mix, but doesn't alter content which is already there.

doc/2-interface/settings.md

@@ -47,6 +47,7 @@ settings are saved when clicking the **OK** or **Apply** buttons at the bottom o
 - **When creating new song**:
   - **Display system preset selector**
   - **Start with initial system**
+  - **Default author name**
 
 ### Start-up
 
@@ -92,7 +93,7 @@ settings are saved when clicking the **OK** or **Apply** buttons at the bottom o
   - setting this to a high value increases latency.
 - **Exclusive mode**: enables Exclusive Mode, which may offer latency improvements.
   - only available on WASAPI devices in the PortAudio backend!
-- **Low-latency mode (experimental!)**: reduces latency by running the engine faster than the tick rate. useful for live playback/jam mode.
+- **Low-latency mode**: reduces latency by running the engine faster than the tick rate. useful for live playback/jam mode.
   - only enable if your buffer size is small (10ms or less).
 - **Force mono audio**: use if you're unable to hear stereo audio (e.g. single speaker or hearing loss in one ear).
 - **want:** displays requested audio configuration.
@@ -104,6 +105,7 @@ settings are saved when clicking the **OK** or **Apply** buttons at the bottom o
 - **Software clipping**: clips output to nominal range (-1.0 to 1.0) before passing it to the audio device.
   - this avoids activating Windows' built-in limiter.
   - this option shall be enabled when using PortAudio backend with a DirectSound device.
+- **DC offset correction**: apply a filter to remove DC bias, where the output is overall above or below zero. default is on.
 
 ### Metronome
 
@@ -121,22 +123,21 @@ settings are saved when clicking the **OK** or **Apply** buttons at the bottom o
 - **Note input**: enables note input. disable if you intend to use this device only for binding actions.
 - **Velocity input**: enables velocity input when entering notes in the pattern.
 - **Map MIDI channels to direct channels**: when enabled, notes from MIDI channels will be mapped to channels rather than the cursor position.
+- **Program change pass-through**: when enabled, program change events are sent to each channel as instrument change commands.
+  - this option is only available when the previous one is enabled.
 - **Map Yamaha FM voice data to instruments**: when enabled, Furnace will listen for any transmitted Yamaha SysEx patches.
   - this option is only useful if you have a Yamaha FM synthesizer (e.g. TX81Z).
   - selecting a voice or using the "Voice Transmit?" option will send a patch, and Furnace will create a new instrument with its data.
   - this may also be triggered by clicking on "Receive from TX81Z" in the instrument editor (OPZ only).
 - **Program change is instrument selection**: changes the current instrument when a program change event is received.
+  - this option is not available when "Program change pass-through" is enabled.
 - **Value input style**: changes the way values are entered when the pattern cursor is not in the Note column. the following styles are available:
   - **Disabled/custom**: no value input through MIDI.
   - **Two octaves (0 is C-4, F is D#5)**: maps keys in two octaves to single nibble input. the layout is:
-    - ` - octave n -- octave n+1 -`
-    - ` 1 3   6 8 A   D F   # # # `
-    - `0 2 4 5 7 9 B C E # # # # #`
+    ![two octaves layout 1](MIDI-value-input-1.png)
   - **Raw (note number is value)**: the note number becomes the input value. not useful if you want to input anything above 7F.
   - **Two octaves alternate (lower keys are 0-9, upper keys are A-F)**: maps keys in two octaves, but with a different layout:
-    - ` - octave n -- octave n+1 -`
-    - ` A B   C D E   F #   # # # `
-    - `0 1 2 3 4 5 6 7 8 9 # # # #`
+    ![two octaves layout 2](MIDI-value-input-2.png)
   - **Use dual control change (one for each nibble)**: maps two control change events to the nibbles of a value.
     - **CC of upper nibble**: select the CC number that will change the upper nibble.
     - **CC of lower nibble**: select the CC number that will change the lower nibble.
@@ -147,6 +148,7 @@ settings are saved when clicking the **OK** or **Apply** buttons at the bottom o
     - **Control**: select the CC number that will change the value.
 - **Per-column control change**: when enabled, you can map several control change events to a channel's columns.
 - **Volume curve**: adjust the velocity to volume curve.
+  - the default is 2.0, which matches General MIDI standard.
 - **Actions**: this allows you to bind note input and control change events to actions.
   - **`+`** button: adds a new action.
   - window-with-arrow button: new action with learning! press a button or move a slider/knob/something on your device.
@@ -299,6 +301,15 @@ below all the binds, select a key from the dropdown list to add it. it will appe
   - applies when playback is stopped.
 - **Don't scroll when moving cursor**
 - **Move cursor with scroll wheel**
+  - **No**
+  - **Yes**
+  - **Inverted**
+
+### Assets
+
+- **Display instrument type menu when adding instrument**
+  - if turned off, the menu can still be opened by right-clicking the add button.
+- **Select asset after opening one**
 
 ## Appearance
 
@@ -430,8 +441,6 @@ below all the binds, select a key from the dropdown list to add it. it will appe
   - **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
 

doc/3-pattern/README.md

@@ -38,18 +38,39 @@ clicking on a channel name mutes that channel.
 
 double-clicking or right-clicking it enables solo mode, in which only that channel will be audible.
 
-clicking the `++` at the top left corner of the pattern view cycles through three channel bar view modes:
-- **Compact**: shows only channel names.
-- **Expanded**: as shown above. adds buttons:
+clicking the `++` at the top left corner of the pattern view pops up a small menu to set view modes:
+- **Effect columns/collapse**: displays extra options for collapsing channels and adding/removing effect columns:
   - **-**: collapse visible columns. changes to **+** when columns are hidden; click to expand them.
   - **<**: disables the last effect column and hides it. effects are not deleted...
-  - **>**: adds an effects column. if one previously existed, its contents will be preserved.
+  - **>**: adds an effect column. if one previously existed, its contents will be preserved.
 - **Pattern names**: displays pattern names (per channel). pattern names are also visible when hovering over a pattern in the order list.
-
-right-clicking the `++` toggles the visualizer, which is active only during playback.
+- **Channel group hints**: display indicators when channels are paired in some way (e.g. OPL3 4-op mode).
+- **Visualizer**: during playback, show visual effects in the pattern view.
+  - also can be toggled by right-clicking on the `++` button.
+- **Channel status**: displays icons that indicate activity in the channel. see the "channel status" section below.
 
 to rename and/or hide channels, open [the Channels window](../8-advanced/channels.md) via the window menu.
 
+### channel status
+
+- note status:
+  - ![note off](status-note-off.png) note off
+  - ![note on](status-note-on.png) note on
+  - ![macro released](status-note-on-rel.png) note on but macro released (`REL`)
+  - ![note released](status-note-off-rel.png) note released (`===`)
+- pitch alteration:
+  - ![no effect](status-pitch-none.png) nothing
+  - ![pitch up](status-pitch-up.png) pitch slide up
+  - ![pitch down](status-pitch-down.png) pitch slide down
+  - ![portamento](status-pitch-porta.png) portamento
+  - ![arpeggio](status-pitch-arpeg.png) arpeggio
+- volume alteration:
+  - ![no effect](status-volume-none.png) nothing
+  - ![volume up](status-volume-up.png) volume slide up
+  - ![volume down](status-volume-down.png) volume slide down
+  - ![tremolo](status-volume-tremolo.png) tremolo
+- other icons may be present depending on the used chips.
+
 
 ## input
 

doc/3-pattern/effects.md

@@ -154,16 +154,16 @@ ex | FM     | OPM       | OPZ       | OPLL  | AY-3-8910  | AY8930     | Lynx
  W |        | LFO Shape | LFO Shape | Patch | Waveform   | Waveform   |          | Waveform   |
  1 |        | AMD       | AMD       |       |            | Duty       |          | FilterMode |
  2 |        | PMD       | PMD       |       | Envelope   | Envelope   |          | Resonance  |
- 3 | LFOSpd | LFO Speed | LFO Speed |       | AutoEnvNum | AutoEnvNum |          | Special    |
- A | ALG    | ALG       | ALG       |       | AutoEnvDen | AutoEnvDen |          |            |
+ 3 | LFOSpd | LFO Speed | LFO Speed |       | AutoEnvNum | AutoEnvNum |          |            |
+ A | ALG    | ALG       | ALG       |       | AutoEnvDen | AutoEnvDen |          | Cutoff     |
  B | FB     | FB        | FB        |       |            | Noise AND  |          |            |
  C | FMS    | FMS       | FMS       |       |            | Noise OR   |          |            |
  D | AMS    | AMS       | AMS       |       |            |            |          |            |
- 4 | OpMask | OpMask    |           |       |            |            |          | Test/Gate  |
- 5 |        |           | AMD2      |       |            |            |          |            |
- 6 |        |           | PMD2      |       |            |            |          |            |
- 7 |        |           | LFO2Speed |       |            |            |          |            |
- 8 |        |           | LFO2Shape |       |            |            |          |            |
+ 4 | OpMask | OpMask    |           |       |            |            |          | Special    |
+ 5 |        |           | AMD2      |       |            |            |          | Attack     |
+ 6 |        |           | PMD2      |       |            |            |          | Decay      |
+ 7 |        |           | LFO2Speed |       |            |            |          | Sustain    |
+ 8 |        |           | LFO2Shape |       |            |            |          | Release    |
 
 ex | SAA1099  | X1-010     | Namco 163  | FDS       | Sound Unit | ES5506    | MSM6258  |
 ---|----------|------------|------------|-----------|------------|-----------|----------|

doc/4-instrument/README.md

@@ -96,31 +96,55 @@ every macro can be defined though one of three methods, selectable with the left
 - ![ADSR](macro-button-ADSR.png) **ADSR:** this is a traditional ADSR envelope, defined by the rate of increase and decrease of value over time.
 - ![LFO](macro-button-LFO.png) **LFO:** the Low Frequency Oscillator generates a repeating wave of values.
 
-some macros are "bitmap" style. they represent a number of "bits" that can be toggled individually, and the values listed represent the sum of which bits are turned on.
-
 ### sequence
 
 ![sequence macro editor](macro-seq.png)
 
+![clipped sequence macro editor](macro-seq-clip.png)
+
+![bitmask sequence macro editor](macro-seq-bitmask.png)
+
 the number between the macro type label and the macro type button is the macro length in steps. the `-` and `+` buttons change the length of the macro. start out by adding at least a few steps.
 
 the values of the macro can be drawn in the "bar graph" box.
+- arpeggio and pitch macros may have values above or below the visible area; small chevrons will be shown until they are scrolled into view.
+- bitmask-style macros show labels for each of their bits, and these are edited as toggles.
 
-just beneath the box is a shorter bar that controls looping.
+arpeggio macros have a short bar for setting whether to interpret the values as being "relative" or "fixed".
+- by default, values are offsets **relative** to the note.
+- if clicked on, a value becomes **fixed** and will be played at its corresponding note without regard to the note entered into the pattern.
+  - values are counted from `C-0`. for example, a fixed value of 48 produces a `C-4` note.
+  - fixed values are especially useful for noise instruments with preset periods.
+
+below this is a short bar that controls macro loop and release.
 - click to set the start point of a loop; the end point is the last value or release point. it appears as half-height bars. right-click to remove the loop.
 - shift-click to set the release point. when played, the macro will hold here until the note is released. it appears as a full-height bar. right-click to remove the release point.
 
 finally, the sequence of values can be directly edited in the text box at the bottom.
 - the loop start is entered as a `|`.
 - the release point is entered as a `/`.
-- in arpeggio macros, a value starting with a `@` is an absolute note (instead of a relative shift). no matter the note entered in the pattern, `@` values will be played at that exact note. this is especially useful for noise instruments with preset periods.
+- in arpeggio macros, a value starting with a `@` is a fixed value as described above.
+- in bitmask-style macros, the values are added up in binary and converted to decimal. see [the hexadecimal guide](../1-intro/hex.md) for more info.
+
+in all cases except bitmask macros, right-clicking on the graph opens up an editing menu:
+- **copy**: copies the macro.
+- **paste**: pastes the macro in the clipboard.
+- **clear**: clears the macro.
+- **clear contents**: resets all values to 0.
+- **offset**:
+  - **X**: slides the data "horizontally" within the macro, filling the gap with zeroes. data moved past the start or end is lost.
+  - **Y**: increases or decreases all values, clipping them if they would move past the allowed range.
+- **scale**:
+  - **X**: stretches the macro.
+  - **Y**: multiplies all values by the scale factor, clipping them if they would exceed the allowed range.
+- **randomize**: replaces all values with random values between **Min** and **Max**.
 
 ### ADSR
 
 ![ADSR macro editor](macro-ADSR.png)
 
 - **Bottom** and **Top** determine the range of outputs generated by the macro. (Bottom can be larger than Top to invert the envelope!) All outputs will be between these two values.
-- attack, Decay, Sustain, SusDecay, and Release accept inputs between 0 to 255. these are scaled to the distance between Bottom and Top.
+- Attack, Decay, Sustain, SusDecay, and Release accept inputs between 0 to 255. these are scaled to the distance between Bottom and Top.
 - **Attack** is how much the value moves toward Top with each tick.
 - **Hold** sets how many ticks to stay at Top before Decay.
 - **Decay** is how much the value moves to the Sustain level.

doc/4-instrument/c64.md

@@ -5,15 +5,14 @@ the C64 instrument editor consists of two tabs: "C64" to control various paramet
 ## C64
 
 - **Waveform**: allows selecting a waveform.
-  - more than one waveform can be selected at once. in that case logical AND mix of waves will occur.
+  - more than one waveform can be selected at once. in that case a logical AND mix of waves will occur...
+    - due to hardware flaws, the mixing is a bit weird and sounds different between the 6581 and the 8580.
   - noise is an exception. it cannot be used with any of the other waveforms.
 - **Attack**: determines the rising time for the sound. the bigger the value, the slower the attack. (0 to 15).
 - **Decay**: determines the diminishing time for the sound. the higher the value, the longer the decay (0 to 15).
 - **Sustain**: sets the volume level at which the sound stops decaying and holds steady (0 to 15).
 - **Release**: determines the rate at which the sound fades out after note off. the higher the value, the longer the release (0 to 15).
-
 - **Duty**: specifies the width of a pulse wave (0 to 4095).
-
 - **Ring Modulation**: when enabled, the channel's output will be multiplied with the previous channel's.
 - **Oscillator Sync**: enables oscillator hard sync. as the previous channel's oscillator finishes a cycle, it resets the period of the channel's oscillator, forcing the latter to have the same base frequency. this can produce a harmonically rich sound, the timbre of which can be altered by varying the synchronized oscillator's frequency.
 
@@ -25,10 +24,9 @@ the C64 instrument editor consists of two tabs: "C64" to control various paramet
     - **low**: a low-pass filter. the lower the cutoff, the darker the sound.
     - **high**: a high-pass filter. higher cutoff values result in a less "bassy" sound.
     - **band**: a band-pass filter. cutoff determines which part of the sound is heard (from bass to treble).
-    - **ch3off**: mutes channel 3 when enabled. not sure why is this part of the chip's design, but it is.
+    - **ch3off**: mutes channel 3 when enabled. it was originally planned for usage with two registers where program could read current oscillator and envelope outputs, thus making vibrato and SFX generation easier. but who wanted to sacrifice one channel out of three! so aforementioned was just done in software, and the feature was never used.
+    - multiple filter modes can be selected simultaneously. for example, selecting both "low" and "high" results in a bandstop (notch) filter.
 
-- **Volume Macro is Cutoff Macro**: turns the volume macro in the Macros tab into a filter cutoff macro.
-  - volume control is global (affects entire chip output), hence the option.
 - **Absolute Cutoff Macro**: when enabled, the cutoff macro will go from 0 to 2047, and it will be absolute (in other words, control the cutoff directly rather than being relative).
 - **Absolute Duty Macro**: when enabled, the duty macro will go from 0 to 4095.
 - **Don't test before new note**: this option disables the one-tick hard reset and test bit before a new note.
@@ -37,12 +35,26 @@ the C64 instrument editor consists of two tabs: "C64" to control various paramet
 
 - **Volume**: volume sequence.
   - warning: volume sequence is global! this means it controls the chip's volume and therefore affects all channels.
-  - this macro becomes **Cutoff** when the **Volume Macro is Cutoff Macro** option is enabled in the C64 tab.
 - **Arpeggio**: pitch sequence.
 - **Duty**: pulse width sequence.
 - **Waveform**: select the waveform used by instrument.
 - **Pitch**: fine pitch.
+- **Cutoff**: filter cutoff.
 - **Filter mode**: select the filter mode.
 - **Resonance**: filter resonance sequence.
-- **Special**: ring and oscillator sync selector.
-- **Test/Gate**: when on, the test bit is set, which mutes the channel.
+- **Special**: ring and oscillator sync selector, as well as:
+  - **gate bit**:
+    - set (1): key on. if previous state was 0 it triggers envelope start/restart; if previous state was 1, it does nothing.
+    - reset (0): key off. if previous state was 1 it triggers envelope release; if previous state was 0, it does nothing.
+  - **test bit**:
+    - set (1): immediately mute channel
+      - if the channel is a source of ring mod and/or hard sync, those stop working until the bit is reset.
+    - reset (0): unmute channel and restore ring mod/hard sync.
+- **Attack**: sets envelope attack speed.
+  - if you modify attack speed when the envelope is in attack phase it immediately changes.
+- **Decay**: sets envelope decay speed.
+  - if you modify decay speed when envelope is in decay phase it immediately changes.
+- **Sustain**: sets envelope sustain level.
+  - if you modify sustain level when envelope is in sustain phase it immediately changes, although you can only go down. for example, 9-to-8 and 8-to-8 both work, but 8-to-9 immediately mutes the channel.
+- **Release**: sets envelope release speed.
+  - if you modify release speed when envelope is in release phase it immediately changes.

doc/6-sample/README.md

@@ -154,8 +154,22 @@ in there, you can modify certain data pertaining to your sample, such as the:
   - **Low-pass**: amount to attenuate everything above cutoff.
   - **Band-pass**: amount to attenuate everything outside cutoff.
   - **High-pass**: amount to attenuate everything below cutoff.
+- **Crossfade loop points**: applies a "fade" between the loop's starting point and the end.
+  - **Number of samples**: how many samples in the loop region to take into account for crossfade.
+  - **Linear <-> Equal power**: the curve used to crossfade.
 - **Preview sample**: plays sample at base frequency.
 - **Stop sample preview**: stops preview.
 - **Create instrument from sample**: creates a new instrument with its sample set to the current sample.
 - **Zoom**: shows and sets sample view zoom level.
 - **Zoom mode**: switches between "Auto" (entire sample fits in window) and "100%" (each horizontal pixel represents one sample point).
+
+in the sample viewer:
+- left-click and drag to select a region of the sample.
+- right-click to display a menu:
+  - **cut**: puts the selection in the sample clipboard and deletes it from the sample.
+  - **copy**: copies the selection into the sample clipboard.
+  - **paste**: inserts the sample clipboard at the start of the selection.
+  - **paste (replace)**: replaces the selection with the sample clipboard.
+  - **paste (mix)**: mixes the sample clipboard into the existing sample, beginning at the start of the selection.
+  - **set loop to selection**: changes loop region to match selection.
+  - **create wavetable from selection**: copies the selection into a new wavetable entry.