This is a scratch pad for the Shaped Windows Google Summer of Code 2010 project, by Eli Gottlieb
The code is available here: --( http://hg.libsdl.org/SDL/gsoc2010_shaped_windows )--
GSoC code submitted and merged with 1.3 branch.
The actual API itself is simple. SDL_CreateShapedWindow() returns an SDL_Window with the correct attributes and the capability to be shaped. From there, the user can either check if any particular window is a shaped window via a predicate function, or they can set the shape of a window by passing a shape surface with an alpha channel into SDL_SetWindowShape(). This function also accepts a structure of mode parameters, which are currently used to specify the cutoff value for the shape's alpha channel. At or above that cutoff value, a pixel is visible in the shape. Below that, it's not part of the shape.
Possible pre-processing pipelines:
input shape bitmap stored as surface or texture -(1)-> SDL rendering-from-texture function -(2)-> possible region-queue or mask bitmap -(3)-> render target associated with window shape is presented -(4)-> driver-specific shape-setting functions
1. Two-valued alpha channel determines shape.
1. possibly optional, some drivers' internal representations of shapes may be close enough to be used in place of an abstract data structure
1. user signals that they are finished drawing the window shape
1. driver-independent abstract data structure such as mask or region queue is converted to driver-specific data and the window shape is actually changed.
Currently figuring out how to link to the shape extension.
Most commonly used is code that essentially sets a "region" which defines which pixels are shown and which are not. Most algorithms uses the Win32 region functions to compose this shape which is simple but works. In any case, the input to this process is a binarized (1bit) image. Note that you don't get any "blending" on the edges with this approach.
Here some other sample code:
Now there is another way to provide transparency using an alpha-bitmap in Windows. The API to be used is the UpdateLayeredWindow() call:
Even with this approach a shape vector may still be important, to get rid of clicks to the window - a window that is almost transparent (i.e. alpha=1) seems to have no shape, but will still receive clicks on those pixels. Note also, that the layered window API is not supported on WinCE (but the shape API is).
The OnPaint functions makes the background transparent by drawing black on it.
If Cocoa also uses also a shape, it may be good to break out a common "2D shape calculation" algorithm that applies to both architectures.
Note that a shape structure made out of regions has a list of 2D points defining a polygon AND a add/delete flag. For example a doughnut is made of two circle regions, one added and one deleted.