furnace/doc/7-systems/opl.md

# 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](opll.md), and later chips in the series added more waveforms (than just the typical sine) and even a 4-operator mode.

the original OPL (Yamaha YM3526) was present as an expansion for the Commodore 64 and MSX computers (erm, a variant of it). it only had 9 two-operator channels and drums mode.

Y8950 is essentially the same chip, but with one additional channel for ADPCM sample playback, behaving in a similar way as the one found in YM2608.

its successor, the OPL2 (Yamaha YM3812), 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 (Yamaha YMF262) added 9 more channels, 4 more waveforms, rudimentary 4-operator mode (pairing up to 12 channels to make up to six 4-operator channels), quadraphonic output and some other things.

the OPL4 (Yamaha YMF278) retains the FM block from OPL3, but adds 24 sample channels on top! samples are 44100 Hz, can be between 8, 12 or 16-bit, stereo (with 16 different levels) and can read PCM data from ROM or SRAM (up to 4 MB).

afterwards everyone moved to Windows and software mixed PCM streaming...

## 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 and OPL4).
- `15xx`: **set operator 4 level.**
  - only in 4-op mode (OPL3 and OPL4).
- `16xy`: **set multiplier of operator.**
  - `x` is the operator (1-4; last 2 operators only in 4-op mode).
  - `y` is the new MULT value..
- `17xx`: **set vibrato depth.**
  - `0`: normal
  - `1`: double
  - this effect applies to all channels.
- `18xx`: **toggle drums mode.**
  - `0` disables it and `1` enables it.
  - only in drums chip.
- `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).
- `2Axy`: **set waveform of operator.**
  - `x` is the operator from 1 to 4; the last 2 operators only work in 4-op mode. a value of `0` means "all operators".
  - `y` is the value.
  - only in OPL2 or higher.
- `30xx`: **enable envelope hard reset.**
  - this works by inserting a quick release and tiny delay before a new note.
- `50xy`: **set AM of operator.**
  - `x` is the operator from 1 to 4; the last 2 operators only work in 4-op mode. a value of `0` means "all operators".
  - `y` determines whether AM is on.
- `51xy`: **set SL of operator.**
  - `x` is the operator from 1 to 4; the last 2 operators only work in 4-op mode. a value of `0` means "all operators".
  - `y` is the value.
- `52xy`: **set RR of operator.**
  - `x` is the operator from 1 to 4; the last 2 operators only work in 4-op mode. a value of `0` means "all operators".
  - `y` is the value.
- `53xy`: **set VIB of operator.**
  - `x` is the operator from 1 to 4; the last 2 operators only work in 4-op mode. a value of `0` means "all operators".
  - `y` determines whether VIB is on.
- `54xy`: **set KSL of operator.**
  - `x` is the operator from 1 to 4; the last 2 operators only work in 4-op mode. a value of `0` means "all operators".
  - `y` is the value.
- `55xy`: **set SUS of operator.**
  - `x` is the operator from 1 to 4; the last 2 operators only work in 4-op mode. a value of `0` means "all operators".
  - `y` determines whether SUS is on.
- `56xx`: **set DR of all operators.**
- `57xx`: **set DR of operator 1.**
- `58xx`: **set DR of operator 2.**
- `59xx`: **set DR of operator 3.**
  - only in 4-op mode (OPL3).
- `5Axx`: **set DR of operator 4.**
  - only in 4-op mode (OPL3).
- `5Bxy`: **set KSR of operator.**
  - `x` is the operator from 1 to 4; the last 2 operators only work in 4-op mode. a value of `0` means "all operators".
  - `y` determines whether KSR is on.

## info

these chips use the [FM (OPL)](../4-instrument/fm-opl.md) instrument editor. Y8950 ADPCM uses [Generic Sample](../4-instrument/sample.md) and [ADPCM-B](../4-instrument/adpcm-b.md) instrument editors.

when two channels are joined for 4-op mode, the channel bar will show `4OP` on a bracket tying them together.

## chip config

the following options are available in the Chip Manager window:

- **Clock rate**: sets the rate at which the chip will run.

additionally, in OPL3:

- **Chip type**: sets the chip model. OPL3-L uses resampling.
- **Compatible panning**: for compatibility with old Furnace.

additionally, in OPL4:

- **RAM Size**: sets the RAM size for sample storage
system doc work 2022-03-22 05:58:07 +00:00			`# 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.`
Update opl.md ditto 2023-06-14 09:17:42 +00:00			`however, it also had a [drums mode](opll.md), and later chips in the series added more waveforms (than just the typical sine) and even a 4-operator mode.`
system doc work 2022-03-22 05:58:07 +00:00
somewhat improved system descriptions 2022-03-26 18:55:20 +00:00			`the original OPL (Yamaha YM3526) was present as an expansion for the Commodore 64 and MSX computers (erm, a variant of it). it only had 9 two-operator channels and drums mode.`
system doc work 2022-03-22 05:58:07 +00:00
fulfill requested changes needs review 2024-10-09 05:21:44 +00:00			`Y8950 is essentially the same chip, but with one additional channel for ADPCM sample playback, behaving in a similar way as the one found in YM2608.`
Updated OPL docs (for OPL4). This is actually freq-mod's work, I'm just putting it in the same PR. 2024-10-03 18:21:53 +00:00
somewhat improved system descriptions 2022-03-26 18:55:20 +00:00			`its successor, the OPL2 (Yamaha YM3812), added 3 more waveforms and was one of the more popular chips because it was present on the AdLib card for PC.`
system doc work 2022-03-22 05:58:07 +00:00			`later Creative would borrow the chip to make the Sound Blaster, and totally destroyed AdLib's dominance.`

