Communication

Mailing list

IRC

The KWin development IRC channel is #kwin on freenode. General KDE development is in channel #kde-devel, user support in #kde

Bugzilla

The bugs.kde.org product for KWin is 'kwin'. Information about the various components and the priority system is documented on KWin/Bugzilla.

KWin parts

KWin consists of several parts:

The KWin core, located in toplevel directory, which implements the window manager and compositor.

The decoration plugins, located in clients and kdeartwork/kwin-styles, which are responsible for the visual representation of the windows.

The effects plugins, located in effects/*, which are responsible for compositing effects

The libkdecorations library, located in libkdecorations/*, which is used for communication between the core and the decoration, and also implements some shared functionality for the decorations.

The libkwineffects library, located in libkwineffects/*, which is used for communication between the core and the effects and also implements some shared functionality for the effects and the compositor.

KWin structure

KWin has relatively few classes. The two main classes are Client, which represents windows
on the screen, and Workspace, which represents the whole screen and manages windows. Since
KWin also needs to track unmanaged windows for compositing, there is a base class Toplevel
for all windows, from which Client inherits, and from which also class Unmanaged inherits. A third
inheriting class Deleted keeps a copy of the window pixmap for animation when a window is closed.
These classes are rather large, because they fulfill complicated tasks. In order to reduce size
of their source files these some functionality is in separate .cpp file grouped by their purpose. Lately the functionality is getting split out of Workspace.

Window Manager

The following lists the source files relevant for the core of the window manager:

workspace.* - core of class Workspace

client.* - core of class Client

toplevel.* - core of the base class Toplevel

unmanaged.* - core of the class Unmanaged

activities.* - Functionality related to Activities

appmenu.* - Functionality for embedding the Application's menu into the window decoration

activation.cpp - focus handling and window activation

client_machine.* - detects whether a Client is on a local or on a remote system

options.* - all configuration options for KWin are stored in this class

decorations.* - loading of the right decoration plugin

utils.* - various small utility functions/classes

xcbutils.* - wrapper classes for accessing XCB

KWin also uses code from kdelibs, specifically files netwm.cpp, netwm.h, netwm_def.h and netwm_p.h
from kdelibs/kdecore. These files implement support for the EWMH window manager specification,
originally called NETWM (hence the filenames).

KWin Decorations

If you want to develop a decoration plugin for KWin, you can use follow this HOWTO. The HOWTO does not include the latest changes in KDE 4. These plugins have to be written in C++.

Developing KWin

Building KWin

Restarting KWin

Since KWin takes care of focus handling, first killing KWin and then launching new instance can cause focus trouble. Therefore it's possible to run 'kwin --replace', which will start new KWin instance and tell the old one to quit.

Handling the case when KWin crashes

Again, without KWin running there may be focus problems. To restart KWin when not being able to focus KRunner or a Konsole switch to text console, and run 'DISPLAY=:0 kwin --replace' (and then you can run 'kwin --replace' again from X).

If KWin is temporarily unusable because of some change and e.g. crashes during startup, it is possible to run another window manager, for example Metacity, Compiz, OpenBox or FVWM (the command is similar to restarting KWin, i.e. 'metacity --replace', 'compiz --replace', 'openbox --replace' or 'fvwm -replace'). A good idea is also to have the distribution's KWin around to be able to switch to this if the development version is broken.

Debugging KWin

Focus problems once more. It is not possible to debug KWin in gdb in the X session that KWin is managing, because that'd block focus and window operations. It is necessary to switch to a text console and attach to the running KWin instance from there, or launch it as 'DISPLAY=:0 gdb kwin'.

Since KWin is such an important component of KDE, it is usually better to start another X for development.

Starting separate X for testing KWin: use a separate user, login to a text console and run
"( X vt10 :1 -terminate &); sleep 5; DISPLAY=:1 xterm". This launches another X with DISPLAY=:1
on virtual console 10 (Ctrl+Alt+F10) with xterm. Then it's normally possible to run just KWin
or whole KDE with startkde (in which case it's a good idea to disable xterm from session management
in KControl->KDE components->Session manager).

Another solution is to use Xephyr which allows to have the KWin which is getting debugged on the same screen as the IDE. But some features are not available on Xephyr like OpenGL based compositing.

Window manager spec

The EWMH window manager specification, also known as NETWM, is located at the freedesktop.org site, http://standards.freedesktop.org/wm-spec/wm-spec-latest.html. It defines how the window manager communicates information with the applications and other desktop utilities such as the taskbar or pager.

Notes

So, you feel brave, huh? But KWin is not THAT difficult. Some parts, especially the X-related ones,
can be very complicated, but for many parts even knowledge of X and Xlib is not necessary. Most X
code is wrapped in helper functions. However, although many
features don't require touching X/Xlib directly, still X/Xlib may impose their semantics on the way
things are done. When in doubt, simply ask.

All merge requests for KWin should be sent to GitLab for review first. Even seemingly harmless changes may have extensive consequences. For more information, see Infrastructure/GitLab.

Various notes:

kDebug has overloaded operator << for the Client class, so you can e.g. use 'kDebug() << this;'

in class Client and it will print information about the window.

KWin itself cannot create any normal windows, because it would have trouble managing its own windows. For such cases (which should be rare) a small external helper application is needed (kdialog should often do, and for special cases such a utility needs to be written like kwin/killer).

OpenGL

KWin uses OpenGL for its compositor and in some effects. Most effects do not use OpenGL directly, so it is possible to write effects without the knowledge of OpenGL. If you want to directly manipulate the rendering scene or working on the Compositor itself you must have at least some basic knowledge about OpenGL.

OpenGL comes in two different flavors: fixed functionality and programmable pipeline. There are several versions of OpenGL. OpenGL 1.x only supports fixed functionality, OpenGL ES 2.0 and OpenGL 3/4 (forward compatible profile) only supports programmable pipeline. OpenGL 2.x supports both way of programming.

KWin has code paths for both fixed functionality and programmable pipeline. By default KWin uses programmable pipeline and only falls back to fixed functionality if the GPU does not support it. New code should focus on programmable pipeline and restrict itself to the OpenGL ES 2.0 API.

Books

There are various books about OpenGL, documenting different bits of the API

OpenGL Programming Guide - The Redbook The online resource is the (outdated) 5th edition not covering OpenGL Shading Language. Even the 6th edition does only contain a small chapter on OpenGL Shading Language and the previous chapters are slightly outdated, too. Nevertheless it's a good book for learning the concepts of OpenGL, but does not help much on KWin development.

OpenGL Shading Language a good book about OpenGL Shading Language. In the 2nd edition it was strongly focusing on extending the fixed functionality with some programmable states. It seems that in the 3rd edition it got updated to using only shaders. The examples might be too extensive for the use in KWin.

OpenGL SuperBible This is one of the best books for OpenGL development. The 4th edition has an extensive view on both fixed functionality as well as programmable pipeline. In the 5th edition fixed functionality has been completely removed and the book has been rewritten for programmable pipeline with OpenGL 3. The book is well structured and has a good teaching approach. One of the best features is the API documentation in the Appendix.

API Documentation

Finding the right API documentation for OpenGL is rather difficult. KWin uses in general functionality from OpenGL 2.1 but also uses some functionality provided by Extensions. The programmable pipeline code path should be compatible with OpenGL ES 2.0, this means it is not allowed to use fixed functionality API calls, even if listed in the OpenGL 2.1 reference pages.

OpenGL 2.1 Reference Pages Complete OpenGL 2.1 API including GLX. This includes both fixed functionality and programmable pipeline. Do not use any API call only available since OpenGL 2.0 in the fixed functionality code path and do check whether an API call is still available in the OpenGL 3.3 core context for the programmable pipeline path

OpenGL ES 2.0 Reference Pages Subset of OpenGL 2 for embedded devices. Best restrict to this API in the programmable pipeline path. Any API call not available in OpenGL ES 2.0 will fail when compiling against OpenGL ES.