system doc work

papers/doc/7-systems/README.md

@@ -4,6 +4,7 @@ this is a list of systems that Furnace supports, including each system's effects
 
 - [Sega Genesis/Mega Drive](genesis.md)
 - [Sega Master System](sms.md)
+- [Yamaha OPLL](opll.md)
 - [Game Boy](game-boy.md)
 - [PC Engine/TurboGrafx-16](pce.md)
 - [NES](nes.md)
@@ -15,6 +16,7 @@ this is a list of systems that Furnace supports, including each system's effects
 - [Amiga](amiga.md)
 - [Yamaha YM2612 standalone](ym2612.md)
 - [Yamaha YM2151 standalone](ym2151.md)
+- [SegaPCM](segapcm.md)
 - [Atari 2600](tia.md)
 - [Philips SAA1099](saa1099.md)
 - [Microchip AY8930](ay8930.md)
@@ -22,5 +24,8 @@ this is a list of systems that Furnace supports, including each system's effects
 - [Seta/Allumer X1-010](x1-010.md)
 - [WonderSwan](wonderswan.md)
 - [Bubble System WSG](bubblesystem.md)
+- [Yamaha OPL](opl.md)
+- [PC Speaker](pcspkr.md)
+- [Commodore PET](pet.md)
 
-Furnace also reads .dmf files with the [Yamaha YMU759](ymu759.md) system, but does not emulate the chip at all.
+Furnace also reads .dmf files with the [Yamaha YMU759](ymu759.md) system, but...

papers/doc/7-systems/arcade.md

@@ -1,7 +1,7 @@
 # Arcade (Yamaha YM2151/PCM)
 
 this chip combination was used in the Sega OutRun, X and Y arcade boards, and perhaps a few others.
-the actual PCM chip had 16 channels, but the number has been cut to 5 in DefleMask for seemingly arbitrary reasons. a system with all 16 channels may be coming soon.
+the actual PCM chip had 16 channels, but the number has been cut to 5 in DefleMask for seemingly arbitrary reasons.
 
 # effects
 

papers/doc/7-systems/bubblesystem.md

@@ -8,7 +8,7 @@ Also known as K005289, but that's just part of the logic used for pitch and wave
 Waveform select and Volume control are tied with single AY-3-8910 IO for both channels.
 Another AY-3-8910 IO is used for reading sound hardware status.
 
-furnace emulates this configurations as single system, waveform format is 15 level and 32 width.
+Furnace emulates this configurations as single system, waveform format is 15 level and 32 width.
 
 # effects
 

papers/doc/7-systems/lynx.md

@@ -2,7 +2,7 @@
 
 The Atari Lynx is a 16 bit handheld console developed by (obviously) Atari Corporation, and initially released in September of 1989, with the worldwide release being in 1990.
 
-The Lynx, while being an incredible handheld for the time (and a lot more powerful than a Game Boy), unfortunately meant nothing in the end due to the Lynx being a market failiure, and ending up as one of the things that contributed to the downfall of Atari.
+The Lynx, while being an incredible handheld for the time (and a lot more powerful than a Game Boy), unfortunately meant nothing in the end due to the Lynx being a market failure, and ending up as one of the things that contributed to the downfall of Atari.
 
 Although the Lynx is still getting (rather impressive) homebrew developed for it, it does not mean that the Lynx is a popular system at all.
 
@@ -17,4 +17,6 @@ The Atari Lynx's custom sound chip and CPU (MIKEY) is a 6502-based 8 bit CPU run
  - The MIKEY also has a variety of pitches to choose from, and they go from 32Hz to "above the range of human hearing", according to Atari.
 
 ## Effect commands
- - `3xxx`: Load LFSR (0 to FFF). For it to work, duty macro in instrument editor must be set to some value, without it LFSR will not be fed with any bits.
+ - `3xxx`: Load LFSR (0 to FFF).
+  - this is a bitmask.
+  - for it to work, duty macro in instrument editor must be set to some value, without it LFSR will not be fed with any bits.

papers/doc/7-systems/opl.md

