* Reimplemented Mixer::pauseAll to simply invoke pause on all channels

  (implying change of semantics)
* Reordered the params of Mixer::playRaw (the SoundType now comes first, not last)
* Removed Mixer::isPaused
* Removed Mixer::getSoundElapsedTimeOfSoundID
* Added some doxygen comments to the Mixer

svn-id: r25356

13 files changed, 102 insertions, 87 deletions

diff --git a/engines/agos/sound.cpp b/engines/agos/sound.cpp
index 3349f93a77..b6ee6cf02c 100644
--- a/engines/agos/sound.cpp
+++ b/engines/agos/sound.cpp
@@ -248,7 +248,7 @@ void VocSound::playSound(uint sound, uint loopSound, Audio::SoundHandle *handle,
 	int size, rate;
 	byte *buffer = Audio::loadVOCFromStream(*_file, size, rate);
 	assert(buffer);
-	_mixer->playRaw(handle, buffer, size, rate, flags | Audio::Mixer::FLAG_AUTOFREE, sound);
+	_mixer->playRaw(Audio::Mixer::kSFXSoundType, handle, buffer, size, rate, flags | Audio::Mixer::FLAG_AUTOFREE, sound);
 }
 
 void RawSound::playSound(uint sound, uint loopSound, Audio::SoundHandle *handle, byte flags, int vol) {
@@ -261,7 +261,7 @@ void RawSound::playSound(uint sound, uint loopSound, Audio::SoundHandle *handle,
 	byte *buffer = (byte *)malloc(size);
 	assert(buffer);
 	_file->read(buffer, size);
-	_mixer->playRaw(handle, buffer, size, 22050, flags | Audio::Mixer::FLAG_AUTOFREE, sound);
+	_mixer->playRaw(Audio::Mixer::kSFXSoundType, handle, buffer, size, 22050, flags | Audio::Mixer::FLAG_AUTOFREE, sound);
 }
 
 #ifdef USE_MAD
@@ -671,9 +671,9 @@ void Sound::playRawData(byte *soundData, uint sound, uint size) {
 	memcpy(buffer, soundData, size);
 
 	if (_vm->getPlatform() == Common::kPlatformPC)
-		_mixer->playRaw(&_effectsHandle, buffer, size, 8000, Audio::Mixer::FLAG_UNSIGNED | Audio::Mixer::FLAG_AUTOFREE, sound);
+		_mixer->playRaw(Audio::Mixer::kSFXSoundType, &_effectsHandle, buffer, size, 8000, Audio::Mixer::FLAG_UNSIGNED | Audio::Mixer::FLAG_AUTOFREE, sound);
 	else
-		_mixer->playRaw(&_effectsHandle, buffer, size, 8000, Audio::Mixer::FLAG_AUTOFREE, sound);
+		_mixer->playRaw(Audio::Mixer::kSFXSoundType, &_effectsHandle, buffer, size, 8000, Audio::Mixer::FLAG_AUTOFREE, sound);
 }
 
 // Feeble Files specific
@@ -737,7 +737,7 @@ void Sound::playSoundData(Audio::SoundHandle *handle, byte *soundData, uint soun
 		memcpy(buffer, soundData + stream.pos(), size);
 	}
 
-	_mixer->playRaw(handle, buffer, size, rate, flags | Audio::Mixer::FLAG_AUTOFREE, sound, vol, pan);
+	_mixer->playRaw(Audio::Mixer::kSFXSoundType, handle, buffer, size, rate, flags | Audio::Mixer::FLAG_AUTOFREE, sound, vol, pan);
 }
 
 void Sound::stopSfx5() {
diff --git a/engines/queen/sound.cpp b/engines/queen/sound.cpp
index 6cea53f1c1..b416bb953c 100644
--- a/engines/queen/sound.cpp
+++ b/engines/queen/sound.cpp
@@ -198,7 +198,7 @@ void SBSound::playSoundData(Common::File *f, uint32 size, Audio::SoundHandle *so
 	if (sound) {
 		f->read(sound, size);
 		byte flags = Audio::Mixer::FLAG_UNSIGNED | Audio::Mixer::FLAG_AUTOFREE;
-		_mixer->playRaw(soundHandle, sound, size, 11025, flags);
+		_mixer->playRaw(Audio::Mixer::kSFXSoundType, soundHandle, sound, size, 11025, flags);
 	}
 }
 
diff --git a/engines/saga/sound.cpp b/engines/saga/sound.cpp
index 37f9cf174f..d528db5add 100644
--- a/engines/saga/sound.cpp
+++ b/engines/saga/sound.cpp
@@ -79,7 +79,7 @@ void Sound::playSoundBuffer(Audio::SoundHandle *handle, SoundBuffer &buffer, int
 	if (!buffer.isSigned)
 		flags |= Audio::Mixer::FLAG_UNSIGNED;
 
-	_mixer->playRaw(handle, buffer.buffer, buffer.size, buffer.frequency, flags, -1, volume);
+	_mixer->playRaw(Audio::Mixer::kSFXSoundType, handle, buffer.buffer, buffer.size, buffer.frequency, flags, -1, volume);
 }
 
 void Sound::playSound(SoundBuffer &buffer, int volume, bool loop) {
diff --git a/engines/scumm/he/cup_player_he.cpp b/engines/scumm/he/cup_player_he.cpp
index 695d298be6..f2e181fb41 100644
--- a/engines/scumm/he/cup_player_he.cpp
+++ b/engines/scumm/he/cup_player_he.cpp
@@ -169,7 +169,7 @@ void CUP_Player::updateSfx() {
 					flags |= Audio::Mixer::FLAG_LOOP;
 					loopEnd = soundSize - 8;
 				}
-				_mixer->playRaw(&sfxChannel->handle, soundData + 8, soundSize - 8, 11025, flags, -1, 255, 0, 0, loopEnd);
+				_mixer->playRaw(Audio::Mixer::kSFXSoundType, &sfxChannel->handle, soundData + 8, soundSize - 8, 11025, flags, -1, 255, 0, 0, loopEnd);
 			}
 		} else {
 			warning("Unable to find a free channel to play sound %d", sfx->num);
diff --git a/engines/scumm/he/sound_he.cpp b/engines/scumm/he/sound_he.cpp
index 931ef12c95..17cc10c59e 100644
--- a/engines/scumm/he/sound_he.cpp
+++ b/engines/scumm/he/sound_he.cpp
@@ -535,7 +535,7 @@ void SoundHE::playHESound(int soundID, int heOffset, int heChannel, int heFlags)
 		musicFile.close();
 
 		if (_vm->_game.heversion == 70) {
-			_mixer->playRaw(&_heSoundChannels[heChannel], spoolPtr, size, 11025, flags, soundID, 255, 0, 0,0, type);
+			_mixer->playRaw(type, &_heSoundChannels[heChannel], spoolPtr, size, 11025, flags, soundID, 255, 0, 0, 0);
 			return;
 		}
 	}
