added doxygeb comments

added checks to public functions if resources already got loaded

svn-id: r43046

2 files changed, 62 insertions, 40 deletions

diff --git a/sound/mods/tfmx.cpp b/sound/mods/tfmx.cpp
index 5d37125e56..1f4713b97c 100644
--- a/sound/mods/tfmx.cpp
+++ b/sound/mods/tfmx.cpp
@@ -59,11 +59,9 @@ Tfmx::Tfmx(int rate, bool stereo)
 	for (int i = 0; i < kNumVoices; ++i) 
 		_channelCtx[i].paulaChannel = (byte)i;
 
-	_playerCtx.song = -1;
 	_playerCtx.volume = 0x40;
 	_playerCtx.patternSkip = 6;
-	stopPatternChannels();
-	stopMacroChannels();
+	stopSongImpl();
 
 	setTimerBaseValue(kPalCiaClock);
 	setInterruptFreqUnscaled(kPalDefaultCiaVal);
@@ -242,17 +240,12 @@ void Tfmx::macroRun(ChannelContext &channel) {
 				// those commands are: Wait, WaitDMA, AddPrevNote, AddNote, SetNote, <unknown Cmd>
 				// DMA On is affected aswell
 				// TODO remember time disabled, remember pending dmaoff?.
-			} else {
-				//TODO ?
 			}
 
-			if (macroPtr[2])
-				channel.volume = macroPtr[3];
-			else if (macroPtr[3])
-				channel.volume = channel.relVol * 3 + macroPtr[3];
-			else
-				continue;
-			Paula::setChannelVolume(channel.paulaChannel, channel.volume);
+			if (macroPtr[2] || macroPtr[3]) {
+				channel.volume = (macroPtr[2] ? 0 : channel.relVol * 3) + macroPtr[3];
+				Paula::setChannelVolume(channel.paulaChannel, channel.volume);
+			}
 			continue;
 
 		case 0x01:	// DMA On
@@ -919,6 +912,8 @@ void Tfmx::doMacro(int note, int macro, int relVol, int finetune, int channelNo)
 	assert(0 <= note && note < 0xC0);
 	Common::StackLock lock(_mutex);
 
+	if (!hasResources())
+		return;
 	channelNo &= (kNumVoices - 1);
 	ChannelContext &channel = _channelCtx[channelNo];
 	unlockMacroChannel(channel);
@@ -935,30 +930,19 @@ void Tfmx::stopMacroEffect(int channel) {
 	Paula::disableChannel(_channelCtx[channel].paulaChannel);
 }
 
