More cleanup, plus support for cutscene leadout music. For now, we only

play that music for cutscenes that have subtitles.

svn-id: r10460

12 files changed, 373 insertions, 895 deletions

diff --git a/sword2/driver/_mouse.cpp b/sword2/driver/_mouse.cpp
index 7be7fece42..f2eff1820d 100644
--- a/sword2/driver/_mouse.cpp
+++ b/sword2/driver/_mouse.cpp
@@ -17,53 +17,6 @@
  * $Header$
  */
 
-//=============================================================================
-//
-//	Filename	:	mouse.c
-//	Created		:	17th September 1996
-//	By			:	P.R.Porter
-//
-//	Summary		:	This module holds the interface to the mouse..
-//
-//	Functions
-//	---------
-//
-//	--------------------------------------------------------------------------
-//
-//  _mouseEvent *MouseEvent(void)
-//
-//	The address of a _mouseEvent pointer is passed in.  If there is a mouse 
-//	event in the queue, a the value of the mouse event pointer is set to the
-//	address of the event, otherwise, the mouse event pointer is set to NULL.
-//
-//	--------------------------------------------------------------------------
-//
-//	int32 SetMouseAnim(uint8 *ma, int32 size)
-//
-//	A pointer to a valid mouse animation is passed in, along with the size of
-//	the header plus sprite data.  Remember to check that the function has 
-//	successfully completed, as memory allocation is required.
-//	Pass NULL in to clear the mouse sprite.
-//
-//	--------------------------------------------------------------------------
-//
-//	int32 SetLuggageAnim(uint8 *ma, int32 size)
-//
-//	A pointer to a valid luggage animation is passed in, along with the size of
-//	the header plus sprite data.  Remember to check that the function has 
-//	successfully completed, as memory allocation is required.
-//	Pass NULL in to clear the luggage sprite.  Luggage sprites are of the same
-//	format as mouse sprites.
-//
-//	--------------------------------------------------------------------------
-//
-//	int32 AnimateMouse(void)
-//
-//	This function animates the current mouse pointer.  If no pointer is 
-//	currently defined, an error code is returned.
-//
-//=============================================================================
-
 #include "stdafx.h"
 #include "driver96.h"
 #include "d_draw.h"
@@ -239,6 +192,11 @@ void DrawMouse(void) {
 	g_system->set_mouse_cursor(_mouseData, mouse_width, mouse_height, hotspot_x, hotspot_y);
 }
 
