SCI: Make Pharkas CD opcodes return explicit values. Document.

1 files changed, 25 insertions, 6 deletions

diff --git a/engines/sci/engine/ksound.cpp b/engines/sci/engine/ksound.cpp
index 032191e4c1..32636fbc71 100644
--- a/engines/sci/engine/ksound.cpp
+++ b/engines/sci/engine/ksound.cpp
@@ -233,19 +233,38 @@ reg_t kDoAudio(EngineState *s, int argc, reg_t *argv) {
 #endif
 		}
 
-		// 3 new subops in Pharkas. kDoAudio in Pharkas sits at seg026:038C
+		// 3 new subops in Pharkas CD (including CD demo). kDoAudio in Pharkas sits at seg026:038C
 	case 11:
 		// Not sure where this is used yet
 		warning("kDoAudio: Unhandled case 11, %d extra arguments passed", argc - 1);
 		break;
 	case 12:
-		// Seems to be some sort of audio sync, used in Pharkas. Silenced the
-		// warning due to the high level of spam it produces. (takes no params)
-		//warning("kDoAudio: Unhandled case 12, %d extra arguments passed", argc - 1);
+		// SSCI calls this function with no parameters from
+		// the TalkRandCycle class and branches on the return
+		// value like a boolean. The conjectured purpose of
+		// this function is to ensure that the talker's mouth
+		// does not move if there is read jitter (slow CD
+		// drive, scratched CD). The old behavior here of not
+		// doing anything caused a nonzero value to be left in
+		// the accumulator by chance. This is equivalent, but
+		// more explicit.
+
+		return make_reg(0, 1);
 		break;
 	case 13:
-		// Used in Pharkas whenever a speech sample starts (takes no params)
-		//warning("kDoAudio: Unhandled case 13, %d extra arguments passed", argc - 1);
+		// SSCI returns a serial number for the played audio
+		// here, used in the PointsSound class. The reason is severalfold:
+
+		// 1. SSCI does not support multiple wave effects at once
+		// 2. FPFP may disable its icon bar during the points sound.
+		// 3. Each new sound preempts any sound already playing.
+		// 4. If the points sound is interrupted before completion,
+		// the icon bar could remain disabled.
+
+		// Since points (1) and (3) do not apply to us, we can simply
+		// return a constant here. This is equivalent to the
+		// old behavior, as above.
+		return make_reg(0, 1);
 		break;
 	case 17:
 		// Seems to be some sort of audio sync, used in SQ6. Silenced the