@@ -0,0 +1,47 @@
+# Yamaha OPL
+
+a series of FM sound chips which were very popular in DOS land. it was so popular that even Yamaha made a logo for it!
+
+essentially a downgraded version of Yamaha's other FM chips, with only 2 operators per channel.
+however, it also had a drums mode, and later chips in the series added more waveforms (than just the typical sine) and even a 4-operator mode.
+
+the original OPL was present as an expansion for the Commodore 64 and MSX computers (erm, a variant of it). it only had 9 channels and drums mode.
+
+its successor, the OPL2, added 3 more waveforms and was one of the more popular chips because it was present on the AdLib card for PC.
+later Creative would borrow the chip to make the Sound Blaster, and totally destroyed AdLib's dominance.
+
+the OPL3 added 9 more channels, 4 more waveforms, 4-operator mode (pairing up to 12 channels to make up to six 4-operator channels), quadraphonic output (sadly Furnace only supports stereo) and some other things.
+it was overkill.
+
+afterwards everyone moved to Windows and software mixing...
+
+# effects
+
+- 10xx: set AM depth. the following values are accepted:
+  - 0: 1dB (shallow)
+  - 1: 4.8dB (deep)
+  - this effect applies to all channels.
+- `11xx`: set feedback of channel.
+- `12xx`: set operator 1 level.
+- `13xx`: set operator 2 level.
+- `14xx`: set operator 3 level.
+  - only in 4-op mode (OPL3).
+- `15xx`: set operator 4 level.
+  - only in 4-op mode (OPL3).
+- `16xy`: set multiplier of operator.
+  - `x` is the operator (1-4; last 2 operators only in 4-op mode).
+  - `y` is the mutliplier.
+- 17xx: set vibrato depth. the following values are accepted:
+  - 0: normal
+  - 1: double
+  - this effect applies to all channels.
+- `18xx`: toggle drums mode.
+  - 0 disables it and 1 enables it.
+  - only in drums system.
+- `19xx`: set attack of all operators.
+- `1Axx`: set attack of operator 1.
+- `1Bxx`: set attack of operator 2.
+- `1Cxx`: set attack of operator 3.
+  - only in 4-op mode (OPL3).
+- `1Dxx`: set attack of operator 4.
+  - only in 4-op mode (OPL3).

papers/doc/7-systems/opll.md

@@ -1,21 +1,34 @@
 # Yamaha YM2413/OPLL
-The YM2413, otherwise known as OPLL, is a cost-reduced FM synthesis sound chip manufactured by Yamaha Corporation and based on the Yamaha YM3812 sound chip (OPL2).
 
-As of Furnace version 0.5.7pre4, the OPLL sound chip is not yet emulated. It is, however, emulated in Deflemask as of version 1.1.0. Support for loading .DMFs which contain the YM2413 was added in Furnace version 0.5.7pre4.
+the YM2413, otherwise known as OPLL, is a cost-reduced FM synthesis sound chip manufactured by Yamaha Corporation and based on the Yamaha YM3812 sound chip (OPL2). thought OPL was downgraded enough? :p
 
-## Technical specifications
-The YM2413 is equipped with the following features:
- - 9 channels of 2 operator FM synthesis
- - A drum/percussion mode, replacing the last 3 voices with 3 rhythm channels
- - 1 user-definable patch (this patch can be changed throughout the course of the song)
- - 15 pre-defined patches which can all be used at the same time
- - Support for ADSR on both the modulator and the carrier
- - Sine and half-sine based FM synthesis
- - 9 octave note control
- - 4096 different frequencies for channels
- - 16 unique volume levels (NOTE: Volume 0 is NOT silent.)
- - Modulator and carrier key scaling
- - Built-in hardware vibrato support
+# technical specifications
 
-## Effect commands
-TODO: Add effect commands here when YM2413 emulation is added.
+the YM2413 is equipped with the following features:
+
+- 9 channels of 2 operator FM synthesis
+- A drum/percussion mode, replacing the last 3 voices with 3 rhythm channels
+- 1 user-definable patch (this patch can be changed throughout the course of the song)
+- 15 pre-defined patches which can all be used at the same time
+- Support for ADSR on both the modulator and the carrier
+- Sine and half-sine based FM synthesis
+- 9 octave note control
+- 4096 different frequencies for channels
+- 16 unique volume levels (NOTE: Volume 0 is NOT silent.)
+- Modulator and carrier key scaling
+- Built-in hardware vibrato support
+
+# effects
+
+- `11xx`: set feedback of channel.
+- `12xx`: set operator 1 level.
+- `13xx`: set operator 2 level.
+- `16xy`: set multiplier of operator.
+  - `x` is the operator (1 or 2).
+  - `y` is the mutliplier.
+- `18xx`: toggle drums mode.
+  - 0 disables it and 1 enables it.
+  - only in drums system.
+- `19xx`: set attack of all operators.
+- `1Axx`: set attack of operator 1.
+- `1Bxx`: set attack of operator 2.

