Merge branch 'master' into effects

.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,28 @@ 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 (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(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,7 +108,7 @@ 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)
@@ -278,6 +294,12 @@ else()
   endif()
 endif()
 
+if (BUILD_GUI)
+  if (NOT WITH_RENDER_SDL AND NOT WITH_RENDER_OPENGL)
+    message(FATAL_ERROR "No render backends selected!")
+  endif()
+endif()
+
 set(AUDIO_SOURCES
 src/audio/abstract.cpp
 src/audio/midi.cpp
@@ -583,13 +605,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/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
@@ -678,6 +702,31 @@ 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_sdlrenderer.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 (NOT WIN32 AND NOT APPLE)
   CHECK_INCLUDE_FILE(sys/io.h SYS_IO_FOUND)
   CHECK_INCLUDE_FILE(linux/input.h LINUX_INPUT_FOUND)
@@ -826,7 +875,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,10 +1,10 @@
 # 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
@@ -83,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
@@ -119,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/extra/x86_64/furnace/) is now 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.
+
+- **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
@@ -144,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:
@@ -181,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
@@ -192,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
 
@@ -223,6 +257,8 @@ Available options:
 
 ## console usage
 
+(note: if on Windows, type `furnace.exe` instead, or `Debug\furnace.exe` on MSVC)
+
 ```
 ./furnace
 ```
@@ -241,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):
 
@@ -269,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
 
@@ -296,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
 
@@ -312,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

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,11 @@
+# instrument list
+
+image
+
+# wavetable list
+
+image
+
+# sample list
+
+image

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,23 @@
+# play/edit controls
+
+image
+
+these are used to control playback and change parameters of the pattern view.
+
+TODO: explain
+
+## other layouts
+
+the layout can be changed in Settings > Appearance to one of these:
+
+### classic
+
+image
+
+### compact
+
+image
+
+### compact (vertical)
+
+image

doc/2-interface/song-info.md

@@ -0,0 +1,5 @@
+# song info
+
+# sub-songs
+
+# speed