- 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

1 files changed, 5 insertions, 3 deletions

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;