COMMON: OSystem now has a PaletteManager

svn-id: r55806

1 files changed, 107 insertions, 0 deletions

diff --git a/graphics/palette.h b/graphics/palette.h
new file mode 100644
index 0000000000..72db16a3d3
--- /dev/null
+++ b/graphics/palette.h
@@ -0,0 +1,107 @@
+/* ScummVM - Graphic Adventure Engine
+ *
+ * ScummVM is the legal property of its developers, whose names
+ * are too numerous to list here. Please refer to the COPYRIGHT
+ * file distributed with this source distribution.
+ *
+ * This program is free software; you can redistribute it and/or
+ * modify it under the terms of the GNU General Public License
+ * as published by the Free Software Foundation; either version 2
+ * of the License, or (at your option) any later version.
+
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ * GNU General Public License for more details.
+
+ * You should have received a copy of the GNU General Public License
+ * along with this program; if not, write to the Free Software
+ * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
+ *
+ * $URL$
+ * $Id$
+ *
+ */
+
+#ifndef GRAPHICS_PALETTE_H
+#define GRAPHICS_PALETTE_H
+
+#include "common/noncopyable.h"
+
+/**
+ * The PaletteManager is part of the OSystem backend API and responsible
+ * for handling the (possibly emulated) "hardware" palette needed for
+ * many old games (e.g. in EGA and VGA mode).
+ *
+ * By itself it is a pure abstract class, i.e. an "interface"; you can
+ * use the OSystem::getPaletteManager() method to obtain an instance
+ * that you can use to perform actual palette modifications.
+ */
+class PaletteManager : Common::NonCopyable {
+public:
+	virtual ~PaletteManager() {}
+
+	/**
+	 * 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 accomplished via start=0, num=256.
+	 *
+	 * The palette data is specified in interleaved RGBA 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 green component of the first
+	 * new color; the third byte the blue component, the last byte to the alpha
+	 * (transparency) value. Then the second color starts, and so on. So memory
+	 * looks like this: R1-G1-B1-A1-R2-G2-B2-A2-R3-...
+	 *
+	 * @param colors	the new palette data, in interleaved RGBA 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).
+	 * @note It is an error if this function gets called when the pixel format
+	 *       in use (the return value of getScreenFormat) has more than one
+	 *       byte per pixel.
+	 * @note The alpha value is not actually used, and future revisions of this
+	 *       API are probably going to remove it.
+	 *
+	 * @see getScreenFormat
+	 */
+	virtual void setPalette(const byte *colors, uint start, uint num) = 0;
+
+	/**
+	 * 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
+	 * @param num		the number of palette entries to be read
+	 *
+	 * @note It is an error if this function gets called when the pixel format
+	 *       in use (the return value of getScreenFormat) has more than one
+	 *       byte per pixel.
+	 *
+	 * @see getScreenFormat
+	 */
+	virtual void grabPalette(byte *colors, uint start, uint num) = 0;
+};
+
+#endif