View source for KWin/Shadow

TODO: document the current shadow system

== KWin Shadows ==
The ideas for a new shadow system originated from the disadvantages of the old system. The old code shows serious bugs in conjunction with blur effect, slows down the system, is mostly obsoleted by the decoration shadows and not consistent with the overall look'n'feel. The widget style has no influence in the shadow.

=== Giving control to the Widget Style ===
The new system should give the control to the widget style. A shadow is part of the overall light model. The compositor does not know about the light model or about things like the Oxygen glow.

Nevertheless the decoration shadows should be kept and the new shadow system should only be used if the decoration does not provide shadows. The new system is therefore mostly meant for unmanaged windows such as menus, tooltips, dropdown menus, etc. but can also be used for "normal" windows with a legacy decoration. In future we could think about allowing an ARGB deco to not use the decoration shadows any more, but the new system. For decorations like Aurorae we will still need the decoration shadows. Nevertheless for decorations direct API calls are to be preferred over using any X property based systems!

=== The shadow elements ===
The shadow elements are inspired by Plasma's FrameSvg borders. There will be eight pixmaps defining the shadow:
 * top
 * top-right
 * right
 * bottom-right
 * bottom
 * bottom-left
 * left
 * top-left
The center element is not required as we do not want to have shadows behind the window. 

The compositor announces support for the shadows through adding _KDE_NET_WM_SHADOW to _NET_SUPPORTED

=== Requesting Shadow for a Window ===
To set a shadow for a window the toolkit/widget style should set the property _KDE_NET_WM_SHADOW. The structure of the property is the X11 ids of the pixmaps defining the shadow elements followed by the padding in the various directions starting from top in clockwise direction. 4 padding elements are required, corresponding to the 4 sides of the shadow:
 * padding in y-pixels for TOP
 * padding in x-pixels for RIGHT
 * padding in y-pixels for BOTTOM
 * padding in x-pixels for LEFT

Padding for the corners is derived from the 4 values above.

An example for a shadow of 10 pixels in all directions and 20 pixels on the bottom and tiled borders:
_KDE_NET_WM_SHADOW=#top, #top-right, #right, #bottom-right, #bottom, #bottom-left, #left, #top-left, 10, 10, 20, 10

The pixmaps start from the offsets derived from the 4 padding values above and are painted in their complete size. For the borders the pixmaps are stretched in the respective direction, the other size is fixed.

It is the task of the toolkit/widget style to ensure that the pixmaps are valid, namely that they have been created and exist in memory as an X11 pixmap. If the shadow changes the pixmaps can be updated and the compositor needs to respond to damage events on the pixmaps. A toolkit/widget style may share the pixmaps between various processes and this is also recommended to do, if possible.

=== Implementation in KWin ===
Shadows are moved directly into the compositor following the approach of the decoration shadows. Window quads for each of the shadow areas are added and rendered before the window (if it is RGB) or rendered together with the window in case of RGBA (for Oxygen the latter case will always be the case).

Moving the shadows directly into the compositor and not in an effect should provide the required performance and should not show the visual bugs seen before with e.g. blur effect. The shadow belongs to the window, so even wobbly shadows should work better ;-)