@@ -586,7 +586,7 @@ void SoundHE::playHESound(int soundID, int heOffset, int heChannel, int heFlags)
 		}
 
 		_mixer->stopHandle(_heSoundChannels[heChannel]);
-		_mixer->playRaw(&_heSoundChannels[heChannel], sound, size, rate, flags, soundID, 255, 0, 0,0, type);
+		_mixer->playRaw(type, &_heSoundChannels[heChannel], sound, size, rate, flags, soundID, 255, 0, 0,0);
 	}
 	// Support for sound in Humongous Entertainment games
 	else if (READ_BE_UINT32(ptr) == MKID_BE('DIGI') || READ_BE_UINT32(ptr) == MKID_BE('TALK')) {
@@ -642,7 +642,7 @@ void SoundHE::playHESound(int soundID, int heOffset, int heChannel, int heFlags)
 		}
 
 		_mixer->stopHandle(_heSoundChannels[heChannel]);
-		_mixer->playRaw(&_heSoundChannels[heChannel], ptr + heOffset + 8, size, rate, flags, soundID, 255, 0, 0,0, type);
+		_mixer->playRaw(type, &_heSoundChannels[heChannel], ptr + heOffset + 8, size, rate, flags, soundID, 255, 0, 0,0);
 
 	}
 	// Support for PCM music in 3DO versions of Humongous Entertainment games
@@ -660,7 +660,7 @@ void SoundHE::playHESound(int soundID, int heOffset, int heChannel, int heFlags)
 
 		_mixer->stopID(_currentMusic);
 		_currentMusic = soundID;