doc finalization: systems 2023-09-10 06:44:29 +00:00			`the OPL3 (Yamaha YMF262) added 9 more channels, 4 more waveforms, rudimentary 4-operator mode (pairing up to 12 channels to make up to six 4-operator channels), quadraphonic output and some other things.`
system doc work 2022-03-22 05:58:07 +00:00
fulfill requested changes needs review 2024-10-09 05:21:44 +00:00			`the OPL4 (Yamaha YMF278) retains the FM block from OPL3, but adds 24 sample channels on top! samples are 44100 Hz, can be between 8, 12 or 16-bit, stereo (with 16 different levels) and can read PCM data from ROM or SRAM (up to 4 MB).`
Updated OPL docs (for OPL4). This is actually freq-mod's work, I'm just putting it in the same PR. 2024-10-03 18:21:53 +00:00
somewhat improved system descriptions 2022-03-26 18:55:20 +00:00			`afterwards everyone moved to Windows and software mixed PCM streaming...`
system doc work 2022-03-22 05:58:07 +00:00
only one header per doc file 2023-09-11 00:34:13 +00:00			`## effects`
system doc work 2022-03-22 05:58:07 +00:00
Lots of little cleanup. Trying for more consistency and clarity, especially for quick reference. 2023-06-25 07:05:30 +00:00			- `10xx`: set AM depth. the following values are accepted:
			- `0`: 1dB (shallow)
			- `1`: 4.8dB (deep)
system doc work 2022-03-22 05:58:07 +00:00			`- this effect applies to all channels.`
Lots of little cleanup. Trying for more consistency and clarity, especially for quick reference. 2023-06-25 07:05:30 +00:00			- `11xx`: set feedback of channel.
			- `12xx`: set operator 1 level.
			- `13xx`: set operator 2 level.
			- `14xx`: set operator 3 level.
