From e46ba2f29ff20a317e708d15dc5be904cdf005eb Mon Sep 17 00:00:00 2001
From: Max Horn
Date: Mon, 15 Mar 2004 00:45:45 +0000
Subject: Added OSystem::getDefaultGraphicsMode(); renamed
 OSystem::get_height() and get_width() to getHeight and getWidth(); augmented
 some doxygen comments in common/system.h

svn-id: r13284
---
 backends/PalmOS/Src/palm.cpp |  16 ++---
 backends/PalmOS/Src/palm.h   |   4 +-
 backends/dc/dc.h             |   4 +-
 backends/gp32/gp32.h         |   4 +-
 backends/morphos/morphos.cpp |   4 +-
 backends/morphos/morphos.h   |   4 +-
 backends/sdl/events.cpp      |   2 +-
 backends/sdl/graphics.cpp    |   8 ++-
 backends/sdl/sdl-common.h    |   5 +-
 backends/x11/x11.cpp         |   8 +--
 common/system.cpp            |  10 +---
 common/system.h              | 139 +++++++++++++++++++++++++++++++++----------
 12 files changed, 143 insertions(+), 65 deletions(-)

diff --git a/backends/PalmOS/Src/palm.cpp b/backends/PalmOS/Src/palm.cpp
index d61c7d6dee..1c4948ad9c 100644
--- a/backends/PalmOS/Src/palm.cpp
+++ b/backends/PalmOS/Src/palm.cpp
@@ -649,10 +649,10 @@ void OSystem_PALMOS::updateScreen() {
 		if (oldCol != gVars->indicator.on) {	
 			// redraw if needed
 			if (_lastKeyModifier)
-				draw1BitGfx((kDrawKeyState + _lastKeyModifier - 1), 2, get_height() + 2, true);
+				draw1BitGfx((kDrawKeyState + _lastKeyModifier - 1), 2, getHeight() + 2, true);
 			
 			if(_useNumPad)
-				draw1BitGfx(kDrawNumPad, (get_width() >> 1) - 32, get_height() + 2, true);
+				draw1BitGfx(kDrawNumPad, (getWidth() >> 1) - 32, getHeight() + 2, true);
 		}
 	}
 
