Added some more mixer doxygen docs; cleaned up Mixer API a bit, removing some very specialised methods

svn-id: r15914

11 files changed, 160 insertions, 75 deletions

diff --git a/common/system.h b/common/system.h
index da2c0fde5c..63e642a34c 100644
--- a/common/system.h
+++ b/common/system.h
@@ -569,6 +569,8 @@ public:
 	/**
 	 * Determine the output sample rate. Audio data provided by the sound
 	 * callback will be played using this rate.
+	 * @note Client code other than the sound mixer should _not_ use this
+	 *       method. Instead, call SoundMixer::getOutputRate()!
 	 * @return the output sample rate
 	 */
 	virtual int getOutputSampleRate() const = 0;
diff --git a/graphics/animation.cpp b/graphics/animation.cpp
index 42ac082ab9..2ce89fc838 100644
--- a/graphics/animation.cpp
+++ b/graphics/animation.cpp
@@ -174,7 +174,7 @@ bool BaseAnimationState::decodeFrame() {
 					return false;
 
 				if (checkPaletteSwitch() || (bgSoundStream == NULL) ||
-					((_snd->getChannelElapsedTime(bgSound) * 12) / 1000 < framenum + 1) ||
+					((_snd->getSoundElapsedTime(bgSound) * 12) / 1000 < framenum + 1) ||
 					frameskipped > 10) {
 					if (frameskipped > 10) {
 						warning("force frame %i redraw", framenum);
@@ -183,7 +183,7 @@ bool BaseAnimationState::decodeFrame() {
 					drawYUV(sequence_i->width, sequence_i->height, info->display_fbuf->buf);
 
 					if (bgSoundStream) {
-						while ((_snd->getChannelElapsedTime(bgSound) * 12) / 1000 < framenum)
+						while ((_snd->getSoundElapsedTime(bgSound) * 12) / 1000 < framenum)
 							_sys->delayMillis(10);
 					} else {
 						ticks += 83;
diff --git a/queen/sound.cpp b/queen/sound.cpp
index 7ff117ec82..68e64efbe9 100644
--- a/queen/sound.cpp
+++ b/queen/sound.cpp
@@ -27,6 +27,10 @@
 #include "queen/queen.h"
 #include "queen/resource.h"
 
+#include "sound/flac.h"
+#include "sound/mp3.h"
+#include "sound/vorbis.h"
+
 #define	SB_HEADER_SIZE	110
 #define	STOP_MUSIC	-1
 
@@ -190,7 +194,7 @@ void MP3Sound::sfxPlay(const char *name, bool isSpeech) {
 	if (_vm->resource()->fileExists(name)) {
 		uint32 size;
 		File *f = _vm->resource()->giveCompressedSound(name, &size);
-		_mixer->playMP3(isSpeech ? &_speechHandle : &_sfxHandle, f, size);
+		_mixer->playInputStream(isSpeech ? &_speechHandle : &_sfxHandle, makeMP3Stream(f, size), false);
 	}
 }
 #endif
@@ -200,7 +204,7 @@ void OGGSound::sfxPlay(const char *name, bool isSpeech) {
 	if (_vm->resource()->fileExists(name)) {
 		uint32 size;
 		File *f = _vm->resource()->giveCompressedSound(name, &size);		
-		_mixer->playVorbis(isSpeech ? &_speechHandle : &_sfxHandle, f, size);
+		_mixer->playInputStream(isSpeech ? &_speechHandle : &_sfxHandle, makeVorbisStream(f, size), false);
 	}
 }
 #endif
@@ -210,7 +214,7 @@ void FLACSound::sfxPlay(const char *name, bool isSpeech) {
 	if (_vm->resource()->fileExists(name)) {
 		uint32 size;
 		File *f = _vm->resource()->giveCompressedSound(name, &size);		
-		_mixer->playFlac(isSpeech ? &_speechHandle : &_sfxHandle, f, size);
+		_mixer->playInputStream(isSpeech ? &_speechHandle : &_sfxHandle, makeFlacStream(f, size), false);
 	}
 }
 #endif
diff --git a/scumm/player_mod.cpp b/scumm/player_mod.cpp
index 4f917072f0..3102df1cd1 100644
--- a/scumm/player_mod.cpp
+++ b/scumm/player_mod.cpp
@@ -31,7 +31,7 @@ namespace Scumm {
 Player_MOD::Player_MOD(ScummEngine *scumm) {
 	int i;
 	_mixer = scumm->_mixer;
-	_samplerate = scumm->_system->getOutputSampleRate();
+	_samplerate = _mixer->getOutputRate();
 	_mixamt = 0;
 	_mixpos = 0;
 
@@ -150,7 +150,7 @@ void Player_MOD::premix_proc(void *param, int16 *buf, uint len) {
 	((Player_MOD *) param)->do_mix(buf, len);
 }
 
-void Player_MOD::do_mix (int16 *data, uint len) {
+void Player_MOD::do_mix(int16 *data, uint len) {
 	int i;
 	int dpos = 0;
 	uint dlen = 0;
diff --git a/scumm/player_v2.cpp b/scumm/player_v2.cpp
index bf6bde1f4c..ea4032f41a 100644
--- a/scumm/player_v2.cpp
+++ b/scumm/player_v2.cpp
@@ -348,7 +348,7 @@ Player_V2::Player_V2(ScummEngine *scumm, bool pcjr) {
 	_vm = scumm;
 	_system = scumm->_system;
 	_mixer = scumm->_mixer;
-	_sample_rate = _system->getOutputSampleRate();
+	_sample_rate = _mixer->getOutputRate();
 	_mutex = _system->createMutex();
 
 	_header_len = (scumm->_features & GF_OLD_BUNDLE) ? 4 : 6;
diff --git a/scumm/script_v72he.cpp b/scumm/script_v72he.cpp
index 4f63a152e3..47ffe6d35e 100644
--- a/scumm/script_v72he.cpp
+++ b/scumm/script_v72he.cpp
@@ -966,7 +966,7 @@ void ScummEngine_v72he::o72_setTimer() {
 void ScummEngine_v72he::o72_unknown5A() {
 	// Seems to get length of sound already played
 	int snd = pop();
-	int r = _mixer->getChannelElapsedTime(_sound->_musicChannelHandle);
+	int r = _mixer->getSoundElapsedTime(_sound->_musicChannelHandle);
 
 	push(r * 10);
 	debug(1,"o72_unknown5A stub (%d)", snd);
diff --git a/scumm/smush/smush_player.cpp b/scumm/smush/smush_player.cpp
index 2940cda6b9..5d6d764bf7 100644
--- a/scumm/smush/smush_player.cpp
+++ b/scumm/smush/smush_player.cpp
@@ -43,6 +43,7 @@
 #include "scumm/insane/insane.h"
 
 #include "sound/mixer.h"
+#include "sound/vorbis.h"
 
 #ifdef DUMP_SMUSH_FRAMES
 #include <png.h>
@@ -1162,7 +1163,7 @@ void SmushPlayer::tryOggFile(const char *filename) {
 	if (_compressedFile.isOpen()) {
 		int size = _compressedFile.size();
 		_compressedFileMode = true;
-		_vm->_mixer->playVorbis(&_compressedFileSoundHandle, &_compressedFile, size);
+		_vm->_mixer->playInputStream(&_compressedFileSoundHandle, makeVorbisStream(&_compressedFile, size), false);
 	}
 #endif
 }
diff --git a/simon/sound.cpp b/simon/sound.cpp
index 9eca280ef8..56b14b8d00 100644
--- a/simon/sound.cpp
+++ b/simon/sound.cpp
@@ -18,10 +18,16 @@
  */
 
 #include "stdafx.h"
+
 #include "common/file.h"
 #include "common/util.h"
+
 #include "simon/sound.h"
+
+#include "sound/flac.h"
+#include "sound/mp3.h"
 #include "sound/voc.h"
+#include "sound/vorbis.h"
 
 namespace Simon {
 
@@ -213,7 +219,7 @@ void MP3Sound::playSound(uint sound, PlayingSoundHandle *handle, byte flags)
 
 	uint32 size = _offsets[sound + i] - _offsets[sound];
 
-	_mixer->playMP3(handle, _file, size);
+	_mixer->playInputStream(handle, makeMP3Stream(_file, size), false);
 }
 #endif
 
@@ -237,7 +243,7 @@ void VorbisSound::playSound(uint sound, PlayingSoundHandle *handle, byte flags)
 
 	uint32 size = _offsets[sound + i] - _offsets[sound];
 
-	_mixer->playVorbis(handle, _file, size);
+	_mixer->playInputStream(handle, makeVorbisStream(_file, size), false);
 }
 #endif
 
@@ -261,7 +267,7 @@ void FlacSound::playSound(uint sound, PlayingSoundHandle *handle, byte flags)
 
 	uint32 size = _offsets[sound + i] - _offsets[sound];
 
-	_mixer->playFlac(handle, _file, size);
+	_mixer->playInputStream(handle, makeFlacStream(_file, size), false);
 }
 #endif
 
diff --git a/sound/mixer.cpp b/sound/mixer.cpp
index 6ecbe68fdd..b70f997126 100644
--- a/sound/mixer.cpp
+++ b/sound/mixer.cpp
@@ -27,9 +27,9 @@
 #include "sound/mixer.h"
 #include "sound/rate.h"
 #include "sound/audiostream.h"
+#include "sound/flac.h"
 #include "sound/mp3.h"
 #include "sound/vorbis.h"
-#include "sound/flac.h"
 
 
 #pragma mark -
@@ -150,7 +150,7 @@ SoundMixer::SoundMixer() {
 		_channels[i] = 0;
 
 	_mixerReady = _syst->setSoundCallback(mixCallback, this);
-	_outputRate = (uint) _syst->getOutputSampleRate();
+	_outputRate = (uint)_syst->getOutputSampleRate();
 
 	if (_outputRate == 0)
 		error("OSystem returned invalid sample rate");
@@ -316,30 +316,6 @@ void SoundMixer::playRaw(PlayingSoundHandle *handle, void *sound, uint32 size, u
 	insertChannel(handle, chan);
 }
 
-#ifdef USE_MAD
-void SoundMixer::playMP3(PlayingSoundHandle *handle, File *file, uint32 size, byte volume, int8 balance, int id) {
-	// Create the input stream
-	AudioStream *input = makeMP3Stream(file, size);
-	playInputStream(handle, input, false, volume, balance, id);
-}
-#endif
-
-#ifdef USE_VORBIS
-void SoundMixer::playVorbis(PlayingSoundHandle *handle, File *file, uint32 size, byte volume, int8 balance, int id) {
-	// Create the input stream
-	AudioStream *input = makeVorbisStream(file, size);
-	playInputStream(handle, input, false, volume, balance, id);
-}
-#endif
-
-#ifdef USE_FLAC
-void SoundMixer::playFlac(PlayingSoundHandle *handle, File *file, uint32 size, byte volume, int8 balance, int id) {
-	// Create the input stream
-	AudioStream *input = makeFlacStream(file, size);
-	playInputStream(handle, input, false, volume, balance, id);
-}
-#endif
-
 void SoundMixer::playInputStream(PlayingSoundHandle *handle, AudioStream *input, bool isMusic, byte volume, int8 balance, int id, bool autofreeStream) {
 	Common::StackLock lock(_mutex);
 
@@ -468,7 +444,7 @@ void SoundMixer::setChannelBalance(PlayingSoundHandle handle, int8 balance) {
 		_channels[index]->setBalance(balance);
 }
 
-uint32 SoundMixer::getChannelElapsedTime(PlayingSoundHandle handle) {
+uint32 SoundMixer::getSoundElapsedTime(PlayingSoundHandle handle) {
 	Common::StackLock lock(_mutex);
 
 	if (!handle.isActive())
@@ -477,14 +453,14 @@ uint32 SoundMixer::getChannelElapsedTime(PlayingSoundHandle handle) {
 	int index = handle.getIndex();
 
 	if ((index < 0) || (index >= NUM_CHANNELS)) {
-		warning("soundMixer::getChannelElapsedTime has invalid index %d", index);
+		warning("soundMixer::getSoundElapsedTime has invalid index %d", index);
 		return 0;
 	}
 
 	if (_channels[index])
 		return _channels[index]->getElapsedTime();
 
-	warning("soundMixer::getChannelElapsedTime has no channel object for index %d", index);
+	warning("soundMixer::getSoundElapsedTime has no channel object for index %d", index);
 	return 0;
 }
 
diff --git a/sound/mixer.h b/sound/mixer.h
index ae5055616b..725c1f7c4d 100644
--- a/sound/mixer.h
+++ b/sound/mixer.h
@@ -83,14 +83,20 @@ public:
 	SoundMixer();
 	~SoundMixer();
 
+
+
 	/**
 	 * Is the mixer ready and setup? This may not be the case on systems which
 	 * don't support digital sound output. In that case, the mixer proc may
 	 * never be called. That in turn can cause breakage in games which use the
 	 * premix callback for syncing. In particular, the Adlib MIDI emulation...
+	 *
+	 * @return whether the mixer is ready and setup
 	 */
 	bool isReady() const { return _mixerReady; };
 
+
+
 	/**
 	 * Set the premix procedure. This is mainly used for the adlib music, but
 	 * is not limited to it. The premix proc is invoked by the mixer whenever
@@ -113,22 +119,23 @@ public:
 	void setupPremix(AudioStream *stream);
 
 
-	// start playing a raw sound
+
+	/**
+	 * Start playing the given raw sound data.
+	 * Internally, this simply creates an audio input stream wrapping the data
+	 * (using the makeLinearInputStream factory function), which is then
+	 * passed on to playInputStream.
+	 */
 	void playRaw(PlayingSoundHandle *handle, void *sound, uint32 size, uint rate, byte flags,
 				int id = -1, byte volume = 255, int8 balance = 0, uint32 loopStart = 0, uint32 loopEnd = 0);
-#ifdef USE_MAD
-	void playMP3(PlayingSoundHandle *handle, File *file, uint32 size, byte volume = 255, int8 balance = 0, int id = -1);
-#endif
-#ifdef USE_VORBIS
-	void playVorbis(PlayingSoundHandle *handle, File *file, uint32 size, byte volume = 255, int8 balance = 0, int id = -1);
-#endif
-#ifdef USE_FLAC
-	void playFlac(PlayingSoundHandle *handle, File *file, uint32 size, byte volume = 255, int8 balance = 0, int id = -1);
-#endif
 
+	/**
+	 * Start playing the given audio input stream.
+	 */
 	void playInputStream(PlayingSoundHandle *handle, AudioStream *input, bool isMusic, byte volume = 255, int8 balance = 0, int id = -1, bool autofreeStream = true);
 
 
+
 	/** Start a new stream. */
 	void newStream(PlayingSoundHandle *handle, uint rate, byte flags, uint32 buffer_size, byte volume = 255, int8 balance = 0);
 
@@ -143,63 +150,149 @@ public:
 	 */
 	void endStream(PlayingSoundHandle handle);
 
-	/** stop all currently playing sounds */
+
+
+	/**
+	 * Stop all currently playing sounds.
+	 */
 	void stopAll();
 
-	/** stop playing the sound with given ID  */
+	/**
+	 * Stop playing the sound with given ID.
+	 *
+	 * @param id the ID of the sound to affect
+	 */
 	void stopID(int id);
 
-	/** stop playing the channel for the given handle */
+	/**
+	 * Stop playing the sound corresponding to the given handle.
+	 *
+	 * @param handle the sound to affect
+	 */
 	void stopHandle(PlayingSoundHandle handle);
 
-	/** pause/unpause all channels */
+
+
+	/**
+	 * Pause/unpause the mixer (this temporarily stops all audio processing,
+	 * including all regular channels and the premix channel).
+	 *
+	 * @param paused true to pause the mixer, false to unpause it
+	 */
 	void pauseAll(bool paused);
 
-	/** check if sound ID is active */
+	/**
+	 * Pause/unpause the sound with the given ID.
+	 *
+	 * @param id the ID of the sound to affect
+	 * @param paused true to pause the sound, false to unpause it
+	 */
+	void pauseID(int id, bool paused);
+
+	/**
+	 * Pause/unpause the sound corresponding to the given handle.
+	 *
+	 * @param handle the sound to affect
+	 * @param paused true to pause the sound, false to unpause it
+	 */
+	void pauseHandle(PlayingSoundHandle handle, bool paused);
+
+
+
+	/**
+	 * Check if a sound with the given ID is active.
+	 *
+	 * @param id the ID of the sound to query
+	 * @return true if the sound is active
+	 */
 	bool isSoundIDActive(int id);
 
-	/** check if mixer is paused */
+	/**
+	 * Check if the mixer is paused (using pauseAll).
+	 *
+	 * @return true if the mixer is paused
+	 */
 	bool isPaused();
 
-	/** pause/unpause the sound with the given ID */
-	void pauseID(int id, bool paused);
 
-	/** pause/unpause the channel for the given handle */
-	void pauseHandle(PlayingSoundHandle handle, bool paused);
 
-	/** set the channel volume for the given handle (0 - 255) */
+	/**
+	 * Set the channel volume for the given handle.
+	 *
+	 * @param handle the sound to affect
+	 * @param volume the new channel volume (0 - 255)
+	 */
 	void setChannelVolume(PlayingSoundHandle handle, byte volume);
 
-	/** set the channel balance for the given handle (-127 ... 0 ... 127) (left ... center ... right)*/
+	/**
+	 * Set the channel balance for the given handle.
+	 *
+	 * @param handle the sound to affect
+	 * @param balance the new channel balance:
+	 *        (-127 ... 0 ... 127) corresponds to (left ... center ... right)
+	 */
 	void setChannelBalance(PlayingSoundHandle handle, int8 balance);
 
-	/** get approximation of for how long the channel has been playing */
-	uint32 getChannelElapsedTime(PlayingSoundHandle handle);
+	/**
+	 * Get approximation of for how long the channel has been playing.
+	 */
+	uint32 getSoundElapsedTime(PlayingSoundHandle handle);
 
-	/** Check whether any SFX channel is active.*/
+	/**
+	 * Check whether any SFX channel is active.
+	 *
+	 * @return true if any SFX (= non-music) channels are active.
+	 */
 	bool hasActiveSFXChannel();
 
-	/** set the global volume, 0-256 */
+	/**
+	 * Set the global volume.
+	 *
+	 * @param volume the new global volume, 0-256
+	 */
 	void setVolume(int volume);
 
-	/** query the global volume, 0-256 */
+	/**
+	 * Query the global volume.
+	 *
+	 * @return the global music volume, 0-256
+	 */
 	int getVolume() const { return _globalVolume; }
 
-	/** set the music volume, 0-256 */
+	/**
+	 * Set the music volume.
+	 *
+	 * @param volume the new music volume, 0-256
+	 */
 	void setMusicVolume(int volume);
 
-	/** query the music volume, 0-256 */
+	/**
+	 * Query the music volume.
+	 *
+	 * @return the current music volume, 0-256
+	 */
 	int getMusicVolume() const { return _musicVolume; }
 
-	/** query the output rate in kHz */
+	/**
+	 * Query the system's audio output sample rate. This returns
+	 * the same value as OSystem::getOutputSampleRate().
+	 *
+	 * @return the output sample rate in Hz
+	 */
 	uint getOutputRate() const { return _outputRate; }
 
 private:
 	void insertChannel(PlayingSoundHandle *handle, Channel *chan);
 
-	/** main mixer method */
+	/**
+	 * Internal main method -- all the actual mixing work is done from here.
+	 */
 	void mix(int16 * buf, uint len);
 
+	/**
+	 * The mixer callback function, passed on to OSystem::setSoundCallback().
+	 * This simply calls the mix() method.
+	 */
 	static void mixCallback(void *s, byte *samples, int len);
 };
 
diff --git a/sword1/sound.cpp b/sword1/sound.cpp
index 7438a876d2..c9b5806f5a 100644
--- a/sword1/sound.cpp
+++ b/sword1/sound.cpp
@@ -26,6 +26,9 @@
 #include "sword1/logic.h"
 #include "sword1/sword1.h"
 
+#include "sound/mp3.h"
+#include "sound/vorbis.h"
+
 namespace Sword1 {
 
 #define SOUND_SPEECH_ID 1
@@ -191,7 +194,7 @@ bool Sound::startSpeech(uint16 roomNo, uint16 localNo) {
 #ifdef USE_MAD
 		else if (_cowMode == CowMp3) {
 			_cowFile.seek(index);
-			_mixer->playMP3(&_speechHandle, &_cowFile, sampleSize, speechVol, speechPan, SOUND_SPEECH_ID);
+			_mixer->playInputStream(&_speechHandle, makeMP3Stream(&_cowFile, sampleSize), false, speechVol, speechPan, SOUND_SPEECH_ID);
 			// with compressed audio, we can't calculate the wave volume.
 			// so default to talking.
 			for (int cnt = 0; cnt < 480; cnt++)
@@ -202,7 +205,7 @@ bool Sound::startSpeech(uint16 roomNo, uint16 localNo) {
 #ifdef USE_VORBIS
 		else if (_cowMode == CowVorbis) {
 			_cowFile.seek(index);
-			_mixer->playVorbis(&_speechHandle, &_cowFile, sampleSize, speechVol, speechPan, SOUND_SPEECH_ID);
+			_mixer->playInputStream(&_speechHandle, makeVorbisStream(&_cowFile, sampleSize), false, speechVol, speechPan, SOUND_SPEECH_ID);
 			for (int cnt = 0; cnt < 480; cnt++)
 				_waveVolume[cnt] = true;	
 			_waveVolPos = 0;