added some doxygen comments to common/system.h; cleaned up the OSystem interface a bit

svn-id: r8116

backends/PalmOS/Src/palm.cpp

@@ -515,12 +515,10 @@ void OSystem_PALMOS::delay_msecs(uint msecs) {
 	SysTaskDelay((SysTicksPerSecond()*msecs)/1000);
 }
 
-void *OSystem_PALMOS::create_thread(ThreadProc *proc, void *param) {
+void OSystem_PALMOS::create_thread(ThreadProc *proc, void *param) {
 	_thread.active	= true;
 	_thread.proc	= proc;
 	_thread.param	= param;
-	
-	return 0;
 }
 
 void OSystem_PALMOS::set_timer(int timer, int (*callback)(int))
@@ -536,7 +534,7 @@ void OSystem_PALMOS::set_timer(int timer, int (*callback)(int))
 }
 
 /* Mutex handling */
-void *OSystem_PALMOS::create_mutex(void)
+void *OSystem_PALMOS::create_mutex()
 {
   return NULL;
 }

backends/PalmOS/Src/palm.h

@@ -77,7 +77,7 @@ public:
 	void delay_msecs(uint msecs);
 	
 	// Create a thread
-	void *create_thread(ThreadProc *proc, void *param);
+	void create_thread(ThreadProc *proc, void *param);
 	
 	// Get the next event.
 	// Returns true if an event was retrieved.	
@@ -105,7 +105,7 @@ public:
 	void set_timer(int timer, int (*callback)(int));
 
 	// Mutex handling
-	void *create_mutex(void);
+	void *create_mutex();
 	void lock_mutex(void *mutex);
 	void unlock_mutex(void *mutex);
 	void delete_mutex(void *mutex);
@@ -140,7 +140,7 @@ protected:
 	bool _overlay_visible;
 
 private:
-	typedef void (OSystem_PALMOS::*RendererProc)(void);
+	typedef void (OSystem_PALMOS::*RendererProc)();
 	RendererProc _renderer_proc;
 
 	UInt8 *_sndDataP, *_sndTempP;

backends/dc/dc.h

