more OSystem docs & cleanup

svn-id: r8118

18 files changed, 152 insertions, 81 deletions

diff --git a/backends/PalmOS/Src/palm.cpp b/backends/PalmOS/Src/palm.cpp
index 6d46ce31de..5ee9a9628a 100644
--- a/backends/PalmOS/Src/palm.cpp
+++ b/backends/PalmOS/Src/palm.cpp
@@ -1112,7 +1112,7 @@ void OSystem_PALMOS::move_screen(int dx, int dy, int height) {
 	SysTaskDelay(1); // prevent crash on Clie device using successive [HR]WinScrollRectangle !
 }
 
-bool OSystem_PALMOS::set_sound_proc(void *param, SoundProc *proc, byte format) {
+bool OSystem_PALMOS::set_sound_proc(SoundProc *proc, void *param, SoundFormat format) {
 
 	_sound.active = true;
 	_sound.proc = proc;
diff --git a/backends/PalmOS/Src/palm.h b/backends/PalmOS/Src/palm.h
index fcfb2014a7..d561080564 100644
--- a/backends/PalmOS/Src/palm.h
+++ b/backends/PalmOS/Src/palm.h
@@ -86,7 +86,7 @@ public:
 	void SimulateArrowKeys(Event *event, Int8 iHoriz, Int8 iVert, Boolean repeat);
 
 	// Set function that generates samples 
-	bool set_sound_proc(void *param, SoundProc *proc, byte sound);
+	bool set_sound_proc(SoundProc *proc, void *param, SoundFormat format);
 
 	// Poll cdrom status
 	// Returns true if cd audio is playing
diff --git a/backends/dc/audio.cpp b/backends/dc/audio.cpp
index 0b0cb8c639..526d8cbbef 100644
--- a/backends/dc/audio.cpp
+++ b/backends/dc/audio.cpp
@@ -34,8 +34,7 @@ void initSound()
   do_sound_command(CMD_SET_BUFFER(3));
 }
 
-bool OSystem_Dreamcast::set_sound_proc(void *param, SoundProc *proc,
-				       byte format)
+bool OSystem_Dreamcast::set_sound_proc(SoundProc *proc, void *param, SoundFormat format)
 {
 #if SAMPLE_MODE == 0
   assert(format == SOUND_16BIT);
diff --git a/backends/dc/dc.h b/backends/dc/dc.h
index 5dff783657..56cdb8dd00 100644
--- a/backends/dc/dc.h
+++ b/backends/dc/dc.h
@@ -48,7 +48,7 @@ class OSystem_Dreamcast : public OSystem {
   bool poll_event(Event *event);
   
   // Set function that generates samples 
-  bool set_sound_proc(void *param, SoundProc *proc, byte sound);
+  bool set_sound_proc(SoundProc *proc, void *param, SoundFormat format);
 		
   // Poll cdrom status
   // Returns true if cd audio is playing
diff --git a/backends/gp32/gp32.cpp b/backends/gp32/gp32.cpp
index 62b10b9a95..cb62c227ba 100644
--- a/backends/gp32/gp32.cpp
+++ b/backends/gp32/gp32.cpp
@@ -980,7 +980,7 @@ bool OSystem_GP32::poll_event(Event *event) { 	// fixme: make more user-friendly
 // Set the function to be invoked whenever samples need to be generated
 // Format is the sample type format.
 // Only 16-bit signed mode is needed for simon & scumm
-bool OSystem_GP32::set_sound_proc(void *param, SoundProc *proc, byte format) { 
+bool OSystem_GP32::set_sound_proc(SoundProc *proc, void *param, SoundFormat format) { 
 	return false; 
 }
 
diff --git a/backends/gp32/gp32.h b/backends/gp32/gp32.h
index 686ece4f27..825eeccb51 100644
--- a/backends/gp32/gp32.h
+++ b/backends/gp32/gp32.h
@@ -80,7 +80,7 @@ public:
 	// Set the function to be invoked whenever samples need to be generated
 	// Format is the sample type format.
 	// Only 16-bit signed mode is needed for simon & scumm
-	bool set_sound_proc(void *param, SoundProc *proc, byte format);
+	bool set_sound_proc(SoundProc *proc, void *param, SoundFormat format);
 	
 	// Get or set a property
 	uint32 property(int param, Property *value);
diff --git a/backends/morphos/morphos.cpp b/backends/morphos/morphos.cpp
index 34dde38f3f..2c9674101d 100644
--- a/backends/morphos/morphos.cpp
+++ b/backends/morphos/morphos.cpp
@@ -1404,7 +1404,7 @@ void OSystem_MorphOS::set_mouse_cursor(const byte *buf, uint w, uint h, int hots
 	UndrawMouse();
 }
 
-bool OSystem_MorphOS::set_sound_proc(void *param, OSystem::SoundProc *proc, byte format)
+bool OSystem_MorphOS::set_sound_proc(OSystem::SoundProc *proc, void *param, OSystem::SoundFormat format)
 {
 	SoundProc = proc;
 	SoundParam = param;
diff --git a/backends/morphos/morphos.h b/backends/morphos/morphos.h
index 6327edd647..2fed3dae28 100644
--- a/backends/morphos/morphos.h
+++ b/backends/morphos/morphos.h
@@ -99,7 +99,7 @@ class OSystem_MorphOS : public OSystem
 		virtual void warp_mouse(int x, int y);
 
 		// Set the function to be invoked whenever samples need to be generated
-		virtual bool set_sound_proc(void *param, SoundProc *proc, byte format);
+		virtual bool set_sound_proc(SoundProc *proc, void *param, SoundFormat format);
 				  void fill_sound    (byte * stream, int len);
 
 		virtual uint32 property(int param, Property *value);
diff --git a/backends/null/null.cpp b/backends/null/null.cpp
index 4878ebeffa..8098445a89 100644
--- a/backends/null/null.cpp
+++ b/backends/null/null.cpp
@@ -42,7 +42,7 @@ public:
 	void delay_msecs(uint msecs);
 	void create_thread(ThreadProc *proc, void *param) { }
 	bool poll_event(Event *event) { return false; }
-	bool set_sound_proc(void *param, SoundProc *proc, byte sound) {}
+	bool set_sound_proc(SoundProc *proc, void *param, SoundFormat format) {}
 	void quit() { exit(1); }
 	uint32 property(int param, Property *value) { return 0; }
 	static OSystem *create(int gfx_mode, bool full_screen);
diff --git a/backends/sdl/sdl-common.cpp b/backends/sdl/sdl-common.cpp
index f9096c098c..9970d20b13 100644
--- a/backends/sdl/sdl-common.cpp
+++ b/backends/sdl/sdl-common.cpp
@@ -827,7 +827,7 @@ bool OSystem_SDL_Common::poll_event(Event *event) {
 	return false;
 }
 
-bool OSystem_SDL_Common::set_sound_proc(void *param, SoundProc *proc, byte /* format */) {
+bool OSystem_SDL_Common::set_sound_proc(SoundProc *proc, void *param, SoundFormat format) {
 	SDL_AudioSpec desired;
 
 	memset(&desired, 0, sizeof(desired));
diff --git a/backends/sdl/sdl-common.h b/backends/sdl/sdl-common.h
index 71a44d46f6..89d28a8087 100644
--- a/backends/sdl/sdl-common.h
+++ b/backends/sdl/sdl-common.h
@@ -78,7 +78,7 @@ public:
 	bool poll_event(Event *event);
 
 	// Set function that generates samples 
-	bool set_sound_proc(void *param, SoundProc *proc, byte sound);
+	bool set_sound_proc(SoundProc *proc, void *param, SoundFormat format);
 
 	// Poll CD status
 	// Returns true if cd audio is playing
diff --git a/backends/wince/wince.cpp b/backends/wince/wince.cpp
index 6db546172e..967b6d9070 100644
--- a/backends/wince/wince.cpp
+++ b/backends/wince/wince.cpp
@@ -1673,7 +1673,7 @@ void own_soundProc(void *buffer, byte *samples, int len) {
 		memset(samples, 0, len);
 }
 
-bool OSystem_WINCE3::set_sound_proc(void *param, SoundProc *proc, byte format) {
+bool OSystem_WINCE3::set_sound_proc(SoundProc *proc, void *param, SoundFormat format) {
 	SDL_AudioSpec desired;
 
 	/* only one format supported at the moment */
diff --git a/backends/wince/wince.h b/backends/wince/wince.h
index 9af0e4e81b..1b369caeed 100644
--- a/backends/wince/wince.h
+++ b/backends/wince/wince.h
@@ -116,7 +116,7 @@ public:
 	bool poll_event(Event *event);
 	
 	// Set function that generates samples 
-	bool set_sound_proc(void *param, SoundProc *proc, byte sound);
+	bool set_sound_proc(SoundProc *proc, void *param, SoundFormat format);
 		
 	// Poll cdrom status
 	// Returns true if cd audio is playing
diff --git a/backends/x11/x11.cpp b/backends/x11/x11.cpp
index 106b0e7138..1f467a550c 100644
--- a/backends/x11/x11.cpp
+++ b/backends/x11/x11.cpp
@@ -96,7 +96,7 @@ public:
 	bool poll_event(Event *event);
 
 	// Set function that generates samples 
-	bool set_sound_proc(void *param, SoundProc *proc, byte sound);
+	bool set_sound_proc(SoundProc *proc, void *param, SoundFormat format);
 
 	// Poll cdrom status
 	// Returns true if cd audio is playing
diff --git a/common/system.h b/common/system.h
index 3158b732d5..21cfb29fd2 100644
--- a/common/system.h
+++ b/common/system.h
@@ -27,16 +27,25 @@
 #include "savefile.h"
 
 /**
- * Interface for ScummVM backends.
+ * Interface for ScummVM backends. If you want to port ScummVM to a system
+ * which is not currently covered by any of our backends, this is the place
+ * to start. ScummVM will create an instance of a subclass of this interface
+ * and use it to interact with the system.
+ *
+ * In particular, a backend provides a video surface for ScummVM to draw in;
+ * methods to create threads and timers, to handle user input events,
+ * control audio CD playback, and sound output.
  */
 class OSystem {
 public:
 	typedef void *MutexRef;
 	typedef int ThreadProc(void *param);
 	typedef void SoundProc(void *param, byte *buf, int len);
+	//typedef int TimerProc(int interval);
 
 	/**
 	 * The types of events backends can generate.
+	 * @todo Add events for quit request, and screen size change.
 	 * @see Event
 	 */
 	enum EventCode {
@@ -92,18 +101,37 @@ public:
 		bool show_cursor;
 	};
 	
-	enum {
+	enum SoundFormat {
 		SOUND_8BIT = 0,
 		SOUND_16BIT = 1
 	};
-	
-	/** Set colors of the palette. */
-	virtual void set_palette(const byte *colors, uint start, uint num) = 0;
+
+
+
+	/** @name Graphics */
+	//@{
 
 	/** Set the size of the video bitmap. Typically 320x200 pixels. */
 	virtual void init_size(uint w, uint h) = 0;
 
 	/**
+	 * Returns the currently set screen height.
+	 * @see init_size
+	 * @return the currently set screen height
+	 */
+	virtual int16 get_height() = 0;
+
+	/**
+	 * Returns the currently set screen width.
+	 * @see init_size
+	 * @return the currently set screen width
+	 */
+	virtual int16 get_width() = 0;
+
+	/** Set colors of the palette. */
+	virtual void set_palette(const byte *colors, uint start, uint num) = 0;
+
+	/**
 	 * Draw a bitmap to screen.
 	 * The screen will not be updated to reflect the new bitmap, you have
 	 * to call update_screen to do that.
@@ -123,6 +151,46 @@ public:
 	/** Update the dirty areas of the screen. */
 	virtual void update_screen() = 0;
 
+	/**
+	 * Set current shake position, a feature needed for some SCUMM screen effects.
+	 * The effect causes the displayed graphics to be shifted upwards by the specified 
+	 * (always positive) offset. The area at the bottom of the screen which is moved
+	 * into view by this is filled by black. This does not cause any graphic data to
+	 * be lost - that is, to restore the original view, the game engine only has to
+	 * call this method again with a 0 offset. No calls to copy_rect are necessary.
+	 * @param shakeOffset	the shake offset
+	 */
+	virtual void set_shake_pos(int shakeOffset) = 0;
+
+	/** Convert the given RGB triplet into a NewGuiColor. A NewGuiColor can be
+	 * 8bit, 16bit or 32bit, depending on the target system. The default
+	 * implementation generates a 16 bit color value, in the 565 format
+	 * (that is, 5 bits red, 6 bits green, 5 bits blue).
+	 * @see colorToRGB
+	 */
+	virtual NewGuiColor RGBToColor(uint8 r, uint8 g, uint8 b) {
+		return ((((r >> 3) & 0x1F) << 11) | (((g >> 2) & 0x3F) << 5) | ((b >> 3) & 0x1F));
+	}
+
+	/** Convert the given NewGuiColor into a RGB triplet. A NewGuiColor can be
+	 * 8bit, 16bit or 32bit, depending on the target system. The default
+	 * implementation takes a 16 bit color value and assumes it to be in 565 format
+	 * (that is, 5 bits red, 6 bits green, 5 bits blue).
+	 * @see RGBToColor
+	 */
+	virtual void colorToRGB(NewGuiColor color, uint8 &r, uint8 &g, uint8 &b) {
+		r = (((color >> 11) & 0x1F) << 3);
+		g = (((color >> 5) & 0x3F) << 2);
+		b = ((color&0x1F) << 3);
+	}
+
+	//@}
+
+
+
+	/** @name Mouse */
+	//@{
+
 	/** Show or hide the mouse cursor. */
 	virtual bool show_mouse(bool visible) = 0;
 	
@@ -142,18 +210,14 @@ public:
 	
 	/** Set the bitmap used for drawing the cursor. */
 	virtual void set_mouse_cursor(const byte *buf, uint w, uint h, int hotspot_x, int hotspot_y) = 0;
+
+	//@}
 	
-	/**
-	 * Set current shake position, a feature needed for some SCUMM screen effects.
-	 * The effect causes the displayed graphics to be shifted upwards by the specified 
-	 * (always positive) offset. The area at the bottom of the screen which is moved
-	 * into view by this is filled by black. This does not cause any graphic data to
-	 * be lost - that is, to restore the original view, the game engine only has to
-	 * call this method again with a 0 offset. No calls to copy_rect are necessary.
-	 * @param shakeOffset	the shake offset
-	 */
-	virtual void set_shake_pos(int shakeOffset) = 0;
-		
+	
+
+	/** @name Events and Threads */
+	//@{
+
 	/** Get the number of milliseconds since the program was started. */
 	virtual uint32 get_msecs() = 0;
 	
@@ -163,25 +227,39 @@ public:
 	/**
 	 * Create a thread with the given entry procedure.
 	 * @param proc	the thread main procedure
-	 * @param param	an arbitrary parameter which is stored and passed to
-	 *              proc when it is invoked in its own thread.
+	 * @param param	an arbitrary parameter which is stored and passed to proc
 	 * @return 
 	 */
 	virtual void create_thread(ThreadProc *proc, void *param) = 0;
 	
-	// Get the next event.
-	// Returns true if an event was retrieved.	
+	/** Add a new callback timer. */
+	virtual void set_timer(int timer, int (*callback)(int)) = 0;
+	
+	/**
+	 * Get the next event in the event queue.
+	 * @param event	point to an Event struct, which will be filled with the event data.
+	 * @return true if an event was retrieved.
+	 */
 	virtual bool poll_event(Event *event) = 0;
 
-	// Set the function to be invoked whenever samples need to be generated
-	// Format is the sample type format.
-	// Only 16-bit signed mode is needed for simon & scumm
-	virtual bool set_sound_proc(void *param, SoundProc *proc, byte format) = 0;
-	
-	// Get or set a property
-	virtual uint32 property(int param, Property *value) = 0;
+	//@}
+
+
+
+	/** @name Sound */
+	//@{
+	/**
+	 * Set the audio callback which is invoked whenever samples need to be generated.
+	 * Currently, only the 16-bit signed mode is ever used for Simon & Scumm
+	 * @param proc		pointer to the callback.
+	 * @param param		an arbitrary parameter which is stored and passed to proc.
+	 * @param format	the sample type format.
+	 */
+	virtual bool set_sound_proc(SoundProc *proc, void *param, SoundFormat format) = 0;
+	//@} 
 		
 
+
 	/**
 	 * @name Audio CD
 	 * The methods in this group deal with Audio CD playback.
@@ -215,12 +293,8 @@ public:
 	//@} 
 
 
-	// Add a new callback timer
-	virtual void set_timer(int timer, int (*callback)(int)) = 0;
 
-	/**
-	 * @name Mutex handling
-	 */
+	/** @name Mutex handling */
 	//@{
 	/**
 	 * Create a new mutex.
@@ -249,12 +323,9 @@ public:
 	virtual void delete_mutex(MutexRef mutex) = 0;
 	//@} 
 
-	// Quit
-	virtual void quit() = 0;
+
 	
-	/**
-	 * @name Overlay
-	 */
+	/** @name Overlay */
 	//@{
 	virtual void show_overlay() = 0;
 	virtual void hide_overlay() = 0;
@@ -263,25 +334,21 @@ public:
 	virtual void copy_rect_overlay(const NewGuiColor *buf, int pitch, int x, int y, int w, int h) = 0;
 	//@} 
 
-	// Low-level graphics access
-	virtual int16 get_height() {return 200;}
-	virtual int16 get_width() {return 320;}
 
-	// Methods that convert RGB to/from colors suitable for the overlay.
-	// Default implementation assumes 565 mode.
-	virtual NewGuiColor RGBToColor(uint8 r, uint8 g, uint8 b) {
-		return ((((r >> 3) & 0x1F) << 11) | (((g >> 2) & 0x3F) << 5) | ((b >> 3) & 0x1F));
-	}
-	virtual void colorToRGB(NewGuiColor color, uint8 &r, uint8 &g, uint8 &b) {
-		r = (((color >> 11) & 0x1F) << 3);
-		g = (((color >> 5) & 0x3F) << 2);
-		b = ((color&0x1F) << 3);
-	}
 
-	// Savefile management
+	/** @name Miscellaneous */
+	//@{
+	/** Get or set a backend property. */
+	virtual uint32 property(int param, Property *value) = 0;
+
+	/** Quit (exit) the application. */
+	virtual void quit() = 0;
+
+	/** Savefile management. */
 	virtual SaveFileManager *get_savefile_manager() {
 		return new SaveFileManager();
 	}
+	//@}
 };
 
 /* Factory functions. This means we don't have to include the headers for
diff --git a/common/timer.cpp b/common/timer.cpp
index b2b3cbf1bf..906f621c91 100644
--- a/common/timer.cpp
+++ b/common/timer.cpp
@@ -24,26 +24,28 @@
 #include "scummsys.h"
 #include "timer.h"
 
-static Engine * eng;
+static Timer *g_timer = NULL;
 
 Timer::Timer(Engine * engine) {
 	memset(this,0,sizeof(Timer)); //palmos
 	
 	_initialized = false;
 	_timerRunning = false;
-	eng = _engine = engine;
+	_engine = engine;
+	g_timer = this;
 }
 
 Timer::~Timer() {
 	release();
 }
 
-static int timer_handler (int t) {
-	eng->_timer->handler(&t);
-	return t;
+int Timer::timer_handler(int t) {
+	if (g_timer)
+		return g_timer->handler(t);
+	return 0;
 }
 
-int Timer::handler(int * t) {
+int Timer::handler(int t) {
 	uint32 interval, l;
 
 	if (_timerRunning) {
@@ -62,16 +64,16 @@ int Timer::handler(int * t) {
 		}
 	}
 
-	return *t;
+	return t;
 }
 
 bool Timer::init() {
 	int32 l;
 
 	if (_engine->_system == NULL) {
-	printf("Timer: OSystem not initialized !\n");
-	return false;
-}
+		warning("Timer: OSystem not initialized!");
+		return false;
+	}
 
 	if (_initialized == true) 
 		return true;
@@ -112,7 +114,7 @@ bool Timer::installProcedure (TimerProc procedure, int32 interval) {
 	bool found = false;
 
 	if (_initialized == false) {
-		printf ("Timer: is not initialized !");
+		warning("Timer: is not initialized!");
 		return false;
 	}
 
@@ -129,7 +131,7 @@ bool Timer::installProcedure (TimerProc procedure, int32 interval) {
 
 	_timerRunning = true;
 	if (!found)	{
-		printf ("Can't find free slot !");
+		warning("Can't find free slot!");
 		return false;
 	}
 
@@ -140,7 +142,7 @@ void Timer::releaseProcedure (TimerProc procedure) {
 	int32 l;
 
 	if (_initialized == false) {
-		printf ("Timer: is not initialized !");
+		warning("Timer: is not initialized!");
 		return;
 	}
 
diff --git a/common/timer.h b/common/timer.h
index 4a69247bfa..0ed416679d 100644
--- a/common/timer.h
+++ b/common/timer.h
@@ -52,11 +52,14 @@ public:
 	  Timer(Engine *engine);
 	 ~Timer();
 
-	int handler(int *t);
 	bool init();
 	void release();
 	bool installProcedure(TimerProc procedure, int32 interval);
 	void releaseProcedure(TimerProc procedure);
+
+protected:
+	static int timer_handler(int t);
+	int handler(int t);
 };
 
 #endif
diff --git a/sound/mixer.cpp b/sound/mixer.cpp
index 957b4bd0ed..5433032021 100644
--- a/sound/mixer.cpp
+++ b/sound/mixer.cpp
@@ -188,7 +188,7 @@ bool SoundMixer::bindToSystem(OSystem *syst) {
 	if (rate == 0)
 		error("OSystem returned invalid sample rate");
 
-	return syst->set_sound_proc(this, onGenerateSamples, OSystem::SOUND_16BIT);
+	return syst->set_sound_proc(onGenerateSamples, this, OSystem::SOUND_16BIT);
 }
 
 void SoundMixer::stopAll() {