-		_mixer->playRaw(NULL, ptr + 8, size, rate, flags, soundID, 255, 0, 0,0, Audio::Mixer::kMusicSoundType);
+		_mixer->playRaw(Audio::Mixer::kMusicSoundType, NULL, ptr + 8, size, rate, flags, soundID, 255, 0, 0,0);
 	}
 	else if (READ_BE_UINT32(ptr) == MKID_BE('MIDI')) {
 		if (_vm->_imuse) {
diff --git a/engines/scumm/sound.cpp b/engines/scumm/sound.cpp
index 8a71b455e9..bde14d3c55 100644
--- a/engines/scumm/sound.cpp
+++ b/engines/scumm/sound.cpp
@@ -188,7 +188,7 @@ void Sound::playSound(int soundID) {
 		// Allocate a sound buffer, copy the data into it, and play
 		sound = (char *)malloc(size);
 		memcpy(sound, ptr, size);
-		_mixer->playRaw(NULL, sound, size, rate, flags, soundID);
+		_mixer->playRaw(Audio::Mixer::kSFXSoundType, NULL, sound, size, rate, flags, soundID);
 	}
 	// WORKAROUND bug # 1311447
 	else if (READ_BE_UINT32(ptr) == 0x460e200d) {
@@ -210,7 +210,7 @@ void Sound::playSound(int soundID) {
 		// Allocate a sound buffer, copy the data into it, and play
 		sound = (char *)malloc(size);
 		memcpy(sound, ptr, size);
-		_mixer->playRaw(NULL, sound, size, rate, flags, soundID);
+		_mixer->playRaw(Audio::Mixer::kSFXSoundType, NULL, sound, size, rate, flags, soundID);
 	}
 	// Support for sampled sound effects in Monkey Island 1 and 2
 	else if (READ_BE_UINT32(ptr) == MKID_BE('SBL ')) {
@@ -281,7 +281,7 @@ void Sound::playSound(int soundID) {
 		// Allocate a sound buffer, copy the data into it, and play
 		sound = (char *)malloc(size);
 		memcpy(sound, ptr + 6, size);
-		_mixer->playRaw(NULL, sound, size, rate, flags, soundID);
+		_mixer->playRaw(Audio::Mixer::kSFXSoundType, NULL, sound, size, rate, flags, soundID);
 	}
 	else if ((_vm->_game.platform == Common::kPlatformFMTowns && _vm->_game.version == 3) || READ_BE_UINT32(ptr) == MKID_BE('SOUN') || READ_BE_UINT32(ptr) == MKID_BE('TOWS')) {
 
@@ -334,7 +334,7 @@ void Sound::playSound(int soundID) {
 				if (loopEnd > 0)
 					flags |= Audio::Mixer::FLAG_LOOP;
 
-				_mixer->playRaw(NULL, sound, waveSize, rate, flags, soundID, 255, 0, loopStart, loopEnd);
+				_mixer->playRaw(Audio::Mixer::kSFXSoundType, NULL, sound, waveSize, rate, flags, soundID, 255, 0, loopStart, loopEnd);
 			}
 			break;
 		case 1:
@@ -395,7 +395,7 @@ void Sound::playSound(int soundID) {
 		sound = (char *)malloc(size);
 		int vol = ptr[24] * 4;
 		memcpy(sound, ptr + READ_BE_UINT16(ptr + 8), size);
-		_mixer->playRaw(NULL, sound, size, rate, Audio::Mixer::FLAG_AUTOFREE, soundID, vol, 0);
+		_mixer->playRaw(Audio::Mixer::kSFXSoundType, NULL, sound, size, rate, Audio::Mixer::FLAG_AUTOFREE, soundID, vol, 0);
 	}
 	else {
 
diff --git a/engines/sky/intro.cpp b/engines/sky/intro.cpp
index 6c50ea9804..55143d7f86 100644
--- a/engines/sky/intro.cpp
+++ b/engines/sky/intro.cpp
@@ -740,7 +740,7 @@ bool Intro::nextPart(uint16 *&data) {
 		// probably use _skySound instead of calling playRaw()
 		// directly, but this will have to do for now.
 		memset(vData, 127, sizeof(struct dataFileHeader));
-		_mixer->playRaw(&_voice, vData, _skyDisk->_lastLoadedFileSize, 11025,
+		_mixer->playRaw(Audio::Mixer::kSFXSoundType, &_voice, vData, _skyDisk->_lastLoadedFileSize, 11025,
 				Audio::Mixer::FLAG_AUTOFREE | Audio::Mixer::FLAG_UNSIGNED, SOUND_VOICE);
 		return true;
 	case WAITVOICE:
@@ -757,12 +757,12 @@ bool Intro::nextPart(uint16 *&data) {
 		return true;
 	case LOOPBG:
 		_mixer->stopID(SOUND_BG);
-		_mixer->playRaw(&_bgSfx, _bgBuf + 256, _bgSize - 768, 11025,
+		_mixer->playRaw(Audio::Mixer::kSFXSoundType, &_bgSfx, _bgBuf + 256, _bgSize - 768, 11025,
 				Audio::Mixer::FLAG_UNSIGNED | Audio::Mixer::FLAG_LOOP, SOUND_BG);
 		return true;
 	case PLAYBG:
 		_mixer->stopID(SOUND_BG);
-		_mixer->playRaw(&_bgSfx, _bgBuf + 256, _bgSize - 768, 11025,
+		_mixer->playRaw(Audio::Mixer::kSFXSoundType, &_bgSfx, _bgBuf + 256, _bgSize - 768, 11025,
 				Audio::Mixer::FLAG_UNSIGNED, SOUND_BG);
 		return true;
 	case STOPBG:
diff --git a/engines/sky/sound.cpp b/engines/sky/sound.cpp
index b2263482dd..edcfd81581 100644
--- a/engines/sky/sound.cpp
+++ b/engines/sky/sound.cpp
@@ -1040,7 +1040,7 @@ void Sound::playSound(uint32 id, byte *sound, uint32 size, Audio::SoundHandle *h
 	memcpy(buffer, sound+sizeof(struct dataFileHeader), size);
 
 	_mixer->stopID(id);
-	_mixer->playRaw(handle, buffer, size, 11025, flags, id);
+	_mixer->playRaw(Audio::Mixer::kSFXSoundType, handle, buffer, size, 11025, flags, id);
 }
 
 void Sound::loadSection(uint8 pSection) {
@@ -1118,9 +1118,9 @@ void Sound::playSound(uint16 sound, uint16 volume, uint8 channel) {
 	}
 
 	if (channel == 0)
-		_mixer->playRaw(&_ingameSound0, _soundData + dataOfs, dataSize, sampleRate, flags, SOUND_CH0, volume, 0, loopSta, loopEnd);
+		_mixer->playRaw(Audio::Mixer::kSFXSoundType, &_ingameSound0, _soundData + dataOfs, dataSize, sampleRate, flags, SOUND_CH0, volume, 0, loopSta, loopEnd);
 	else
-		_mixer->playRaw(&_ingameSound1, _soundData + dataOfs, dataSize, sampleRate, flags, SOUND_CH1, volume, 0, loopSta, loopEnd);
+		_mixer->playRaw(Audio::Mixer::kSFXSoundType, &_ingameSound1, _soundData + dataOfs, dataSize, sampleRate, flags, SOUND_CH1, volume, 0, loopSta, loopEnd);
 }
 
 void Sound::fnStartFx(uint32 sound, uint8 channel) {
@@ -1245,7 +1245,7 @@ bool Sound::startSpeech(uint16 textNum) {
 		rate = 11025;
 
 	_mixer->stopID(SOUND_SPEECH);
-	_mixer->playRaw(&_ingameSpeech, playBuffer, speechSize, rate, Audio::Mixer::FLAG_UNSIGNED | Audio::Mixer::FLAG_AUTOFREE, SOUND_SPEECH);
+	_mixer->playRaw(Audio::Mixer::kSFXSoundType, &_ingameSpeech, playBuffer, speechSize, rate, Audio::Mixer::FLAG_UNSIGNED | Audio::Mixer::FLAG_AUTOFREE, SOUND_SPEECH);
 	return true;
 }
 
diff --git a/engines/sword1/sound.cpp b/engines/sword1/sound.cpp
index f699a4c475..fa4d9c3adc 100644
--- a/engines/sword1/sound.cpp
+++ b/engines/sword1/sound.cpp
@@ -172,7 +172,7 @@ void Sound::playSample(QueueElement *elem) {
 						flags |= Audio::Mixer::FLAG_STEREO;
 					if (_fxList[elem->id].type == FX_LOOP)
 						flags |= Audio::Mixer::FLAG_LOOP;
-					_mixer->playRaw(&elem->handle, sampleData + 0x2C, size, 11025, flags, elem->id, volume, pan);
+					_mixer->playRaw(Audio::Mixer::kSFXSoundType, &elem->handle, sampleData + 0x2C, size, 11025, flags, elem->id, volume, pan);
 			}
 		} else
 			break;
@@ -196,7 +196,7 @@ bool Sound::startSpeech(uint16 roomNo, uint16 localNo) {
 			uint32 size;
 			int16 *data = uncompressSpeech(index + _cowHeaderSize, sampleSize, &size);
 			if (data)
-				_mixer->playRaw(&_speechHandle, data, size, 11025, SPEECH_FLAGS, SOUND_SPEECH_ID, speechVol, speechPan);
+				_mixer->playRaw(Audio::Mixer::kSFXSoundType, &_speechHandle, data, size, 11025, SPEECH_FLAGS, SOUND_SPEECH_ID, speechVol, speechPan);
 		}
 #ifdef USE_MAD
 		else if (_cowMode == CowMp3) {
diff --git a/engines/sword2/animation.cpp b/engines/sword2/animation.cpp
index 3f9cbb482e..838c37dc6e 100644
--- a/engines/sword2/animation.cpp
+++ b/engines/sword2/animation.cpp
@@ -351,7 +351,7 @@ void MoviePlayer::play(int32 leadIn, int32 leadOut) {
 			}
 
 			if (startNextText && !_mixer->isSoundHandleActive(_speechHandle)) {
-				_mixer->playRaw(&_speechHandle, t->speech, t->speechBufferSize, 22050, flags);
+				_mixer->playRaw(Audio::Mixer::kSFXSoundType, &_speechHandle, t->speech, t->speechBufferSize, 22050, flags);
 				startNextText = false;
 			}
 
diff --git a/engines/sword2/sound.cpp b/engines/sword2/sound.cpp
index 561b7dc45e..b1de94f3ad 100644
--- a/engines/sword2/sound.cpp
+++ b/engines/sword2/sound.cpp
@@ -311,7 +311,7 @@ int32 Sound::playFx(Audio::SoundHandle *handle, byte *data, uint32 len, uint8 vo
 	if (loop)
 		flags |= Audio::Mixer::FLAG_LOOP;
 
-	_vm->_mixer->playRaw(handle, data + stream.pos(), size, rate, flags, -1, vol, pan, 0, 0, soundType);
+	_vm->_mixer->playRaw(soundType, handle, data + stream.pos(), size, rate, flags, -1, vol, pan, 0, 0);
 	return RD_OK;
 }
 
diff --git a/sound/mixer.cpp b/sound/mixer.cpp
index ad203ece5b..2cb1063828 100644
--- a/sound/mixer.cpp
+++ b/sound/mixer.cpp
@@ -114,8 +114,6 @@ Mixer::Mixer() {
 	for (i = 0; i < ARRAYSIZE(_volumeForSoundType); i++)
 		_volumeForSoundType[i] = kMaxMixerVolume;
 
-	_paused = false;
-
 	for (i = 0; i != NUM_CHANNELS; i++)
 		_channels[i] = 0;
 
@@ -133,10 +131,6 @@ uint Mixer::getOutputRate() const {
 	return (uint)_syst->getOutputSampleRate();
 }
 
-bool Mixer::isPaused() {
-	return _paused;
-}
-
 void Mixer::setupPremix(AudioStream *stream, SoundType type) {
 	Common::StackLock lock(_mutex);
 
@@ -173,8 +167,13 @@ void Mixer::insertChannel(SoundHandle *handle, Channel *chan) {
 	}
 }
 
-void Mixer::playRaw(SoundHandle *handle, void *sound, uint32 size, uint rate, byte flags,
-			int id, byte volume, int8 balance, uint32 loopStart, uint32 loopEnd, SoundType type) {
+void Mixer::playRaw(
+			SoundType type,
+			SoundHandle *handle,
+			void *sound,
+			uint32 size, uint rate, byte flags,
+			int id, byte volume, int8 balance,
+			uint32 loopStart, uint32 loopEnd) {
 	Common::StackLock lock(_mutex);
 
 	// Prevent duplicate sounds
@@ -207,8 +206,13 @@ void Mixer::playRaw(SoundHandle *handle, void *sound, uint32 size, uint rate, by
 	insertChannel(handle, chan);
 }
 
-void Mixer::playInputStream(SoundType type, SoundHandle *handle, AudioStream *input,
-			int id, byte volume, int8 balance, bool autofreeStream, bool permanent) {
+void Mixer::playInputStream(
+			SoundType type,
+			SoundHandle *handle,
+			AudioStream *input,
+			int id, byte volume, int8 balance,
+			bool autofreeStream,
+			bool permanent) {
 	Common::StackLock lock(_mutex);
 
 	if (input == 0) {
@@ -242,20 +246,18 @@ void Mixer::mix(int16 *buf, uint len) {
 	//  zero the buf
 	memset(buf, 0, 2 * len * sizeof(int16));
 
-	if (!_paused) {
-		if (_premixChannel)
-			_premixChannel->mix(buf, len);
+	if (_premixChannel)
+		_premixChannel->mix(buf, len);
 
-		// now mix all channels
-		for (int i = 0; i != NUM_CHANNELS; i++)
-			if (_channels[i]) {
-				if (_channels[i]->isFinished()) {
-					delete _channels[i];
-					_channels[i] = 0;
-				} else if (!_channels[i]->isPaused())
-					_channels[i]->mix(buf, len);
-			}
-	}
+	// now mix all channels
+	for (int i = 0; i != NUM_CHANNELS; i++)
+		if (_channels[i]) {
+			if (_channels[i]->isFinished()) {
+				delete _channels[i];
+				_channels[i] = 0;
+			} else if (!_channels[i]->isPaused())
+				_channels[i]->mix(buf, len);
+		}
 }
 
 void Mixer::mixCallback(void *s, byte *samples, int len) {
@@ -319,14 +321,6 @@ void Mixer::setChannelBalance(SoundHandle handle, int8 balance) {
 	_channels[index]->setBalance(balance);
 }
 
-uint32 Mixer::getSoundElapsedTimeOfSoundID(int id) {
-	Common::StackLock lock(_mutex);
-	for (int i = 0; i != NUM_CHANNELS; i++)
-		if (_channels[i] && _channels[i]->getId() == id)
-			return _channels[i]->getElapsedTime();
-	return 0;
-}
-
 uint32 Mixer::getSoundElapsedTime(SoundHandle handle) {
 	Common::StackLock lock(_mutex);
 
@@ -338,7 +332,12 @@ uint32 Mixer::getSoundElapsedTime(SoundHandle handle) {
 }
 
 void Mixer::pauseAll(bool paused) {
-	_paused = paused;
+	Common::StackLock lock(_mutex);
+	for (int i = 0; i != NUM_CHANNELS; i++) {
+		if (_channels[i] != 0) {
+			_channels[i]->pause(paused);
+		}
+	}
 }
 
 void Mixer::pauseID(int id, bool paused) {
@@ -354,7 +353,7 @@ void Mixer::pauseID(int id, bool paused) {
 void Mixer::pauseHandle(SoundHandle handle, bool paused) {
 	Common::StackLock lock(_mutex);
 
-	// Simply ignore pause/unpause requests for handles of sound that alreayd terminated
+	// Simply ignore (un)pause requests for sounds that already terminated
 	const int index = handle._val % NUM_CHANNELS;
 	if (!_channels[index] || _channels[index]->_handle._val != handle._val)
 		return;
diff --git a/sound/mixer.h b/sound/mixer.h
index bb3e3a711f..f2bec71057 100644
--- a/sound/mixer.h
+++ b/sound/mixer.h
@@ -38,6 +38,12 @@ class AudioStream;
 class Channel;
 class Mixer;
 
+/**
+ * A SoundHandle instances corresponds to a specific sound
+ * being played via the mixer. It can be used to control that
+ * sound (pause it, stop it, etc.).
+ * @see The Mixer class
+ */
 class SoundHandle {
 	friend class Channel;
 	friend class Mixer;
@@ -46,6 +52,10 @@ public:
 	inline SoundHandle() : _val(0xFFFFFFFF) {}
 };
 
+/**
+ * The main audio mixer handles mixing of an arbitrary number of
+ * input audio streams (in the form of AudioStream instances).
+ */
 class Mixer {
 public:
 	enum {
@@ -96,8 +106,6 @@ private:
 
 	int _volumeForSoundType[4];
 
-	bool _paused;
-
 	uint32 _handleSeed;
 	Channel *_channels[NUM_CHANNELS];
 
@@ -136,18 +144,38 @@ public:
 	 * (using the makeLinearInputStream factory function), which is then
 	 * passed on to playInputStream.
 	 */
-	void playRaw(SoundHandle *handle,
-				void *sound, uint32 size, uint rate, byte flags,
-				int id = -1, byte volume = 255, int8 balance = 0,
-				uint32 loopStart = 0, uint32 loopEnd = 0,
-				SoundType type = kSFXSoundType);
+	void playRaw(
+		SoundType type,
+		SoundHandle *handle,
+		void *sound, uint32 size, uint rate, byte flags,
+		int id = -1, byte volume = 255, int8 balance = 0,
+		uint32 loopStart = 0, uint32 loopEnd = 0);
 
 	/**
 	 * Start playing the given audio input stream.
+	 *
+	 * Note that the sound id assigned below is unique. At most one stream
+	 * with a given idea can play at any given time. Trying to play a sound
+	 * with an id that is already in use causes the new sound to be not played.
+	 *
+	 * @param type	the type (voice/sfx/music) of the stream
+	 * @param handle	a SoundHandle which can be used to reference and control
+	 *                  the stream via suitable mixer methods
+	 * @param input	the actual AudioStream to be played
+	 * @param id	a unique id assigned to this stream
+	 * @param volume	the volume with which to play the sound, ranging from 0 to 255
+	 * @param balance	the balance with which to play the sound, ranging from -128 to 127
+	 * @param autofreeStream	a flag indicating whether the stream should be
+	 *                          freed after playback finished
+	 * @param permanent	a flag indicating whether a plain stopAll call should
+	 *                  not stop this particular stream
 	 */
-	void playInputStream(SoundType type, SoundHandle *handle, AudioStream *input,
-				int id = -1, byte volume = 255, int8 balance = 0,
-				bool autofreeStream = true, bool permanent = false);
+	void playInputStream(
+		SoundType type,
+		SoundHandle *handle,
+		AudioStream *input,
+		int id = -1, byte volume = 255, int8 balance = 0,
+		bool autofreeStream = true, bool permanent = false);
 
 
 
@@ -173,10 +201,10 @@ public:
 
 
 	/**
-	 * Pause/unpause the mixer (this temporarily stops all audio processing,
-	 * including all regular channels and the premix channel).
+	 * Pause/unpause all sounds, including all regular channels and the
+	 * premix channel.
 	 *
-	 * @param paused true to pause the mixer, false to unpause it
+	 * @param paused true to pause everything, false to unpause
 	 */
 	void pauseAll(bool paused);
 
@@ -215,20 +243,13 @@ public:
 	int getSoundID(SoundHandle handle);
 
 	/**
-	 * Check if a sound with the given hANDLE is active.
+	 * Check if a sound with the given handle is active.
 	 *
 	 * @param handle sound to query
 	 * @return true if the sound is active
 	 */
 	bool isSoundHandleActive(SoundHandle handle);
 
-	/**
-	 * Check if the mixer is paused (using pauseAll).
-	 *
-	 * @return true if the mixer is paused
-	 */
-	bool isPaused();
-
 
 
 	/**
@@ -249,11 +270,6 @@ public:
 	void setChannelBalance(SoundHandle handle, int8 balance);
 
 	/**
-	 * Get approximation of for how long the Sound ID has been playing.
-	 */
-	uint32 getSoundElapsedTimeOfSoundID(int id);
-
-	/**
 	 * Get approximation of for how long the channel has been playing.
 	 */
 	uint32 getSoundElapsedTime(SoundHandle handle);