- Adapt documentation, that keycolor in setMouseCursor may not exceed the maximum color value of the specified format.

- Change SDL backend to assert out on invalid keycolor values

In case we really need a way to specify "no keycolor" we need to
discuss on how to do it *properly*.

svn-id: r47123

3 files changed, 13 insertions, 7 deletions

diff --git a/backends/platform/sdl/graphics.cpp b/backends/platform/sdl/graphics.cpp
index e02e2f0d1d..ce3647d6fb 100644
--- a/backends/platform/sdl/graphics.cpp
+++ b/backends/platform/sdl/graphics.cpp
@@ -1490,9 +1490,11 @@ void OSystem_SDL::setMouseCursor(const byte *buf, uint w, uint h, int hotspot_x,
 		_cursorFormat = Graphics::PixelFormat::createFormatCLUT8();
 	else if (format->bytesPerPixel <= _screenFormat.bytesPerPixel)
 		_cursorFormat = *format;
-	keycolor &= (1 << (_cursorFormat.bytesPerPixel << 3)) - 1;
+
+	if (_cursorFormat.bytesPerPixel < 4)
+		assert(keycolor < (uint)(1 << (_cursorFormat.bytesPerPixel << 3)));
 #else
-	keycolor &= 0xFF;
+	assert(keycolor <= 0xFF);
 #endif
 
 	if (w == 0 || h == 0)
diff --git a/common/system.h b/common/system.h
index 1e1ee5d886..9b136fde35 100644
--- a/common/system.h
+++ b/common/system.h
@@ -770,14 +770,16 @@ public:
 	/**
 	 * Set the bitmap used for drawing the cursor.
 	 *
-	 * @param buf				the pixmap data to be used (8bit/pixel)
+	 * @param buf				the pixmap data to be used
 	 * @param w					width of the mouse cursor
 	 * @param h					height of the mouse cursor
 	 * @param hotspotX			horizontal offset from the left side to the hotspot
 	 * @param hotspotY			vertical offset from the top side to the hotspot
-	 * @param keycolor			transparency color index
+	 * @param keycolor			transparency color value. This should not exceed the maximum color value of the specified format.
+	 *                          In case it does the behavior is undefined. The backend might just error out or simply ignore the
+	 *                          value. (The SDL backend will just assert to prevent abuse of this).
 	 * @param cursorTargetScale	scale factor which cursor is designed for
-	 * @param format			pointer to the pixel format which cursor graphic uses
+	 * @param format			pointer to the pixel format which cursor graphic uses (0 means screen format)
 	 */
 	virtual void setMouseCursor(const byte *buf, uint w, uint h, int hotspotX, int hotspotY, uint32 keycolor, int cursorTargetScale = 1, const Graphics::PixelFormat *format = NULL) = 0;
 
diff --git a/graphics/cursorman.h b/graphics/cursorman.h
index e0f9fcda2d..6b84be9f60 100644
--- a/graphics/cursorman.h
+++ b/graphics/cursorman.h
@@ -64,7 +64,8 @@ public:
 	 * @param h			the height
 	 * @param hotspotX	the hotspot X coordinate
 	 * @param hotspotY	the hotspot Y coordinate
-	 * @param keycolor	the index for the transparent color
+	 * @param keycolor	the color value for the transparent color. This may not exceed
+	 *                  the maximum color value as defined by format.
 	 * @param targetScale	the scale for which the cursor is designed
 	 * @param format	a pointer to the pixel format which the cursor graphic uses, 
 	 *					CLUT8 will be used if this is NULL or not specified.
@@ -90,7 +91,8 @@ public:
 	 * @param h		the height
 	 * @param hotspotX	the hotspot X coordinate
 	 * @param hotspotY	the hotspot Y coordinate
-	 * @param keycolor	the index for the transparent color
+	 * @param keycolor	the color value for the transparent color. This may not exceed
+	 *                  the maximum color value as defined by format.
 	 * @param targetScale	the scale for which the cursor is designed
 	 * @param format	a pointer to the pixel format which the cursor graphic uses,
 	 *					CLUT8 will be used if this is NULL or not specified.