Merge branch 'master' of https://github.com/tildearrow/furnace into k053260

.github/workflows/build.yml

@@ -82,7 +82,7 @@ jobs:
           package_ext=".dmg"
         else
           package_name="${package_name}-Linux-${{ matrix.config.arch }}"
-          package_ext=".AppImage"
+          package_ext=".tar.gz"
         fi
 
         echo "Package identifier: ${package_name}"
@@ -128,10 +128,7 @@ jobs:
           librtmidi-dev \
           libsndfile1-dev \
           zlib1g-dev \
-          libjack-jackd2-dev \
-          appstream
-        wget "https://github.com/AppImage/AppImageKit/releases/download/continuous/appimagetool-x86_64.AppImage" || wget "https://tildearrow.org/storage/furnace/ci/appimagetool-x86_64.AppImage"
-        chmod +x appimagetool-x86_64.AppImage
+          libjack-jackd2-dev
 
     - name: Install Dependencies [Linux armhf]
       if: ${{ runner.os == 'Linux' && matrix.config.compiler != 'mingw' && matrix.config.arch == 'armhf' }}
@@ -151,9 +148,6 @@ jobs:
           libsndfile1-dev:armhf \
           zlib1g-dev:armhf \
           libjack-jackd2-dev:armhf
-        wget "https://github.com/AppImage/AppImageKit/releases/download/continuous/appimagetool-x86_64.AppImage" || wget "https://tildearrow.org/storage/furnace/ci/appimagetool-x86_64.AppImage"
-        wget "https://github.com/AppImage/AppImageKit/releases/download/continuous/runtime-armhf" || wget "https://tildearrow.org/storage/furnace/ci/runtime-armhf"
-        chmod +x appimagetool-x86_64.AppImage
         ls /usr/arm-linux-gnueabihf/lib
 
     - name: Configure (System Libraries)
@@ -243,6 +237,7 @@ jobs:
           -DCMAKE_INSTALL_PREFIX=/usr \
           -DCMAKE_BUILD_TYPE=${{ env.BUILD_TYPE }} \
           -DWARNINGS_ARE_ERRORS=${USE_WAE} \
+          -DWITH_DEMOS=OFF -DWITH_INSTRUMENTS=OFF -DWITH_WAVETABLES=OFF \
           "${CMAKE_EXTRA_ARGS[@]}"
 
     - name: Build
@@ -300,24 +295,37 @@ jobs:
         #  strip -s build/furnace
         #fi
 
-        mkdir -p target/furnace.AppDir
-        make -C ${PWD}/build DESTDIR=${PWD}/target/furnace.AppDir install
-        pushd target
+        mkdir -p target/furnace
+        make -C ${PWD}/build DESTDIR=${PWD}/target/furnace install
+        pushd target/furnace
+
+        cp -v ../../res/logo.png .DirIcon
+
+        cd usr
+
+        mv bin/furnace ..
+        rmdir bin
+
+        rm -r share/applications
+        rm -r share/doc
+        rm -r share/icons
+        rm -r share/licenses
+        rm -r share/metainfo
+
+        rmdir share
+
+        cd ..
+
+        cp ../../LICENSE .
+        cp ../../README.md .
+        cp -r ../../papers papers
+        rmdir usr
 
-        pushd furnace.AppDir
-        cp -v usr/share/{icons/hicolor/1024x1024/apps/furnace.png,applications/furnace.desktop} ./
-        ln -s furnace.png .DirIcon
-        mv -v usr/share/metainfo/{furnace.appdata,org.tildearrow.furnace.metainfo}.xml
-        cp -v ../../res/AppRun ./
         popd
 
-        if [ '${{ matrix.config.arch }}' == 'armhf' ]; then
-          ../appimagetool-x86_64.AppImage --runtime-file=../runtime-armhf furnace.AppDir
-        else
-          ../appimagetool-x86_64.AppImage furnace.AppDir
-        fi
-        mv Furnace-*.AppImage ../${{ steps.package-identify.outputs.filename }}
-        popd
+        cd target
+
+        tar -zcv -f ../${{ steps.package-identify.outputs.filename }} furnace
 
     - name: Upload artifact
       if: ${{ github.repository == 'tildearrow/furnace' && github.ref_name == 'master' }}

CMakeLists.txt

@@ -54,12 +54,34 @@ else()
   set(WITH_JACK_DEFAULT OFF)
 endif()
 
+set(WITH_RENDER_SDL_DEFAULT ON)
+if (APPLE)
+  set(WITH_RENDER_OPENGL_DEFAULT OFF)
+else()
+  set(WITH_RENDER_OPENGL_DEFAULT ON)
+endif()
+if (WIN32)
+  set(WITH_RENDER_DX11_DEFAULT ON)
+else()
+  set(WITH_RENDER_DX11_DEFAULT OFF)
+endif()
+
+if (ANDROID)
+  set(USE_GLES_DEFAULT ON)
+else()
+  set(USE_GLES_DEFAULT OFF)
+endif()
+
 option(BUILD_GUI "Build the tracker (disable to build only a headless player)" ${BUILD_GUI_DEFAULT})
 option(USE_RTMIDI "Build with MIDI support using RtMidi." ${USE_RTMIDI_DEFAULT})
 option(USE_SDL2 "Build with SDL2. Required to build with GUI." ${USE_SDL2_DEFAULT})
 option(USE_SNDFILE "Build with libsndfile. Required in order to work with audio files." ${USE_SNDFILE_DEFAULT})
 option(USE_BACKWARD "Use backward-cpp to print a backtrace on crash/abort." ${USE_BACKWARD_DEFAULT})
 option(WITH_JACK "Whether to build with JACK support. Auto-detects if JACK is available" ${WITH_JACK_DEFAULT})
+option(WITH_RENDER_SDL "Whether to build with the SDL_Renderer render backend." ${WITH_RENDER_SDL_DEFAULT})
+option(WITH_RENDER_OPENGL "Whether to build with the OpenGL render backend." ${WITH_RENDER_OPENGL_DEFAULT})
+option(WITH_RENDER_DX11 "Whether to build with the DirectX 11 render backend." ${WITH_RENDER_DX11_DEFAULT})
+option(USE_GLES "Use OpenGL ES for the OpenGL render backend." ${USE_GLES_DEFAULT})
 option(SYSTEM_FFTW "Use a system-installed version of FFTW instead of the vendored one" OFF)
 option(SYSTEM_FMT "Use a system-installed version of fmt instead of the vendored one" OFF)
 option(SYSTEM_LIBSNDFILE "Use a system-installed version of libsndfile instead of the vendored one" OFF)
@@ -92,12 +114,19 @@ set(DEPENDENCIES_LIBRARY_DIRS "")
 set(DEPENDENCIES_LINK_OPTIONS "")
 set(DEPENDENCIES_LEGACY_LDFLAGS "")
 
-if (BUILD_GUI)
+if (BUILD_GUI AND WITH_RENDER_SDL)
   set(SYSTEM_SDL_MIN_VER 2.0.18)
 else()
   set(SYSTEM_SDL_MIN_VER 2.0.0)
 endif()
 
+if (WIN32)
+  # support Windows XP
+  if (SUPPORT_XP)
+    add_compile_definitions("_WIN32_WINNT=0x0501")
+  endif()
+endif()
+
 list(APPEND DEPENDENCIES_INCLUDE_DIRS "extern/SAASound/include")
 list(APPEND DEPENDENCIES_INCLUDE_DIRS "extern/vgsound_emu-modified")
 
@@ -278,6 +307,12 @@ else()
   endif()
 endif()
 
+if (BUILD_GUI)
+  if (NOT WITH_RENDER_SDL AND NOT WITH_RENDER_OPENGL AND NOT WITH_RENDER_DX11)
+    message(FATAL_ERROR "No render backends selected!")
+  endif()
+endif()
+
 set(AUDIO_SOURCES
 src/audio/abstract.cpp
 src/audio/midi.cpp
@@ -557,6 +592,9 @@ src/engine/platform/dummy.cpp
 
 src/engine/export/abstract.cpp
 src/engine/export/amigaValidation.cpp
+
+src/engine/effect/abstract.cpp
+src/engine/effect/dummy.cpp
 )
 
 if (USE_SNDFILE)
