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

svn-id: r15914

2 files changed, 129 insertions, 60 deletions

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);
 };