From b51f2f3212ae8a5abbdce4d947ec2d1cad1a0b6f Mon Sep 17 00:00:00 2001
From: Max Horn
Date: Tue, 19 Jun 2007 22:39:59 +0000
Subject: 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
---
 common/system.h | 29 +++++++++++++++++++++--------
 1 file changed, 21 insertions(+), 8 deletions(-)

(limited to 'common/system.h')

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;
 
 	/**
-- 
cgit v1.2.3