discourage use of legacy sample mode

doc/6-sample/README.md

@@ -33,15 +33,15 @@ the following sound chips have sample support:
 - Yamaha PCMD8/YMZ280B
 - MMC5 (last channel only)
 
-## compatible sample mode
+## compatible sample mode (LEGACY)
 
-effect `17xx` enables/disables compatible sample mode whether supported (e.g. on Sega Genesis or PC Engine).
+**use of this mode is discouraged in favor of Sample type instruments.**
+
+effect `17xx` enables/disables compatible sample mode where supported (e.g. on Sega Genesis or PC Engine).
 
 in this mode, samples are mapped to notes in an octave from C to B, allowing you to use up to 12 samples.
 if you need to use more samples, you may change the sample bank using effect `EBxx`.
 
-use of this mode is discouraged in favor of Sample type instruments.
-
 ## notes
 
 due to limitations in some of those sound chips, some restrictions exist:

doc/7-systems/pce.md

@@ -18,8 +18,8 @@ furthermore, it has some PCM and LFO!
   - `03`: LFO enabled, shift 8.
   - when LFO is enabled, channel 2 is muted and its output is passed to channel 1's frequency.
 - `13xx`: **set LFO speed.**
-- `17xx`: **toggle PCM mode.**
-  - _this effect is here for compatibility reasons_; it is otherwise recommended to use Sample type instruments (which automatically enable PCM mode when used).
+- `17xx`: **toggle LEGACY sample mode.**
+  - **this effect exists only for compatibility reasons! its use is NOT recommented. use Sample type instruments instead.**
 
 # info
 

doc/7-systems/vrc6.md

@@ -15,7 +15,8 @@ Furnace supports this routine for PCM playback, but it consumes a lot of CPU tim
 these effects only are effective in the pulse channels.
 
 - `12xx`: **set duty cycle.** range is `0` to `7`.
-- `17xx`: **toggle PCM mode.**
+- `17xx`: **toggle LEGACY sample mode.**
+  - **this effect exists only for compatibility reasons! its use is NOT recommented. use Sample type instruments instead.**
 
 # info
 

doc/7-systems/x1-010.md

@@ -27,7 +27,8 @@ in Furnace, you can enable the envelope shape split mode. when it is set, its wa
 
 - `10xx`: **change wave.**
 - `11xx`: **change envelope shape.** also wavetable.
-- `17xx`: **toggle PCM mode.**
+- `17xx`: **toggle LEGACY sample mode.**
+  - **this effect exists only for compatibility reasons! its use is NOT recommented. use Sample type instruments instead.**
 - `20xx`: **set PCM frequency.** range is `1` to `FF`.
   - PCM frequency formula: `step * (clock / 8192)`.
   - range is 1.95KHz to 498KHz if the chip clock is 16MHz.

doc/7-systems/ym2612.md

@@ -16,8 +16,9 @@ as of Furnace 0.6pre5, Furnace offers DualPCM, a Z80 driver that splits channel
 - `16xy`: **set multiplier of operator.**
   - `x` is the operator (1-4).
   - `y` is the multiplier.
-- `17xx`: **enable PCM channel.**
+- `17xx`: **toggle LEGACY sample mode.**
   - this only works on channel 6.
+  - **this effect exists only for compatibility reasons! its use is NOT recommented. use Sample type instruments instead.**
 - `18xx`: **toggle extended channel 3 mode.**
   - 0 disables it and 1 enables it.
   - only in extended channel 3 chip.
