New pan and volume instructions

[undisbeliever]

Updated 22 November 2024

• [ ] Tremolo

  • bytecode arguments: u16 unsigned offset-per-tick, u8 quarter-wavelength-in-ticks
    • offset-per-tick is unsigned 8.8 fixed point (1/256th of a fine-volume unit)
    • A quarter-wavelength-in-ticks value of 0 is 256 ticks.
  • bytecode assembly: tremolo amplitude (1-255), quarter-wavelength-in-ticks (1-256)
  • MML syntax:
    • v~<amplitude>,<quarter_wavelength_in_ticks>
    • V~<amplitude>,<quarter_wavelength_in_ticks>
  • bytecode module will transform amplitude to an unsigned 8.8 fixed point (fraction /256ths) offset-per-tick argument
  • Tremolo uses a triangular waveform
  • Tremolo directly modifies channelSoA.volume
  • Tremolo is disabled if volume underflows or overflows
  • Tremolo is disabled if volume is changed by set_pan_and_volume, adjust_volume or set_volume

• [ ] Volume slide

  • 2 bytecode instructions:
    • volume_slide_down
    • volume_slide_up
  • bytecode arguments: u16 unsigned offset-per-tick, u8 ticks
    • offset-per-tick is unsigned 8.8 fixed point (1/256th of a fine-volume unit)
    • A ticks value of 0 is 256 ticks.
  • bytecode assembly: volume_slide rel (-255 to +255), ticks (1-256)
    • rel is the total relative volume change at the end of the volume slide.
  • MML syntax (unsure):
    • vs+<1..16>,<ticks>
    • vs-<1..16>,<ticks>
    • Vs+<1..255>,<ticks>
    • Vs-<1..255>,<ticks>
    • Using vs and Vs will simplify the MML parser (as v commands are swallowed by merge_pan_or_volume())
  • bytecode module will transform rel to an unsigned 8.8 fixed point (fraction /256ths) offset-per-tick argument
  • Volume slide uses the same code path as tremolo
    • A state bit is used to determine if the volume effect stops when the countdown-timer is zero
    • directly modifies channelSoA.volume
    • disabled if volume underflows or overflows
    • disabled if volume is changed by set_pan_and_volume, adjust_volume or set_volume

• [ ] Panbrello

  • Same format/syntax as tremolo
    • panbrello
    • MML syntax: p~<1..128>,<ticks>

• [ ] Pan Slide

  • Same format/syntax as a volume slide.
    • pan_slide_down
    • pan_slide_up
    • MML syntax: ps+<1..128>,<ticks>, ps-<1..128>,<ticks>

• [ ] Invert

  • Inverts a channel's left and/or right volume
  • bytecode argument: u8 lr00000m
    • l bit - invert left channel if surround mode
    • r bit - invert right channel if surround mode
    • m bit - invert channel if mono or stereo mode
  • bytecode assembly: invert <none|both|left|right|mono> [right] [mono]
  • MML syntax:
    • I0 - disable inverted channels
    • I - invert both channels
    • IM - invert channel if mono or stereo mode (not surround)
    • IL - invert left channel if surround
    • IR - invert right channel if surround
    • ILR - invert left and right channels if surround (not mono) - unsure on syntax
  • CAUTION: The l and r bits are ignored in stereo mode

[KungFuFurby]

First feedback here will be with the inversion settings.

It looks like you have things set up in the inversion settings so that waveform cancelation doesn't become a problem in mono. I recommend adding an optional mono word specification to the bytecode assembly that will allow the mono flag to be set or not set according to the user's preference, and something similar in MML would also get involved (probably a lowercase m). It can also be implied to be set if both sides are set.

I also recommend a sound driver setting that will allow left and right channels to be inverted separately (as in like mono/stereo/surround: surround allows all of them, stereo means no separate inversion settings for left/right (treat like mono when handling inversion) but allow panning, and mono also doesn't have panning) to prevent waveform cancelation issues. This would also apply to the echo volume, as that also supports negative values. The main volume (referring to the MVOL DSP registers) is in the same situation, but is never changed from $7F.

[undisbeliever]

I recommend adding an optional mono word specification to the bytecode assembly that will allow the mono flag to be set or not set according to the user's preference, and something similar in MML would also get involved (probably a lowercase m). It can also be implied to be set if both sides are set.

In this context are you talking about a command to set the channel inversion mono flag? or the global stereo/mono flag?

I also recommend a sound driver setting that will allow left and right channels to be inverted separately (as in like mono/stereo/surround: surround allows all of them, stereo means no separate inversion settings for left/right (treat like mono when handling inversion) but allow panning, and mono also doesn't have panning) to prevent waveform cancelation issues. This would also apply to the echo volume, as that also supports negative values. The main volume (referring to the MVOL DSP registers) is in the same situation, but is never changed from $7F.

A surround global flag sounds useful. I'll need to code golf a way to efficiently detect sign changes in set_stereo_echo_volume, but it shouldn't be too hard.

[KungFuFurby]

I recommend adding an optional mono word specification to the bytecode assembly that will allow the mono flag to be set or not set according to the user's preference, and something similar in MML would also get involved (probably a lowercase m). It can also be implied to be set if both sides are set.

In this context are you talking about a command to set the channel inversion mono flag? or the global stereo/mono flag?

I meant the m bit in the invert command, so the channel inversion mono flag that you specified.

[undisbeliever]

Updated the syntax of the MML syntax of the invert instruction.

@KungFuFurby should the MML syntax for volume/pan slides use ticks or length? I'm leaning towards ticks as that matches the vibrato, tremolo, panbrello and early-release effects.

I've noticed that PMDMML has a q [l length] syntax (ie ql16 is set_early_release 6 on a 96 ZenLen) and uses l length on a few commands that have tick arguments. I could add that to the syntax, use ticks by default and optionally allow a volume slide for a given length (ie, vs+5,l4).

What are your thoughts on the matter?

[KungFuFurby]

Sounds like a good call.

---

I think I understand most of the logic for the inversion syntaxes... except I'm leaning towards M being an optional add-on to any of those since it would logically set the m bit for the invert command. It also makes for a nice match-up to the bytecode assembly syntax you defined up above.