|
Size: 3055
Comment: Fix some syntax
|
Size: 5235
Comment: Documenting API proposal
|
| Deletions are marked like this. | Additions are marked like this. |
| Line 3: | Line 3: |
| The code is available here: http://hg.libsdl.org/SDL-gsoc2010_shaped_windows |
The code is available here: http://hg.libsdl.org/SDL-gsoc2010_shaped_windows |
| Line 9: | Line 8: |
| Wrote a test program SDL_eyes and integrated it into the SDL testing framework. Time to discuss and verify the API. | |
| Line 11: | Line 11: |
| The actual API itself is simple. SDL_[[CreateShapedWindow|!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 select the shape of a shaped window as a rendering target. Once the shape of a window has been selected, rendering to it works like rendering to any other rendering target, though the internal representation used for the shape is platform-specific. The thing to note, for users, is that whether a rendered shape is "positive" space (part of the visible window) or "negative" space (transparent) is dependent on its alpha channel. An alpha value of 0 makes a shape or pixel transparent. An non-zero alpha value makes a shape or pixel positive space. The "z-value" of space rendered to a window's shape is determined according to the Painter's Algorithm. To demonstrate by example, if the user wants to draw a donut shape, they should first render a circle of positive space and then a smaller circle of negative space within it. In my view, this is intuitive for users experienced in 2D graphics programming and allows drivers whose shaped-window implementations use vector shapes a convenient ordering by which to determine how different regions of space overlap. I actually want to add a few extra drawing functions to the SDL rendering API for circles, ellipses, and polygons. I'm going to add those to SDL_video.h before submitting my proposed API in full When the user is finished drawing the shape of a window using the rendering functions, they simply call SDL_!RenderPresent() on that same rendering target to actually |
|
| Line 13: | Line 20: |
| === Pre-Processing === Possible pre-processing pipelines: |
|
| Line 14: | Line 23: |
| === Pre-Processing === | 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 |
| Line 16: | Line 25: |
| Possible pre-processing pipeline: input_mask surface -(1)-> 8bit alpha -(2)-> 1bit mask -(3)-> 2D region -(4)-> arch specific set shape 1. some setting may be needed for this step, like a key color 1. optional, may be enabled via a mode or when architecture needs it 1. optional, depends on architecture requirements 1. this internal function can receive pointers to all the above and use what it needs |
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. |
| Line 26: | Line 31: |
| Line 34: | Line 38: |
| Line 36: | Line 39: |
| Line 40: | Line 42: |
| Line 47: | Line 50: |
| Now there is another way to provide transparency using an alpha-bitmap in Windows. The API to be used is the UpdateLayeredWindow() call: | |
| Line 48: | Line 52: |
| Now there is another way to provide transparency using an alpha-bitmap in Windows. The API to be used is the UpdateLayeredWindow() call: * MSDN info: http://msdn.microsoft.com/en-us/library/ms633556%28VS.85%29.aspx |
* MSDN info: [[http://msdn.microsoft.com/en-us/library/ms633556(VS.85).aspx|http://msdn.microsoft.com/en-us/library/ms633556%28VS.85%29.aspx]] |
| Line 55: | Line 58: |
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. |
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. |
| Line 59: | Line 61: |
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
Contents
Status
Wrote a test program SDL_eyes and integrated it into the SDL testing framework. Time to discuss and verify the API.
Documentation
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 select the shape of a shaped window as a rendering target. Once the shape of a window has been selected, rendering to it works like rendering to any other rendering target, though the internal representation used for the shape is platform-specific. The thing to note, for users, is that whether a rendered shape is "positive" space (part of the visible window) or "negative" space (transparent) is dependent on its alpha channel. An alpha value of 0 makes a shape or pixel transparent. An non-zero alpha value makes a shape or pixel positive space.
The "z-value" of space rendered to a window's shape is determined according to the Painter's Algorithm. To demonstrate by example, if the user wants to draw a donut shape, they should first render a circle of positive space and then a smaller circle of negative space within it. In my view, this is intuitive for users experienced in 2D graphics programming and allows drivers whose shaped-window implementations use vector shapes a convenient ordering by which to determine how different regions of space overlap.
I actually want to add a few extra drawing functions to the SDL rendering API for circles, ellipses, and polygons. I'm going to add those to SDL_video.h before submitting my proposed API in full
When the user is finished drawing the shape of a window using the rendering functions, they simply call SDL_RenderPresent() on that same rendering target to actually
Notes
Pre-Processing
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
- Two-valued alpha channel determines shape.
- possibly optional, some drivers' internal representations of shapes may be close enough to be used in place of an abstract data structure
- user signals that they are finished drawing the window shape
- driver-independent abstract data structure such as mask or region queue is converted to driver-specific data and the window shape is actually changed.
X11
Set via the "Shape Extension" http://en.wikipedia.org/wiki/Shape_extension
Documentation with C API http://www.xfree86.org/current/shapelib.html
- If extension is missing from X, add Load "extmod" to the "Modules" section of the xorg.conf file (=makes for a good error message on shape extension detection).
Per-pixel alpha for window-shapes require support from a "compositing window manager".
Windows
Regions
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:
Sets shape by generating regions: http://comrade.ownz.com/docs/shapewnd.html
Shape of Form by using background key color: http://msdn.microsoft.com/en-us/beginner/cc963986.aspx
Setting per-Window alpha: http://msdn.microsoft.com/en-us/beginner/cc963986.aspx
Form app in .Net calling the Win32 Api: http://www.codeproject.com/KB/miscctrl/AlphaForm.aspx
Great summary with examples for all modes in Delphi: http://melander.dk/articles/alphasplash/
Layered Window
Now there is another way to provide transparency using an alpha-bitmap in Windows. The API to be used is the UpdateLayeredWindow() call:
MSDN info: http://msdn.microsoft.com/en-us/library/ms633556%28VS.85%29.aspx
Sample code: http://www.nuonsoft.com/blog/2009/05/27/how-to-use-updatelayeredwindow/
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).
OSX
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.
Shape Regions
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.