Updated OPL docs (for OPL4). This is actually freq-mod's work, I'm just putting it in the same PR. 2024-10-03 18:21:53 +00:00			`- only in 4-op mode (OPL3 and OPL4).`
Lots of little cleanup. Trying for more consistency and clarity, especially for quick reference. 2023-06-25 07:05:30 +00:00			- `15xx`: set operator 4 level.
Updated OPL docs (for OPL4). This is actually freq-mod's work, I'm just putting it in the same PR. 2024-10-03 18:21:53 +00:00			`- only in 4-op mode (OPL3 and OPL4).`
De-capitalization of docs (and little typo fixes) There are also a couple tiny instances of formatting, like [sic] in the Namco 163 doc (yes, it is now correctly formatted) and a couple labels that needed bold. 2023-09-10 17:16:55 +00:00			- `16xy`: set multiplier of operator.
system doc work 2022-03-22 05:58:07 +00:00			- `x` is the operator (1-4; last 2 operators only in 4-op mode).
Revert "Revert "Revert "Fixed typos" (#1121)"" This reverts commit fb61309ac72c5bed7673319562cb4e04d4190963. 2023-09-13 04:28:45 +00:00			- `y` is the new MULT value..
Lots of little cleanup. Trying for more consistency and clarity, especially for quick reference. 2023-06-25 07:05:30 +00:00			- `17xx`: set vibrato depth.
			- `0`: normal
			- `1`: double
system doc work 2022-03-22 05:58:07 +00:00			`- this effect applies to all channels.`
Lots of little cleanup. Trying for more consistency and clarity, especially for quick reference. 2023-06-25 07:05:30 +00:00			- `18xx`: toggle drums mode.
			- `0` disables it and `1` enables it.
lots of doc updates 2022-10-16 05:53:05 +00:00			`- only in drums chip.`
Lots of little cleanup. Trying for more consistency and clarity, especially for quick reference. 2023-06-25 07:05:30 +00:00			- `19xx`: set attack of all operators.
			- `1Axx`: set attack of operator 1.
			- `1Bxx`: set attack of operator 2.
			- `1Cxx`: set attack of operator 3.
system doc work 2022-03-22 05:58:07 +00:00			`- only in 4-op mode (OPL3).`
Lots of little cleanup. Trying for more consistency and clarity, especially for quick reference. 2023-06-25 07:05:30 +00:00			- `1Dxx`: set attack of operator 4.
system doc work 2022-03-22 05:58:07 +00:00			`- only in 4-op mode (OPL3).`
Lots of little cleanup. Trying for more consistency and clarity, especially for quick reference. 2023-06-25 07:05:30 +00:00			- `2Axy`: set waveform of operator.
			- `x` is the operator from 1 to 4; the last 2 operators only work in 4-op mode. a value of `0` means "all operators".
document (NON-WORKING) extended op param effects 2022-05-02 23:15:51 +00:00			- `y` is the value.
			`- only in OPL2 or higher.`
Lots of little cleanup. Trying for more consistency and clarity, especially for quick reference. 2023-06-25 07:05:30 +00:00			- `30xx`: enable envelope hard reset.
document (NON-WORKING) extended op param effects 2022-05-02 23:15:51 +00:00			`- this works by inserting a quick release and tiny delay before a new note.`
Lots of little cleanup. Trying for more consistency and clarity, especially for quick reference. 2023-06-25 07:05:30 +00:00			- `50xy`: set AM of operator.
			- `x` is the operator from 1 to 4; the last 2 operators only work in 4-op mode. a value of `0` means "all operators".
document (NON-WORKING) extended op param effects 2022-05-02 23:15:51 +00:00			- `y` determines whether AM is on.
Lots of little cleanup. Trying for more consistency and clarity, especially for quick reference. 2023-06-25 07:05:30 +00:00			- `51xy`: set SL of operator.
			- `x` is the operator from 1 to 4; the last 2 operators only work in 4-op mode. a value of `0` means "all operators".
document (NON-WORKING) extended op param effects 2022-05-02 23:15:51 +00:00			- `y` is the value.
Lots of little cleanup. Trying for more consistency and clarity, especially for quick reference. 2023-06-25 07:05:30 +00:00			- `52xy`: set RR of operator.
			- `x` is the operator from 1 to 4; the last 2 operators only work in 4-op mode. a value of `0` means "all operators".
document (NON-WORKING) extended op param effects 2022-05-02 23:15:51 +00:00			- `y` is the value.
Lots of little cleanup. Trying for more consistency and clarity, especially for quick reference. 2023-06-25 07:05:30 +00:00			- `53xy`: set VIB of operator.
			- `x` is the operator from 1 to 4; the last 2 operators only work in 4-op mode. a value of `0` means "all operators".
document (NON-WORKING) extended op param effects 2022-05-02 23:15:51 +00:00			- `y` determines whether VIB is on.
Lots of little cleanup. Trying for more consistency and clarity, especially for quick reference. 2023-06-25 07:05:30 +00:00			- `54xy`: set KSL of operator.
			- `x` is the operator from 1 to 4; the last 2 operators only work in 4-op mode. a value of `0` means "all operators".
document (NON-WORKING) extended op param effects 2022-05-02 23:15:51 +00:00			- `y` is the value.
Lots of little cleanup. Trying for more consistency and clarity, especially for quick reference. 2023-06-25 07:05:30 +00:00			- `55xy`: set SUS of operator.
			- `x` is the operator from 1 to 4; the last 2 operators only work in 4-op mode. a value of `0` means "all operators".
document (NON-WORKING) extended op param effects 2022-05-02 23:15:51 +00:00			- `y` determines whether SUS is on.
Lots of little cleanup. Trying for more consistency and clarity, especially for quick reference. 2023-06-25 07:05:30 +00:00			- `56xx`: set DR of all operators.
			- `57xx`: set DR of operator 1.
			- `58xx`: set DR of operator 2.
			- `59xx`: set DR of operator 3.
document (NON-WORKING) extended op param effects 2022-05-02 23:15:51 +00:00			`- only in 4-op mode (OPL3).`
Lots of little cleanup. Trying for more consistency and clarity, especially for quick reference. 2023-06-25 07:05:30 +00:00			- `5Axx`: set DR of operator 4.
document (NON-WORKING) extended op param effects 2022-05-02 23:15:51 +00:00			`- only in 4-op mode (OPL3).`
Lots of little cleanup. Trying for more consistency and clarity, especially for quick reference. 2023-06-25 07:05:30 +00:00			- `5Bxy`: set KSR of operator.
			- `x` is the operator from 1 to 4; the last 2 operators only work in 4-op mode. a value of `0` means "all operators".
Update opl.md ditto 2023-06-14 09:17:42 +00:00			- `y` determines whether KSR is on.
Documentation stuff! New page for the effect list, updates to chanOsc, and links to instrument types from every "system" page. 2023-08-04 16:11:53 +00:00
only one header per doc file 2023-09-11 00:34:13 +00:00			`## info`
Documentation stuff! New page for the effect list, updates to chanOsc, and links to instrument types from every "system" page. 2023-08-04 16:11:53 +00:00
Updated OPL docs (for OPL4). This is actually freq-mod's work, I'm just putting it in the same PR. 2024-10-03 18:21:53 +00:00			`these chips use the [FM (OPL)](../4-instrument/fm-opl.md) instrument editor. Y8950 ADPCM uses [Generic Sample](../4-instrument/sample.md) and [ADPCM-B](../4-instrument/adpcm-b.md) instrument editors.`
Documenting channel pair hints. 2023-11-03 03:32:21 +00:00
document chip options 2024-07-06 19:52:07 +00:00			when two channels are joined for 4-op mode, the channel bar will show `4OP` on a bracket tying them together.

			`## chip config`

			`the following options are available in the Chip Manager window:`

			`- Clock rate: sets the rate at which the chip will run.`

			`additionally, in OPL3:`

			`- Chip type: sets the chip model. OPL3-L uses resampling.`
			`- Compatible panning: for compatibility with old Furnace.`
Updated OPL docs (for OPL4). This is actually freq-mod's work, I'm just putting it in the same PR. 2024-10-03 18:21:53 +00:00
			`additionally, in OPL4:`

			`- RAM Size: sets the RAM size for sample storage`