Support SE cancelling of single files

[Ghabry]

As mentioned in #1120 by Cherry you can cancel a single SE by simply playing it 4 times with 0 volume to reach the per-file channel limit.

A RPG_RT implementation detail that is abused by some games.

I've done some tests, it's confirmed it has a 4 channel limit per sound, it does not matter if the sound has different parameters for volume, pitch and balance.

Additionally, RPG_RT is able to play up to 16 samples at once. When all sample slots are used, it overrides a whole sample slot, even if that older slot plays 4 samples, they will be replaced with the new sample.

Edit: added test case.

Edit the test case and replace the last blow6 line with blow7. Because blow 6 was repeated at the line above, it used the slot 16 twice, but when replacing with blow7, there would be 17 different sounds playing, then the earthquake (using all its 4 channels) won't play.

So it seems SE cancelling could even cancel all playing different sounds if they get played by any sample at 0 volume at least 16 different times.

[Ghabry]

This is no new information compared to what Cherry stated but the test case will be useful, thanks!

Implementing this is some work as it would require adding new APIs to the Audio backends and the 4-channel-limit should be handled in Game_System which does all the bookkeeping, that's too high level for the Audio-API.

New functions/changes needed:

void SE_Play -> int SE_Play. Returns a channel number.
bool SE_IsPlaying(int channel) const; Tests if a channel is currently playing a SE.
void SE_Stop(int channel); Stops one SE channel

[carstene1ns]

Do not forget the callbacks when a sound finished, or do you have unlimited channels and map them to hardware later?

[Ghabry]

I would map the channel id directly to a audio backend channel. We can increase them to 64 everywhere because they are all software mixing, except for the 3DS. For the 3DS we reach a hardware limitation, and I don't think this is solvable because the CPU is too slow for software mixing.

I thought about a callback first because this is nicer to code against but this is problematic here because the underlying APIs (e.g. SDL mixer) only tell you if a channel finished through polling which gives you a busy loop in the audio thread.

For the Game_System bookkeeping there could be a "channel id -> filename" mapping which is checked before SE_Play is called, there are 2 cases that can happen:

1. The filename appears < 4 times in the array -> just call SE_Play
2. The filename appears 4 times in the array -> Poll these 4 channels if SE still playing, if channel is free remove that entry and proceed with step 1
   (though this data structure is inconvenient for the 16 samples limit)

For case 1 there will be also some automatic cleaning because when the audio backend decides to reuse a finished channel Game_System will simply overwrite the entry with the new mapping.

Guess I forgot something important but that's how I would design this.

and some of those slots are held by the never-released system sounds (I think cursor, decision, cancel, buzzer).

This may require some additional testing to confirm, for the previous test case didn't reproduce them and maybe they actually block some channels 🤔.