From d7e4ebaa9c08a33f5cfc56c9c30f3b916e7f566a Mon Sep 17 00:00:00 2001
From: Eli Gottlieb <eligottlieb@gmail.com>
Date: Thu, 10 Jun 2010 17:37:19 -0400
Subject: [PATCH] Stubbed out the new get/set parameter functions, added the
 start of the enum, union, and struct for those parameters themselves, and
 added doxygen comments throughout the SDL_shape.h header.

---
 include/SDL_shape.h   | 68 +++++++++++++++++++++++++++++++++++++++++++
 src/video/SDL_shape.c | 14 +++++++++
 2 files changed, 82 insertions(+)

diff --git a/include/SDL_shape.h b/include/SDL_shape.h
index 4d032ae0f..01f4aa454 100644
--- a/include/SDL_shape.h
+++ b/include/SDL_shape.h
@@ -59,9 +59,77 @@ extern "C" {
  */
 extern DECLSPEC SDL_Window * SDLCALL SDL_CreateShapedWindow(const char *title,unsigned int x,unsigned int y,unsigned int w,unsigned int h,Uint32 flags);
 
+/**
+ * \brief Return whether the given window is a shaped window. 
+ *
+ * \param window The window to query for being shaped.
+ *
+ * \return SDL_TRUE if the window is a shaped window and SDL_FALSE otherwise.
+ * \sa SDL_CreateShapedWindow
+ */
 extern DECLSPEC SDL_bool SDLCALL SDL_WindowIsShaped(const SDL_Window *window);
+
+/**
+ * \brief Select the shape of a given window as a rendering target.
+ *
+ * \param window The window whose shape should become the current rendering target.
+ *
+ * \return 0 on success, -1 if something other than a valid shaped window is passed into \c window.
+ *
+ * The shape of the window given in \c window is selected as the new render target, and in the default mode (see
+ * SDL_WindowShapeParams) the alpha channel of that render target determines which pixels of the window are part of its
+ * visible shape and which are not according to a cutoff value.  All normal SDL rendering functions can be used on it,
+ * and its own specific parameters can be examined and set with SDL_GetShapeParameters() and SDL_SetShapeParameters().
+ * The final shape will be computed and the actual appearance of the window changed only upon a call to
+ * SDL_RenderPresent().
+ *
+ * \sa SDL_GetShapeParameters
+ * \sa SDL_SetShapeParameters
+ * \sa SDL_RenderPresent
+ */
 extern DECLSPEC int SDLCALL SDL_SelectShapeRenderer(const SDL_Window *window);
 
+/** \brief An enum denoting the specific type of contents present in an SDL_WindowShapeParams union. */
+typedef enum {ShapeModeDefault, ShapeModeBinarizeAlpha} WindowShapeMode;
+/** \brief A union containing parameters for shaped windows. */
+typedef union {
+	/** \brief a cutoff alpha value for binarization of the window shape's alpha channel. */
+	Uint8 binarizationCutoff;
+} SDL_WindowShapeParams;
+
+/** \brief A struct that tags the SDL_WindowShapeParams union with an enum describing the type of its contents. */
+typedef struct SDL_WindowShapeMode {
+	WindowShapeMode mode;
+	SDL_WindowShapeParams parameters;
+} SDL_WindowShapeMode;
+
+/**
+ * \brief Set the shape parameters of a shaped window.
+ *
+ * \param window The shaped window whose parameters should be set.
+ * \param shapeMode The parameters to set for the shaped window.
+ *
+ * \return 0 on success, -1 on invalid parameters in the shapeMode argument, or -2 if the SDL_Window given is not a
+ *         shaped window.
+ *
+ * \sa SDL_WindowShapeMode
+ * \sa SDL_GetShapeParameters
+ */
+extern DECLSPEC int SDLCALL SDL_SetShapeParameters(SDL_Window *window,SDL_WindowShapeMode shapeMode);
+
+/**
+ * \brief Set the shape parameters of a shaped window.
+ *
+ * \param window The shaped window whose parameters should be retrieved.
+ * \param shapeMode An empty shape-parameters structure to fill.
+ *
+ * \return 0 on success, -1 on a null shapeMode, or -2 if the SDL_Window given is not a shaped window.
+ *
+ * \sa SDL_WindowShapeMode
+ * \sa SDL_SetShapeParameters
+ */
+extern DECLSPEC int SDLCALL SDL_GetShapeParameters(SDL_Window *window,SDL_WindowShapeMode *shapeMode);
+
 /* Ends C function definitions when using C++ */
 #ifdef __cplusplus
 /* *INDENT-OFF* */
diff --git a/src/video/SDL_shape.c b/src/video/SDL_shape.c
index 6df038dca..bfc826880 100644
--- a/src/video/SDL_shape.c
+++ b/src/video/SDL_shape.c
@@ -37,3 +37,17 @@ SDL_bool SDL_WindowIsShaped(const SDL_Window *window) {
 int SDL_SelectShapeRenderer(const SDL_Window *window) {
 	return -1;
 }
+
+int SDL_SetShapeParameters(SDL_Window *window,SDL_WindowShapeMode shapeMode) {
+	if(window == NULL || !SDL_WindowIsShaped(window))
+		return -2;
+	return -3;
+}
+
+int SDL_GetShapeParameters(SDL_Window *window,SDL_WindowShapeMode *shapeMode) {
+	if(shapeMode == NULL)
+		return -1;
+	if(window == NULL || !SDL_WindowIsShaped(window))
+		return -2;
+	return -3;
+}