Redesign audio core to return a locked AudioPlayer object instead of having a multitude of helper functions

[ivan-mogilko]

The "audio core" system was implemented in 3.6.0, as a part of moving from Allegro 4 towards SDL-based utilities and a more convenient audio thread.

Although the original idea of "audio core" interface was to have everything behind the set of functions, in practice it proved to be rather annoying, as we had to have a duplicate function per each "audio player" action. This creates a mostly redundant layer of complexity.
But besides that, there's a technical issue: each "audio core" function's call locks the mutex, and sometimes we need to do several things at once. This means either call several functions with a lock/unlock pair in a succession, or write more cumbersome helper functions that do a number of things under one lock/unlock pair. If calling several functions, the state of the audio player may actually change in between. (In fact, it may even get disposed in between, although this probably never happened in practice because of how our synchronization is organized.)

The new design is inspired by the older "Channel Lock" existing in versions 3.5.0-3.5.1 (e.g. see this code), and follows this outline:

1. AudioCoreSlot is picked out to a separate code unit and renamed to AudioPlayer.
2. Majority of audio core's playback control and state reading functions are REMOVED.
3. Instead, there's ONE function called audio_core_get_player() that returns a AudioPlayer's pointer wrapped into a AudioPlayerLock class, which holds a mutex lock, and unlocks on destruction. AudioPlayerLock class lets user to work with AudioPlayer, doing any manipulation necessary, and unlocks the provided mutex as soon as it gets out of scope.

[ericoporto]

Hey, this looks similar to the video player implementation in #2338 but ported to audio. Is this the idea? Can the new video player internals also be backported even if keeping the script API the same as is now in 3.6.x?

[ivan-mogilko]

Hey, this looks similar to the video player implementation in #2338 but ported to audio. Is this the idea?

No, not at all. There have already been "audio player", only called differently (AudioCoreSlot). I only renamed it.
On contrary, in #2338 I was redoing video to look like the audio system; and I'd like to do changes similar to this PR for video too, either in #2338 or after that.

The idea is that currently each action on audio player has to come through extra layer of functions, like:

audio_core_slot_pause(slot_);
audio_core_slot_seek_ms(slot_, (float)pos_ms);
float posms_f;
audio_core_slot_get_play_state(slot_, posms_f);

each of these functions inside do 2 things:

• lock the mutex
• call the real method from "audio player".

This PR replaces this with direct access to "audio player":

player = audio_core_get_player(slot_);
player->Pause();
player->Seek((float)pos_ms);
float posms_f = player->GetPositionMs();

This solves 2 issues: removes extra functions in between (now it looks like a object-oriented code too), and reduces number of mutex locks/unlocks.

Can the new video player internals also be backported even if keeping the script API the same as is now in 3.6.x?

Maybe some things could be backported; but I would not like to backport whole "video core" thing, because there may be only one active player at a time with old script API. But I guess it's worth adding a video thread there, for performance,