papers/doc/7-systems/pcspkr.md

@@ -0,0 +1,7 @@
+# PC Speaker
+
+40 years of one square beep - and still going!
+
+# effects
+
+ha! effects...

papers/doc/7-systems/pet.md

@@ -0,0 +1,11 @@
+# Commodore PET
+
+a computer from 1977 which was leader on US schools back then. subsequently the Apple II took its throne.
+
+maybe no better than a computer terminal, but somebody discovered a way to update the screen at turbo rate - and eventually its sound "chip" (it was nothing more than an 8-bit shift register) was abused as well.
+
+some of these didn't even have sound...
+
+# effects
+
+- 10xx: set waveform. `xx` is a bitmask.

papers/doc/7-systems/segapcm.md

@@ -0,0 +1,12 @@
+# SegaPCM
+
+16 channels of PCM? no way!
+
+yep, that's right! 16 channels of PCM!
+
+a chip used in the Sega OutRun/X/Y arcade boards. eventually the MultiPCM surpassed it with 24 channels, and later they joined the software mixing gang.
+
+# effects
+- `20xx`: set PCM frequency.
+  - `xx` is a 256th fraction of 31250Hz.
+  - this effect exists for mostly DefleMask compatibility - it is otherwise recommended to use Sample type instruments.

papers/doc/7-systems/x1-010.md

@@ -2,7 +2,7 @@
 
 One of sound chip originally designed by Seta, mainly used at their arcade hardwares at late-80s to early-2000s.
 It has 2 output channels, but no known hardware using this feature for stereo sound.
-Later hardware paired this with external bankswitching logic, but its logic is not emulated now in current furnace revision.
+Later hardware paired this with external bankswitching logic, but this isn't emulated yet.
 Allumer one is just rebadged Seta's thing for use in their arcade hardwares.
 
 It has 16 channels, and all channels can be switchable to PCM sample or wavetable playback mode.
@@ -26,9 +26,9 @@ In furnace, You can set envelope shape split mode. When it sets, its waveform wi
 # effects
 
 - `10xx`: change wave.
-- `11xx`: change envelope shape. (also wavetable)
+- `11xx`: change envelope shape (also wavetable).
 - `17xx`: toggle PCM mode.
-- `20xx`: set PCM frequency. (1 to FF)*
+- `20xx`: set PCM frequency (1 to FF).
 - `22xx`: set envelope mode.
   - bit 0 sets whether envelope will affect this channel.
   - bit 1 sets whether envelope one-shot mode. when it sets, channel is halted after envelope cycle is ended.

papers/doc/7-systems/ym2151.md

@@ -1,6 +1,8 @@
 # Yamaha YM2151
 
-the sound chip powering the Arcade system, available for standalone use if you want to make X68000 music or pair it with a 16-channel Sega PCM when it comes.
+the sound chip powering several arcade boards and the Sharp X1/X68000.
+
+it also was present on several pinball machines and synthesizers of the era, and later surpassed by the YM2414 (OPZ) present in the world-famous TX81Z.
 
 # effects
 

papers/doc/7-systems/ym2610b.md

@@ -1,6 +1,7 @@
 # Taito Arcade/Yamaha YM2610B
 
-YM2610B is basically YM2610 with 2 extra FM channels used at some 90s Taito Arcade hardwares, it's backward compatible with non-B chip.
+YM2610B is basically YM2610 with 2 extra FM channels used at some 90s Taito arcade hardware.
+it is backward compatible with the original chip.
 
 # effects
 
@@ -54,4 +55,4 @@ YM2610B is basically YM2610 with 2 extra FM channels used at some 90s Taito Arca
   - in this mode the envelope period is set to the channel's notes, multiplied by a fraction.
   - `x` is the numerator.
   - `y` is the denominator.
-  - if `x` or `y` are 0 this will disable auto-envelope mode.
+  - if `x` or `y` are 0 this will disable auto-envelope mode.

papers/doc/7-systems/ymu759.md

@@ -4,7 +4,8 @@ the Yamaha YMU759 is a sound chip designed for feature phones during the early 2
 it is also known as MA-2.
 
 sadly Yamaha didn't care about these chips too much, and the register specs were completely unavailable, which means the YMU759 is totally unsupported and unemulated besides Yamaha's official emulator for it built into MidRadio.
-hence Furnace does not emulate the chip (and doesn't even let you add it to a song).
+
+Furnace 0.6 loads DefleMask modules written for this system; however, it doesn't support any of its effects and is simulated using the OPL core.
 
 # effects