New Decoration API

The current KDecoration API is rather dated, limited and not designed for the use in a composited setup. In order to provide ARGB decorations the PaintRedirector had been introduced which has been identified as a bottleneck. The API has hardly changed with KDE 4 and the only major change was the introduction of Window Tabbing. Unfortunately the API for Window Tabbing entered without a proper API review and without feedback of decoration developers making the API hard to use and impossible to maintain.

Most of the issues with the KDecoration API are not fixable without breaking the ABI promise. In fact most of the API issues are not even fixable in a source compatible way. Introducing a new API would mean that all existing decorations would not be usable any more rendering the only remaining decorations the maintained ones: Oxygen and Aurorae.

Therefore a new API has to be provided alongside the existing KDecoration API without inheriting or using anything of the existing API. In order to properly develop the API we should not install the headers or provide a stable ABI. Only decorations shipped with KWin should be allowed to use it. ABI stability should be guaranteed like it is done for KWin Effects.

API Changes Compared to KDecoration

Signals for Client Changes

All changes of the client should use signals and not virtuals. Using singals makes it easier to extend the API in future releases (e.g. new button types). The existing API is inconsistant as some buttons emit signals instead of using virtuals

QProperties

All client states should be exported as QProperties. Getters and Setters should be Qt-stylish.

Client Group

The Client Group API needs a major rework. Especially it is important to notify the client when clients are added or removed. It might be useful to rename everything to WindowTabs as that's how it is named in common speak. No need to have a tech speak.

Remove Border Sizes

Border sizes should be handled completly inside the decoration like it is done in Oxygen and Aurorae.

Remove Most of the Abilities

The only interesting Abilities are the DecorationButtons. All decorations should support ARGB, provide shadow, use blur and so on. In case we do allow clients to define what buttons to render without the user to interact the Abilities are not needed at all.

No CommonDecoration

The concept of a common decoration does hardly make any sense for a modern decoration. Especially the window tabbing addition showed how difficult it is to extend the class in a usingful manner.

Remove Drawboad

Not needed any more. We are composited and have an effect for nice resizing.

No Paint Redirector

The PaintRedirector should be dropped completly. Instead of letting the decoration create the widget, KWin core should create the widget and just pass a QPainter to the decoration. The QPainter could be created directly on the pixmap KWin uses for compositing.

Rendering outside the Decoration

Rendering outside the decoration like shadows should be completly possible. This has to go further than the current possibilities. E.g. button glow on hover has to be supported. Idea: decoration specifies a canvas area and a interaction area. The interaction area is used for mouse events, snapping etc, while the canvas is only rendered. This obsoletes the requirement for specifying border, padding and mask.

Requiring Compositing

To ease the most important use case it might be an idea to require (OpenGL) Compositing. If Compositing is not enabled KWin won't load the decoration and when compositing gets disabled KWin unloads the decoration and loads a legacy decoration. This would make the life easier for everyone.

OpenGL rendering

In case we require OpenGL Compositing, we could hook the rendering into the normal Scene rendering allowing the decoration to render OpenGL code directly on the screen or maybe provide a QPainter with an OpenGL backend. Fredrik is working on a GL deco.

QML Support

QML might be interesting for decorations. This could allow to just load a different QML file as the decoration while keeping the interaction in KWin core.

GraphicsView Support

Properly not needed as obsoleted by QML.

Custom Decoration Buttons

Does it make sense to control the decoration buttons globally? Wouldn't it be better to give complete control about the decoration buttons to the decoration and let it decide which to render? (Probably users will consider this as a "GNOME" way of handling things ;-)

GPL instead of BSD

Given that the decoration API will not be made a stable ABI and not be exported, nobody can write decorations outside the KWin source tree obsoleting the need for allowing proprietary decorations. In case the decoration API allows to use QML, we are able to allow proprietary decorations even if the API is GPL. Furthermore it is my personal belief (mgraesslin writing here) that the decoration API is a derived work of KWin core due to exporting the state of the Client object, which requires that the API has to be GPL.

Unit tests

The complete API should have Unit tests and a well defined behavior.

Test Application

There should be a test-application for Decorations and the API similar to AuroraeDesigner and oxygen-demo.