@@ -86,4 +87,4 @@ CSM is beyond the scope of this documentation. for more information, see this [b
 
 ## DualPCM
 
-thanks to the Z80 sound CPU, DualPCM can play two samples at once! this mode splits channel 6 into two individual PCM channels with variable pitch. these are mixed together in software and streamed to channel 6 with a mix rate of 13750 Hz. VGM export requires the "direct stream mode" option to be enabled, and resulting files will be very large.
+thanks to the Z80 sound CPU, DualPCM can play two samples at once! this mode splits channel 6 into two individual PCM channels with variable pitch. these are mixed together in software and streamed to channel 6 with a mix rate of 13750 Hz. VGM export requires the "direct stream mode" option to be enabled, and resulting files will be very large.

src/engine/engine.cpp

@@ -107,7 +107,7 @@ const char* DivEngine::getEffectDesc(unsigned char effect, int chan, bool notNul
     case 0xea:
       return "EAxx: Legato";
     case 0xeb:
-      return "EBxx: Set sample bank";
+      return "EBxx: Set LEGACY sample mode bank";
     case 0xec:
       return "ECxx: Note cut";
     case 0xed:

src/engine/sysDef.cpp

@@ -451,7 +451,7 @@ void DivEngine::registerSystems() {
 
   EffectHandlerMap fmOPN2EffectHandlerMap(fmEffectHandlerMap);
   fmOPN2EffectHandlerMap.insert({
-    {0x17, {DIV_CMD_SAMPLE_MODE, "17xx: Toggle PCM mode"}},
+    {0x17, {DIV_CMD_SAMPLE_MODE, "17xx: Toggle PCM mode (LEGACY)"}},
     {0xdf, {DIV_CMD_SAMPLE_DIR, "DFxx: Set sample playback direction (0: normal; 1: reverse)"}},
   });
 
@@ -681,7 +681,7 @@ void DivEngine::registerSystems() {
       {0x11, {DIV_CMD_STD_NOISE_MODE, "11xx: Toggle noise mode"}},
       {0x12, {DIV_CMD_PCE_LFO_MODE, "12xx: Setup LFO (0: disabled; 1: 1x depth; 2: 16x depth; 3: 256x depth)"}},
       {0x13, {DIV_CMD_PCE_LFO_SPEED, "13xx: Set LFO speed"}},
-      {0x17, {DIV_CMD_SAMPLE_MODE, "17xx: Toggle PCM mode"}}
+      {0x17, {DIV_CMD_SAMPLE_MODE, "17xx: Toggle PCM mode (LEGACY)"}}
     }
   );
 
@@ -939,7 +939,7 @@ void DivEngine::registerSystems() {
     {DIV_INS_AMIGA, DIV_INS_AMIGA, DIV_INS_NULL},
     {
       {0x12, {DIV_CMD_STD_NOISE_MODE, "12xx: Set duty cycle (pulse: 0 to 7)"}},
-      {0x17, {DIV_CMD_SAMPLE_MODE, "17xx: Toggle PCM mode (pulse channel)"}},
+      {0x17, {DIV_CMD_SAMPLE_MODE, "17xx: Toggle PCM mode (LEGACY)"}},
     }
   );
 
@@ -1182,7 +1182,7 @@ void DivEngine::registerSystems() {
       {0x11, {DIV_CMD_STD_NOISE_MODE, "11xx: Setup noise mode (0: disabled; 1-8: enabled/tap)"}},
       {0x12, {DIV_CMD_WS_SWEEP_TIME, "12xx: Setup sweep period (0: disabled; 1-20: enabled/period)"}},
       {0x13, {DIV_CMD_WS_SWEEP_AMOUNT, "13xx: Set sweep amount"}},
-      {0x17, {DIV_CMD_SAMPLE_MODE, "17xx: Toggle PCM mode"}},
+      {0x17, {DIV_CMD_SAMPLE_MODE, "17xx: Toggle PCM mode (LEGACY)"}},
     }
   );
 
@@ -1497,7 +1497,7 @@ void DivEngine::registerSystems() {
       {0x10, {DIV_CMD_WAVE, "10xx: Set waveform"}},
       {0x11, {DIV_CMD_X1_010_ENVELOPE_SHAPE, "11xx: Set envelope shape"}},
       {0x12, {DIV_CMD_X1_010_SAMPLE_BANK_SLOT, "12xx: Set sample bank slot (0 to 7)"}},
-      {0x17, {DIV_CMD_SAMPLE_MODE, "17xx: Toggle PCM mode"}},
+      {0x17, {DIV_CMD_SAMPLE_MODE, "17xx: Toggle PCM mode (LEGACY)"}},
     },
     {
       {0x20, {DIV_CMD_SAMPLE_FREQ, "20xx: Set PCM frequency (1 to FF)"}},