+/**
+ * Get the next pending mouse event.
+ * @return a pointer to the mouse event, or NULL of there is none
+ */
+
 _mouseEvent *MouseEvent(void) {
 	_mouseEvent *me;
 
@@ -258,6 +216,10 @@ uint8 CheckForMouseEvents(void) {
 	return mouseBacklog;	// return the number of mouse events waiting
 }
 
+/**
+ * Animates the current mouse pointer
+ */
+
 int32 AnimateMouse(void) {
 	uint8 prevMouseFrame = mouseFrame;
 
@@ -275,6 +237,14 @@ int32 AnimateMouse(void) {
 	return RD_OK;
 }
 
+/**
+ * Sets the mouse cursor animation.
+ * @param ma a pointer to the animation data, or NULL to clear the current one
+ * @param size the size of the mouse animation data
+ * @param mouseFlash RDMOUSE_FLASH or RDMOUSE_NOFLASH, depending on whether
+ * or not there is a lead-in animation
+ */
+
 int32 SetMouseAnim(uint8 *ma, int32 size, int32 mouseFlash) {
 	if (mouseAnim) {
 		free(mouseAnim);
@@ -308,6 +278,13 @@ int32 SetMouseAnim(uint8 *ma, int32 size, int32 mouseFlash) {
 	return RD_OK;
 }
 
+/**
+ * Sets the "luggage" animation to accompany the mouse animation. Luggage
+ * sprites are of the same format as mouse sprites.
+ * @param ma a pointer to the animation data, or NULL to clear the current one
+ * @param size the size of the animation data
+ */
+
 int32 SetLuggageAnim(uint8 *ma, int32 size) {
 	if (luggageAnim) {
 		free(luggageAnim);
diff --git a/sword2/driver/d_draw.cpp b/sword2/driver/d_draw.cpp
index be53f47234..a25a3dee89 100644
--- a/sword2/driver/d_draw.cpp
+++ b/sword2/driver/d_draw.cpp
@@ -92,12 +92,22 @@ int32 PlotDots(int16 x, int16 y, int16 count) {
 
 }
 
-int32 InitialiseDisplay(int16 width, int16 height, int16 colourDepth, int32 windowType) {
+/**
+ * Initialise the display with the sizes passed in.
+ * @return RD_OK, or an error code if the display cannot be set up.
+ */
+
+int32 InitialiseDisplay(int16 width, int16 height) {
+	g_system->init_size(width, height);
+
 	screenWide = width;
 	screenDeep = height;
 
 	lpBackBuffer = (byte *) malloc(screenWide * screenDeep);
-	return(RD_OK);
+	if (!lpBackBuffer)
+		return RDERR_OUTOFMEMORY;
+
+	return RD_OK;
 }
 
 // FIXME: Clean up this mess. I don't want to add any new flags, but some of
@@ -115,10 +125,18 @@ void ClearTransFx(void) {
 	renderCaps |= RDBLTFX_ALLHARDWARE;
 }
 
+/**
+ * Sets the edge blend and arithmetic stretching effects.
+ */
+
 void SetBltFx(void) {
 	renderCaps |= (RDBLTFX_EDGEBLEND | RDBLTFX_ARITHMETICSTRETCH);
 }
 
+/**
+ * Clears the edge blend and arithmetic stretching effects.
+ */
+
 void ClearBltFx(void) { 
 	renderCaps &= ~(RDBLTFX_EDGEBLEND | RDBLTFX_ARITHMETICSTRETCH);
 }
@@ -131,26 +149,26 @@ void ClearShadowFx(void) {
 	renderCaps &= ~RDBLTFX_SHADOWBLEND;
 }
 
-int32 GetRenderType(void)
-{
+/**
+ * @return the graphics detail setting
+ */
+
+int32 GetRenderType(void) {
 	if (renderCaps & RDBLTFX_ALLHARDWARE)
-	{
-		return (0);
-	}
-	else
-	{
-		if (renderCaps & (RDBLTFX_EDGEBLEND + RDBLTFX_ARITHMETICSTRETCH))
-			return (3);
-		else
-		{
-			if (renderCaps & RDBLTFX_SHADOWBLEND)
-				return(2);
-			else
-				return (1);
-		}
-	}
+		return 0;
+
+	if (renderCaps & (RDBLTFX_EDGEBLEND | RDBLTFX_ARITHMETICSTRETCH))
+		return 3;
+
+	if (renderCaps & RDBLTFX_SHADOWBLEND)
+		return 2;
+
+	return 1;
 }
 
+/**
+ * Fill the screen buffer with palette colour zero.
+ */
 
 int32 EraseBackBuffer( void ) {
 	memset(lpBackBuffer + MENUDEEP * screenWide, 0, screenWide * RENDERDEEP);
@@ -160,7 +178,7 @@ int32 EraseBackBuffer( void ) {
 
 int32 NextSmackerFrame(void) {
 	warning("stub NextSmackerFrame");
-	return(RD_OK);
+	return RD_OK;
 }
 
 
@@ -183,16 +201,19 @@ void DrawTextObject(_movieTextObject *obj) {
 		DrawSurface(obj->textSprite, textSurface);
 }
 
+/**
+ * Plays an animated cutscene.
+ * @param filename the file name of the cutscene file
+ * @param text the subtitles and voiceovers for the cutscene
+ * @param musicOut lead-out music
+ */
+
 int32 PlaySmacker(char *filename, _movieTextObject *text[], uint8 *musicOut) {
 	warning("semi-stub PlaySmacker %s", filename);
 
 	// WORKAROUND: For now, we just do the voice-over parts of the
 	// movies, since they're separate from the actual smacker files.
 
-	// Do we really need to pre-cache the text sprites and speech data
-	// like this? It'd be simpler to just store the text id and construct
-	// the data as we go along.
-
 	if (text) {
 		uint8 oldPal[1024];
 		uint8 tmpPal[1024];
@@ -246,6 +267,8 @@ int32 PlaySmacker(char *filename, _movieTextObject *text[], uint8 *musicOut) {
 
 		PlayingSoundHandle handle = 0;
 
+		bool skipCutscene = false;
+
 		while (1) {
 			if (!text[textCounter])
 				break;
@@ -273,12 +296,14 @@ int32 PlaySmacker(char *filename, _movieTextObject *text[], uint8 *musicOut) {
 
 			if (ReadKey(&ke) == RD_OK && ke.keycode == 27) {
 				g_sword2->_mixer->stopHandle(handle);
+				skipCutscene = true;
 				break;
 			}
 
 			// Simulate ~12 frames per second. I don't know what
 			// frame rate the original movies had, or even if it
 			// was constant, but this seems to work reasonably.
+
 			g_system->delay_msecs(80);
 		}
 
@@ -294,6 +319,12 @@ int32 PlaySmacker(char *filename, _movieTextObject *text[], uint8 *musicOut) {
 		r.right = screenWide;
 		r.bottom = MENUDEEP;
 		UploadRect(&r);
+
+		// FIXME: For now, only play the lead-out music for cutscenes
+		// that have subtitles.
+
+		if (!skipCutscene)
+			g_sound->playLeadOut(musicOut);
 	}
 
 	return RD_OK;
diff --git a/sword2/driver/d_sound.cpp b/sword2/driver/d_sound.cpp
index 1afb5ce309..f2e31f66d0 100644
--- a/sword2/driver/d_sound.cpp
+++ b/sword2/driver/d_sound.cpp
@@ -234,6 +234,29 @@ void Sword2Sound::restoreMusicState() {
 	music[restoreStream]._lastSample = music[2]._lastSample;
 }
 
+void Sword2Sound::playLeadOut(uint8 *leadOut) {
+	int i;
+
+	if (!leadOut)
+		return;
+
+	PlayFx(0, leadOut, 0, 0, RDSE_FXLEADOUT);
+
+	i = GetFxIndex(-1);
+
+	if (i == MAXFX) {
+		warning("playLeadOut: Can't find lead-out sound handle");
+		return;
+	}
+
+	while (fx[i]._handle) {
+		ServiceWindows();
+		g_system->delay_msecs(30);
+	}
+
+	CloseFx(-2);
+}
+
 // --------------------------------------------------------------------------
 // This function returns the index of the sound effect with the ID passed in.
 // --------------------------------------------------------------------------
@@ -281,7 +304,7 @@ void Sword2Sound::FxServer(int16 *data, uint len) {
 
 	if (fxPaused) {
 		for (i = 0; i < MAXFX; i++) {
-			if ((fx[i]._id == (int32) 0xfffffffe) || (fx[i]._id == (int32) 0xffffffff)) {
+			if ((fx[i]._id == -1) || (fx[i]._id == -2)) {
 				if (!fx[i]._handle) {
 					fx[i]._id = 0;
 					if (fx[i]._buf != NULL) {
@@ -681,47 +704,35 @@ int32 Sword2Sound::PlayFx(int32 id, uint8 *data, uint8 vol, int8 pan, uint8 type
 
 	if (soundOn) {
 		if (data == NULL) {
-			if (type == RDSE_FXLEADOUT) {
-				id = (int32) 0xffffffff;
-				i = GetFxIndex(id);
-				if (i == MAXFX) {
-					warning("PlayFx(%d, %d, %d, %d) - Not open", id, vol, pan, type);
-					return RDERR_FXNOTOPEN;
-				}
+			i = GetFxIndex(id);
+			if (i == MAXFX) {
+				warning("PlayFx(%d, %d, %d, %d) - Not open", id, vol, pan, type);
+				return RDERR_FXNOTOPEN;
+			}
+			if (loop == 1)
+				fx[i]._flags |= SoundMixer::FLAG_LOOP;
+			else 
 				fx[i]._flags &= ~SoundMixer::FLAG_LOOP;
-
-				// Start the sound effect playing
-
-				byte volume = musicMuted ? 0 : musicVolTable[musicVol];
-
-				g_engine->_mixer->playRaw(&fx[i]._handle, fx[i]._buf, fx[i]._bufSize, fx[i]._rate, fx[i]._flags, -1, volume, 0);
-			} else {
-				i = GetFxIndex(id);
-				if (i == MAXFX) {
-					warning("PlayFx(%d, %d, %d, %d) - Not open", id, vol, pan, type);
-					return RDERR_FXNOTOPEN;
-				}
-				if (loop == 1)
-					fx[i]._flags |= SoundMixer::FLAG_LOOP;
-				else 
-					fx[i]._flags &= ~SoundMixer::FLAG_LOOP;
 				 
-				fx[i]._volume = vol;
+			fx[i]._volume = vol;
 
-				// Start the sound effect playing
+			// Start the sound effect playing
 
-				byte volume = fxMuted ? 0 : vol * fxVol;
-				int8 p = panTable[pan + 16];
+			byte volume = fxMuted ? 0 : vol * fxVol;
+			int8 p = panTable[pan + 16];
 
-				g_engine->_mixer->playRaw(&fx[i]._handle, fx[i]._buf, fx[i]._bufSize, fx[i]._rate, fx[i]._flags, -1, volume, p);
-			}
+			g_engine->_mixer->playRaw(&fx[i]._handle, fx[i]._buf, fx[i]._bufSize, fx[i]._rate, fx[i]._flags, -1, volume, p);
 		} else {
-			if (type == RDSE_FXLEADIN) {
-				id = (int32) 0xfffffffe;
+			if (type == RDSE_FXLEADIN || type == RDSE_FXLEADOUT) {
+				if (type == RDSE_FXLEADIN)
+					id = -2;
+				else
+					id = -1;
+
 				hr = OpenFx(id, data);
-				if (hr != RD_OK) {
+				if (hr != RD_OK)
 					return hr;
-				}
+
 				i = GetFxIndex(id);
 				if (i == MAXFX) {
 					warning("PlayFx(%d, %d, %d, %d) - Not found", id, vol, pan, type);
@@ -804,7 +815,7 @@ int32 Sword2Sound::ClearAllFx(void) {
 		return(RD_OK);
 
 	for (int i = 0; i < MAXFX; i++) {
-		if (fx[i]._id && fx[i]._id != (int32) 0xfffffffe && fx[i]._id != (int32) 0xffffffff) {
+		if (fx[i]._id && fx[i]._id != -1 && fx[i]._id != -2) {
 			g_engine->_mixer->stopHandle(fx[i]._handle);
 			fx[i]._id = 0;
 			fx[i]._paused = false;
@@ -867,7 +878,7 @@ int32 Sword2Sound::PauseFx(void) {
 int32 Sword2Sound::PauseFxForSequence(void) {
 	if (!fxPaused) {
 		for (int i = 0; i < MAXFX; i++) {
-			if (fx[i]._id && fx[i]._id != (int32) 0xfffffffe) {
+			if (fx[i]._id && fx[i]._id != -2) {
 				g_engine->_mixer->pauseHandle(fx[i]._handle, true);
 				fx[i]._paused = true;
 			} else {
diff --git a/sword2/driver/d_sound.h b/sword2/driver/d_sound.h
index 520a320446..54048bd76a 100644
--- a/sword2/driver/d_sound.h
+++ b/sword2/driver/d_sound.h
@@ -102,6 +102,7 @@ class Sword2Sound {
 		int32 StreamCompMusic(const char *filename, uint32 musicId, bool looping);
 		void saveMusicState();
 		void restoreMusicState();
+		void playLeadOut(uint8 *leadOut);
 		int32 MusicTimeRemaining();
 		int32 ReverseStereo(void);
 		uint8 GetFxVolume(void);
diff --git a/sword2/driver/driver96.h b/sword2/driver/driver96.h
index df32ec50d7..17c5df0742 100644
--- a/sword2/driver/driver96.h
+++ b/sword2/driver/driver96.h
@@ -17,442 +17,6 @@
  * $Header$
  */
 
-//=============================================================================
-//
-//	Filename	:	driver96.h
-//	Created		:	6th August 1996
-//	By			:	P.R.Porter
-//
-//	Summary		:	This include file defines all interfaces to the Revolution
-//					driver96 system.  All game code which requires driver
-//					functions should simlply include this file.
-//
-//	Functions
-//	---------
-//
-//	---------------------------------------------------------------------------
-//	------------------------------- d_draw.c ----------------------------------
-//	---------------------------------------------------------------------------
-//
-//	int32 InitialiseDisplay(int32 width, int32 height, int32 colourDepth, int32 windowType)
-//
-//	Initialises the directDraw display with the sizes and colour depths passed
-//	in.  The windowType is either RD_FULLSCREEN or RD_WINDOWED depending upon
-//	whether the app is to run in a window or not.  If RD_WINDOWED is selected,
-//	the runction may returnRDERR_GOFULLSCREEN which implies that the window
-//	size and colour depth requested is not compatible with the current
-//	settings.
-//	If the required display cannot be set up, then an error code is
-//	returned, otherwise zero.
-//
-//	---------------------------------------------------------------------------
-//	
-//	int32 ResetDisplay(void)
-//
-//	Closes down the directDraw sub-system and resets the display back to it's
-//	original size.  Returns an RD code.
-//
-//	---------------------------------------------------------------------------
-//
-//	int32 EraseBackBuffer(void)
-//
-//	Fills the back buffer with palette colour zero.  Returns an RD code.
-//
-//	---------------------------------------------------------------------------
-//
-//	void InterpretDirectDrawError(int32 error)
-//
-//	This function is passed the pointer to a direct draw error code, and
-//	translates this into a revolution driver error code.  It also reports the
-//	error.
-//
-//	---------------------------------------------------------------------------
-//
-//	int32 SetBltFx(void)
-//
-//	Sets the edge blend and arithmetic stretching effects.
-//
-//	---------------------------------------------------------------------------
-//
-//	int32 ClearBltFx(void)
-//
-//	Clears the edge blend and arithmetic stretching effects.
-//
-//	---------------------------------------------------------------------------
-//
-//	int32 RenderHard(void);
-//
-//	Turns on the hardware renderer.  Returns an error if the
-//	hardware is not capable of rendering.
-//
-//	---------------------------------------------------------------------------
-//
-//	int32 RenderSoft(void);
-//
-//	Turns on the software renderer.  Returns an error if it
-//	is already on.
-//
-//	---------------------------------------------------------------------------
-//
-//	int32 GetRenderType(void)
-//
-//	Returns the type of rendering currently being used.
-//	0 = H/W rendering,	1 = S/W Rendering + BltFxOFF,  2 = S/W Rendering + BltFxON
-//
-//	---------------------------------------------------------------------------
-//
-//	int32 PlaySmacker(char *filename)
-//
-//	Plays the smacker file, filename.
-//
-//	--------------------------- rdwin.c ---------------------------------------
-//	---------------------------------------------------------------------------
-//
-//	int32 ServiceWindows(void)
-//
-//	This function should be called at a high rate ( > 20 per second) to service
-//	windows and the interfaces it provides.
-//
-//	---------------------------------------------------------------------------
-//
-//	int32 CloseAppWindow(void)
-//
-//	Removes all windows hooks from the application.
-//
-//	---------------------------------------------------------------------------
-//
-//	void SetWindowName(const char *windowName)
-//
-//	Set the window name to windowName and stores this name in gameName for future
-//  use.
-//
-//	---------------------------------------------------------------------------
-//	--------------------------------- language.c ------------------------------
-//	---------------------------------------------------------------------------
-//
-//	int32 GetLanguageVersion(uint8 *version)
-//
-//	This function modifies the 'version' passed in to be the current language.
-//	The first time this function is called, it gets the language from the 
-//	version.inf file distributed on the game CD.  It returns an RD error code
-//	if this file cannot be opened, or the version cannot be obtained from it.
-//
-//	---------------------------------------------------------------------------
-//	
-//	int32 SetLanguageVersion(uint8 version)
-//
-//	This function is useful for debugging.  It sets the version to the one
-//	passed in.
-//
-//	---------------------------------------------------------------------------
-//	
-//	int32 GetGameName(uint8 *name);
-//
-//	Fills the string pointed to by name with the title of the game, depending
-//	upon what the current language version is.
-//
-//	--------------------------------------------------------------------------
-//	------------------------------- palette.c --------------------------------
-//	--------------------------------------------------------------------------
-//
-//	void BS2_SetPalette(int32 startEntry, int32 noEntries, uint8 *colourTable, uint8 setNow)
-//
-//	Sets the palette from position startEntry for noEntries, to the data 
-//	pointed to by colourTable.  To set the palette immediately pass
-//	RDPAL_INSTANT.  If you want to fade later, pass RDPAL_FADE.
-//
-//	--------------------------------------------------------------------------
-//
-//	int32 UpdatePaletteMatchTable(uint8 *data)
-//
-//	Uses the current palCopy to create a table of palette indeces which will
-//	be searched later for a quick palette match - only if NULL is passed in
-//	as the data.  If a pointer to valid data is passed in, the palette match
-//	table is copied from that data.
-//
-//	--------------------------------------------------------------------------
-//
-//	uint8 QuickMatch(uint8 r, uint8 g, uint8 b)
-//
-//	Returns the palette index of the closest matching colour in the palette
-//	to these RGB values.
-//
-//	--------------------------------------------------------------------------
-//
-//	int32 FadeUp(float time)
-//
-//	Fades the palette up from black to the current palette in time.
-//
-//	--------------------------------------------------------------------------
-//
-//	int32 FadeDown(float time)
-//
-//	Fades the palette down to black from the current palette in time.
-//
-//	--------------------------------------------------------------------------
-//
-//	uint8 GetFadeStatus(void)
-//
-//	Returns the fade status which can be one of RDFADE_UP, RDFADE_DOWN or
-//	RDFADE_NONE.
-//
-//
-//	--------------------------------------------------------------------------
-//	-------------------------------- mouse.c ---------------------------------
-//	--------------------------------------------------------------------------
-//
-//  _mouseEvent *MouseEvent(void)
-//
-//	If there is a mouse event in the queue, a valid pointer is returned.
-//	Otherwise, NULL.
-//
-//	--------------------------------------------------------------------------
-//
-//	int32 SetMouseAnim(uint8 *ma, int32 size, int32 mouseFlash)
-//
-//	A pointer to a valid mouse animation is passed in, along with the size of
-//	the header plus sprite data.  Remember to check that the function has 
-//	successfully completed, as memory allocation is required.  When the mouse
-//	animation has been set, the mouse sprite does not need to be kept in the
-//	memory manager.
-//	Pass NULL in to clear the mouse sprite.
-//	mouseFlash should be either RDMOUSE_FLASH or RDMOUSE_NOFLASH
-//	defining whether to pulse the mouse or not.
-//
-//	--------------------------------------------------------------------------
-//
-//	int32 SetLuggageAnim(uint8 *la, int32 size)
-//
-//	A pointer to a valid luggage animation is passed in, along with the size of
-//	the header plus sprite data.  Remember to check that the function has 
-//	successfully completed, as memory allocation is required.
-//	Pass NULL in to clear the luggage sprite.  Luggage sprites are of the same
-//	format as mouse sprites.
-//
-//	--------------------------------------------------------------------------
-//
-//	int32 AnimateMouse(void)
-//
-//	This function animates the current mouse pointer.  If no pointer is 
-//	currently defined, an error code is returned.
-//
-//
-//	--------------------------------------------------------------------------
-//	------------------------------ keyboard.c --------------------------------
-//	--------------------------------------------------------------------------
-//
-//  BOOL KeyWaiting(void)
-//
-//	This function returns TRUE if there is an unprocessed key waiting in the
-//	queue, FALSE otherwise.
-//
-//	--------------------------------------------------------------------------
-//
-//	int32 ReadKey(_keyboardEvent *key)
-//
-//	Sets the value of key passed in to the current waiting key.  If there is
-//	no key waiting, an error code is returned.
-//
-//
-//	--------------------------------------------------------------------------
-//	------------------------------- sprite.c ---------------------------------
-//	--------------------------------------------------------------------------
-//
-//	int32 DrawSprite(_spriteInfo *s)
-//
-//	Draws a sprite onto the screen of the type defined in the _spriteInfo
-//	structure.  The _spriteInfo structure consists of the following elements:
-//
-//	int16	x;				// coords for top-left of sprite
-//	int16	y;
-//	uint16	w;				// dimensions of sprite (before scaling)
-//	uint16	h;
-//	uint16	scale;			// scale at which to draw, given in 256ths 
-//							   ['0' or '256' MEANS DON'T SCALE]
-//	uint16	scaledWidth;	// new dimensions
-//	uint16	scaledHeight;	//
-//	uint16	blend			// blending value.
-//	uint16	type;			// combination of the bits below
-//	uint8	*data;			// pointer to the sprite data
-//	uint8	*colourTable;	// pointer to 16-byte colour table - only 
-//							   applicable to 16-col compression type
-//
-//	WARNING:  Sprites will only be drawn onto the background.  Sprites will not
-//		appear over the menubar areas.  The mouse and menu drawing is treated
-//		as a special case.
-//
-//	The type of the sprite can be any of the following:
-//
-//	if (RDSPR_TRANS)
-//		The sprite has a transparent colour zero
-//		if (RDSPR_NOCOMPRESSION)
-//			The sprite data must not be compressed (slow to draw)
-//			The RDSPR_DISPLAYALIGN bit may be set to draw the sprite
-//				at coordinates relative to the top left corner of the
-//				monitor.
-//		else
-//			Compression must be set as one of the following:
-//				RDSPR_RLE16
-//				RDSPR_RLE256
-//				RDSPR_LAYERCOMPRESSION
-//	else
-//		The sprite has an opaque colour zero
-//		RDSPR_NOCOMPRESSION must be set!
-//		RDSPR_DISPLAYALIGN may be set to align the coordinates of the sprite
-//			to the top left corner of the monitor.
-//
-//	---------------------------------------------------------------------------
-//
-//	int32 CreateSurface(_spriteInfo *s, uint32 *surface)
-//
-//	Creates a sprite surface in video memory (if possible) and returns it's
-//	handle in surface.
-//
-//	---------------------------------------------------------------------------
-//
-//	void DrawSurface(_spriteInfo *s, uint32 surface, ScummVM::Rect *clipRect)
-//
-//	Draws the sprite surface created earlier.
-//
-//	---------------------------------------------------------------------------
-//
-//	void DeleteSurface(uint32 surface)
-//
-//	Deletes a surface from video memory.
-//
-//	---------------------------------------------------------------------------
-//
-//	int32 OpenLightMask(_spriteInfo *s)
-//
-//	Opens the light masking sprite for a room.
-//
-//	---------------------------------------------------------------------------
-//
-//	int32 CloseLightMask(void)
-//
-//	Closes the light masking sprite for a room.
-//
-//	--------------------------------------------------------------------------
-//	------------------------------- render.c ---------------------------------
-//	--------------------------------------------------------------------------
-//	
-//	int32 RenderParallax(_parallax *p)
-//
-//	Draws a parallax layer at the current position determined by the scroll.
-//	A parallax can be either foreground, background or the main screen.
-//
-//	---------------------------------------------------------------------------
-//
-//	int32 SetScrollTarget(int16 sx, int16 sy)
-//
-//	Sets the scroll target position for the end of the game cycle.  The drivers
-//	will then automatically scroll as many times as it can to reach this 
-//	position in the allotted time.
-//
-//	--------------------------------------------------------------------------
-//
-//	int32 InitialiseRenderCycle(void)
-//
-//	Initialises the timers before the render loop is entered.
-//
-//	--------------------------------------------------------------------------
-//
-//	int32 StartRenderCycle(void)
-//
-//	This function should be called when the game engine is ready to start
-//	the render cycle.
-//
-//	--------------------------------------------------------------------------
-//
-//	int32 EndRenderCycle(BOOL *end)
-//
-//	This function should be called at the end of the render cycle.  If the
-//	render cycle is to be terminated, the function sets *end to 1.  Otherwise,
-//	the render cycle should continue.
-//
-//	--------------------------------------------------------------------------
-//
-//	int32 SetLocationMetrics(uint16 w, uint16 h)
-//
-//	This function tells the drivers the size of the background screen for the
-//	current location.
-//
-//	--------------------------------------------------------------------------
-//
-//	int32 PlotPoint(uint16 x, uint16 y, uint8 colour)
-//
-//	Plots the point x,y in relation to the top left corner of the background.
-//
-//	--------------------------------------------------------------------------
-//
-//	int32 DrawLine(int16 x1, int16 y1, int16 x2, int16 y2, uint8 colour)
-//
-//	Draws a line from the point x1,y1 to x2,y2 of the specified colour.
-//
-//	--------------------------------------------------------------------------
-//
-//	int32 InitialiseBackgroundLayer(_parallax *p)
-//
-//	This function should be called five times with either the parallax layer
-//	or a NULL pointer in order of background parallax to foreground parallax.
-//
-//	--------------------------------------------------------------------------
-//
-//	int32 CloseBackgroundLayer(void)
-//
-//	Should be called once after leaving a room to free up video memory.
-//
-//	--------------------------------------------------------------------------
-//
-//	int32 PlotDots(int16 x, int16 y, int16 count)
-//
-//	Plots 'count' dots at the position x,y.
-//
-//	--------------------------------------------------------------------------
-//	---------------------------- menu.c --------------------------------------
-//	--------------------------------------------------------------------------
-//
-//	int32 ProcessMenu(void)
-//
-//	This function should be called regularly to process the menuber system.
-//	The rate at which this function is called will dictate how smooth the menu
-//	system is.  The menu cannot be drawn at a higher rate than the system
-//	vbl rate.
-//
-//	--------------------------------------------------------------------------
-//
-//	int32 ShowMenu(uint8 menu)
-//
-//	This function brings the menu in to view.  The choice of top or bottom menu
-//	is defined by the parameter menu being either RDMENU_TOP or RDMENU_BOTTOM.
-//	An error code is returned if the menu is already shown.
-//
-//	--------------------------------------------------------------------------
-//
-//	int32 HideMenu(uint8 menu)
-//
-//	This function hides the menu defined by the parameter menu.  If the menu is
-//	already hidden, an error code is returned.
-//
-//	--------------------------------------------------------------------------
-//
-//	int32 SetMenuIcon(uint8 menu, uint8 pocket, uint8 *icon)
-//
-//	This function sets a menubar icon to that passed in.  If icon is NULL, the
-//	pocket is cleared, otherwise, that icon is placed into pocket.  The menu is
-//	either RDMENU_TOP or RDMENU_BOTTOM.  Valid error codes include
-//	RDERR_INVALIDPOCKET if the pocket number does not exist.  Initially, there
-//	are 15 pockets.
-//
-//	--------------------------------------------------------------------------
-//
-//	uint8 GetMenuStatus(uint8 menu)
-//
-//	This function returns the status of the menu passed in menu.  Return values
-//	are RDMENU_OPENING, RDMENU_CLOSING, RDMENU_HIDDEN and RDMENU_SHOWN.
-//
-//=============================================================================
-
 #ifndef DRIVER96_H
 #define DRIVER96_H
 
@@ -745,7 +309,7 @@ typedef struct {
 //-----------------------------------------------------------------------------
 //  Display functions - from d_draw.c
 //-----------------------------------------------------------------------------
-extern int32 InitialiseDisplay(int16 width, int16 height, int16 colourDepth, int32 windowType);
+extern int32 InitialiseDisplay(int16 width, int16 height);
 extern int32 EraseBackBuffer(void);
 extern void SetTransFx(void);
 extern void ClearTransFx(void);
diff --git a/sword2/driver/keyboard.cpp b/sword2/driver/keyboard.cpp
index e25eb4714e..b9aef1425c 100644
--- a/sword2/driver/keyboard.cpp
+++ b/sword2/driver/keyboard.cpp
@@ -17,40 +17,6 @@
  * $Header$
  */
 
-//=============================================================================
-//
-//	Filename	:	keyboard.c
-//	Created		:	19th September 1996
-//	By			:	P.R.Porter
-//
-//	Summary		:	This module holds the interface to the keyboard
-//
-//	Functions
-//	---------
-//
-//	--------------------------------------------------------------------------
-//
-//  BOOL KeyWaiting(void)
-//
-//	This function returns TRUE if there is an unprocessed key waiting in the
-//	queue, FALSE otherwise.
-//
-//	--------------------------------------------------------------------------
-//
-//	int32 ReadKey(char *key)
-//
-//	Sets the value of key passed in to the current waiting key.  If there is
-//	no key waiting, an error code is returned.
-//	
-//	--------------------------------------------------------------------------
-//
-//	void GetKeyStatus(_drvKeyStatus *s)
-//
-//	Retrieves the status of the keyboard handler.
-//	
-//=============================================================================
-
-
 #include "stdafx.h"
 #include "driver96.h"
 
@@ -70,10 +36,19 @@ void WriteKey(uint16 ascii, int keycode, int modifiers) {
 	}
 }
 
+/**
+ * @return true if there is an unprocessed key waiting in the queue
+ */
+
 bool KeyWaiting(void) {
 	return keyBacklog != 0;
 }
 
+/**
+ * Sets the value of the keyboard event passed in to the current waiting key.
+ * @return RD_OK, or an error code to indicate there is no key waiting.
+ */
+
 int32 ReadKey(_keyboardEvent *ev) {
 	if (!keyBacklog)
 		return RDERR_NOKEYWAITING;
diff --git a/sword2/driver/language.cpp b/sword2/driver/language.cpp
index 81e63f4663..6ac4ec66f9 100644
--- a/sword2/driver/language.cpp
+++ b/sword2/driver/language.cpp
@@ -17,43 +17,6 @@
  * $Header$
  */
 
-//=============================================================================
-//
-//	Filename	:	language.c
-//	Created		:	20th August 1996
-//	By			:	P.R.Porter
-//
-//	Summary		:	This module holds the functions which govern which language
-//					version is current.
-//
-//	Functions
-//	---------
-//
-//	--------------------------------------------------------------------------
-//
-//	int32 GetLanguageVersion(uint8 *version)
-//
-//	This function modifies the 'version' passed in to be the current language.
-//	The first time this function is called, it gets the language from the 
-//	version.inf file distributed on the game CD.  It returns an RD error code
-//	if this file cannot be opened, or the version cannot be obtained from it.
-//
-//	---------------------------------------------------------------------------
-//	
-//	int32 SetLanguageVersion(uint8 version)
-//
-//	This function is useful for debugging.  It sets the version to the one
-//	passed in.
-//
-//	---------------------------------------------------------------------------
-//	
-//	int32 GetGameName(uint8 *name);
-//
-//	Fills the string pointed to by name with the title of the game, depending
-//	upon what the current language version is.
-//
-//=============================================================================
-
 #include "stdafx.h"
 #include "driver96.h"
 
@@ -61,6 +24,15 @@ uint8 languageVersion = ENGLISH;
 
 static uint8 versionFromFile = 0;
 
+/**
+ * This function modifies the 'version' passed in to be the current language.
+ * The first time this function is called, it gets the language from the
+ * version.inf file distributed on the game CD.
+ * @param version a pointer to the variable to store language information in
+ * @return an RD error code if version.inf cannot be opened, or the version
+ * cannot be obtained from it
+ */
+
 int32 GetLanguageVersion(uint8 *version) {
 	if (versionFromFile) {
 		*version = languageVersion;
@@ -72,11 +44,22 @@ int32 GetLanguageVersion(uint8 *version) {
 	return RD_OK;
 }
 
+/**
+ * This function is useful for debugging. It sets the version to the one passed
+ * in.
+ */
+
 int32 SetLanguageVersion(uint8 version) {
 	languageVersion = version;
 	return RD_OK;
 }
 
+/**
+ * Fills the string pointed to by 'name' with the title of the game, depending
+ * upon what the current language version is.
+ * @param name buffer to store the title of the game in
+ */
+
 int32 GetGameName(uint8 *name) {
 	uint8 version;
 	int32 rv;
@@ -94,7 +77,7 @@ int32 GetGameName(uint8 *name) {
 		strcpy((char *) name, "Baphomet's Fluch II");
 		break;
 	default:
-		strcpy((char *)name, "Some game or other, part 86");
+		strcpy((char *) name, "Some game or other, part 86");
 		return RDERR_INVALIDVERSION;
 	}
 
diff --git a/sword2/driver/menu.cpp b/sword2/driver/menu.cpp
index 7a3647fa43..f0783eac6a 100644
--- a/sword2/driver/menu.cpp
+++ b/sword2/driver/menu.cpp
@@ -17,61 +17,6 @@
  * $Header$
  */
 
-//=============================================================================
-//
-//	Filename	:	menu.c
-//	Created		:	14th November 1996
-//	By			:	P.R.Porter
-//
-//	Summary		:	This module holds the code for the driver96 menu system.
-//
-//	Functions
-//	---------
-//
-//	--------------------------------------------------------------------------
-//
-//	int32 ProcessMenu(void)
-//
-//	This function should be called regularly to process the menuber system.
-//	The rate at which this function is called will dictate how smooth the menu
-//	system is.  The menu cannot be drawn at a higher rate than the system
-//	vbl rate.
-//
-//	--------------------------------------------------------------------------
-//
-//	int32 ShowMenu(uint8 menu)
-//
-//	This function brings the menu in to view.  The choice of top or bottom menu
-//	is defined by the parameter menu being either RDMENU_TOP or RDMENU_BOTTOM.
-//	An error code is returned if the menu is already shown.
-//
-//	--------------------------------------------------------------------------
-//
-//	int32 HideMenu(uint8 menu)
-//
-//	This function hides the menu defined by the parameter menu.  If the menu is
-//	already hidden, an error code is returned.
-//
-//	--------------------------------------------------------------------------
-//
-//	int32 SetMenuIcon(uint8 menu, uint8 pocket, uint8 *icon)
-//
-//	This function sets a menubar icon to that passed in.  If icon is NULL, the
-//	pocket is cleared, otherwise, that icon is placed into pocket.  The menu is
-//	either RDMENU_TOP or RDMENU_BOTTOM.  Valid error codes include
-//	RDERR_INVALIDPOCKET if the pocket number does not exist.  Initially, there
-//	are 15 pockets.
-//
-//	--------------------------------------------------------------------------
-//
-//	uint8 GetMenuStatus(uint8 menu)
-//
-//	This function returns the status of the menu passed in menu.  Return values
-//	are RDMENU_OPENING, RDMENU_CLOSING, RDMENU_HIDDEN and RDMENU_SHOWN.
-//
-//=============================================================================
-
-
 #include "stdafx.h"
 #include "driver96.h"
 #include "menu.h"
@@ -115,6 +60,12 @@ void ClearIconArea(int menu, int pocket, ScummVM::Rect *r) {
 	}
 }
 
+/**
+ * This function should be called regularly to process the menubar system. The
+ * rate at which this function is called will dictate how smooth the menu
+ * system is.
+ */
+
 int32 ProcessMenu(void) {
 	byte *src, *dst;
 	uint8 menu;
@@ -258,6 +209,12 @@ int32 ProcessMenu(void) {
 	return RD_OK;
 }
 
+/**
+ * This function brings a specified menu into view. 
+ * @param menu RDMENU_TOP or RDMENU_BOTTOM, depending on which menu to show
+ * @return RD_OK, or an error code
+ */
+
 int32 ShowMenu(uint8 menu) {
 	// Check for invalid menu parameter
 	if (menu > RDMENU_BOTTOM)
@@ -272,6 +229,12 @@ int32 ShowMenu(uint8 menu) {
 	return RD_OK;
 }
 
+/**
+ * This function hides a specified menu.
+ * @param menu RDMENU_TOP or RDMENU_BOTTOM depending on which menu to hide
+ * @return RD_OK, or an error code
+ */
+
 int32 HideMenu(uint8 menu) {
 	// Check for invalid menu parameter
 	if (menu > RDMENU_BOTTOM)
@@ -286,6 +249,10 @@ int32 HideMenu(uint8 menu) {
 	return RD_OK;
 }
 
+/**
+ * This function hides both menus immediately.
+ */
+
 int32 CloseMenuImmediately(void) {
 	ScummVM::Rect r;
 	int i;
@@ -308,6 +275,14 @@ int32 CloseMenuImmediately(void) {
 	return RD_OK;
 }
 
+/**
+ * This function sets a menubar icon.
+ * @param menu RDMENU_TOP or RDMENU_BOTTOM, depending on which menu to change
+ * @param pocket the menu pocket to change
+ * @param icon icon data, or NULL to clear the icon
+ * @return RD_OK, or an error code
+ */
+
 int32 SetMenuIcon(uint8 menu, uint8 pocket, uint8 *icon) {
 	ScummVM::Rect r;
 
@@ -341,6 +316,10 @@ int32 SetMenuIcon(uint8 menu, uint8 pocket, uint8 *icon) {
 	return RD_OK;
 }
 
+/**
+ * @return The status of the menu
+ */
+
 uint8 GetMenuStatus(uint8 menu) {
 	if (menu > RDMENU_BOTTOM)
 		return RDMENU_HIDDEN;
diff --git a/sword2/driver/palette.cpp b/sword2/driver/palette.cpp
index f2b9ea0162..38a83a211c 100644
--- a/sword2/driver/palette.cpp
+++ b/sword2/driver/palette.cpp
@@ -17,61 +17,6 @@
  * $Header$
  */
 
-//=============================================================================
-//
-//	Filename	:	palette.c
-//	Created		:	22nd August 1996
-//	By			:	P.R.Porter
-//
-//	Summary		:	This module holds the palette functions and the interface
-//					to the directDraw palette.
-//
-//	Functions
-//	---------
-//
-//	--------------------------------------------------------------------------
-//
-//	void BS2_SetPalette(int32 startEntry, int32 noEntries, uint8 *colourTable)
-//
-//	Sets the palette from position startEntry for noEntries, to the data 
-//	pointed to by colourTable.
-//
-//	--------------------------------------------------------------------------
-//
-//	void UpdatePaletteMatchTable(uint8 *data)
-//
-//	Uses the current palCopy to create a table of palette indeces which will
-//	be searched later for a quick palette match, if data is NULL.  Otherwise
-//	it uses the table passed in.
-//
-//	--------------------------------------------------------------------------
-//
-//	uint8 QuickMatch(uint8 r, uint8 g, uint8 b)
-//
-//	Returns the palette index of the closest matching colour in the palette
-//	to these RGB values.
-//
-//	--------------------------------------------------------------------------
-//
-//	int32 FadeUp(float time)
-//
-//	Fades the palette up from black to the current palette in time.
-//
-//	--------------------------------------------------------------------------
-//
-//	int32 FadeDown(float time)
-//
-//	Fades the palette down to black from the current palette in time.
-//
-//	--------------------------------------------------------------------------
-//
-//	uint8 GetFadeStatus(void)
-//
-//	Returns the fade status which can be one of RDFADE_UP, RDFADE_DOWN or
-//	RDFADE_NONE.
-//
-//=============================================================================
-
 #include "stdafx.h"
 #include <stdio.h>
 
@@ -141,6 +86,13 @@ uint8 GetMatch(uint8 r, uint8 g, uint8 b) {
 	return minIndex;
 }
 
+/**
+ * Sets or creates a table of palette indices which will be searched later for
+ * a quick palette match.
+ * @param data either the palette match table, or NULL to create a new table
+ * from the current palCopy
+ */
+
 int32 UpdatePaletteMatchTable(uint8 *data) {
 	if (!data) {
 		int16 red, green, blue;
@@ -166,6 +118,14 @@ int32 UpdatePaletteMatchTable(uint8 *data) {
 	return RD_OK;
 }
 
+/**
+ * Matches a colour triplet to a palette index.
+ * @param r red colour component
+ * @param g green colour component
+ * @param b blue colour component
+ * @return the palette index of the closest matching colour in the palette
+ */
+
 // FIXME: This used to be inlined - probably a good idea - but the
 // linker complained when I tried to use it in sprite.cpp.
 
@@ -173,6 +133,13 @@ uint8 QuickMatch(uint8 r, uint8 g, uint8 b) {
 	return paletteMatch[((int32) (r >> 2) << 12) + ((int32) (g >> 2) << 6) + (b >> 2)];
 }
 
+/**
+ * Sets the palette.
+ * @param startEntry the first colour entry to set
+ * @param noEntries the number of colour entries to set
+ * @param colourTable the new colour entries
+ */
+
 int32 BS2_SetPalette(int16 startEntry, int16 noEntries, uint8 *colourTable, uint8 fadeNow) {
 	if (noEntries == 0) {
 		RestorePalette();
@@ -196,6 +163,11 @@ int32 DimPalette(void) {
 	return RD_OK;
 }
 
+/**
+ * Fades the palette up from black to the current palette.
+ * @param time the time it will take the palette to fade up
+ */
+
 int32 FadeUp(float time) {
 	if (fadeStatus != RDFADE_BLACK && fadeStatus != RDFADE_NONE)
 		return RDERR_FADEINCOMPLETE;
@@ -207,6 +179,11 @@ int32 FadeUp(float time) {
 	return RD_OK;
 }
 
+/**
+ * Fades the palette down to black from the current palette.
+ * @param time the time it will take the palette to fade down
+ */
+
 int32 FadeDown(float time) {
 	if (fadeStatus != RDFADE_BLACK && fadeStatus != RDFADE_NONE)
 		return RDERR_FADEINCOMPLETE;
@@ -218,6 +195,12 @@ int32 FadeDown(float time) {
 	return RD_OK;
 }
 
+/**
+ * Get the current fade status
+ * @return RDFADE_UP (fading up), RDFADE_DOWN (fading down), RDFADE_NONE
+ * (not faded), or RDFADE_BLACK (completely faded down)
+ */
+
 uint8 GetFadeStatus(void) {
 	return fadeStatus;
 }
diff --git a/sword2/driver/rdwin.cpp b/sword2/driver/rdwin.cpp
index 743c68201d..5a053d8ebe 100644
--- a/sword2/driver/rdwin.cpp
+++ b/sword2/driver/rdwin.cpp
@@ -73,6 +73,10 @@ void Sword2State::parseEvents() {
 	}
 }
 
+/**
+ * Quit the game.
+ */
+
 int32 CloseAppWindow(void) {
 	warning("stub CloseAppWindow");
 /*
@@ -89,6 +93,11 @@ void SetNeedRedraw() {
 	_needRedraw = true;
 }
 
+/**
+ * This function should be called at a high rate (> 20 per second) to service
+ * windows and the interface it provides.
+ */
+
 int32 ServiceWindows(void) {
 	g_sword2->parseEvents();
 	FadeServer();
@@ -107,6 +116,11 @@ int32 ServiceWindows(void) {
 	return RD_OK;
 }
 
+/**
+ * Set the window name to windowName and stores this name in gameName for
+ * future use.
+ */
+
 void SetWindowName(const char *windowName) {
 	warning("stub SetWindowName( %s )", windowName);
 	// SetWindowText(hwnd, windowName);
diff --git a/sword2/driver/render.cpp b/sword2/driver/render.cpp
index a1a33de24a..7a90fbb3a6 100644
--- a/sword2/driver/render.cpp
+++ b/sword2/driver/render.cpp
@@ -17,89 +17,6 @@
  * $Header$
  */
 
-//=============================================================================
-//
-//	Filename	:	render.c
-//	Created		:	26th September 1996
-//	By			:	P.R.Porter
-//
-//	Summary		:	This module holds the functions which deal with rendering
-//					the background and parallax layers, and controlling the
-//					speed of the scroll (number of frames)
-//
-//	Functions
-//	---------
-//
-//	---------------------------------------------------------------------------
-//	
-//	int32 RenderParallax(_parallax *p, int16 layer)
-//
-//	Draws a parallax layer at the current position determined by the scroll.
-//	A parallax can be either foreground, background or the main screen.
-//
-//	---------------------------------------------------------------------------
-//
-//	int32 SetScrollTarget(int16 sx, int16 sy)
-//
-//	Sets the scroll target position for the end of the game cycle.  The drivers
-//	will then automatically scroll as many times as it can to reach this 
-//	position in the allotted time.
-//
-//	--------------------------------------------------------------------------
-//
-//	int32 StartRenderCycle(void)
-//
-//	This function should be called when the game engine is ready to start
-//	the render cycle.
-//
-//	--------------------------------------------------------------------------
-//
-//	int32 EndRenderCycle(BOOL *end)
-//
-//	This function should be called at the end of the render cycle.  If the
-//	render cycle is to be terminated, the function sets *end to 1.  Otherwise,
-//	the render cycle should continue.
-//
-//	--------------------------------------------------------------------------
-//
-//	int32 SetLocationMetrics(uint16 w, uint16 h)
-//
-//	This function tells the drivers the size of the background screen for the
-//	current location.
-//
-//	--------------------------------------------------------------------------
-//
-//	int32 PlotPoint(uint16 x, uint16 y, uint8 colour)
-//
-//	Plots the point x,y in relation to the top left corner of the background.
-//
-//	--------------------------------------------------------------------------
-//
-//	int32 DrawLine(int16 x1, int16 y1, int16 x2, int16 y2, uint8 colour)
-//
-//	Draws a line from the point x1,y1 to x2,y2 of the specified colour.
-//
-//	--------------------------------------------------------------------------
-//
-//	int32 InitialiseBackgroundLayer(_parallax *p)
-//
-//	This function should be called five times with either the parallax layer
-//	or a NULL pointer in order of background parallax to foreground parallax.
-//
-//	--------------------------------------------------------------------------
-//
-//	int32 CloseBackgroundLayer(void)
-//
-//	Should be called once after leaving a room to free up video memory.
-//
-//	--------------------------------------------------------------------------
-//
-//	int32 PlotDots(int16 x, int16 y, int16 count)
-//
-//	Plots 'count' dots at the position x,y.
-//
-//=============================================================================
-
 #include "stdafx.h"
 #include "driver96.h"
 #include "d_draw.h"
@@ -479,6 +396,14 @@ int32 RestoreBackgroundLayer(_parallax *p, int16 l)
 	return RD_OK;
 }
 
+/**
+ * Plots a point relative to the top left corner of the screen. This is only
+ * used for debugging.
+ * @param x x-coordinate of the point
+ * @param y y-coordinate of the point
+ * @param colour colour of the point
+ */
+
 int32 PlotPoint(uint16 x, uint16 y, uint8 colour) {
 	warning("stub PlotPoint( %d, %d, %d )", x, y, colour);
 /*
@@ -517,6 +442,15 @@ int32 PlotPoint(uint16 x, uint16 y, uint8 colour) {
 
 }
 
+/**
+ * Draws a line from one point to another. This is only used for debugging.
+ * @param x0 x-coordinate of the start point
+ * @param y0 y-coordinate of the start point
+ * @param x1 x-coordinate of the end point
+ * @param y1 y-coordinate of the end point
+ * @param colour colour of the line
+ */
+
 // Uses Bressnham's incremental algorithm!
 int32 DrawLine(int16 x0, int16 y0, int16 x1, int16 y1, uint8 colour) {
 	warning("stub DrawLine( %d, %d, %d, %d, %d )", x0, y0, x1, y1, colour);
@@ -752,6 +686,13 @@ int32 DrawLine(int16 x0, int16 y0, int16 x1, int16 y1, uint8 colour) {
 	return RD_OK;
 }
 
+/**
+ * This function tells the driver the size of the background screen for the
+ * current location.
+ * @param w width of the current location
+ * @param h height of the current location
+ */
+
 int32 SetLocationMetrics(uint16 w, uint16 h) {
 	locationWide = w;
 	locationDeep = h;
@@ -759,6 +700,11 @@ int32 SetLocationMetrics(uint16 w, uint16 h) {
 	return RD_OK;
 }
 
+/**
+ * Draws a parallax layer at the current position determined by the scroll. A
+ * parallax can be either foreground, background or the main screen.
+ */
+
 int32 RenderParallax(_parallax *p, int16 l) {
 	int16 x, y;
 	int16 i, j;
@@ -804,12 +750,21 @@ int32 RenderParallax(_parallax *p, int16 l) {
 // Uncomment this when benchmarking the drawing routines.
 #define LIMIT_FRAME_RATE
 
+/**
+ * Initialises the timers before the render loop is entered.
+ */
+
 int32 InitialiseRenderCycle(void) {
 	initialTime = SVM_timeGetTime();
 	totalTime = initialTime + MILLISECSPERCYCLE;
 	return RD_OK;
 }
 
+/**
+ * This function should be called when the game engine is ready to start the
+ * render cycle.
+ */
+
 int32 StartRenderCycle(void) {
 	scrollxOld = scrollx;
 	scrollyOld = scrolly;
@@ -844,6 +799,12 @@ void sleepUntil(int32 time) {
 	}
 }
 
+/**
+ * This function should be called at the end of the render cycle.
+ * @param end the function sets this to true if the render cycle is to be
+ * terminated, or false if it should continue
+ */
+
 int32 EndRenderCycle(bool *end) {
 	int32 time;
 
@@ -892,6 +853,12 @@ int32 EndRenderCycle(bool *end) {
 	return RD_OK;
 }
 
+/**
+ * Sets the scroll target position for the end of the game cycle. The driver
+ * will then automatically scroll as many times as it can to reach this
+ * position in the allotted time.
+ */
+
 int32 SetScrollTarget(int16 sx, int16 sy) {
 	scrollxTarget = sx;
 	scrollyTarget = sy;
@@ -899,6 +866,11 @@ int32 SetScrollTarget(int16 sx, int16 sy) {
 	return RD_OK;
 }
 
+/**
+ * This function should be called five times with either the parallax layer
+ * or a NULL pointer in order of background parallax to foreground parallax.
+ */
+
 int32 InitialiseBackgroundLayer(_parallax *p) {
 	uint8 *memchunk;
 	uint8 zeros;
@@ -1022,6 +994,10 @@ int32 InitialiseBackgroundLayer(_parallax *p) {
 
 }
 
+/**
+ * Should be called once after leaving the room to free up memory.
+ */
+
 int32 CloseBackgroundLayer(void) {
 	debug(2, "CloseBackgroundLayer");
 
diff --git a/sword2/driver/sprite.cpp b/sword2/driver/sprite.cpp
index 5d69d871e4..e246fd9935 100644
--- a/sword2/driver/sprite.cpp
+++ b/sword2/driver/sprite.cpp
@@ -17,46 +17,6 @@
  * $Header$
  */
 
-//=============================================================================
-//
-//	Filename	:	sprite.c
-//	Created		:	23rd September 1996
-//	By			:	P.R.Porter
-//
-//	Summary		:	This module holds the sprite drawing functions.
-//
-//	Functions
-//	---------
-//
-//	--------------------------------------------------------------------------
-//
-//	int32 CreateSurface(_spriteInfo *s, uint32 *surface)
-//
-//	Creates a sprite surface in video memory (if possible) and returns it's
-//	handle in surface.
-//
-//	---------------------------------------------------------------------------
-//
-//	int32 DrawSurface(_spriteInfo *s, uint32 surface, ScummVM::Rect *clipRect)
-//
-//	Draws the sprite surface created earlier.  If the surface has been lost,
-//	it is recreated.
-//
-//	---------------------------------------------------------------------------
-//
-//	int32 DeleteSurface(uint32 surface)
-//
-//	Deletes a surface from video memory.
-//
-//	--------------------------------------------------------------------------
-//
-//	int32 DrawSprite(_spriteInfo *s)
-//
-//	Draws a sprite onto the screen.  The _spriteInfo structure holds all of
-//	the information needed to draw the sprite - see driver96.h for details
-//
-//=============================================================================
-
 #include "stdafx.h"
 #include "driver96.h"
 #include "d_draw.h"
@@ -68,14 +28,13 @@
 char shitColourTable[1024];
 static uint8 *lightMask = 0;
 
-// --------------------------------------------------------------------------
-//
-// int32 MirrorSprite(uint8 *dst, uint8 *src, int16 w, int16 h)
-//
-// This function takes the sprite pointed to by src and creates a mirror
-// image of it in dst.
-//
-// --------------------------------------------------------------------------
+/**
+ * This function takes a sprite and creates a mirror image of it.
+ * @param dst destination buffer
+ * @param src source buffer
+ * @param w width of the sprite
+ * @param h height of the sprite
+ */
 
 int32 MirrorSprite(uint8 *dst, uint8 *src, int16 w, int16 h) {
 	int16 x, y;
@@ -90,16 +49,13 @@ int32 MirrorSprite(uint8 *dst, uint8 *src, int16 w, int16 h) {
 	return RD_OK;
 }
 
-// --------------------------------------------------------------------------
-//
-// int32 DecompressRLE256(uint8 *dest, uint8 *source, int32 decompSize)
-//
-// This function takes a compressed frame of a sprite (with up to 256 colours)
-// and decompresses it into the area of memory marked by the destination
-// pointer.  The decompSize is used to measure when the decompression process
-// has completed.
-//
-// --------------------------------------------------------------------------
+/**
+ * This function takes a compressed frame of a sprite with up to 256 colours
+ * and decompresses it.
+ * @param dest destination buffer
+ * @param source source buffer
+ * @param decompSize the expected size of the decompressed sprite
+ */
 
 int32 DecompressRLE256(uint8 *dest, uint8 *source, int32 decompSize) {
 	// PARAMETERS:
@@ -177,12 +133,9 @@ int32 DecompressRLE256(uint8 *dest, uint8 *source, int32 decompSize) {
 	return rv;
 }
 
-// --------------------------------------------------------------------------
-//
-// void UnwindRaw16(uint8 *dest, uint8 *source, uint8 blockSize, uint8 *colTable)
-//
-// This function unwinds a run of colour 16 data into 256 colour palette data.
-// --------------------------------------------------------------------------
+/**
+ * Unwinds a run of 16-colour data into 256-colour palette data.
+ */
 
 void UnwindRaw16(uint8 *dest, uint8 *source, uint8 blockSize, uint8 *colTable) {
 	// for each pair of pixels
@@ -210,27 +163,16 @@ void UnwindRaw16(uint8 *dest, uint8 *source, uint8 blockSize, uint8 *colTable) {
 	}
 }
 
-// --------------------------------------------------------------------------
-//
-// int32 DecompressRLE16(uint8 *dest, uint8 *source, int32 decompSize, uint8 *colTable)
-//
-// This function takes a compressed frame of a sprite (with up to 16 colours)
-// and decompresses it into the area of memory marked by the destination
-// pointer.  The decompSize is used to measure when the decompression process
-// has completed.  The colour table which maps the 16 encoded colours to the 
-// current palette is passed in to colTable.
-//
-// --------------------------------------------------------------------------
+/**
+ * This function takes a compressed frame of a sprite (with up to 16 colours)
+ * and decompresses it.
+ * @param dest destination buffer
+ * @param source source buffer
+ * @param decompSize the expected size of the uncompressed sprite
+ * @param colTable mapping from the 16 encoded colours to the current palette
+ */
 
 int32 DecompressRLE16(uint8 *dest, uint8 *source, int32 decompSize, uint8 *colTable) {
-	// PARAMETERS:
-	// source	points to the start of the sprite data for input
-	// decompSize	gives size of decompressed data in bytes
-	// dest		points to start of destination buffer for decompressed
-	//		data
-	// colTable	points to a 16-byte table of colours used to encode
-	//		the RAW pixels into 4-bits each
-
 	uint8 headerByte;			// block header byte
 	uint8 *endDest = dest + decompSize;	// pointer to byte after end of decomp buffer
 	int32 rv;
@@ -301,9 +243,14 @@ int32 DecompressRLE16(uint8 *dest, uint8 *source, int32 decompSize, uint8 *colTa
 	return rv;
 }
 
-// The surface functions are used by the in-game dialogs and for displaying
-// cutscene subtitles. Everything that isn't needed for those cases (blending,
-// scaling, etc.) has been removed.
+/**
+ * Creates a sprite surface. Sprite surfaces are used by the in-game dialogs
+ * and for displaying cutscene subtitles, which makes them much easier to draw
+ * than standard sprites.
+ * @param s information about how to decode the sprite
+ * @param sprite the buffer that will be created to store the surface
+ * @return RD_OK, or an error code
+ */
 
 int32 CreateSurface(_spriteInfo *s, uint8 **sprite) {
 	uint8 *newSprite;
@@ -342,6 +289,13 @@ int32 CreateSurface(_spriteInfo *s, uint8 **sprite) {
 	return RD_OK;
 }
 
+/**
+ * Draws the sprite surface created earlier.
+ * @param s information about how to place the sprite
+ * @param surface pointer to the surface created earlier
+ * @param clipRect the clipping rectangle
+ */
+
 void DrawSurface(_spriteInfo *s, uint8 *surface, ScummVM::Rect *clipRect) {
 	ScummVM::Rect rd, rs;
 	uint16 x, y, srcPitch;
@@ -406,6 +360,10 @@ void DrawSurface(_spriteInfo *s, uint8 *surface, ScummVM::Rect *clipRect) {
 	SetNeedRedraw();
 }
 
+/**
+ * Destroys a surface.
+ */
+
 void DeleteSurface(uint8 *surface) {
 	free(surface);
 }
@@ -416,6 +374,24 @@ void DeleteSurface(uint8 *surface) {
 uint16 xScale[SCALE_MAXWIDTH];
 uint16 yScale[SCALE_MAXHEIGHT];
 
+/**
+ * Draws a sprite onto the screen. The type of the sprite can be a combination
+ * of the following flags, some of which are mutually exclusive:
+ * RDSPR_DISPLAYALIGN	The sprite is drawn relative to the top left corner
+ *			of the screen
+ * RDSPR_FLIP		The sprite is mirrored
+ * RDSPR_TRANS		The sprite has a transparent colour zero
+ * RDSPR_BLEND		The sprite is translucent
+ * RDSPR_SHADOW		The sprite is affected by the light mask. (Scaled
+ *			sprites always are.)
+ * RDSPR_NOCOMPRESSION	The sprite data is not compressed
+ * RDSPR_RLE16		The sprite data is a 16-colour compressed sprite
+ * RDSPR_RLE256		The sprite data is a 256-colour compressed sprite
+ * @param s all the information needed to draw the sprite
+ * @warning Sprites will only be drawn onto the background, not over menubar
+ * areas.
+ */
+
 // FIXME: I'm sure this could be optimized. There's plenty of data copying and
 // mallocing here.
 
@@ -709,6 +685,10 @@ int32 DrawSprite(_spriteInfo *s) {
 	return RD_OK;
 }
 
+/**
+ * Opens the light masking sprite for a room.
+ */
+
 int32 OpenLightMask(_spriteInfo *s) {
 	// FIXME: The light mask is only needed on higher graphics detail
 	// settings, so to save memory we could simply ignore it on lower
@@ -728,6 +708,10 @@ int32 OpenLightMask(_spriteInfo *s) {
 	return RD_OK;
 }
 
+/**
+ * Closes the light masking sprite for a room.
+ */
+
 int32 CloseLightMask(void) {
 	if (!lightMask)
 		return RDERR_NOTOPEN;