New echo instructions

[undisbeliever]

Updated 16 November 2024

I think the MML echo commands should use the \ syntax. This makes it more obvious to the song-author they are global commands and non-standard MML.

• [ ] set_echo_invert_flags lr00000m

  • Surround mode: set echo invert flags
  • Stereo and mono mode: set echo invert flags to 0xff if m-flag set, or 0 if m-flag clear.
  • Writes to the EVOL_L and EVOL_R S-DSP registers, based on the echo volume and echo invert flags.
  • MML syntax: (unsure) \ei 0, \ei, \ei M \ei L \ei R, \ei LR in the same format as channel invert.

• [ ] set_echo_volume u8

  • Argument range is 0-127
  • Sets the left and right echo volume to argument & 0x7f
  • Equivalent to set_stereo_echo_volume arg, arg.
  • Writes to the EVOL_L and EVOL_R S-DSP registers, based on the echo invert flags.
  • MML syntax: \evol <0..127>

• [ ] set_stereo_echo_volume u8, u8

  • Stereo & surround mode: Sets the left and right echo volume.
    • Arguments will be masked with 0x7f
  • Mono mode: Sets the left and right echo to the average of the two arguments.
  • Writes to the EVOL_L and EVOL_R S-DSP registers, based on the echo invert flags.
  • MML syntax \evol <left 0..127>,<right 0..127>

• [ ] adjust_echo_volume i8 adjust

  • Adds adjust to the echo volume channels
  • Echo volume is clamped to 0..127 range
  • Writes to the EVOL_L and EVOL_R S-DSP registers, based on the echo invert flags.
  • MML syntax \evol +<1..127> \evol -<1..128>

• [ ] adjust_stereo_echo_volume i8 left, i8 right

  • Stereo & surround mode: Adds left to the left echo volume and right to the right echo volume.
  • Mono mode: adjust_echo_volume (left+right)/2
  • Each channel is clamped to 0..127 range
  • Writes to the EVOL_L and EVOL_R S-DSP registers, based on the echo invert flags.
  • MML syntax \evol <+-left>,<+-right>

• [ ] set_echo_feedback i8

  • Sets the EFB S-DSP register
  • MML syntax \efb <-128..127>

• [ ] adjust_echo_feedback i8 amount

  • Adds signed amount to EFB S-DSP register (with clamping).
  • MML syntax \efb+ <1..127> & \efb- <1..128>

• [ ] set_fir i8 i8 i8 i8 i8 i8 i8 i8

  • Set FIR filter S-DSP registers
  • MML syntax \fir { i8 i8 i8 i8 i8 i8 i8 i8 }
  • Will set FIR filter to 0 before setting the FIR filter to avoid exploding the song.
  • Sets the S-DSP Echo filter coefficients

• [ ] set_fir_tap u8 tap, i8 value

  • Set an individual FIR filter tap
  • MML syntax: \ftap <0-7>,<-128..127>
  • tap is pre-shifted by 4

• [ ] adjust_fir_tap u8 tap, i8 adjust [, i8 limit]

  • Adds adjust to an individual FIR filter tap
  • MML syntax: \ftap+ <0-7>,<1..127>[,<limit>] & \ftap- <0-7>,<1..128>[,<limit>]
  • tap is pre-shifted by 4
  • Limit is optional.
  • Ensures the tap does not exceed limit (useful for adjusting tap in loops)
  • adjust and limit must have the same sign (ie, both negative or both positive).
  • Will be 2 different opcodes adjust_fir_tap and adjust_fir_tap_limit.

• [ ] set_echo_delay u8

  • Sets the EDL S-DSP register
  • MML syntax \edl <delay_in_milliseconds>
  • Add #MaxEchoLength to the song header
    • ESA register would be based off #MaxEchoLength. This ensures ESA is only set once in song initialisation.
    • Allows the song author to limit maximum echo length in a song.
  • set_echo_delay cannot be > #MaxEchoLength
  • TODO: Should the compiler find #MaxEchoLength if it not declared in the header?
  • TODO: Determine what is required to minimise glitches
    • Document how to change echo delay without glitches
    • Song compiler and audio driver will not change echo settings for set_echo_delay.
    • A song-checker will emit a warning if an echo buffer glitch might occur