@@ -578,13 +616,15 @@ extern/imgui_patched/imgui.cpp
 extern/imgui_patched/imgui_draw.cpp
 extern/imgui_patched/imgui_tables.cpp
 extern/imgui_patched/imgui_widgets.cpp
-extern/imgui_patched/backends/imgui_impl_sdlrenderer.cpp
-extern/imgui_patched/backends/imgui_impl_sdl.cpp
+extern/imgui_patched/backends/imgui_impl_sdl2.cpp
 extern/imgui_patched/misc/cpp/imgui_stdlib.cpp
 extern/igfd/ImGuiFileDialog.cpp
 
 src/gui/plot_nolerp.cpp
 
+src/gui/render.cpp
+src/gui/render/abstract.cpp
+
 src/gui/font_exo.cpp
 src/gui/font_liberationSans.cpp
 src/gui/font_mononoki.cpp
@@ -673,6 +713,47 @@ if (APPLE)
   list(APPEND GUI_SOURCES extern/nfd-modified/src/nfd_cocoa.mm)
 endif()
 
+if (WITH_RENDER_SDL)
+  list(APPEND GUI_SOURCES src/gui/render/renderSDL.cpp)
+  list(APPEND GUI_SOURCES extern/imgui_patched/backends/imgui_impl_sdlrenderer2.cpp)
+  list(APPEND DEPENDENCIES_DEFINES HAVE_RENDER_SDL)
+  message(STATUS "UI render backend: SDL_Renderer")
+endif()
+
+if (WITH_RENDER_OPENGL)
+  list(APPEND GUI_SOURCES src/gui/render/renderGL.cpp)
+  list(APPEND GUI_SOURCES extern/imgui_patched/backends/imgui_impl_opengl3.cpp)
+  list(APPEND DEPENDENCIES_DEFINES HAVE_RENDER_GL)
+  if (USE_GLES)
+    list(APPEND DEPENDENCIES_DEFINES USE_GLES)
+    list(APPEND DEPENDENCIES_DEFINES IMGUI_IMPL_OPENGL_ES2)
+  endif()
+  if (WIN32)
+    list(APPEND DEPENDENCIES_LIBRARIES opengl32)
+  elseif(USE_GLES)
+    list(APPEND DEPENDENCIES_LIBRARIES GLESv2)
+  else()
+    list(APPEND DEPENDENCIES_LIBRARIES GL)
+  endif()
+  message(STATUS "UI render backend: OpenGL")
+endif()
+
+if (WITH_RENDER_DX11)
+  if (WIN32)
+    if (SUPPORT_XP)
+      message(FATAL_ERROR "SUPPORT_XP is on. cannot enable DirectX 11 backend.")
+    else()
+      list(APPEND GUI_SOURCES src/gui/render/renderDX11.cpp)
+      list(APPEND GUI_SOURCES extern/imgui_patched/backends/imgui_impl_dx11.cpp)
+      list(APPEND DEPENDENCIES_DEFINES HAVE_RENDER_DX11)
+      list(APPEND DEPENDENCIES_LIBRARIES d3d11)
+      message(STATUS "UI render backend: DirectX 11")
+    endif()
+  else()
+    message(FATAL_ERROR "DirectX 11 render backend only for Windows!")
+  endif()
+endif()
+
 if (NOT WIN32 AND NOT APPLE)
   CHECK_INCLUDE_FILE(sys/io.h SYS_IO_FOUND)
   CHECK_INCLUDE_FILE(linux/input.h LINUX_INPUT_FOUND)
@@ -744,10 +825,6 @@ if (WIN32)
   if (NOT MSVC)
     list(APPEND DEPENDENCIES_LIBRARIES -static)
   endif()
-  # support Windows XP
-  if (SUPPORT_XP)
-    list(APPEND DEPENDENCIES_DEFINES "_WIN32_WINNT=0x0501")
-  endif()
 elseif (APPLE)
   find_library(COCOA Cocoa REQUIRED)
   list(APPEND DEPENDENCIES_LIBRARIES ${COCOA})
@@ -821,7 +898,8 @@ if (NOT ANDROID OR TERMUX)
     install(TARGETS furnace RUNTIME DESTINATION ${CMAKE_INSTALL_BINDIR})
     install(FILES res/furnace.desktop DESTINATION ${CMAKE_INSTALL_DATADIR}/applications)
     install(FILES res/furnace.appdata.xml DESTINATION ${CMAKE_INSTALL_DATADIR}/metainfo)
-    install(DIRECTORY papers DESTINATION ${CMAKE_INSTALL_DOCDIR})
+    install(DIRECTORY doc DESTINATION ${CMAKE_INSTALL_DOCDIR})
+    install(DIRECTORY papers DESTINATION ${CMAKE_INSTALL_DOCDIR}/other)
     install(FILES LICENSE DESTINATION ${CMAKE_INSTALL_DATADIR}/licenses/furnace)
     if (WITH_DEMOS)
       install(DIRECTORY demos DESTINATION ${CMAKE_INSTALL_DATADIR}/furnace)

README.md

@@ -1,17 +1,17 @@
 # Furnace (chiptune tracker)
 
-![screenshot](papers/screenshot2.png)
+![screenshot](papers/screenshot3.png)
 
 the biggest multi-system chiptune tracker ever made!
 
