From 6308dd77d69cd2f33e84cc06058e2d707a67a1b6 Mon Sep 17 00:00:00 2001
From: Johannes Schickel
Date: Mon, 20 Dec 2010 17:28:17 +0000
Subject: OSYSTEM: Clarify grabPalette documentation after talking with Max
 about it.

svn-id: r54978
---
 common/system.h | 17 +++++++++++++++++
 1 file changed, 17 insertions(+)

(limited to 'common')

diff --git a/common/system.h b/common/system.h
index 97fe582813..52fb2dbd56 100644
--- a/common/system.h
+++ b/common/system.h
@@ -548,6 +548,23 @@ public:
 	 * Grabs a specified part of the currently active palette.
 	 * The format is the same as for setPalette.
 	 *
+	 * This should return exactly the same RGB data as was setup via previous
+	 * setPalette calls.
+	 *
+	 * For example, for every valid value of start and num of the following
+	 * code:
+	 *
+	 * byte origPal[num*4];
+	 * // Setup origPal's data however you like
+	 * g_system->setPalette(origPal, start, num);
+	 * byte obtainedPal[num*4];
+	 * g_system->grabPalette(obtainedPal, start, num);
+	 *
+	 * the following should be true:
+	 *
+	 * For each i < num : memcmp(&origPal[i*4], &obtainedPal[i*4], 3) == 0
+	 * (i is an uint here)
+	 *
 	 * @see setPalette
 	 * @param colors	the palette data, in interleaved RGBA format
 	 * @param start		the first platte entry to be read
-- 
cgit v1.2.3