KWin/Hacking: Difference between revisions

From KDE Community Wiki
(→‎KWin parts: fix broken links)
m (Fix minor typos)
 
(21 intermediate revisions by 5 users not shown)
Line 5: Line 5:


=== IRC ===
=== IRC ===
The KWin development IRC channel is #kwin on [http://freenode.net freenode]. General KDE development is in channel #kde-devel, user support in #kde
The KWin development IRC channel is #kwin on [http://libera.chat Libera Chat]. General KDE development is in channel #kde-devel, user support in #kde


=== Bugzilla ===
=== Bugzilla ===
Line 13: Line 13:


KWin consists of several parts:
KWin consists of several parts:
* The KWin core, located in [https://projects.kde.org/projects/kde/kde-workspace/repository/revisions/master/show/kwin kde-workspace/kwin/*], which implements the window manager and compositor.
* The KWin core, located in [https://projects.kde.org/projects/kde/workspace/kwin/repository/revisions/master/show toplevel directory], which implements the window manager and compositor.
* The decoration plugins, located in [https://projects.kde.org/projects/kde/kde-workspace/repository/revisions/master/show/kwin/clients kde-workspace/kwin/clients] and kdeartwork/kwin-styles, which are responsible for the visual representation of the windows.
* The decoration plugins, located in [https://projects.kde.org/projects/kde/workspace/kwin/repository/revisions/master/show/clients clients] and kdeartwork/kwin-styles, which are responsible for the visual representation of the windows.
* The effects plugins, located in [https://projects.kde.org/projects/kde/kde-workspace/repository/revisions/master/show/kwin/effects kde-workspace/kwin/effects], which are responsible for compositing effects
* The effects plugins, located in [https://projects.kde.org/projects/kde/workspace/kwin/repository/revisions/master/show/effects effects/*], which are responsible for compositing effects
* The libkdecorations library, located in [https://projects.kde.org/projects/kde/kde-workspace/repository/revisions/master/show/kwin/libkdecorations kde-workspace/kwin/libkdecorations/*], which is used for communication between the core and the decoration, and also implements some shared functionality for the decorations.
* The libkdecorations library, located in [https://projects.kde.org/projects/kde/workspace/kwin/repository/revisions/master/show/libkdecorations 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 [https://projects.kde.org/projects/kde/kde-workspace/repository/revisions/master/show/kwin/libkwineffects kde-workspace/kwin/libkwineffects/*], which is used for communication between the core and the effects and also implements some shared functionality for the effects and the compositor.
* The libkwineffects library, located in [https://projects.kde.org/projects/kde/workspace/kwin/repository/revisions/master/show/libkwineffects libkwineffects/*], which is used for communication between the core and the effects and also implements some shared functionality for the effects and the compositor.
* KControl modules, located in [https://projects.kde.org/projects/kde/kde-workspace/repository/revisions/master/show/kwin/kcmkwin kde-workspace/kwin/kcmkwin].
* KControl modules, located in [https://projects.kde.org/projects/kde/workspace/kwin/repository/revisions/master/show/kcmkwin kcmkwin/*].
* The KWin Scripting bindings for JavaScript and QtQuick are located in [https://projects.kde.org/projects/kde/workspace/kwin/repository/revisions/master/show/scripting scripting/*]
* KWin Scripts in JavaScript and/or QtQuick are located in [https://projects.kde.org/projects/kde/workspace/kwin/repository/revisions/master/show/scripts scripts/*]
* The Window and Desktop Switching framework is located in [https://projects.kde.org/projects/kde/workspace/kwin/repository/revisions/master/show/tabbox tabbox/*]


=== KWin structure ===
=== KWin structure ===
Line 26: Line 29:
for all windows, from which Client inherits, and from which also class Unmanaged inherits. A third
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.
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 other to reduce size
These classes are rather large, because they fulfill complicated tasks. In order to reduce the size
of their source files these some functionality is in separate .cpp file grouped by their purpose.
of their source files these some functionality is in a separate .cpp file grouped by their purpose. Lately, the functionality is getting split out of Workspace.


==== Window Manager ====
==== Window Manager ====
Line 33: Line 36:
* workspace.* - core of class Workspace
* workspace.* - core of class Workspace
* client.* - core of class Client
* client.* - core of class Client
* deleted.* - core of class Deleted
* toplevel.* - core of the base class Toplevel
* toplevel.* - core of the base class Toplevel
* unmanaged.* - core of the class Unmanaged
* 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
* activation.cpp - focus handling and window activation
* client_machine.* - detects whether a Client is on a local or on a remote system
* cursor.* - Mouse cursor related functionality like mouse polling
* deleted.* - core of class Deleted
* dbusinterface.* - Implementation of KWin's DBus interface, delegating to other classes
* events.cpp - event handling is in events.cpp
* events.cpp - event handling is in events.cpp
* focuschain.* - The Focus Chain for each desktop and most recently used Clients
* geometry.cpp - geometry-related code
* geometry.cpp - geometry-related code
* layers.cpp - stacking-related code
* layers.cpp - stacking-related code
* manage.cpp - code dealing with new windows
* manage.cpp - code dealing with new windows
* netinfo.* - Implementation of KWin's sub calles for NETRootInfo and NETWinInfo
* outline.* - code for showing an outline when e.g. using Alt+Tab or quicktiling
* outline.* - code for showing an outline when e.g. using Alt+Tab or quicktiling
* placement.cpp - window placements algorithms
* placement.cpp - window placements algorithms
* rules.cpp - code for window-specific settings
* rules.cpp - code for window-specific settings
* screenedge.* - code for screen edge activation
* screenedge.* - code for screen edge activation
* screens.* - multi-screen handling code
* sm.cpp - session management code
* sm.cpp - session management code
* tabgroup.* - Window tabs related code
* tabgroup.* - Window tabs related code
* thumbnailitem.* - QML DeclarativeItem to render a Window Thumbnail (or Icon without Compositing)
* thumbnailitem.* - QML DeclarativeItem to render a Window Thumbnail (or Icon without Compositing)
* useractions.cpp - handling of the Alt+F3 menu, shortcuts and other user actions
* useractions.* - handling of the Alt+F3 menu, shortcuts and other user actions
* virtualdesktops.* - Functionality related to Virtual Desktops


==== Compositor ====
==== Compositor ====
The following lists the source files relevant to the compositor:
The following lists the source files relevant to the compositor:
* composite.cpp - code related to redirecting windows to pixmaps and tracking their damage
* composite.* - code related to redirecting windows to pixmaps and tracking their damage
* effects.* - support for compositing effects
* effects.* - support for compositing effects
* eglonxbackend.* - OpenGL backend using EGL for either OpenGL or OpenGL ES
* egl_wayland_backend.* - OpenGL backend using EGL to render to a Wayland surface
* glxbackend.* - OpenGL backend using GLX
* lanczosfilter.* - Lanczos Filter for improved OpenGL based thumbnail rendering
* lanczosfilter.* - Lanczos Filter for improved OpenGL based thumbnail rendering
* overlaywindow.* - the Overlay Window used for Compositing
* overlaywindow.* - the Overlay Window used for Compositing
* paintredierctor.* - Redirects painting of decoration widget into a pixmap
* paintredierctor.* - Redirects painting of decoration widget into a paint device for usage by the Scenes
* scene.* - base class for compositing backends, with shared functionality
* scene.* - base class for compositing backends, with shared functionality
* scene_basic.* - a very simple testing compositing code
* scene_basic.* - a very simple testing compositing code
Line 64: Line 79:
* scene_xrender.* - compositing backend using XRender
* scene_xrender.* - compositing backend using XRender
* shadow.* - Window Shadows
* shadow.* - Window Shadows
The implementation of a custom scene can be found in [[KWin/Hacking/Scene]].


==== Helper Classes ====
==== Helper Classes ====
Line 76: Line 93:
* notifications.* - for KNotify
* notifications.* - for KNotify
* options.* - all configuration options for KWin are stored in this class
* options.* - all configuration options for KWin are stored in this class
* plugins.* - loading of the right decoration plugin
* decorations.* - loading of the right decoration plugin
* utils.* - various small utility functions/classes
* 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
KWin also uses code from kdelibs, specifically files netwm.cpp, netwm.h, netwm_def.h and netwm_p.h
Line 88: Line 106:


If you prefer designing a theme, you can use Aurorae (shipped with KWin), [https://projects.kde.org/projects/playground/artwork/dekorator deKorator] or [https://projects.kde.org/projects/playground/artwork/smaragd Smaragd]. For Aurorae there is a [http://techbase.kde.org/User:Mgraesslin/Aurorae tutorial] on techbase and it is recommended to use [http://kde-apps.org/content/show.php/AuroraeDesigner?content=122763 AuroraeDesigner].
If you prefer designing a theme, you can use Aurorae (shipped with KWin), [https://projects.kde.org/projects/playground/artwork/dekorator deKorator] or [https://projects.kde.org/projects/playground/artwork/smaragd Smaragd]. For Aurorae there is a [http://techbase.kde.org/User:Mgraesslin/Aurorae tutorial] on techbase and it is recommended to use [http://kde-apps.org/content/show.php/AuroraeDesigner?content=122763 AuroraeDesigner].
It is also possible to develop window decorations using QML. But the API is still considered unstable and because of that not yet documented. An example is the Plastik decoration since 4.10.


== Developing KWin ==
== Developing KWin ==
=== Building KWin ===
Please see [[KWin/Building]] for Qt4 and [[KWin/Frameworks]] for Qt5
=== Restarting 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.
Since KWin takes care of focus handling, first killing KWin and then launching a new instance can cause focus trouble. Therefore it's possible to run 'kwin --replace', which will start a new KWin instance and tell the old one to quit.


=== Handling the case when KWin crashes ===
=== 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).
Again, without KWin running there may be focus problems. To restart KWin when not being able to focus KRunner or a Konsole switch to a 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').
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 ===
=== Debugging KWin ===
Line 108: Line 131:
or whole KDE with startkde (in which case it's a good idea to disable xterm from session management
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).
in KControl->KDE components->Session manager).
Another solution is to use Xephyr which allows having 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 ===
=== Window manager spec ===
Line 120: Line 145:
things are done. When in doubt, simply ask.
things are done. When in doubt, simply ask.


All patches for KWin should be sent to [http://reviewboard.kde.org ReviewBoard] for review first. Even seemingly harmless changes may have extensive consequences.
All merge requests for KWin should be sent to [https://invent.kde.org/ GitLab] for review first. Even seemingly harmless changes may have extensive consequences. For more information, see [[Infrastructure/GitLab]].


Various notes:
Various notes:
Line 134: Line 159:


The source repository was reformatted with [https://projects.kde.org/projects/kde/kdebase/kde-workspace/repository/revisions/4fd08556a1702462335f4f1307da663c2c54b2c2 git commit 4fd08556].
The source repository was reformatted with [https://projects.kde.org/projects/kde/kdebase/kde-workspace/repository/revisions/4fd08556a1702462335f4f1307da663c2c54b2c2 git commit 4fd08556].
=== Submitting Changes ===
KWin development uses [https://git.reviewboard.kde.org ReviewBoard] for code review. Upload your change for the repository "kwin" (for 4.11 it's "kde-workspace") and add review group kwin.


== Documentation ==
== Documentation ==
Line 139: Line 167:


As already said, many parts of KWin don't need knowledge of Xlib or even how X actually works.
As already said, many parts of KWin don't need knowledge of Xlib or even how X actually works.
Some parts do, and it may be also useful to have at least a basic understand for general
Some parts do, and it may be also useful to have at least a basic understanding for general
understanding. A reference manual for Xlib can be found e.g.
understanding. A reference manual for Xlib can be found e.g.
at ftp://ftp.x.org/pub/X11R7.0/doc/PDF/xlib.pdf , a tutorial explaining basic can be found
at ftp://ftp.x.org/pub/X11R7.0/doc/PDF/xlib.pdf , a tutorial explaining basic can be found
Line 153: Line 181:
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.
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 [http://www.khronos.org/opengles/sdk/docs/man/ OpenGL ES 2.0 API].
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 [http://www.khronos.org/opengles/sdk/docs/man/ OpenGL ES 2.0 API].


==== Books ====
==== Books ====
There are various books about OpenGL, documenting different bits of the API
There are various books about OpenGL, documenting different bits of the API
* [http://www.opengl.org/documentation/red_book/ OpenGL Programming Guide - The Redbook] The online resource is the (outdated) 5th edition not covering OpenGL Shading Language. Even the [http://www.amazon.com/OpenGL-Programming-Guide-Official-Learning/dp/0321481003 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.
* [http://www.opengl.org/documentation/red_book/ OpenGL Programming Guide - The Redbook] The online resource is the (outdated) 5th edition not covering OpenGL Shading Language. Even the [http://www.amazon.com/OpenGL-Programming-Guide-Official-Learning/dp/0321481003 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.
* [http://www.amazon.com/OpenGL-Shading-Language-Randi-Rost/dp/0321637631/ref=pd_sim_b_2 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.
* [http://www.amazon.com/OpenGL-Shading-Language-Randi-Rost/dp/0321637631/ref=pd_sim_b_2 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 use in KWin.
* [http://www.opengl.org/sdk/docs/books/SuperBible/ OpenGL SuperBible] This is one of the best books for OpenGL development. The [http://www.amazon.com/OpenGL-SuperBible-Comprehensive-Tutorial-Reference/dp/0321498828/ref=pd_sim_b_5 4th edition] has an extensive view on both fixed functionality as well as programmable pipeline. In the [http://www.amazon.com/OpenGL-SuperBible-Comprehensive-Tutorial-Reference/dp/0321712617/ref=pd_sim_b_1 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.
* [http://www.opengl.org/sdk/docs/books/SuperBible/ OpenGL SuperBible] This is one of the best books for OpenGL development. The [http://www.amazon.com/OpenGL-SuperBible-Comprehensive-Tutorial-Reference/dp/0321498828/ref=pd_sim_b_5 4th edition] has an extensive view on both fixed functionality as well as programmable pipeline. In the [http://www.amazon.com/OpenGL-SuperBible-Comprehensive-Tutorial-Reference/dp/0321712617/ref=pd_sim_b_1 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.


Line 164: Line 192:
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.
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.


* [http://www.opengl.org/sdk/docs/man3/ OpenGL 3.3 Reference Pages] These man pages only document the core context. KWin does not yet use OpenGL 3, there might be API calls not yet allowed in KWin. Important: Mesa does not yet support OpenGL 3!
* [http://www.opengl.org/sdk/docs/man3/ OpenGL 3.3 Reference Pages] These man pages only document the core context.  
* [http://www.opengl.org/sdk/docs/man/ 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
* [http://www.opengl.org/sdk/docs/man/ 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
* [http://www.khronos.org/opengles/sdk/docs/man/ 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.
* [http://www.khronos.org/opengles/sdk/docs/man/ 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.

Latest revision as of 17:19, 22 June 2021

Communication

Mailing list

The KWin mailing list is [email protected]. It's rather low traffic.

IRC

The KWin development IRC channel is #kwin on Libera Chat. 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.
  • KControl modules, located in kcmkwin/*.
  • The KWin Scripting bindings for JavaScript and QtQuick are located in scripting/*
  • KWin Scripts in JavaScript and/or QtQuick are located in scripts/*
  • The Window and Desktop Switching framework is located in tabbox/*

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 the size of their source files these some functionality is in a 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
  • cursor.* - Mouse cursor related functionality like mouse polling
  • deleted.* - core of class Deleted
  • dbusinterface.* - Implementation of KWin's DBus interface, delegating to other classes
  • events.cpp - event handling is in events.cpp
  • focuschain.* - The Focus Chain for each desktop and most recently used Clients
  • geometry.cpp - geometry-related code
  • layers.cpp - stacking-related code
  • manage.cpp - code dealing with new windows
  • netinfo.* - Implementation of KWin's sub calles for NETRootInfo and NETWinInfo
  • outline.* - code for showing an outline when e.g. using Alt+Tab or quicktiling
  • placement.cpp - window placements algorithms
  • rules.cpp - code for window-specific settings
  • screenedge.* - code for screen edge activation
  • screens.* - multi-screen handling code
  • sm.cpp - session management code
  • tabgroup.* - Window tabs related code
  • thumbnailitem.* - QML DeclarativeItem to render a Window Thumbnail (or Icon without Compositing)
  • useractions.* - handling of the Alt+F3 menu, shortcuts and other user actions
  • virtualdesktops.* - Functionality related to Virtual Desktops

Compositor

The following lists the source files relevant to the compositor:

  • composite.* - code related to redirecting windows to pixmaps and tracking their damage
  • effects.* - support for compositing effects
  • eglonxbackend.* - OpenGL backend using EGL for either OpenGL or OpenGL ES
  • egl_wayland_backend.* - OpenGL backend using EGL to render to a Wayland surface
  • glxbackend.* - OpenGL backend using GLX
  • lanczosfilter.* - Lanczos Filter for improved OpenGL based thumbnail rendering
  • overlaywindow.* - the Overlay Window used for Compositing
  • paintredierctor.* - Redirects painting of decoration widget into a paint device for usage by the Scenes
  • scene.* - base class for compositing backends, with shared functionality
  • scene_basic.* - a very simple testing compositing code
  • scene_opengl.* - compositing backed using OpenGL
  • scene_opengl_egl.cpp - egl specific part of OpenGL compositing backend
  • scene_opengl_glx.cpp - glx specific part of OpenGL compositing backend
  • scene_xrender.* - compositing backend using XRender
  • shadow.* - Window Shadows

The implementation of a custom scene can be found in KWin/Hacking/Scene.

Helper Classes

The rest of the files contain additional helper classes:

  • atoms.* - so-called atoms (symbolic names for constants in X)
  • bridge.* - communication with the decoration plugin
  • geometrytip.* - window displaying window geometry while moving/resizing
  • group.* - grouping related windows together (warning! This is currently really messy and scary code that should be rewritten).
  • killwindow.* - handling of the Ctrl+Esc feature
  • kwinbindings.cpp - KWin's keyboard shortcuts (used by kdebase/kcontrol/keys)
  • notifications.* - for KNotify
  • 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++.

If you prefer designing a theme, you can use Aurorae (shipped with KWin), deKorator or Smaragd. For Aurorae there is a tutorial on techbase and it is recommended to use AuroraeDesigner.

It is also possible to develop window decorations using QML. But the API is still considered unstable and because of that not yet documented. An example is the Plastik decoration since 4.10.

Developing KWin

Building KWin

Please see KWin/Building for Qt4 and KWin/Frameworks for Qt5

Restarting KWin

Since KWin takes care of focus handling, first killing KWin and then launching a new instance can cause focus trouble. Therefore it's possible to run 'kwin --replace', which will start a 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 a 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 having 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).

Coding style

KWin follows the kdelibs coding style.

The source repository was reformatted with git commit 4fd08556.

Submitting Changes

KWin development uses ReviewBoard for code review. Upload your change for the repository "kwin" (for 4.11 it's "kde-workspace") and add review group kwin.

Documentation

X documentation

As already said, many parts of KWin don't need knowledge of Xlib or even how X actually works. Some parts do, and it may be also useful to have at least a basic understanding for general understanding. A reference manual for Xlib can be found e.g. at ftp://ftp.x.org/pub/X11R7.0/doc/PDF/xlib.pdf , a tutorial explaining basic can be found e.g. at http://users.actcom.co.il/~choo/lupg/tutorials/xlib-programming/xlib-programming.html (note that you don't need to know that all - e.g. GC's are very rarely needed and the section on fonts is today outdated). At http://www.sbin.org/doc/Xlib/index_contents.html can be found an Xlib programming manual (some of those are more or less obsolete these days, but there is e.g. an extensive section related to window management).

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 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 3.3 Reference Pages These man pages only document the core context.
  • 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.