-void Tfmx::stopSong(bool stopAudio) {
-	Common::StackLock lock(_mutex);
-	_playerCtx.song = -1;
-	if (stopAudio) {
-		stopMacroChannels();
-		stopPaula();
-	}
-}
-
 void Tfmx::doSong(int songPos, bool stopAudio) {
 	assert(0 <= songPos && songPos < kNumSubsongs);
 	Common::StackLock lock(_mutex);
 
-	stopPatternChannels();
-	if (stopAudio) {
-		stopMacroChannels();
-		stopPaula();
-	}
+	stopSongImpl(stopAudio);
 
-	_playerCtx.song = (int8)songPos;
+	if (!hasResources())
+		return;
 
 	_trackCtx.loopCount = -1;
 	_trackCtx.startInd = _trackCtx.posInd = _resource->subsong[songPos].songstart;
 	_trackCtx.stopInd = _resource->subsong[songPos].songend;
+	_playerCtx.song = (int8)songPos;
 
 	const bool palFlag = (_resource->headerFlags & 2) != 0;
 	const uint16 tempo = _resource->subsong[songPos].tempo;
@@ -981,8 +965,11 @@ int Tfmx::doSfx(uint16 sfxIndex, bool unlockChannel) {
 	assert(sfxIndex < 128);
 	Common::StackLock lock(_mutex);
 
+	if (!hasResources())
+		return -1;
 	const byte *sfxEntry = getSfxPtr(sfxIndex);
 	if (sfxEntry[0] == 0xFB) {
+		warning("Tfmx: custom patterns are not supported");
 		// custompattern
 		/* const uint8 patCmd = sfxEntry[2];
 		const int8 patExp = (int8)sfxEntry[3]; */
diff --git a/sound/mods/tfmx.h b/sound/mods/tfmx.h
index 2b857dbe1d..9af348ad47 100644
--- a/sound/mods/tfmx.h
+++ b/sound/mods/tfmx.h
@@ -35,15 +35,44 @@ public:
 	Tfmx(int rate, bool stereo);
 	virtual ~Tfmx();
 
-	void stopSong(bool stopAudio = true);
+	/**
+	 * Stops a playing Song (but leaves macros running) and optionally also stops the player
+	 *
+	 * @param stopAudio	stops player and audio output
+	 * @param dataSize	number of bytes to be written
+	 * @return the number of bytes which were actually written.
+	 */
+	void stopSong(bool stopAudio = true) { Common::StackLock lock(_mutex); stopSongImpl(stopAudio); }
+	/**
+	 * Stops currently playing Song (if any) and cues up a new one.
+	 * if stopAudio is specified, the player gets reset before starting the new song
+	 *
+	 * @param songPos	index of Song to play
+	 * @param stopAudio	stops player and audio output
+	 * @param dataSize	number of bytes to be written
+	 * @return the number of bytes which were actually written.
+	 */
 	void doSong(int songPos, bool stopAudio = false);
+	/**
+	 * plays an effect from the sfx-table, does not start audio-playback. 
+	 *
+	 * @param sfxIndex	index of effect to play
+	 * @param unlockChannel	overwrite higher priority effects
+	 * @return	index of the channel which now queued up the effect.
+	 *			-1 in case the effect couldnt be queued up
+	 */
 	int doSfx(uint16 sfxIndex, bool unlockChannel = false);
+	/**
+	 * stop a running macro channel
+	 *
+	 * @param channel	index of effect to stop
+	 */
+	void stopMacroEffect(int channel);
+
 	void doMacro(int note, int macro, int relVol = 0, int finetune = 0, int channelNo = 0);
 	int getTicks() const { return _playerCtx.tickCount; } 
 	int getSongIndex() const { return _playerCtx.song; }
 	void setSignalPtr(uint16 *ptr, uint16 numSignals) { _playerCtx.signal = ptr; _playerCtx.numSignals = numSignals; }
-	void stopMacroEffect(int channel);
-
 	void freeResources() { _deleteResource = true; freeResourceDataImpl(); }
 	bool load(Common::SeekableReadStream &musicData, Common::SeekableReadStream &sampleData, bool autoDelete = true);
 	void setModuleData(Tfmx &otherPlayer);
@@ -93,6 +122,10 @@ private:
 
 	bool _deleteResource;
 
+	bool hasResources() {
+		return _resource && _resource->mdatLen && _resourceSample.sampleLen;
+	}
+
 	struct ChannelContext {
 		byte	paulaChannel;
 
@@ -267,20 +300,22 @@ private:
 		pattern.savedStep = 0;
 	}
 
-	void stopPatternChannels() {
+	void stopSongImpl(bool stopAudio = true) {
+		 _playerCtx.song = -1;
 		for (int i = 0; i < kNumChannels; ++i) {
 			_patternCtx[i].command = 0xFF;
 			_patternCtx[i].expose = 0;
 		}
-	}
-
-	void stopMacroChannels() {
-		for (int i = 0; i < kNumVoices; ++i) {
-			clearEffects(_channelCtx[i]);
-			unlockMacroChannel(_channelCtx[i]);
-			haltMacroProgramm(_channelCtx[i]);
-			_channelCtx[i].note = 0;
-			_channelCtx[i].volume = 0;
+		if (stopAudio) {
+			stopPaula();
+			for (int i = 0; i < kNumVoices; ++i) {
+				clearEffects(_channelCtx[i]);
+				unlockMacroChannel(_channelCtx[i]);
+				haltMacroProgramm(_channelCtx[i]);
+				_channelCtx[i].note = 0;
+				_channelCtx[i].volume = 0;
+				Paula::disableChannel(i);
+			}
 		}
 	}