[Scummvm-devel] PORTERS: Mixer changes and how to deal with them

[Max Horn]

Dear porters,

today I commited patch #1956946 (Audio::Mixer internal API revision).  
This will require you all to make some small tweaks to your ports.  
This should be done quickly (of course compiling & testing the changes  
will require a bit more).

Here I try to detail the change you have to make:

1) Instead of
   #include "sound/mixer.h"
you now do
   #include "sound/mixer_intern.h"

2) you probably want to change
   Audio::Mixer *_mixer;
to
   Audio::MixerImpl *_mixer;
(or else perform casting in some places). This may require you to  
change Mixer to MixerImpl in some other places in your backend code.

3) To instantiate the mixer, change
   _mixer = new Audio::Mixer();
to the following:
   _mixer = new Audio::MixerImpl(this);

4) Most backends hook up the mixer via a method called  
setSoundCallback() (this used to be an OSystem virtual method a long  
time ago). So they contain a line like this
   setSoundCallback(Audio::Mixer::mixCallback, _mixer);
and then a corresponding  method:
   bool OSystem_FOOBAR::setSoundCallback(SoundProc proc, void *param)  
{  .... }

Now things are a bit different. The mixer does not provide a static  
callback function anymore, rather, it directly offers a callback  
*method*. So you either have to write your own static callback  
function; or invoke the  callback method directly. E.g. the SDL  
backend uses this callback wrapper:
   void OSystem_SDL::mixCallback(void *sys, byte *samples, int len) {
     OSystem_SDL *this_ = (OSystem_SDL *)sys;
     assert(this_);

     if (this_->_mixer)
       this_->_mixer->mixCallback(samples, len);
   }
I hope the idea is clear from this, if not, please do not hesitate to  
ask.

Next, you have to tell the Mixer the output sample rate, as well as  
that the system is now ready to process Audio data:
   _mixer->setOutputRate(44100);
   _mixer->setReady(true);
Alternatively, if no audio output is possible, you can tell the mixer  
so, too:
   _mixer->setReady(false);

In the SDL backend, all of this done by a method  
OSystem_SDL::setupMixer(), in backends/platform/sdl/sdl.cpp -- I  
recommend to take a look at it for details.

5) The pure virtual method OSystem::getOutputSampleRate() is *gone*,  
so you do not have to implement it anymore -- you can drop it (the  
mixer now is told the output sample rate explicitly, see above).



Cheers,
Max