[KungFuFurby]

Starting on my feedback in this section with these...

For EVOL, EFB and FIR, I recommend clamping to the signed limits (-128/127), like how volume and panning are also clamped to their respective limits.

---

For translating stereo to mono (I recommend storing the original values, as https://github.com/undisbeliever/terrific-audio-driver/issues/15#issuecomment-2445249018 has some commentary on the inversion settings and the amount of adjustments may vary)...

• If the signs don't match on either side, then change the sign so that both of them match to avoid cancelation situations.
• Add the left and right sides together, then shift right once (divide by 2). The final sign will vary.

---

The next part I'll tackle feedback-wise is the EDL, since the EDL (and the ESA by proxy, though I think you're keeping that fixed based off of the largest EDL setting) is the most notorious one in terms of safely handling echo buffers: although it's quickly relocatable, the buffer size does not change until it has completed its previous loop. In addition, there are indeed some side effects from changing the EDL:

• Shrinking the buffer by reducing the EDL results in part of the previous buffer getting left behind.
• Expanding the buffer by increasing the EDL can result in accidentally processing sound that was left behind from some previous operation.
• The EDL only changes after having gone through a full loop of the buffer on the previous EDL. Thus, an old EDL value of 15 has the longest delay before going to the new EDL.

Now, if you want the EDL to go through a single loop of clearing the entire buffer (which also requires that EON and EFB DSP registers be temporarily zeroed out) before sounding off after changing, then the best move I can see is to let a timer do the job, keep echo writes on, and temporarily zero EVOL to prevent unintended sounds from coming out (perhaps this clear and wait process can also be optional, though at their own risk sound-wise).

• Timer 0 is used for the music and thus is not considered stable for its clock rate.
• Timer 1 is used for the SFX and is stable because the SFX tempo is kept constant. In addition, it's also set to a nice even value of 64.
• Timer 2 is not used at the moment, but it runs 8 times faster than the other timers.

The amount of time to wait should be 2old EDL + 2new EDL timer 1 ticks (assuming timer 1 is set to 64). This is because the buffer has to finish first, then it has to execute one loop before restorations can be done with a new, clean buffer.

So, if you want to implement a waiting period after changing the EDL in order to allow for the buffer to clear before sounding off on it, then...

• Zero out EVOL, EON and EFB
• Wait 2old EDL + 2new EDL timer 1 ticks (assuming timer 1 is 64) for the buffer to clear. Echo writes will remain enabled during this time, as otherwise the buffer won't be cleared.
• Restore EVOL, EON and EFB

The EDL can also be changed without a waiting period, though the side effect notes remain.

---

For adjust_fir_tap, I'm leaning towards making the limit part optional, and this can be done within a single opcode slot. tap is pre-shifted by 4, and perhaps the highest bit of the first byte can indicate whether there is a limit defined. Specifically, lttt0000 where...

• l indicates whether a limit is defined.
• ttt is the FIR tap ID to adjust.

Defining limits in other adjust-based opcodes will require a second slot be taken.

I'm thinking for the MML syntax it could be \ftap+ <0-7>,<0..127>,<0..127> and \ftap- <0-7>,<0..128>,<-1..-128> (the +/- sign is put at the beginning of the command to indicate that the FIR tap is being adjusted, not set, to avoid character conflicts with the sign, and the third parameter is the limit parameter, which I mentioned above as possibly being optional.

[undisbeliever]

Yesterday I tried to code golf the set_stereo_echo_volume and adjust_stereo_echo_volume instructions and ran into issues dealing with signs. Mainly issues with figuring out what to do when one channel's volume changes sign but the channel doesn't change (ie left goes negative, right stays positive). It gets even more complex when I add surround to the mono/stereo setting.