@@ -1058,9 +1058,9 @@ bool OSystem_PALMOS::poll_event(Event *event) {
 					_lastKeyModifier %= 4;
 					
 					if (_lastKeyModifier)
-						draw1BitGfx((kDrawKeyState + _lastKeyModifier - 1), 2, get_height() + 2, true);
+						draw1BitGfx((kDrawKeyState + _lastKeyModifier - 1), 2, getHeight() + 2, true);
 					else
-						draw1BitGfx(kDrawKeyState, 2, get_height() + 2, false);
+						draw1BitGfx(kDrawKeyState, 2, getHeight() + 2, false);
 
 				} else {
 					byte b = 0;
@@ -1075,7 +1075,7 @@ bool OSystem_PALMOS::poll_event(Event *event) {
 					} else if (ev.data.keyDown.chr == 'n' && b == KBD_CTRL) {
 						UInt8 *scr = _screenP + _screenWidth * (_screenHeight + 2);
 						_useNumPad = !_useNumPad;
-						draw1BitGfx(kDrawNumPad, (get_width() >> 1) - 32, get_height() + 2, _useNumPad);
+						draw1BitGfx(kDrawNumPad, (getWidth() >> 1) - 32, getHeight() + 2, _useNumPad);
 
 					} else if (ev.data.keyDown.chr == 'a' && b == (KBD_CTRL|KBD_ALT)) {
 						property(PROP_TOGGLE_ASPECT_RATIO, NULL);
@@ -1089,7 +1089,7 @@ bool OSystem_PALMOS::poll_event(Event *event) {
 					
 					if (_lastKeyModifier) {
 						_lastKeyModifier = MD_NONE;
-						draw1BitGfx(kDrawKeyState, 2, get_height() + 2, false);
+						draw1BitGfx(kDrawKeyState, 2, getHeight() + 2, false);
 					}
 				}
 				return true;
@@ -1773,11 +1773,11 @@ void OSystem_PALMOS::copy_rect_overlay(const byte *buf, int pitch, int x, int y,
 }
 
 
-int16 OSystem_PALMOS::get_height() {
+int16 OSystem_PALMOS::getHeight() {
 	return _screenHeight;
 }
 
-int16 OSystem_PALMOS::get_width() {
+int16 OSystem_PALMOS::getWidth() {
 	return _screenWidth;
 }
 
diff --git a/backends/PalmOS/Src/palm.h b/backends/PalmOS/Src/palm.h
index baee772065..7e39b43862 100644
--- a/backends/PalmOS/Src/palm.h
+++ b/backends/PalmOS/Src/palm.h
@@ -146,8 +146,8 @@ public:
 	void grab_overlay(byte *buf, int pitch);
 	void copy_rect_overlay(const byte *buf, int pitch, int x, int y, int w, int h);
 
-	int16 get_width();
-	int16 get_height();
+	int16 getWidth();
+	int16 getHeight();
 	byte RGBToColor(uint8 r, uint8 g, uint8 b);
 	void ColorToRGB(byte color, uint8 &r, uint8 &g, uint8 &b);
 	// Set a parameter
diff --git a/backends/dc/dc.h b/backends/dc/dc.h
index d18c722f32..8fa314baf5 100644
--- a/backends/dc/dc.h
+++ b/backends/dc/dc.h
@@ -64,8 +64,8 @@ class OSystem_Dreamcast : public OSystem {
   // Set the size of the video bitmap.
   // Typically, 320x200
   void initSize(uint w, uint h);
-  int16 get_height() { return _screen_h; }
-  int16 get_width() { return _screen_w; }
+  int16 getHeight() { return _screen_h; }
+  int16 getWidth() { return _screen_w; }
 
   // Draw a bitmap to screen.
   // The screen will not be updated to reflect the new bitmap
diff --git a/backends/gp32/gp32.h b/backends/gp32/gp32.h
index 435072626d..6fddf3fcfd 100644
--- a/backends/gp32/gp32.h
+++ b/backends/gp32/gp32.h
@@ -40,8 +40,8 @@ public:
 	// Set the size of the video bitmap.
 	// Typically, 320x200
 	void initSize(uint w, uint h);
-	int16 get_height() { return _screenHeight; }
-	int16 get_width() { return _screenWidth; }
+	int16 getHeight() { return _screenHeight; }
+	int16 getWidth() { return _screenWidth; }
 	
 	// Draw a bitmap to screen.
 	// The screen will not be updated to reflect the new bitmap
diff --git a/backends/morphos/morphos.cpp b/backends/morphos/morphos.cpp
index 8b48e542dc..d8c00e3d4e 100644
--- a/backends/morphos/morphos.cpp
+++ b/backends/morphos/morphos.cpp
@@ -1567,12 +1567,12 @@ void OSystem_MorphOS::initSize(uint w, uint h)
 	CreateScreen(CSDSPTYPE_KEEP);
 }
 
-int16 OSystem_MorphOS::get_width()
+int16 OSystem_MorphOS::getWidth()
 {
 	return ScummScrWidth;
 }
 
-int16 OSystem_MorphOS::get_height()
+int16 OSystem_MorphOS::getHeight()
 {
 	return ScummScrHeight;
 }
diff --git a/backends/morphos/morphos.h b/backends/morphos/morphos.h
index 6ce4413641..6e606c61ff 100644
--- a/backends/morphos/morphos.h
+++ b/backends/morphos/morphos.h
@@ -75,8 +75,8 @@ class OSystem_MorphOS : public OSystem
 		virtual void clear_overlay();
 		virtual void grab_overlay(int16 *buf, int pitch);
 		virtual void copy_rect_overlay(const int16 *buf, int pitch, int x, int y, int w, int h);
-		virtual int16 get_height();
-		virtual int16 get_width();
+		virtual int16 getHeight();
+		virtual int16 getWidth();
 
 		// Get the number of milliseconds since the program was started.
 		virtual uint32 get_msecs();
diff --git a/backends/sdl/events.cpp b/backends/sdl/events.cpp
index dae18ae51d..b351db9524 100644
--- a/backends/sdl/events.cpp
+++ b/backends/sdl/events.cpp
@@ -192,7 +192,7 @@ bool OSystem_SDL::poll_event(Event *event) {
 
 			// Alt-Return toggles full screen mode				
 			if (b == KBD_ALT && ev.key.keysym.sym == SDLK_RETURN) {
-				setFeatureState(kFeatureFullscreenMode, !_full_screen);
+				setFullscreenMode(!_full_screen);
 				break;
 			}
 
diff --git a/backends/sdl/graphics.cpp b/backends/sdl/graphics.cpp
index 0c9e603220..09040f5c63 100644
--- a/backends/sdl/graphics.cpp
+++ b/backends/sdl/graphics.cpp
@@ -45,6 +45,10 @@ const OSystem::GraphicsMode *OSystem_SDL::getSupportedGraphicsModes() const {
 	return s_supportedGraphicsModes;
 }
 
+int OSystem_SDL::getDefaultGraphicsMode() const {
+	return GFX_DOUBLESIZE;
+}
+
 bool OSystem_SDL::setGraphicsMode(int mode) {
 	Common::StackLock lock(_graphicsMutex, this);
 
@@ -715,11 +719,11 @@ void OSystem_SDL::add_dirty_rgn_auto(const byte *buf) {
 	}
 }
 
-int16 OSystem_SDL::get_height() {
+int16 OSystem_SDL::getHeight() {
 	return _screenHeight;
 }
 
-int16 OSystem_SDL::get_width() {
+int16 OSystem_SDL::getWidth() {
 	return _screenWidth;
 }
 
diff --git a/backends/sdl/sdl-common.h b/backends/sdl/sdl-common.h
index c82ddb17c2..18ad04aabf 100644
--- a/backends/sdl/sdl-common.h
+++ b/backends/sdl/sdl-common.h
@@ -116,8 +116,8 @@ public:
 	virtual void clear_overlay();
 	virtual void grab_overlay(OverlayColor *buf, int pitch);
 	virtual void copy_rect_overlay(const OverlayColor *buf, int pitch, int x, int y, int w, int h);
-	virtual int16 get_height();
-	virtual int16 get_width();
+	virtual int16 getHeight();
+	virtual int16 getWidth();
 
 	// Methods that convert RGB to/from colors suitable for the overlay.
 	virtual OverlayColor RGBToColor(uint8 r, uint8 g, uint8 b);
@@ -125,6 +125,7 @@ public:
 
 
 	virtual const GraphicsMode *getSupportedGraphicsModes() const;
+	virtual int getDefaultGraphicsMode() const;
 	virtual bool setGraphicsMode(int mode);
 	virtual int getGraphicsMode() const;
 	
diff --git a/backends/x11/x11.cpp b/backends/x11/x11.cpp
index 73b0e2cce8..b48d4244eb 100644
--- a/backends/x11/x11.cpp
+++ b/backends/x11/x11.cpp
@@ -137,8 +137,8 @@ public:
 	void clear_overlay();
 	void grab_overlay(int16 *, int);
 	void copy_rect_overlay(const int16 *, int, int, int, int, int);
-	virtual int16 get_height();
-	virtual int16 get_width();
+	virtual int16 getHeight();
+	virtual int16 getWidth();
 
 
 	static OSystem *create(int gfx_mode, bool full_screen);
@@ -1106,11 +1106,11 @@ void OSystem_X11::copy_rect_overlay(const int16 *src, int pitch, int x, int y, i
 	}
 }
 
-int16 OSystem_X11::get_height() {
+int16 OSystem_X11::getHeight() {
 	return fb_height;
 }
 
-int16 OSystem_X11::get_width() {
+int16 OSystem_X11::getWidth() {
 	return fb_width;
 }
 
diff --git a/common/system.cpp b/common/system.cpp
index 9c2a178dfa..ef41f7c234 100644
--- a/common/system.cpp
+++ b/common/system.cpp
@@ -67,17 +67,13 @@ bool OSystem::setGraphicsMode(const char *name) {
 	if (!name)
 		return false;
 
-	const GraphicsMode *gm = getSupportedGraphicsModes();
-
 	// Sepcial case for the 'default' filter
 	if (!scumm_stricmp(name, "normal") || !scumm_stricmp(name, "default")) {
-#ifdef _WIN32_WCE
-		name = "1x";
-#else
-		name = "2x";
-#endif
+		return setGraphicsMode(getDefaultGraphicsMode());
 	}
 
+	const GraphicsMode *gm = getSupportedGraphicsModes();
+
 	while (gm->name) {
 		if (!scumm_stricmp(gm->name, name)) {
 			return setGraphicsMode(gm->id);
diff --git a/common/system.h b/common/system.h
index d8a9e502b6..e632d40a00 100644
--- a/common/system.h
+++ b/common/system.h
@@ -40,19 +40,20 @@
 class OSystem {
 public:
 	/**
-	 * Return a pointer to the (singleton) OSystem instance, i.e. the backend.
+	 * Returns a pointer to the (singleton) OSystem instance, i.e. the backend.
 	 * This is not a proper singleton, since OSystem is an interface, not
 	 * a real class.
+	 * @return	the pointer to the singleton) OSystem instance
 	 */
 	static OSystem *instance();
 
 public:
 
-	/** Virtual destructor */
+	/** Empty virtual destructor. DO NOT REMOVE! */
 	virtual ~OSystem() {}
 
 	
-	/** @name Graphics */
+	/** @name Feature flags */
 	//@{
 	
 	/**
@@ -127,9 +128,26 @@ public:
 	/** @name Graphics */
 	//@{
 
+	/**
+	 * Description of a graphics mode.
+	 */
 	struct GraphicsMode {
+		/**
+		 * The 'name' of the graphics mode. This name is matched when selecting
+		 * a mode via the command line, or via the config file.
+		 * Examples: "1x", "advmame2x", "hq3x"
+		 */
 		const char *name;
+		/**
+		 * Human readable description of the scaler.
+		 * Examples: "Normal (no scaling)", "AdvMAME2x", "HQ3x"
+		 */
 		const char *description;
+		/**
+		 * ID of the graphics mode. How to use this is completely up to the
+		 * backend. This value will be passed to the setGraphicsMode(int)
+		 * method by client code.
+		 */
 		int id;
 	};
 
@@ -143,6 +161,15 @@ public:
 	 */
 	virtual const GraphicsMode *getSupportedGraphicsModes() const = 0;
 	
+	/**
+	 * Return the ID of the 'default' graphics mode. What exactly this means
+	 * is up to the backend. This mode is set by the client code when no user
+	 * overrides are present (i.e. if no custom graphics mode is selected via
+	 * the command line or a config file).
+	 * @return the ID of the 'default' graphics mode
+	 */
+	virtual int getDefaultGraphicsMode() const = 0;
+	
 	/**
 	 * Switch to the specified graphics mode. If switching to the new mode
 	 * failed, this method returns false.
@@ -156,8 +183,11 @@ public:
 	 * or if switching to the new mode failed, this method returns false.
 	 * @param mode	the name of the new graphics mode
 	 * @return true if the switch was successful, false otherwise
+	 * @note This is implemented via the setGraphicsMode(int) method, as well
+	 *       as getSupportedGraphicsModes() and getDefaultGraphicsMode().
+	 *       In particular, backends do not have to overload this!
 	 */
-	virtual bool setGraphicsMode(const char *name);
+	bool setGraphicsMode(const char *name);
 
 	/**
 	 * Determine which graphics mode is currently active.
@@ -166,34 +196,59 @@ public:
 	virtual int getGraphicsMode() const = 0;
 
 	/**
-	 * Set the size of the video bitmap. Typical sizes include:
+	 * Set the size of the virtual screen. Typical sizes include:
 	 *  - 320x200 (e.g. for most SCUMM games, and Simon)
 	 *  - 320x240 (e.g. for FM-TOWN SCUMM games)
 	 *  - 640x480 (e.g. for Curse of Monkey Island)
+	 * This is the resolution for which the client code generates data;
+	 * this is not necessarily equal to the actual display size. For example,
+	 * a backend my magnify the graphics to fit on screen (see also the
+	 * GraphicsMode); stretch the data to perform aspect ratio correction;
+	 * or shrink it to fit on small screens (in cell phones).
+	 * @param width		the new virtual screen width
+	 * @param height	the new virtual screen height
 	 */
-	virtual void initSize(uint w, uint h) = 0;
+	virtual void initSize(uint width, uint height) = 0;
 
 	/**
-	 * Returns the currently set screen height.
+	 * Returns the currently set virtual screen height.
 	 * @see initSize
-	 * @return the currently set screen height
+	 * @return the currently set virtual screen height
 	 */
-	virtual int16 get_height() = 0;
+	virtual int16 getHeight() = 0;
 
 	/**
-	 * Returns the currently set screen width.
+	 * Returns the currently set virtual screen width.
 	 * @see initSize
-	 * @return the currently set screen width
+	 * @return the currently set virtual screen width
 	 */
-	virtual int16 get_width() = 0;
+	virtual int16 getWidth() = 0;
 
-	/** Set colors of the palette. */
+	/**
+	 * Replace the specified range of the palette with new colors.
+	 * The palette entries from 'start' till (start+num-1) will be replaced - so
+	 * a full palette update is acomplished via start=0, num=256.
+	 * The palette data is specified in interleaved RGB format. That is, the
+	 * first byte of the memory block 'colors' points at is the red component
+	 * of the first new color; the second byte the blue component of the first
+	 * new color; the third byte the green compont. Then the second color
+	 * starts, and so on. So memory looks like this: R1-G1-B1-R2-G2-B2-R3-...
+	 *
+	 * @param colors	the new colors, in interleaved RGB format
+	 * @param start		the first palette entry to be updated
+	 * @param num		the number of palette entries to be updated
+	 *
+	 * @note It is an error if start+num exceeds 256, behaviour is undefined
+	 *       in that case (the backend may ignore it silently or assert).
+	 */
 	virtual void setPalette(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 updateScreen to do that.
+	 * Blit a bitmap to the virtual screen.
+	 * The real screen will not immediately be updated to reflect the changes.
+	 * Client code has to to call updateScreen to ensure any changes are
+	 * visible to the user. This can be used to optimize drawing and reduce
+	 * flicker.
 	 * @see updateScreen
 	 */
 	virtual void copy_rect(const byte *buf, int pitch, int x, int y, int w, int h) = 0;
@@ -240,7 +295,7 @@ public:
 	virtual bool show_mouse(bool visible) = 0;
 
 	/** 
-	 * Move ("warp) the mouse cursor to the specified position.
+	 * Move ("warp") the mouse cursor to the specified position.
 	 */
 	virtual void warp_mouse(int x, int y) = 0;
 
@@ -255,7 +310,7 @@ public:
 	typedef int (*TimerProc)(int interval);
 
 	/**
-	 * The types of events backends can generate.
+	 * The types of events backends may generate.
 	 * @see Event
 	 */
 	enum EventCode {
@@ -285,32 +340,54 @@ public:
 	 */
 	struct Event {
 		EventCode event_code;
+		/**
+		  * Keyboard data; only valid for keyboard events (i.e. EVENT_KEYDOWN
+		  * and EVENT_KEYUP). For all other event types, content is undefined.
+		  */
 		struct {
+			/**
+			 * Abstract key code (will be the same for any given key regardless
+			 * of modifiers being held at the same time.
+			 * @todo Document which values are to be used for non-ASCII keys
+			 * like F1-F10.
+			 * For example, this is the same for both 'A' and Shift-'A'.
+			 */
 			int keycode;
+			/**
+			 * ASCII-value of the pressed key (if any). 
+			 * This depends on modifiers, i.e. pressing the 'A' key results in
+			 * different values here depending on the status of shift, alt and
+			 * caps lock.
+			 */
 			uint16 ascii;
+			/**
+			 * Status of the modifier keys. Bits are set in this for each 
+			 * pressed modifier
+			 * @see KBD_CTRL, KBD_ALT, KBD_SHIFT
+			 */
 			byte flags;
 		} kbd;
-		struct {
-			int x;
-			int y;
-		} mouse;
+		Common::Point mouse;
 	};
 
+	/**
+	 * 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;
+
 	/** Get the number of milliseconds since the program was started. */
 	virtual uint32 get_msecs() = 0;
 
 	/** Delay/sleep for the specified amount of milliseconds. */
 	virtual void delay_msecs(uint msecs) = 0;
 
-	/** Set the timer callback. */
-	virtual void set_timer(TimerProc callback, int interval) = 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.
+	 * Set the timer callback.
+	 * @see Common::Timer
 	 */
-	virtual bool poll_event(Event *event) = 0;
+	virtual void set_timer(TimerProc callback, int interval) = 0;
 
 	//@}
 
@@ -427,8 +504,8 @@ public:
 	virtual void clear_overlay() = 0;
 	virtual void grab_overlay(OverlayColor *buf, int pitch) = 0;
 	virtual void copy_rect_overlay(const OverlayColor *buf, int pitch, int x, int y, int w, int h) = 0;
-	virtual int16 get_overlay_height()	{ return get_height(); }
-	virtual int16 get_overlay_width()	{ return get_width(); }
+	virtual int16 get_overlay_height()	{ return getHeight(); }
+	virtual int16 get_overlay_width()	{ return getWidth(); }
 
 	/** Convert the given RGB triplet into a OverlayColor. A OverlayColor can be
 	 * 8bit, 16bit or 32bit, depending on the target system. The default
-- 
cgit v1.2.3