Implemented the OSystem framebuffer API, as discussed on scummvm-devel. All changes are just fine, and won't cause any compile problems or regressions, despite the fact that I can't test most of the non-SDL backend changes, at an improbability level of two to the power of two hundred and seventy-six thousand to one against - possibly much higher. Anything you still can't cope with is therefore your own problem. Please relax.

svn-id: r27548

2 files changed, 26 insertions, 8 deletions

diff --git a/common/system.cpp b/common/system.cpp
index 2720a19775..f8068d41f5 100644
--- a/common/system.cpp
+++ b/common/system.cpp
@@ -101,3 +101,8 @@ Common::EventManager *OSystem::getEventManager() {
 	return s_eventManager;
 }
 
+void OSystem::clearScreen() {
+	Graphics::Surface *screen = lockScreen();
+	memset(screen->pixels, 0, screen->h * screen->pitch);
+	unlockScreen();
+}
diff --git a/common/system.h b/common/system.h
index 500056e695..a54546f233 100644
--- a/common/system.h
+++ b/common/system.h
@@ -452,21 +452,34 @@ public:
 	virtual void copyRectToScreen(const byte *buf, int pitch, int x, int y, int w, int h) = 0;
 
 	/**
-	 * Copies the current screen contents to a new surface, with the original
-	 * bit depth. This will allocate memory for the pixel data.
-	 * WARNING: surf->free() must be called by the user to avoid leaking.
+	 * Lock the active screen framebuffer and return a Graphics::Surface
+	 * representing it. The caller can then perform arbitrary graphics
+	 * transformations on the framebuffer (blitting, scrolling, etc.).
+	 * Must be followed by matching call to unlockScreen(). Calling code
+	 * should make sure to only lock the framebuffer for the briefest
+	 * periods of time possible, as the whole system is potentially stalled
+	 * while the lock is active.
+	 * Returns 0 if an error occurred. Otherwise an 8bit surface is returned.
 	 *
-	 * @param surf	the surfce to store the data in it
-	 * @return true if all went well, false if an error occured
+	 * The returned surface must *not* be deleted by the client code.
 	 */
-	virtual bool grabRawScreen(Graphics::Surface *surf) = 0;
+	virtual Graphics::Surface *lockScreen() = 0;
+
+	/**
+	 * Unlock the screen framebuffer, and mark it as dirty (i.e. during the
+	 * next updateScreen() call, the whole screen will be updated.
+	 */
+	virtual void unlockScreen() = 0;
 
 	/**
 	 * Clear the screen to black.
 	 */
-	virtual void clearScreen() {}
+	virtual void clearScreen();
 
-	/** Update the dirty areas of the screen. */
+	/**
+	 * Flush the whole screen, that is render the current content of the screen
+	 * framebuffer (resp. the dirty/changed parts of it) to the display.
+	 */
 	virtual void updateScreen() = 0;
 
 	/**