Here's a new idea. Echo volume is unsigned and would have an invert flag in a similar manner as the voice channels.

Advantages:

• Simpler
• The echo volume inversion is controlled by the song author
• Well defined behaviour regarding inversion for mono/stereo/surround mode.

Disadvantages:

• This makes 3 different volume formats in the audio driver. channel volume (vol + pan + invert), echo volume (2x u8 + invert) and EFB/FIR/MVOL (mono signed).
• Cannot set EVOL to -128 (although I don't know why someone would want to do that).

What do you think of these new instructions?

• set_echo_invert_flags lr00000m

  • If stereo mode is surround, echo invert flags are unchanged.

  • If stereo mode is mono or stereo, the echo invert flags will be set to 0xff if m-flag set, or 0 if m-flag clear.

  • set_echo_volume u8

  • Arguments masked by 0x7f, limiting argument range to 0-127.

• set_stereo_echo_volume u8 left, u8 right

  • Arguments masked by 0x7f, limiting argument range to 0-127.
  • If mono: the echo volume will be set to the average of the two arguments ((left+right)/2)

• adjust_stereo_echo_volume i8 left, i8 right

  • If mono: adjust_echo_volume (left+right)/2
  • Saturating add left to echo-volume-left and Saturating add right to echo-volume-right.

• adjust_stereo_echo_volume i8 adjust

  • Saturating adds adjust to echo-volume-left and echo-volume-right variables.

Whenever the echo volume changes the new EVOLL and EVOLR will be calculated using the l/r echo-invert-flags and echo-volume-left/echo-volume-right variables

---

Another alternative is to use echo volume + pan in the same format as voice channels. The main downside of echo pan is that the maximum centred EVOL is 64. I'm not sure if how big of a downside this would be (RainAmbienceWThunder.mml has an EchoVolume of 127).

[undisbeliever]

I'm thinking for the MML syntax it could be \ftap+ <0-7>,<0..127>,<0..127> and \ftap- <0-7>,<0..128>,<-1..-128> That sounds like a good idea.

I can do the same with the echo volume and echo feedback, so \efb+ +12 assemble to adjust_echo_feedback +12.

For adjust_fir_tap, I'm leaning towards making the limit part optional

Also a good idea and it can be easily done with shift and a branch. I think the code would use less space if I make the opcode parameter order tap+limit-flag [, limit], offset.

Thinking about this a bit more - using two different opcodes, adjust_fir_tap tap, offset & adjust_fir_tap_limit limit, tap, offset, would use the least amount of code space and I have 3 unused opcodes at the moment.

Either way, the bytecode assembly would still be adjust_fir_tap tap, offset [, limit].

[KungFuFurby]

I'll choose the first option for the echo volume: unsigned values with invert flags, since it also solves a problem with how to deal with the mono situation.

---

The second plus sign in \efb+ +12 would be redundant in this case, though then again, \efb- 12 would assemble to adjust_echo_feedback -12. Basically, I conjured up the idea on the fly to avoid signed value conflicts (and it is indeed space sensitive, as without the space the end result is a conflict with signage on the numbers). It's also why when I noted the \ftap adjustment syntax, I actually noted unsigned values for most of the parameters (for the limit parameters, I simply matched the sign to your specifications), because the sign is defined at the beginning of the MML syntax in question.

[undisbeliever]

The second plus sign in \efb+ +12 would be redundant in this case

That's a good point and something I hadn't considered. The parameter should be unsigned in this case.

The tokenizer requires a space after a \ MML command. So that would take care of separating \efb, \efb+ and \efb- commands.

I added the second plus because the MML and bytecode syntax for signed numbers (portamento velocity, adjust volume, adjust pan) requires a + or - sign (excluding song headers).

I can always relax the sign requirements for the set EFB and set FIR commands and allow \efb 12 to compile to set_echo_feedback 12 to match the song header.