-[downloads](#downloads) | [discussion/help](#quick-references) | [developer info](#developer-info) | [unofficial packages](#unofficial-packages) | [FAQ](#frequently-asked-questions)
+[downloads](#downloads) | [discussion/help](#quick-references) | [developer info](#developer-info) | [Unix/Linux packages](#packages) | [FAQ](#frequently-asked-questions)
 
 ---
 ## downloads
 
 check out the [Releases](https://github.com/tildearrow/furnace/releases) page. available for Windows, macOS and Linux (AppImage).
 
-[see here](https://nightly.link/tildearrow/furnace/workflows/build/master) for unstable developer builds.
+[see here](https://nightly.link/tildearrow/furnace/workflows/build/master) for the latest unstable build.
 
 ## features
 
@@ -66,9 +66,12 @@ check out the [Releases](https://github.com/tildearrow/furnace/releases) page. a
     - Family Noraebang (OPLL)
   - SID (6581/8580) used in Commodore 64
   - Mikey used in Atari Lynx
-  - ZX Spectrum beeper (SFX-like engine)
+  - ZX Spectrum beeper
+    - SFX-like engine
+    - QuadTone engine
   - Pokémon Mini
   - Commodore PET
+  - Casio PV-1000
   - TIA used in Atari 2600
   - POKEY used in Atari 8-bit computers
   - Game Boy
@@ -80,7 +83,7 @@ check out the [Releases](https://github.com/tildearrow/furnace/releases) page. a
   - over 200 ready to use presets from computers, game consoles and arcade boards...
   - ...or create your own - up to 32 of them or a total of 128 channels!
 - DefleMask compatibility
-  - loads .dmf modules from all versions (beta 1 to 1.1.7)
+  - loads .dmf modules from all versions (beta 1 to 1.1.9)
   - saves .dmf modules - both modern and legacy
     - Furnace doubles as a module downgrader
   - loads/saves .dmp instruments and .dmw wavetables as well
@@ -116,18 +119,19 @@ check out the [Releases](https://github.com/tildearrow/furnace/releases) page. a
 ---
 # quick references
 
- - **discussion**: see the [Discussions](https://github.com/tildearrow/furnace/discussions) section, or (preferably) the [official Discord server](https://discord.gg/EfrwT2wq7z).
- - **help**: check out the [documentation](papers/doc/README.md). it's mostly incomplete, but has details on effects.
+- **discussion**: see the [Discussions](https://github.com/tildearrow/furnace/discussions) section, or the [official Discord server](https://discord.gg/EfrwT2wq7z).
+- **help**: check out the [documentation](doc/README.md). it's incomplete though.
 
-## unofficial packages
+## packages
 
 [![Packaging status](https://repology.org/badge/tiny-repos/furnace.svg)](https://repology.org/project/furnace/versions)
 
 some people have provided packages for Unix/Unix-like distributions. here's a list.
- - **Arch Linux**: [furnace](https://archlinux.org/packages/community/x86_64/furnace/) is now in the community repo!
- - **FreeBSD**: [a package in ports](https://www.freshports.org/audio/furnace/) is available courtesy of ehaupt.
- - **Nix**: [package](https://search.nixos.org/packages?channel=unstable&show=furnace&from=0&size=50&sort=relevance&type=packages&query=furnace) thanks to OPNA2608.
- - **openSUSE**: [a package](https://software.opensuse.org/package/furnace) is available, courtesy of fpesari.
+
+- **Arch Linux**: [furnace](https://archlinux.org/packages/extra/x86_64/furnace/) is in the official repositories.
+- **FreeBSD**: [a package in ports](https://www.freshports.org/audio/furnace/) is available courtesy of ehaupt (warning: 0.5.8!).
+- **Nix**: [package](https://search.nixos.org/packages?channel=unstable&show=furnace&from=0&size=50&sort=relevance&type=packages&query=furnace) thanks to OPNA2608.
+- **openSUSE**: [a package](https://software.opensuse.org/package/furnace) is available, courtesy of fpesari.
 
 ---
 # developer info
@@ -141,7 +145,9 @@ if you can't download these artifacts (because GitHub requires you to be logged
 ## dependencies
 
 - CMake
+- Git (for cloning the repository)
 - JACK (optional, macOS/Linux only)
+- a C/C++ compiler (e.g. Visual Studio or MinGW on Windows, Xcode (the command-line tools are enough) on macOS or GCC on Linux)
 
 if building under Windows or macOS, no additional dependencies are required.
 otherwise, you may also need the following:
@@ -178,10 +184,32 @@ from the developer tools command prompt:
 mkdir build
 cd build
 cmake ..
+```
+
+then open the solution file in Visual Studio and build.
+
+alternatively, do:
+
+```
 msbuild ALL_BUILD.vcxproj
 ```
 
-### macOS and Linux
+### Windows using MinGW
+
+setting up MinGW is a bit more complicated. two benefits are a faster, hotter Furnace, and Windows XP support.
+
+however, one huge drawback is lack of backtrace support, so you'll have to use gdb when diagnosing a crash.
+
+```
+mkdir build
+cd build
+cmake -G "MinGW Makefiles" ..
+mingw32-make
+```
+
+you may use "MSYS Makefiles" instead, depending on how you installed MinGW.
+
+### macOS, Linux and other Unix/Unix-like
 
 ```
 mkdir build
@@ -189,7 +217,16 @@ cd build
 cmake ..
 make
 ```
-Alternatively, build scripts are provided in the `scripts/` folder in the root of the repository.
+
+on macOS you may do the following instead:
+
+```
+mkdir build
+cd build
+cmake -G Xcode ..
+```
+
+...and then load the project on Xcode or type `xcodebuild`.
 
 ### CMake options
 
@@ -220,6 +257,8 @@ Available options:
 
 ## console usage
 
+(note: if on Windows, type `furnace.exe` instead, or `Debug\furnace.exe` on MSVC)
+
 ```
 ./furnace
 ```
@@ -238,23 +277,17 @@ this will play a compatible file.
 
 this will play a compatible file and enable the commands view.
 
-**note that these commands only actually work in Linux environments. on other command lines, such as Windows' Command Prompt, or MacOS Terminal, it may not work correctly.**
+**note that console mode may not work correctly on Windows. you may have to quit using the Task Manager.**
 
 ---
 # frequently asked questions
 
-> woah! 50 sound chips?! I can't believe it!
-
-yup, it's real.
-
-> where's the manual?
-
-see [papers/](papers/doc/README.md). it's kind of incomplete, but at least the sound chips section is there.
-
 > it doesn't open under macOS!
 
 this is due to Apple's application signing policy. a workaround is to right click on the Furnace app icon and select Open.
 
+> it says "Furnace" is damaged and can't be opened!
+
 **as of Monterey, this workaround no longer works (especially on ARM).** yeah, Apple has decided to be strict on the matter.
 if you happen to be on that version, use this workaround instead (on a Terminal):
 
@@ -266,24 +299,25 @@ xattr -d com.apple.quarantine /path/to/Furnace.app
 
 you may need to log out and/or reboot after doing this.
 
+> where's the manual?
+
+see [doc/](doc/README.md). it's kind of incomplete though.
+
+> is there a tutorial?
+
+sadly, the in-program tutorial isn't ready yet. however, [a video tutorial is available on YouTube](https://youtube.com/playlist?list=PLCELB6AsTZUnwv0PC5AAGHjvg47F44YQ1), made by Spinning Square Waves.
+
+> I've lost my song!
+
+Furnace keeps backups of the songs you've worked on before. go to **file > restore backup**.
+
 > .spc export?
 
 **not yet!** coming in 0.7 though, eventually...
 
-> how do I use C64 absolute filter/duty?
+> ROM export?
 
-on Instrument Editor in the C64 tab there are two options to toggle these.
-also provided are two effects:
-
-- `3xxx`: set fine duty.
-- `4xxx`: set fine cutoff. `xxx` range is 000-7ff.
-additionally, you can change the cutoff and/or duty as a macro inside an instrument by clicking the `absolute cutoff macro` and/or `absolute duty macro` checkbox at the bottom of the instrument. (for the filter, you also need to click the checkbox that says `volume macro is cutoff macro`.)
-
-> how do I use PCM on a PCM-capable chip?
-
-two possibilities:
-- the recommended way is by creating the "Sample" type instrument and assigning a sample to it.
-- otherwise you may employ the DefleMask-compatible method, using `17xx` effect.
+**not yet!** coming in 0.7 though, eventually...
 
 > my .dmf song sounds odd at a certain point
 
@@ -293,10 +327,6 @@ Furnace's .dmf compatibility isn't perfect and it's mostly because DefleMask doe
 
 you should only save as .dmf if you're really sure, because the DefleMask format has several limitations. save in Furnace song format instead (.fur).
 
-> how do I solo channels?
-
-right click on the channel name.
-
 ---
 # footnotes
 
@@ -309,4 +339,5 @@ This program is distributed in the hope that it will be useful, but WITHOUT ANY
 You should have received a copy of the GNU General Public License along with this program; if not, write to the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
 
 
-despite the fact this program works with the .dmf, .dmp and .dmw file formats (besides its native .fur format), it is NOT affiliated with Delek or DefleMask in any way, nor it is a replacement for the original program.
+Furnace is NOT affiliated with Delek or DefleMask in any form, regardless of its ability to load and save the .dmf, .dmp and .dmw file formats.
+additionally, Furnace does not intend to replace DefleMask, nor any other program.

TODO.md

@@ -1,6 +1,6 @@
-# to-do for 0.6pre5
+# to-do for 0.6pre6
 
-- tutorial
+- tutorial?
 - ease-of-use improvements... ideas:
   - preset compat flags
   - setting to toggle the Choose a System screen on new project
@@ -8,9 +8,9 @@
   - a more preferable highlight/drag system
   - some speed/intuitive workflow improvements that go a long way 
   - Had a hard time finding the docs on github and in Furnace's folder.
-  - make .pdf manual out of papers/doc/
-  - you're going too fast; please slow down
-  - break compatibility if it relieves complexity 
+  - make .pdf manual out of doc/
+  - you're going too slow; please run
+  - break compatibility if it relieves complexity
 - ins/wave/sample organization (folders and all)
 - multi-key binds
 - bug fixes

android/app/build.gradle

@@ -15,8 +15,8 @@ android {
         }
         minSdkVersion 21
         targetSdkVersion 26
-        versionCode 143
-        versionName "0.6pre4"
+        versionCode 158
+        versionName "0.6pre5"
         externalNativeBuild {
             cmake {
                 arguments "-DANDROID_APP_PLATFORM=android-21", "-DANDROID_STL=c++_static"

android/app/src/main/AndroidManifest.xml

@@ -1,8 +1,8 @@
 <?xml version="1.0" encoding="utf-8"?>
 <manifest xmlns:android="http://schemas.android.com/apk/res/android"
     package="org.tildearrow.furnace"
-    android:versionCode="143"
-    android:versionName="0.6pre4"
+    android:versionCode="158"
+    android:versionName="0.6pre5"
     android:installLocation="auto">
 
     <!-- OpenGL ES 2.0 -->

doc/1-intro/README.md

@@ -0,0 +1,21 @@
+# introduction
+
+Furnace is a tool which allows you to create music using sound chips ("chiptune"), most from the 8/16-bit era.
+
+it has a large selection of features and sound chips. from the NES, SNES and Genesis to ES5506, VIC-20 or even Arcade, Furnace has most likely covered your target with many presets to choose from.
+
+every chip is emulated using many emulation cores, therefore the sound that Furnace produces is authentic to that of real hardware.
+
+## hexadecimal
+
+Furnace uses hexadecimal (abbreviated as "hex") numbers frequently. see [this guide](hex.md) for a crash course.
+
+## interface
+
+Furnace uses a music tracker interface. think of a table with music notes written on it. then that table scrolls up and plays the notes.
+
+due to its nature of being feature-packed, it may be technical and somewhat difficult to get around. therefore we added a basic mode, which hides several advanced features.
+
+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.

doc/1-intro/hex.md

@@ -0,0 +1,97 @@
+# hexadecimal
+
+the hexadecimal numeral system differs from the decimal system by having 16 digits rather than 10:
+
+```
+hex| decimal
+---|---------
+ 0 | 0
+ 1 | 1
+ 2 | 2
+ 3 | 3
+ 4 | 4
+ 5 | 5
+ 6 | 6
+ 7 | 7
+ 8 | 8
+ 9 | 9
+ A | 10
+ B | 11
+ C | 12
+ D | 13
+ E | 14
+ F | 15
+```
+
+when there is more than one digit, these are multiplied by 16, 256, 4096 and so on rather than 10, 100, 1000:
+
+```
+hex | decimal
+----|---------
+ 00 | 0
+ 04 | 4
+ 08 | 8
+ 0F | 15
+ 10 | 16
+ 11 | 17
+ 12 | 18
+ 13 | 19
+ 20 | 32
+ 30 | 48
+ 40 | 64
+```
+
+# hex to decimal
+
+for example, take hexadecimal number `AA`:
+
+```
+          2nd digit -\   /- 1st digit
+                     A   A
+ 16^1*10 = 16*10 = 160 + 10 = 170
+```
+
+now for hexadecimal number `4C5F`:
+
+```
+
+      3rd digit -\    /- 2nd digit
+ 4th digit -\    |    |    /- 1st digit
+            4    C    5    F
+            |    |    |    |
+            |    |    |    15 =        15 =    15 +
+            |    |    \16^1*5 =   16 * 5  =    80
+            |    \--- 16^2*12 =  256 * 12 =  3072
+            \--------- 16^3*4 = 4096 * 4  = 16384
+                                           -------
+                                          = 19551
+```
+
+# decimal to hex
+
+if it's less than 16, just memorize the table at the top of this document.
+
+otherwise find the power of 16 that is closest to the number you want to convert, but no larger than the number.
+then divide, and take the remainder.
+divide the remainder with the previous power of 16, until the divider is 1.
+
+for example, for the decimal number `220`:
+
+```
+220 ÷ 16 = 13 (r = 12)    D
+ 12 ÷  1 = 12 (stop here) C
+
+= DC
+```
+
+now for decimal number `69420`:
+
+```
+69420 ÷ 65536 =  1 (r = 3884)  1
+ 3884 ÷  4096 =  0 (r = 3884)  0
+ 3884 ÷   256 = 15 (r =   44)  F
+   44 ÷    16 =  2 (r =   12)  2
+   12 ÷     1 = 12 (stop here) C
+
+= 10F2C
+```

doc/2-interface/README.md

@@ -0,0 +1,41 @@
+# interface
+
+the Furnace user interface is where the job gets done.
+
+the default layout of Furnace is depicted below.
+
+![interface](interface1.png)
+
+primary topics:
+
+- [menu bar](menu-bar.md)
+- [play/edit controls](play-edit-controls.md)
+- [instrument/wavetable/sample list](asset-list.md)
+- [song information](song-info.md)
+- [pattern view](../3-pattern/README.md)
+- [instrument editor](../4-instrument/README.md)
+- [wavetable editor](../5-wave/README.md)
+- [sample editor](../6-sample/README.md)
+
+advanced topics:
+
+- [mixer](../8-advanced/mixer.md)
+- [grooves](../8-advanced/grooves.md)
+- [channels](../8-advanced/channels.md)
+- [pattern manager](../8-advanced/pat-manager.md)
+- [chip manager](../8-advanced/chip-manager.md)
+- [compatibility flags](../8-advanced/compat-flags.md)
+- [song comments](../8-advanced/comments.md)
+- [piano/input pad](../8-advanced/piano.md)
+- [oscilloscope](../8-advanced/osc.md)
+- [oscilloscope (per channel)](../8-advanced/chanosc.md)
+- [clock](../8-advanced/clock.md)
+- [register view](../8-advanced/regview.md)
+- [log viewer](../8-advanced/log-viewer.md)
+- [statistics](../8-advanced/stats.md)
+
+other topics:
+
+- [UI components](components.md)
+- [global keyboard shortcuts](keyboard.md)
+- [basic mode](basic-mode.md)

doc/2-interface/asset-list.md

@@ -0,0 +1,38 @@
+# instrument list
+
+![instruments window](instruments.png)
+
+Buttons from left to right:
+- **Add:** Creates a new, default instrument.
+- **Duplicate:** Duplicates the currently selected instrument.
+- **Open:** Brings up a file dialog to load a file as a new instrument at the end of the list.
+- **Save:** Brings up a file dialog to save the currently selected instrument.
+- **Toggle folders/standard view:** Enables (and disables) folder view, explained below.
+- **Move up:** Moves the currently selected instrument up in the list. Pattern data will automatically be adjusted to match.
+- **Move down:** Same, but downward.
+- **Delete:** Deletes the currently selected instrument. Pattern data will be adjusted to use the next available instrument in the list.
+
+## folder view
+
+![instruments window in folder view](instruments-folder.png)
+
+In folder view, the "Move up" and "Move down buttons disappear and a new one appears:
+- **New Folder:** Creates a new folder.
+
+Instruments may be dragged from folder to folder and even rearranged within folders without changing their associated numbers.
+
+Right-clicking on a folder allows one to rename or delete it. Deleting a folder does not remove the instruments in it.
+
+# wavetable list
+
+![wavetables window](wavetables.png)
+
+Everything from the instrument list applies here also, with one major difference: Moving waves around with the buttons will change their associated numbers in the list but _not_ in pattern or instrument data. Be careful!
+
+# sample list
+
+![samples window](samples.png)
+
+Everything from the wavetables list applies here also, with the addition of two buttons:
+- **Preview:** Plays the selected sample at its default note.
+- **Stop preview:** Stops the sample playback.

doc/2-interface/components.md

@@ -4,14 +4,14 @@ the user interface consists of several components. this paper describes some of
 
 ## windows
 
-TODO: image
+![window](window.png)
 
 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.
 then drag your mouse, and release it to stop moving.
 
-to resize a window, drag any of the bottom corners (marked by triangular tabs).
+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.
@@ -24,33 +24,40 @@ windows may be docked, which comes in handy.
 
 to dock a window, drag it from its title bar to another location in the workspace or to the location of another window.
 
-while dragging, an overlay with five options will appear, allowing you to select where and how to dock that window.
+while dragging, an overlay with some options will appear, allowing you to select where and how to dock that window.
 the options are:
 
-```
-        UP
- LEFT CENTER RIGHT
-       DOWN
-```
+![docking options](docking.png)
 
 drag your mouse cursor to any of the options to dock the window.
 
-if you drag the window to `CENTER`, the window will be maximized to cover the workspace (if you do this on the workspace), or it will appear as another tab (if you do this on a window).
+if you drag to the sides (marked with blue text), the window will cover that side of the workspace.
+
+if you drag it to a window or empty space (marked with yellow text), five docking positions will appear.
+
+if you drag the window to the center of another window, it will appear as another tab.
+
+if you drag the window to the center of empty space, the window will cover aforementioned empty space.
 
 otherwise the window will be split in two, with the first half covered by the window you docked and the second half covered by the other window.
 
+![tab1](tab1.png)
+
 when a window is docked, its title bar turns into a tab bar, and the function provided by the "collapse" triangle at the top left changes.
 
-if this triangle is clicked, a menu will appear with a single option: "Hide tab bar".
+![tab2](tab2.png)
+
+if this triangle is clicked, a menu will appear with a list of tabs, or a single option if there's only one tab: "Hide tab bar".
 selecting this option will hide the tab bar of that window.
+
+![tab3](tab3.png)
+
 to bring it back, click on the top left corner.
 
 to undock a window, drag its tab away from where it is docked. then it will be floating again.
 
 ## text fields
 
-TODO: image
-
 text fields are able to hold... text.
 
 click on a text field to start editing, and click away to stop editing.
@@ -60,24 +67,18 @@ the following keyboard shortcuts work while on a text field:
 - `Ctrl-X`: cut
 - `Ctrl-C`: copy
 - `Ctrl-V`: paste
-- `Ctrl-Z`: undo
-- `Ctrl-Y`: redo
 - `Ctrl-A`: select all
 
 (replace Ctrl with Command on macOS)
 
 ## number input fields
 
-TODO: image
-
 these work similar to text fields, but you may only input numbers.
 
 they also usually have two buttons which allow you to increase/decrease the amount when clicked (and rapidly do so when click-holding).
 
 ## sliders
 
-TODO: image
-
 sliders are used for controlling values in a quick manner by being dragged.
 
 alternatively, 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 fine values.

doc/2-interface/menu-bar.md

@@ -0,0 +1,226 @@
+# menu bar
+
+the menu bar allows you to select five menus: file, edit, settings, window and help.
+
+# file
+
+- **new...**: create a new song.
+- **open...**: opens the file picker, allowing you to select a song to open.
+- **open recent**: contains a list of the songs you've opened before.
+  - **clear history**: this option erases the file history.
+- **save**: saves the current song.
+  - opens the file picker if this is a new song, or a backup.
+- **save as...**: opens the file picker, allowing you to save the song under a different name.
+- **save as .dmf (1.1.3+)...**: opens the file picker, allowing you to save your song as a .dmf which is compatible with DefleMask 1.1.3 onwards.
+  - this will only work with the systems mentioned in the next option, plus:
+    - Sega Master System (with FM expansion)
+    - NES + Konami VRC7
+    - Famicom Disk System
+  - only use this option if you really need it. there are features which DefleMask does not support, like some effects and FM macros, so these will be lost.
+- **save as .dmf (1.0/legacy)...**: opens the file picker, allowing you to save your song as a .dmf which is compatible with DefleMask Legacy (0.12) or 1.0.
+  - this will only work on the following systems:
+    - Sega Genesis/Mega Drive (YM2612 + SN76489)
+    - Sega Genesis/Mega Drive (YM2612 + SN76489, extended channel 3)
+    - Sega Master System
+    - Game Boy
+    - PC Engine
+    - NES
+    - Commodore 64
+    - Arcade (YM2151 + SegaPCM 5-channel compatibility)
+    - Neo Geo CD (DefleMask 1.0+)
+  - only use this option if you really need it. there are features which DefleMask does not support, like some effects and FM macros, so these will be lost.
+- **export audio...**: export your song to a .wav file. see next section for more details.
+- **export VGM...**: export your song to a .vgm file. see next section for more details.
+- **export ZSM...**: 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.
+  - this option is for developers.
+- **add chip...**: add a chip to the current song.
+- **configure chip...**: set a chip's parameters.
+  - for a list of parameters, see [7-systems](../7-systems/README.md).
+- **change chip...**: change a chip to another.
+  - **Preserve channel positions**: enable this option to make sure Furnace does not auto-arrange/delete channels to compensate for differing channel counts. this can be useful for doing ports, e.g. from Genesis to PC-98.
+- **remove chip...**: remove a chip.
+  - **Preserve channel positions**: same thing as above.
+- **restore backup**: restore a previously saved backup.
+  - Furnace keeps up to 5 backups of a song.
+  - the backup directory is located in:
+    - Windows: `%USERPROFILE%\AppData\Roaming\furnace\backups`
+    - macOS: `~/Library/Application Support/Furnace/backups`
+    - Linux/other: `~/.config/furnace/backups`
+  - this directory grows in size as you use Furnace. remember to delete old backups periodically to save space.
+- **exit**: I think you know what this does.
+
+## export audio
+
+this option allows you to export your song in .wav format. I know I know, no .mp3 or .ogg export yet, but you can use a converter.
+
+there are two parameters:
+
+- **Loops**: sets the number of times the song will loop.
+  - does not have effect if the song ends with `FFxx` effect.
+- **Fade out (seconds)**: sets the fade out time when the song is over.
+  - does not have effect if the song ends with `FFxx` effect.
+
+and three export choices:
+
+- **one file**: exports your song to one .wav file.
+- **multiple files (one per chip)**: exports the output of each chip to .wav files.
+- **multiple files (one per channel)**: exports the output of each channel to .wav files.
+  - useful for usage with a channel visualizer such as corrscope.
+
+## export VGM
+
+this option allows exporting to a VGM (Video Game Music) file. these can be played back with VGMPlay (for example).
+
+the following settings exist:
+
+- **format version**: sets the VGM format version to use.
+  - versions under 1.70 do not support per-chip volumes, and therefore will ignore the Mixer completely.
+  - other versions may not support all chips.
+  - use this option if you need to export for a quirky player or parser.
+    - for example, RYMCast is picky with format versions. if you're going to use this player, select 1.60.
+- **loop**: writes loop. if disabled, the resulting file won't loop.
+- **loop trail**: this option allows you to set how much of the song is written after it loops.
+  - the reason this exists is to work around a VGM format limitation in where post-loop state isn't recorded at all.
+  - this may change the song length as it appears on a player.
+  - **auto-detect**: detect how much to write automatically.
+  - **add one loop**: add one more loop.
+  - **custom**: allows you to specify how many ticks to add.
+    - `0` is effectively none, disabling loop trail completely.
+  - this option will not appear if the loop modality isn't set to None as there wouldn't be a need to.
+- **chips to export**: select which chips are going to be exported.
+  - due to VGM format limitations, you can only select up to two of each chip type.
+  - some chips will not be available, either because VGM doesn't support these yet, or because you selected an old format version.
+- **add pattern change hints**: this option adds a "hint" when a pattern change occurs. only useful if you're a developer.
+  - the format of the "hint" data block that gets written is: `67 66 FE ll ll ll ll 01 oo rr pp pp pp ...`
+    - ll: length, a 32-bit little-endian number
+    - oo: order
+    - rr: initial row (a 0Dxx effect is able to select a different row)
+    - pp: pattern index (one per channel)
+- **direct stream mode**: this option allows DualPCM to work. don't use this for other chips.
+  - may or may not play well with hardware VGM players.
+
+click on **click to export** to begin exporting.
+
+## export ZSM
+
+ZSM (ZSound Music) is a format designed for the Commander X16 to allow hardware playback.
+it may contain data for either YM2151 or VERA chips.
+Calliope is one of the programs that supports playback of ZSM files.
+
+the following settings are available:
+
+- **Tick Rate (Hz)**: select the tick rate the song will run at.
+  - I suggest you use the same rate as the song's.
+  - apparently ZSM doesn't support changing the rate mid-song.
+- **loop**: enables loop. if disabled, the song won't loop.
+
+click on **Begin Export** to... you know.
+
+## export command stream
+
+this option exports a text or binary file which contains a dump of the internal command stream produced when playing the song.
+
+it's not really useful, unless you're a developer and want to use a command stream dump for some reason (e.g. writing a hardware sound driver).
+
+- **export (binary)**: exports in Furnace's own command stream format (FCS). see `export-tech.md` in `papers/` for details.
+- **export (text)**: exports the command stream as a text file. only useful for analysis, really.
+
+# edit
+
+- **undo**: reverts the last action.
+- **redo**: repeats what you undid previously.
+- **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.
+- **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.
+  - **paste with ins (foreground)**: same thing as paste mix, but changes the instrument.
+  - **paste with ins (background)**: same thing as paste mix (background), but changes the instrument.
+  - **paste flood**: inserts the clipboard's contents in the cursor position, and repeats until it hits the end of a pattern.
+  - **paste overflow**: paste, but it will keep pasting even if it runs over another pattern.
+- **delete**: clears the contents in the selection.
+- **select all**: changes the selection so it covers a larger area.
+  - if the selection is wide, it will select the rows in a column.
+  - if the selection is tall, it will select the entire column.
+  - if a column is already selected, it will select the entire channel.
+  - if a channel is already selected, it will select the entire pattern.
+- **operation mask**: this is an advanced feature. see [this page](../3-pattern/opmask.md) for more information.
+- **input latch**: this is an advanced feature. see [this page](../3-pattern/inputlatch.md) for more information.
+- **note/octave up/down**: transposes notes in the current selection.
+- **values up/down**: changes values in the current selection by ±1 or ±16.
+- **transpose**: transpose notes or change values by a specific amount.
+- **interpolate**: fills in gaps in the selection by interpolation between values.
+- **change instrument**: changes the instrument number in a selection.
+- **gradient/fade**: replace the selection with a "gradient" that goes from the beginning of the selection to the end.
+  - does not affect the note column.
+  - **Nibble mode**: when enabled, the fade will be per-nibble (0 to F) rather than per-value (00 to FF).
+    - use for effects like `04xy` (vibrato).
+- **scale**: scales values in the selection by a specific amount.
+  - use to change volume in a selection for example.
+- **randomize**: replaces the selection with random values.
+  - does not affect the note column.
+- **invert values**: `00` becomes `FF`, `01` becomes `FE`, `02` becomes `FD` and so on.
+- **flip selection**: flips the selection so it is backwards.
+- **collapse/expand amount**: allows you to specify how much to collapse/expand in the next options.
+- **collapse**: shrinks the selected contents.
+- **expand**: expands the selected contents.
+- **collapse pattern**: same as collapse, but affects the entire pattern.
+- **expand pattern**: same as expand, but affects the entire pattern.
+- **collapse song**: same as collapse, but affects the entire song.
+  - it also changes speeds and pattern length to compensate.
+- **expand song**: same as expand, but affects the entire song.
+  - it also changes speeds and pattern length to compensate.
+- **find/replace**: opens the Find/Replace window. see [this page](../3-pattern/find-replace.md) for more information.
+- **clear**: allows you to mass-delete things like songs, instruments and the like.
+
+# settings
+
+- **full screen**: expands the Furnace window so it covers your screen.
+- **lock layout**: prevents you from dragging/resizing docked windows, or docking more.
+- **basic mode**: toggles [Basic Mode](basic-mode.md).
+- **visualizer**: toggles pattern view particle effects when the song plays.
+- **reset layout**: resets the workspace to its defaults.
+- **settings...**: opens the Settings window.
+
+# window
+
+- **song information**: shows/hides the Song Information window.
+- **subsongs**: shows/hides the Subsongs window.
+- **speed**: shows/hides the Speed window.
+- **instruments**: shows/hides the instrument list.
+- **wavetables**: shows/hides the wavetable list.
+- **samples**: shows/hides the sample list.
+- **orders**: shows/hides the Orders window.
+- **pattern**: shows/hides the pattern view.
+- **mixer**: shows/hides the Mixer window.
+- **grooves**: shows/hides the Grooves window.
+- **channels**: shows/hides the Channels window.
+- **pattern manager**: shows/hides the Pattern Manager window.
+- **chip manager**: shows/hides the Chip Manager window.
+- **compatibility flags**: shows/hides the Compatibility Flags window.
+- **song comments**: shows/hides the Song Comments window.
+- **instrument editor**: shows/hides the Instrument Editor.
+- **wavetable editor**: shows/hides the Wavetable Editor.
+- **sample editor**: shows/hides the Sample Editor.
+- **play/edit controls**: shows/hides the Play/Edit Controls.
+- **piano/input pad**: shows/hides the Piano/Input Pad window.
+- **oscilloscope (master)**: shows/hides the oscilloscope.
+- **oscilloscope (per-channel)**: shows/hides the per-channel oscilloscope.
+- **volume meter**: shows/hides the volume meter.
+- **clock**: shows/hides the clock.
+- **register view**: shows/hides the Register View window.
+- **log viewer**: shows/hides the log Viewer.
+- **statistics**: shows/hides the Statistics window.
+
+# help
+
+- **effect list**: displays the effect list.
+- **debug menu**: this menu contains various debug utilities.
+  - unless you are working with the Furnace codebase, it's not useful.
+- **inspector**: this options opens the Dear ImGui Metrics/Debugger window.
+  - unless you are working with the Furnace codebase, it's not useful.
+- **panic**: this resets all chips while the song is playing, effectively silencing everything.
+- **about...**: displays the About screen.

doc/2-interface/play-edit-controls.md

@@ -0,0 +1,37 @@
+# play/edit controls
+
+The "Play/Edit Controls" are used to control playback and change parameters of the pattern view.
+
+- ![](control-play.png) **Play:** Plays from cursor position.
+- ![](control-stop.png) **Stop:** Stops all playback.
+- ![](control-play-pattern.png) **Play from the beginning of this pattern:** Plays from the start of current pattern.
+- ![](control-play-repeat.png) **Repeat from the beginning of this pattern:** Repeats current pattern from its start.
+- ![](control-step.png) **Step one row:** Plays only the row at cursor position and moves down one.
+- ![](control-edit.png) **Edit:** Toggles edit mode. If off, nothing can be edited in the pattern window. (Great for playing around on the keyboard!)
+- ![](control-metronome.png) **Metronome:** Toggles the metronome, which only sounds during playback.
+- ![](control-repeat.png) **Repeat pattern:** Toggles pattern repeat. During playback while this is on, the current pattern will play over and over instead of following the order list.
+- **Poly:** Turns on polyphony for previewing notes. Toggles to **Mono** for monophony (one note at a time only).
+- **Octave:** Sets current input octave.
+- **Step:** Sets edit step. If this is 1, entering a note or effect will move to the next row. If this is a larger number, rows will be skipped. If this is 0, the cursor will stay in place.
+- **Follow orders:** If on, the selected order in the orders window will follow the song during playback.
+- **Follow pattern:** If on, the cursor will follow playback and the song will scroll by as it plays.
+
+## layouts
+
+The layout can be changed in Settings > Appearance to one of these:
+
+### classic
+
+![classic play/edit controls](controls-classic.png)
+
+### compact
+
+![compact play/edit controls](controls-compact.png)
+
+### compact (vertical)
+
+![compact vertical play/edit controls](controls-vertical.png)
+
+### split
+
+![split play and edit controls](controls-split.png)

doc/2-interface/song-info.md

@@ -0,0 +1,49 @@
+# song info
+
+- "Name" is for the track's title.
+- "Author" is used to list the contributors to a song. If the song is a cover of someone else's track, it's customary to list their name first, followed by `[cv. YourName]`.
+- "Album" can be used to store the associated album name, the name of the game the song is from, or whatever.
+- "System" is for the game or computer the track is designed for. This is automatically set when creating a new tune, but it can be changed to anything one wants. The "Auto" button will provide a guess based on the chips in use.
+
+All of this metadata will be included in a VGM export. This isn't the case for a WAV export, however.
+
+"Tuning (A-4)" allows one to set tuning based on the note A-4, which should be 440 in most cases. Opening an Amiga MOD will set it to 436 for hardware compatibility.
+
+# subsongs
+
+This window allows one to create **subsongs** – multiple individual songs within a single file. Each song has its own order list and patterns, but all songs within a file share the same chips, samples, and so forth.
+
+- The drop-down box selects the current subsong.
+- The `+` button adds a new subsong.
+- The `−` button permanently deletes the current subsong (unless it's the only one).
+- "Name" sets the title of the current subsong.
+- The box at the bottom can store any arbitrary text, like a separate "Comments" box for the current subsong.
+
+# speed
+
+There are multiple ways to set the tempo of a song.
+
+**Tick Rate** sets the frequency of ticks per second, the rate at which notes and effects are processed.
+- All values are allowed for all chips, but most chips have hardware limitations that mean they should stay at either 60 (approximately NTSC) or 50 (exactly PAL).
+- Clicking the Tick Rate button switches to a more traditional **Base Tempo** BPM setting.
+
+**Speed** sets the number of ticks per row.
+- Clicking the "Speed" button changes to more complex modes covered in the [grooves] page.
+
+**Virtual Tempo** simulates any arbitrary tempo without altering the tick rate. It does this by adding or skipping ticks to approximate the tempo. The two numbers represent a ratio applied to the actual tick rate. Example:
+- Set tick rate to 150 BPM (60 Hz) and speed to 6.
+- Set the first virtual tempo number (numerator) to 200.
+- Set the second virtual tempo number (denominator) to 150.
+- The track will play at 200 BPM.
+- The ratio doesn't have to match BPM numbers. Set the numerator to 4 and the denominator to 5, and the virtual BPM becomes 150 × 4/5 = 120.
+
+**Divider** changes the effective tick rate. A tick rate of 60Hz and a divisor of 6 will result in ticks lasting a tenth of a second each!
+
+**Highlight** sets the pattern row highlights:
+- The first value represents the number of rows per beat.
+- The second value represents the number of rows per measure.
+- These don't have to line up with the music's actual beats and measures. Set them as preferred for tracking. _Note:_ These values are used for the metronome and calculating BPM.
+
+**Pattern Length** is the length of each pattern in rows. This affects all patterns in the song, and every pattern must be the same length. (Individual patterns can be cut short by `0Bxx`, `0Dxx`, and `FFxx` commands.)
+
+**Song Length** shows how many orders are in the order list. Decreasing it will hide the orders at the bottom. Increasing it will restore those orders; increasing it further will add new orders of all `00` patterns.

doc/4-instrument/8930.md

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

doc/4-instrument/README.md

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

doc/4-instrument/amiga.md

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

doc/4-instrument/ay8910.md

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

doc/4-instrument/c64.md

@@ -1,12 +1,13 @@
 # C64 SID instrument editor
 
-C64 instrument editor consists of two tabs: one controlling various parameters of sound channels and macro tab containing seven macros:
+The C64 instrument editor consists of two tabs: "C64" to control various parameters of sound channels, and "Macros" containing several macros.
 
 ## C64
+
 - [Waveform] - allows selecting a waveform. NOTE: more than one waveform can be selected at once, logical AND mix of waves will be produced, with an exception of a noise waveform, it can't be mixed.
 - [Attack] - determines the rising time for the sound. The bigger the value, the slower the attack. (0-15 range)
 - [Decay]- Determines the diminishing time for the sound. The higher the value, the longer the decay. It's the initial amplitude decay rate. (0-15 range)
-- [Sustain] - Determines the diminishing time for the sound. The higher the value, the longer the decay. This is the long "tail" of the sound that continues as long as the key is depressed. (0-15 range)
+- [Sustain] - Sets the volume level at which the sound stops decaying and holds steady. (0-15 range)
 - [Release] - Determines the rate at which the sound disappears after KEY-OFF. The higher the value, the longer the release. (0-15 range)
 - [Ring Modulation] - enables the ring modulation affecting the instrument.
 - [Duty] - specifies the width of a pulse wave. (0-4095 range)
@@ -15,16 +16,20 @@ C64 instrument editor consists of two tabs: one controlling various parameters o
 - [Initialize filter] - initializes the filter with the specified parameters:
 - [Cutoff] - defines the "intensity" of a filter, to put in in layman terms (0-2047 range)
 - [Resonance] - defines an additional controlled amplification of that cutoff frequency, creating a secondary peak forms and colors the original pitch. (0-15 range)
-- [Filter mode] - determined the filter mode NOTE: SID's filter is muliti-mode, you can mix different modes together (like low and high-pass filters at once) CH3-OFF disables the channel 3, for no reason whatsoever lmao
-- [Volume Macrio is a Cutoff macro] - turns a volume macro in a macros tab into a filter cutoff macro.
-- [Absolute Cutoff macro] - changes the behaviour of a cutoff macro from the old-style, compatible to much more define-able.
-- [Absolute Duty macro] - changes the behaviour of a duty cycle macro from the old-style, compatible to much more define-able.
+- [Filter mode] - determined the filter mode NOTE: SID's filter is multi-mode, you can mix different modes together (like low and high-pass filters at once) CH3-OFF disables the channel 3, for no reason whatsoever lmao
+- [Volume Macro is Cutoff Macro] - turns a volume macro in a macros tab into a filter cutoff macro.
+- [Absolute Cutoff Macro] - changes the behaviour of a cutoff macro from the old-style, compatible to much more define-able.
+- [Absolute Duty Macro] - changes the behaviour of a duty cycle macro from the old-style, compatible to much more definable.
+- [Don't test/gate before new note] - Don't reset the envelope to zero when a new note starts. (Read "Test/Gate" below for more info.)
 
 ## Macros
-- [Volume/Cutoff] - volume sequence (WARNING: Volume sequence is global for ALL three channels!!)
+
+- [Volume] - volume sequence (WARNING: Volume sequence is global for ALL three channels!!)
 - [Arpeggio] - pitch sequence
-- [Duty cycle] - pulse duty cycle sequence
+- [Duty] - pulse duty cycle sequence
 - [Waveform] - select the waveform used by instrument
-- [Filter mode] - select the filter mode/squence
+- [Pitch] - fine pitch
+- [Filter mode] - select the filter mode/sequence
 - [Resonance] - filter resonance sequence
 - [Special] - ring and oscillator sync selector
+- [Test/Gate] - When on, the TEST bit resets and locks Oscillator 1 at zero until cleared. The GATE bit controls Oscillator 1's envelope: Gate on runs through the envelope's attack, delay, and sustain; Gate off is envelope release.

doc/4-instrument/fm.md

@@ -8,11 +8,11 @@ FM editor is divided into 7 tabs:
 - [Macros (OP2)] - for macros controlling FM paramets of operator 2
 - [Macros (OP3)] - for macros controlling FM paramets of operator 3
 - [Macros (OP4)] - for macros controlling FM paramets of operator 4
-- [Macros] - for miscellanous macros controlling volume, argeggio and YM2151 noise generator.
+- [Macros] - for miscellaneous macros controlling volume, argeggio and YM2151 noise generator.
 
 ## FM
 
-FM synthesizers Furnace supports are for-operator, meaning it takes four oscillators to produce a single sound. Each operator is controlled by a dozen of sliders:
+FM synthesizers Furnace supports are four-operator, meaning it takes four oscillators to produce a single sound. Each operator is controlled by a dozen sliders:
 
 - [Attack Rate (AR)] - determines the rising time for the sound. The bigger the value, the faster the attack. (0-31 range)
 - [Decay Rate (DR)]- Determines the diminishing time for the sound. The higher the value, the shorter the decay. It's the initial amplitude decay rate. (0-31 range)
@@ -21,7 +21,7 @@ FM synthesizers Furnace supports are for-operator, meaning it takes four oscilla
 - [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)
 - [Total Level (TL)] - Represents the envelope’s highest amplitude, with 0 being the largest and 127 (decimal) the smallest. A change of one unit is about 0.75 dB.
 - [Envelope Scale (KSR)] - A parameter that determines the degree to which the envelope execution speed increases according to the pitch. (0-3 range)
-- [Frequency Multiplier (MULT)] - Determines the operator frequncy in relation to the pitch. (0-15 range)
+- [Frequency Multiplier (MULT)] - Determines the operator frequency in relation to the pitch. (0-15 range)
 - [Fine Detune (DT)] - Shifts the pitch a little (0-7 range)
 - [Coarse Detune (DT2)] - Shifts the pitch by tens of cents (0-3 range) WARNING: this parameter affects only YM2151 sound source!!!
 - [Hardware Envelope Generator (SSG-EG)] - Executes the built-in envelope, inherited from AY-3-8910 PSG. Speed of execution is controlled via Decay Rate. WARNING: this parameter affects only YM2610/YM2612 sound source!!!
@@ -33,14 +33,14 @@ FM synthesizers Furnace supports are for-operator, meaning it takes four oscilla
 
 ## Macros
 
-Macros define the squence of values passed to the given parameter. Via macro, aside previously mentioned parameters, the following can be controlled:
+Macros define the sequence of values passed to the given parameter. Via macro, aside previously mentioned parameters, the following can be controlled:
 
 - LFO Frequency
 - LFO waveform selection WARNING: this parameter affects only YM2151 sound source!!!
 - Amplitude Modulation Depth WARNING: this parameter affects only YM2151 sound source!!!
 - Frequency Modulation Depth WARNING: this parameter affects only YM2151 sound source!!!
 - Arpeggio Macro: pitch change sequence in semitones. Two modes are available:  
-Absolute (defult) - Executes the pitch with absolute change based on the pitch of the actual note.
+Absolute (default) - Executes the pitch with absolute change based on the pitch of the actual note.
 Fixed - Executes at the pitch specified in the sequence regardless of the note pitch.
 - Noise Frequency: specifies the noise frequency in noise mode of YM2151's Channel 8 Operator 4 special mode.
 

doc/4-instrument/game-boy.md

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

doc/4-instrument/lynx.md

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

doc/4-instrument/n163.md

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

doc/4-instrument/pce.md

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

doc/4-instrument/saa.md

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

doc/4-instrument/scc.md

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

doc/4-instrument/standard.md

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

doc/4-instrument/tia.md

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

doc/4-instrument/vera.md

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

doc/4-instrument/vrc6.md

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

doc/5-wave/README.md

@@ -6,7 +6,11 @@ Furnace's wavetable editor is rather simple, you can draw the waveform using mou
 
 Furnace's wavetable editor features multiple ways of creating desired waveform shape:
 
-- Shape tab allows you to select a few predefined basic shapes and indirectly edit it via "Duty", "Exponent" and "XOR Point" sliders TODO: what the last two are doing? What is amplitude/phase for?)
+- Shape tab allows you to select a few predefined basic shapes and indirectly edit it via "Duty", "Exponent" and "XOR Point" sliders:
+  - `Duty` slider affects mainly pulse waves, determining its wisth, like on C64/VRC6
+  - `Exponent` powers the waveform in the mathematical sense of the word (^2, ^3 and so on)
+  - `XOR Point` determines the point where the waveform gets negated.
+  - TODO: amplitude/phase part
 - FM is for creating the waveform with frequency modulation synthesis principles: One can set carrier/modulation levels, frquency multiplier, connection between operators and FM waveforms of these operators.
 - WaveTools allows user to fine-tune the waveform: scale said waveform in both X and Y axes, smoothen, amplify, normalize, convert to signed/unisgned, invert or even randomize the wavetable.
 

doc/6-sample/README.md

@@ -1,6 +1,6 @@
 # samples
 
-In the context of Furnace, a sound sample (usually just referred to as a sample) is a string of numbers that hold sampled PCM audio.
+In the context of Furnace, a sound sample (usually just referred to as a sample) is a string of numbers that represent sampled PCM audio.
 
 In Furnace, these samples can be generated by importing a .wav (think of it as an higher quality MP3) file.
 
@@ -13,6 +13,7 @@ as of Furnace 0.6, the following sound chips have sample support:
 - PC Engine/TurboGrafx-16/HuC6280
 - Amiga/Paula
 - SegaPCM
+- NEC PC-9801/YM2608 (ADPCM channel only)
 - Neo Geo/Neo Geo CD/YM2610 (ADPCM channels only)
 - Seta/Allumer X1-010
 - Atari Lynx
@@ -21,12 +22,16 @@ as of Furnace 0.6, the following sound chips have sample support:
 - QSound
 - ZX Spectrum 48k (1-bit)
 - RF5C68
-- WonderSwan
+- SNES/S-DSP
+- WonderSwan (second channel only)
 - tildearrow Sound Unit
 - VERA (last channel only)
 - Y8950 (last channel only)
 - Konami K007232
-- a few more that I've forgotten to mention
+- Irem GA20
+- Ensoniq OTTO/ES5506
+- Yamaha PCMD8/YMZ280B
+- MMC5 (last channel only)
 
 ## compatible sample mode
 
@@ -45,9 +50,9 @@ due to limitations in some of those sound chips, some restrictions exist:
 - NES: if on DPCM mode, only a limited selection of frequencies is available, and loop position isn't supported (only entire sample).
 - SegaPCM: your sample can't be longer than 65535, and the maximum frequency is 31.25KHz.
 - QSound: your sample can't be longer than 65535, and the loop length shall not be greater than 32767.
-- Neo Geo (ADPCM-A): no looping supported. your samples will play at ~18.5KHz.
-- Neo Geo (ADPCM-B): no loop position supported (only entire sample), and the maximum frequency is ~55KHz.
-- YM2608: the maximum frequency is ~55KHz.
+- Neo Geo (ADPCM-A): no looping supported. your samples will play at 18.518KHz.
+- Neo Geo (ADPCM-B): no loop position supported (only entire sample), and the maximum frequency is 55.555KHz.
+- YM2608: the maximum frequency is 55.555KHz.
 - MSM6258/MSM6295: no arbitrary frequency.
 - ZX Spectrum Beeper: your sample can't be longer than 2048, and it always plays at ~55KHz.
 - Seta/Allumer X1-010: frequency resolution is terrible in the lower end. your sample can't be longer than 131072.
@@ -64,4 +69,4 @@ In there, you can modify certain data pertaining to your sample, such as the:
  - what frequencies to filter, along with filter level/sweep and resonance options (much like the C64)
  - and many more.
 
-The changes you make will be applied as soon as you've committed them to your sample, but they can be undoed and redoed, just like text.
+The changes you make will be applied as soon as you've committed them to your sample, but they can be undone and redoed, just like text.

doc/7-systems/README.md

@@ -38,11 +38,11 @@ this is a list of sound chips that Furnace supports, including effects.
 - [VERA](vera.md)
 - [WonderSwan](wonderswan.md)
 - [Virtual Boy](virtual-boy.md)
-- [Yamaha OPLL](opll.md)
+- [Yamaha YM2413 (OPLL)](opll.md)
 - [Yamaha OPL](opl.md)
 - [Yamaha YM2151](ym2151.md)
 - [Yamaha YM2203](ym2203.md)
-- [Yamaha YM2413](opz.md)
+- [Yamaha YM2414 (OPZ)](opz.md)
 - [Yamaha YM2608](ym2608.md)
 - [Neo Geo/YM2610](ym2610.md)
 - [Taito Arcade/YM2610B](ym2610b.md)