@@ -41,7 +41,7 @@ class OSystem_Dreamcast : public OSystem {
   void delay_msecs(uint msecs);
   
   // Create a thread
-  void *create_thread(ThreadProc *proc, void *param);
+  void create_thread(ThreadProc *proc, void *param);
 	
   // Get the next event.
   // Returns true if an event was retrieved.	
@@ -80,7 +80,7 @@ class OSystem_Dreamcast : public OSystem {
   virtual void set_timer(int timer, int (*callback)(int));
 
   // Mutex handling
-  virtual void *create_mutex(void);
+  virtual void *create_mutex();
   virtual void lock_mutex(void *mutex);
   virtual void unlock_mutex(void *mutex);
   virtual void delete_mutex(void *mutex);

backends/dc/dcmain.cpp

@@ -118,13 +118,13 @@ void OSystem_Dreamcast::quit() {
   exit(0);
 }
 
-void *OSystem_Dreamcast::create_thread(ThreadProc *proc, void *param) {
+void OSystem_Dreamcast::create_thread(ThreadProc *proc, void *param) {
   warning("Creating a thread! (not supported.)\n");
 }
 
 
 /* Mutex handling */
-void *OSystem_Dreamcast::create_mutex(void)
+void *OSystem_Dreamcast::create_mutex()
 {
   return NULL;
 }
@@ -142,7 +142,7 @@ void OSystem_Dreamcast::delete_mutex(void *mutex)
 }
 
 
-void dc_init_hardware(void)
+void dc_init_hardware()
 {
 #ifndef NOSERIAL
   serial_init(57600);

backends/gp32/gp32.cpp

@@ -685,7 +685,7 @@ void OSystem_GP32::undraw_mouse() {	//return; //fixme!
 	///SDL_UnlockSurface(sdl_tmpscreen); 
 }
 
-char * SDL_GetError(void) {
+char * SDL_GetError() {
 
 	// implement
 	return NULL;
@@ -860,7 +860,7 @@ void OSystem_GP32::delay_msecs(uint msecs) {
 }
 	
 // Create a thread
-void* OSystem_GP32::create_thread(ThreadProc *proc, void *param) { return NULL;}
+void OSystem_GP32::create_thread(ThreadProc *proc, void *param) { }
 	
 // Get the next event.
 // Returns true if an event was retrieved.	
@@ -1075,7 +1075,7 @@ void OSystem_GP32::update_cdrom() { }
 void OSystem_GP32::set_timer(int timer, int (*callback)(int)) { }
 
 // Mutex handling
-void* OSystem_GP32::create_mutex(void) { }
+void* OSystem_GP32::create_mutex() { }
 void OSystem_GP32::lock_mutex(void *mutex) { }
 void OSystem_GP32::unlock_mutex(void *mutex) { }
 void OSystem_GP32::delete_mutex(void *mutex) { }

backends/gp32/gp32.h

@@ -71,7 +71,7 @@ public:
 	void delay_msecs(uint msecs);
 	
 	// Create a thread
-	void *create_thread(ThreadProc *proc, void *param);
+	void create_thread(ThreadProc *proc, void *param);
 	
 	// Get the next event.
 	// Returns true if an event was retrieved.	
@@ -102,7 +102,7 @@ public:
 	void set_timer(int timer, int (*callback)(int));
 
 	// Mutex handling
-	void *create_mutex(void);
+	void *create_mutex();
 	void lock_mutex(void *mutex);
 	void unlock_mutex(void *mutex);
 	void delete_mutex(void *mutex);

backends/morphos/morphos.cpp

@@ -308,16 +308,15 @@ void OSystem_MorphOS::set_timer(int timer, int (*callback)(int))
 	warning("set_timer() unexpectedly called");
 }
 
-void *OSystem_MorphOS::create_thread(ThreadProc *proc, void *param)
+void OSystem_MorphOS::create_thread(ThreadProc *proc, void *param)
 {
 	ScummMusicThread = CreateNewProcTags(NP_Entry, (ULONG) proc, NP_CodeType, CODETYPE_PPC,
 													 NP_Name, (ULONG) "ScummVM Music Thread",
 													 NP_Priority, 60, NP_StackSize, 32000,
 													 NP_PPC_Arg1, (ULONG) param, TAG_DONE);
-	return ScummMusicThread;
 }
 
-void *OSystem_MorphOS::create_mutex(void)
+void *OSystem_MorphOS::create_mutex()
 {
 	SignalSemaphore *sem = (SignalSemaphore *) AllocVec(sizeof (SignalSemaphore), MEMF_PUBLIC);
 

backends/morphos/morphos.h

@@ -83,13 +83,13 @@ class OSystem_MorphOS : public OSystem
 		virtual void set_timer(int timer, int (*callback)(int));
 
 		// Mutex handling
-		virtual void *create_mutex(void);
+		virtual void *create_mutex();
 		virtual void lock_mutex(void *mutex);
 		virtual void unlock_mutex(void *mutex);
 		virtual void delete_mutex(void *mutex);
 
 		// Create a thread
-		virtual void *create_thread(ThreadProc *proc, void *param);
+		virtual void create_thread(ThreadProc *proc, void *param);
 
 		// Get the next event.
 		// Returns true if an event was retrieved.

backends/null/null.cpp

@@ -40,7 +40,7 @@ public:
 	void set_shake_pos(int shake_pos) {}
 	uint32 get_msecs();
 	void delay_msecs(uint msecs);
-	void *create_thread(ThreadProc *proc, void *param) { return NULL; }
+	void create_thread(ThreadProc *proc, void *param) { }
 	bool poll_event(Event *event) { return false; }
 	bool set_sound_proc(void *param, SoundProc *proc, byte sound) {}
 	void quit() { exit(1); }

backends/sdl/sdl-common.cpp

@@ -496,8 +496,8 @@ void OSystem_SDL_Common::delay_msecs(uint msecs) {
 	SDL_Delay(msecs);
 }
 
-void *OSystem_SDL_Common::create_thread(ThreadProc *proc, void *param) {
-	return SDL_CreateThread(proc, param);
+void OSystem_SDL_Common::create_thread(ThreadProc *proc, void *param) {
+	SDL_CreateThread(proc, param);
 }
 
 static int mapKey(SDLKey key, SDLMod mod, Uint16 unicode)

backends/sdl/sdl-common.h

@@ -71,7 +71,7 @@ public:
 	void delay_msecs(uint msecs);
 
 	// Create a thread
-	void *create_thread(ThreadProc *proc, void *param);
+	void create_thread(ThreadProc *proc, void *param);
 
 	// Get the next event.
 	// Returns true if an event was retrieved.	
@@ -103,7 +103,7 @@ public:
 	void set_timer(int timer, int (*callback)(int));
 
 	// Mutex handling
-	void *create_mutex(void);
+	void *create_mutex();
 	void lock_mutex(void *mutex);
 	void unlock_mutex(void *mutex);
 	void delete_mutex(void *mutex);

backends/wince/wince.cpp

@@ -71,7 +71,7 @@ typedef BOOL (*tSHCreateMenuBar)(void*);
 
 /*
 // Dynamically linked SDLAudio
-typedef void (*tSDL_AudioQuit)(void);
+typedef void (*tSDL_AudioQuit)();
 typedef int (*tSDL_Init)(Uint32);
 typedef void (*tSDL_PauseAudio)(int);
 typedef int (*tSDL_OpenAudio)(SDL_AudioSpec*, SDL_AudioSpec*);
@@ -439,7 +439,7 @@ SoundProc *real_soundproc;
 
 extern void startFindGame();
 extern void displayGameInfo();
-extern bool loadGameSettings(void);
+extern bool loadGameSettings();
 extern void setFindGameDlgHandle(HWND);
 extern void getSelectedGame(int, char*, TCHAR*, char*);
 extern void runGame(char*);
@@ -448,7 +448,7 @@ extern void palette_update();
 
 extern void own_soundProc(void *buffer, byte *samples, int len);
 
-extern int chooseGame(void);
+extern int chooseGame();
 
 //#define SHMenuBar_GetMenu(hWndMB,ID_MENU) (HMENU)SendMessage((hWndMB), SHCMBM_GETSUBMENU, (WPARAM)0, (LPARAM)ID_MENU)
 
@@ -1623,12 +1623,11 @@ void OSystem_WINCE3::delay_msecs(uint msecs) {
 	Sleep(msecs);
 }
 	
-void *OSystem_WINCE3::create_thread(ThreadProc *proc, void *param) {
+void OSystem_WINCE3::create_thread(ThreadProc *proc, void *param) {
 	// needed for emulated MIDI support (Sam'n'Max)
 	HANDLE handle;
 	handle = CreateThread(NULL, 0, (LPTHREAD_START_ROUTINE)proc, param, 0, NULL);
 	SetThreadPriority(handle, THREAD_PRIORITY_NORMAL);
-	return handle;
 }
 
 int mapKey(int key, byte mod)

backends/wince/wince.h

@@ -109,7 +109,7 @@ public:
 	void delay_msecs(uint msecs);
 	
 	// Create a thread
-	void *create_thread(ThreadProc *proc, void *param);
+	void create_thread(ThreadProc *proc, void *param);
 	
 	// Get the next event.
 	// Returns true if an event was retrieved.	

backends/x11/x11.cpp

@@ -89,7 +89,7 @@ public:
 	void delay_msecs(uint msecs);
 
 	// Create a thread
-	void *create_thread(ThreadProc *proc, void *param);
+	void create_thread(ThreadProc *proc, void *param);
 
 	// Get the next event.
 	// Returns true if an event was retrieved.  
@@ -121,7 +121,7 @@ public:
 	void set_timer(int timer, int (*callback) (int));
 
 	// Mutex handling
-	void *create_mutex(void);
+	void *create_mutex();
 	void lock_mutex(void *mutex);
 	void unlock_mutex(void *mutex);
 	void delete_mutex(void *mutex);
@@ -302,7 +302,7 @@ void OSystem_X11::create_empty_cursor()
 	XDefineCursor(display, window, cursor);
 }
 
-OSystem *OSystem_X11_create(void)
+OSystem *OSystem_X11_create()
 {
 	return OSystem_X11::create(0, 0);
 }
@@ -765,7 +765,7 @@ void OSystem_X11::set_shake_pos(int shake_pos)
 	new_shake_pos = shake_pos;
 }
 
-void *OSystem_X11::create_thread(ThreadProc *proc, void *param)
+void OSystem_X11::create_thread(ThreadProc *proc, void *param)
 {
 	pthread_t *thread = (pthread_t *) malloc(sizeof(pthread_t));
 	if (pthread_create(thread, NULL, (void *(*)(void *))proc, param))
@@ -1029,7 +1029,7 @@ void OSystem_X11::set_timer(int timer, int (*callback) (int))
 	}
 }
 
-void *OSystem_X11::create_mutex(void)
+void *OSystem_X11::create_mutex()
 {
 	pthread_mutex_t *mutex = (pthread_mutex_t *) malloc(sizeof(pthread_mutex_t));
 	pthread_mutex_init(mutex, NULL);

common/system.h

@@ -26,26 +26,20 @@
 #include "scummsys.h"
 #include "savefile.h"
 
-// Interface to the ScummVM backend
-
+/**
+ * Interface for ScummVM backends.
+ */
 class OSystem {
 public:
+	typedef void *MutexRef;
 	typedef int ThreadProc(void *param);
 	typedef void SoundProc(void *param, byte *buf, int len);
 
-	struct Event {
-		int event_code;
-		struct {
-			uint16 ascii;
-			byte flags;
-			int keycode;
-		} kbd;
-		struct {
-			int x,y;
-		} mouse;
-	};
-
-	enum {
+	/**
+	 * The types of events backends can generate.
+	 * @see Event
+	 */
+	enum EventCode {
 		EVENT_KEYDOWN = 1,
 		EVENT_KEYUP = 2,
 		EVENT_MOUSEMOVE = 3,
@@ -63,6 +57,23 @@ public:
 		KBD_SHIFT = 4
 	};
 
+	/**
+	 * Data structure for an event. A pointer to an instance of Event
+	 * can be passed to poll_event. 
+	 */
+	struct Event {
+		EventCode event_code;
+		struct {
+			int keycode;
+			uint16 ascii;
+			byte flags;
+		} kbd;
+		struct {
+			int x;
+			int y;
+		} mouse;
+	};
+
 	enum {
 		PROP_TOGGLE_FULLSCREEN = 1,
 		PROP_SET_WINDOW_CAPTION = 2,
@@ -86,49 +97,77 @@ public:
 		SOUND_16BIT = 1
 	};
 	
-	// Set colors of the palette
+	/** Set colors of the palette. */
 	virtual void set_palette(const byte *colors, uint start, uint num) = 0;
 
-	// Set the size of the video bitmap.
-	// Typically, 320x200
+	/** Set the size of the video bitmap. Typically 320x200 pixels. */
 	virtual void init_size(uint w, uint h) = 0;
 
-	// Draw a bitmap to screen.
-	// The screen will not be updated to reflect the new bitmap
+	/**
+	 * 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.
+	 * @see update_screen
+	 */
 	virtual void copy_rect(const byte *buf, int pitch, int x, int y, int w, int h) = 0;
 
-	// Moves the screen content around by the given amount of pixels
-	// but only the top height pixel rows, the rest stays untouched
+	/**
+	 * Moves the screen content by the offset specified via dx/dy.
+	 * Only the region from x=0 till x=height-1 is affected.
+	 * @param dx	the horizontal offset.
+	 * @param dy	the vertical offset.
+	 * @param height	the number of lines which in which the move will be done.
+	 */
 	virtual void move_screen(int dx, int dy, int height) = 0;
 
-	// Update the dirty areas of the screen
+	/** Update the dirty areas of the screen. */
 	virtual void update_screen() = 0;
 
-	// Either show or hide the mouse cursor
+	/** Show or hide the mouse cursor. */
 	virtual bool show_mouse(bool visible) = 0;
 	
-	// Set the position of the mouse cursor
+	/**
+	 * Set the position of the mouse cursor.
+	 * @see warp_mouse
+	 */
 	virtual void set_mouse_pos(int x, int y) = 0;
 
-	// Warp the mouse cursor. Where set_mouse_pos() only informs the
-	// backend of the mouse cursor's current position, this function
-	// actually moves the cursor to the specified position.
+	/** 
+	 * Warp the mouse cursor to the specified position. Where set_mouse_pos()
+	 * only informs the backend of the mouse cursor's current position, this
+	 * function actually moves the cursor to the specified position.
+	 * @see set_mouse_pos
+	 */
 	virtual void warp_mouse(int x, int y) = 0;
 	
-	// Set the bitmap that's used when drawing the cursor.
+	/** 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;
 	
-	// Shaking is used in SCUMM. Set current shake position.
-	virtual void set_shake_pos(int shake_pos) = 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;
 		
-	// Get the number of milliseconds since the program was started.
+	/** Get the number of milliseconds since the program was started. */
 	virtual uint32 get_msecs() = 0;
 	
-	// Delay for a specified amount of milliseconds
+	/** Delay/sleep for the specified amount of milliseconds. */
 	virtual void delay_msecs(uint msecs) = 0;
 	
-	// Create a thread
-	virtual void *create_thread(ThreadProc *proc, void *param) = 0;
+	/**
+	 * 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.
+	 * @return 
+	 */
+	virtual void create_thread(ThreadProc *proc, void *param) = 0;
 	
 	// Get the next event.
 	// Returns true if an event was retrieved.	
@@ -142,37 +181,87 @@ public:
 	// Get or set a property
 	virtual uint32 property(int param, Property *value) = 0;
 		
-	// Poll cdrom status
-	// Returns true if cd audio is playing
+
+	/**
+	 * @name Audio CD
+	 * The methods in this group deal with Audio CD playback.
+	 */
+	//@{
+
+	/**
+	 * Poll CD status
+	 * @return true if CD audio is playing
+	 */
 	virtual bool poll_cdrom() = 0;
 
-	// Play cdrom audio track
+	/**
+	 * Start audio CD playback. 
+	 * @param track			the track to play.
+	 * @param num_loops		how often playback should be repeated (-1 = infinitely often).
+	 * @param start_frame	the frame at which playback should start.
+	 * @param end_frame		the frame at which playback should end.
+	 */
 	virtual void play_cdrom(int track, int num_loops, int start_frame, int end_frame) = 0;
 
-	// Stop cdrom audio track
+	/**
+	// Stop audio CD playback
+	 */
 	virtual void stop_cdrom() = 0;
 
+	/**
 	// Update cdrom audio status
+	 */
 	virtual void update_cdrom() = 0;
+	//@} 
+
 
 	// Add a new callback timer
 	virtual void set_timer(int timer, int (*callback)(int)) = 0;
 
-	// Mutex handling
-	virtual void *create_mutex(void) = 0;
-	virtual void lock_mutex(void *mutex) = 0;
-	virtual void unlock_mutex(void *mutex) = 0;
-	virtual void delete_mutex(void *mutex) = 0;
+	/**
+	 * @name Mutex handling
+	 */
+	//@{
+	/**
+	 * Create a new mutex.
+	 * @return the newly created mutex, or 0 if an error occured.
+	 */
+	virtual MutexRef create_mutex(void) = 0;
+
+	/**
+	 * Lock the given mutex.
+	 * @param mutex	the mutex to lock.
+	 */
+	virtual void lock_mutex(MutexRef mutex) = 0;
+
+	/**
+	 * Unlock the given mutex.
+	 * @param mutex	the mutex to unlock.
+	 */
+	virtual void unlock_mutex(MutexRef mutex) = 0;
+
+	/**
+	 * Delete the given mutex. Make sure the mutex is unlocked before you delete it.
+	 * If you delete a locked mutex, the behavior is undefined, in particular, your
+	 * program may crash.
+	 * @param mutex	the mutex to delete.
+	 */
+	virtual void delete_mutex(MutexRef mutex) = 0;
+	//@} 
 
 	// Quit
 	virtual void quit() = 0;
 	
-	// Overlay
+	/**
+	 * @name Overlay
+	 */
+	//@{
 	virtual void show_overlay() = 0;
 	virtual void hide_overlay() = 0;
 	virtual void clear_overlay() = 0;
 	virtual void grab_overlay(NewGuiColor *buf, int pitch) = 0;
 	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;}
@@ -195,11 +284,9 @@ public:
 	}
 };
 
-/* Factory functions. This means we don't have to include the
- * OSystem_SDL header file. (which in turn would require the SDL headers)
+/* Factory functions. This means we don't have to include the headers for
+ * all backends.
  */
-
-/* OSystem_SDL */
 extern OSystem *OSystem_SDL_create(int gfx_driver, bool full_screen);
 extern OSystem *OSystem_NULL_create();
 extern OSystem *OSystem_MorphOS_create(int game_id, int gfx_driver, bool full_screen);

scumm/scummvm.cpp

@@ -2155,6 +2155,9 @@ void Scumm::parseEvents() {
 		case OSystem::EVENT_RBUTTONUP:
 			_rightBtnPressed &= ~msDown;
 			break;
+		
+		default:
+			break;
 		}
 	}
 }

simon/simon.cpp

@@ -4498,6 +4498,9 @@ void SimonState::delay(uint amount) {
 					else
 					_exit_cutscene = true;
 					break;
+				
+				default:
+					break;
 			}
 		}
 

sky/sky.cpp

@@ -298,6 +298,9 @@ void SkyState::delay(uint amount) { //copied and mutilated from Simon.cpp
 				case OSystem::EVENT_RBUTTONDOWN:
 					
 					break;
+
+				default:
+					break;
 			}
 		}