View source for Projects/KWin/4.0-release-notes

'''KWin release notes for KDE4.0'''

{{warning|The sections on usage, configuration and performance may not apply to later version of KDE Plasma Workspaces. This page will not be updated!}}

== Introduction ==

KWin, the standard KDE window manager in KDE4.0, ships with the first version
of built-in support for compositing, making it also a compositing manager.
This allows KWin to provide advanced graphical effects, similar to Compiz, while also providing all the features from previous KDE releases (such as very good integration with the rest of KDE, advanced configurability, focus stealing prevention, a well-tested window manager, robust handling of misbehaving applications/toolkits, etc.). Unlike Compiz, KWin still functions even when no system support for compositing is available, with only the compositing features being unavailable.

KWin versions in recent KDE3.x releases included a standalone compositing manager called kompmgr, based on the xcompmgr compositing manager. Kompmgr was only loosely tied with KWin, used only XRender for rendering and provided only basic features like transparency, shadows, and fade in/out animations. The compositing manager implemented in KWin included with KDE4.0 is integrated into the rest of KWin, and it can use either OpenGL or XRender for rendering and has a framework for compositing effects, all of which allows KWin to provide a much wider range of features.

Note, however, that compositing support in KWin in KDE4.0 is still considered experimental, for several reasons. System support for compositing is often problematic (various bugs in X, drivers or other parts of the system), manual configuration of X may be required for proper results (see below), some applications may not be prepared and work well with compositing, the performance may not be adequate, and other problems. Also, while KWin's compositing support is considered usable and reasonably stable, it is relatively new code and has been tested only on a limited range of hardware.

Therefore, compositing support in KWin is disabled by default, and needs to be explicitly enabled. If there are any problems, you can disable it again (see below for troubleshooting) and report a bug with all relevant information about the problem.


== Setting up ==

Compositing support is enabled in KWin's configuration. Press Alt+F3 and select 'Configure Window Behavior'. In the configuration module, select the page 'Desktop Effects' and enable the checkbox 'Enable desktop effects'. After accepting the changes, a dialog with a timeout will appear, asking to confirm enabling of compositing support. If you do not confirm within the timeout,
compositing support will be disabled again, therefore, if enabling compositing triggers any problems, it should be sufficient to wait several seconds before the changes are reverted. Note that after enabling or disabling compositing it is recommended to restart your KDE session in order to ensure that all applications detect the change.

If you cannot enable desktop effects, it may be because either your KDE is not built with the necessary support, or more probably because your system is not capable of providing compositing support. See [https://projects.kde.org/projects/kde/kde-workspace/repository/revisions/bb6fa0acde8525f63d09c198f7c6fb7a312d85fc/entry/kwin/COMPOSITE_HOWTO#L1 COMPOSITE_HOWTO] for some instructions on setting up your system. Note that there may be other factors affecting whether you do or do not have compositing support.

== Usage ==

A quick overview of features provided by the compositing manager in KWin:

* Ctrl+F9 (and Ctrl+F10 for windows from all desktops) shows an overview of all windows and allows activating one of them. The feature can be also activated by moving the mouse into the top-left screen corner. A window can be activated by clicking it or by using arrows and the Enter key. You can also type text to filter the list of windows.
* Ctrl+F8 shortcut activates a desktop grid - all of your virtual desktops will be arranged on the screen (as an enlarged pager). You can select and activate desktops using a number, a function key, by clicking on it, or by using arrows and the Enter key. You can also move windows by dragging them or by right-clicking on them.
* The DesktopGrid effect also provides animations when switching between virtual desktops (can be turned off).
* The window switcher (Alt+Tab by default) provides live thumbnails of windows.
* Windows blocked by modal dialogs are dimmed.
* Screen can be zoomed in and out using Win+<equals>, Win+<minus> and reset using Win+0 (it is currently not possible to use mouse wheel, but this feature is planned). Note that because of input transformation not being yet available in X the zoomed screen has to move around to keep the mouse pointer at the same place like it would be when not zoomed.
* Screen can be shown with inverted colors by pressing Ctrl+Win+I (accessibility feature, Invert effect is not enabled by default).
* There are fade animations during login and logout.
* Windows fade in and out.
* Minimize animation to/from taskbar.
* Windows have shadows.

There are more features that are not enabled by default and need to be explicitly enabled in the configuration.

There are various videos showing assorted compositing features of KWin. For example, search for 'kwin_composite' at youtube.com (please keep in mind that many of those windows are old and show testing or demo effects).


== Using KWin without KDE desktop ==

Similar to older KWin versions it is possible to use KWin with other desktop environments or even as a standalone window manager, as long as the required KDE libraries are installed. Please note that KWin is a pure window manager and does not provide a panel or handle desktop background like some window managers do. KWin's compositing features work in the standalone mode, with some functionality missing (because of a missing taskbar, for example), and, while this has not been tested, it is expected that compositing features will work also when running in other desktop environments, possibly with some
functionality missing again. Reports on using KWin with other desktop environments are welcome.


== Performance ==

Compositing internally works by redirecting window drawing to offscreen memory and composing it on the screen in an additional drawing pass. This means that, in general, a composited desktop (on average) has worse performance than a non-composited desktop (although in some cases it may perform better, be that real improvement or just perceived one due to animations, better
synchronization or similar factors). For example, binding window pixmaps to OpenGL textures (that is, preparing window contents for drawing) can be a relatively costly operation with large windows, making things like animations in a Plasma desktop window or page scrolling in a maximized browser window jerky. Heavy system load can also cause the compositing manager to not repaint often enough, resulting in lagging or jerky screen redrawing.

KWin in KDE4.0 is also relatively new code and has not been extensively optimized yet, therefore its performance may not be in some areas comparable with performance of other compositing managers. In such cases performance should be improved with newer versions.

Note that current XRender implementations (in X/drivers) often perform rather poorly and therefore the OpenGL mode should usually have much better performance. See below for notes on XRender mode.

Tip: Performance/smoothness with nVidia cards: Smoothness of KWin rendering
can be improved by setting the env.variable KWIN_NVIDIA_HACK to 1 (e.g. append
'export KWIN_NVIDIA_HACK=1' to your ~/.profile file). This sets '__GL_YIELD=NOTHING' for KWin, letting KWin use more CPU time for OpenGL operations, however at the expense of affecting performance of other applications. This option is enabled by default since KDE4.0.3, as the performance impact seems to be non-significant. See section 'OPENGL YIELD BEHAVIOR' in README.txt for nVidia cards for details.

Tip: In some cases, overall smoothness may be increased by turning off direct rendering in advanced options in the Desktop Effects configuration module (Alt+F3->Configure Window Behavior).

Tip: Changing the Texture filter in the Advanced Compositing Options to Nearest may improve performance considerably (at the cost of aliasing artifacts), especially on low-end graphics equipment.

== Troubleshooting ==

As already said, compositing support in KWin is considered usable and reasonably stable, but due to several reasons it may not work properly for you.

If there are any problems with compositing support, the simplest option is to disable it again. KWin will normally continue functioning, only not providing compositing features. If you cannot normally turn off compositing support (for example because the screen is corrupted), you can turn it off using one of these ways:
* run the command 'kwriteconfig --file kwinrc --group Compositing --key Enabled false' from the command line
* set environment variable 'KWIN_COMPOSE' to 'N' (append 'export KWIN_COMPOSE=N' to the end of your ~/.profile), this affects compositing only temporarily
You will probably need to switch to text mode or start failsafe session from KDM to be able to perform this.

See file [http://websvn.kde.org/*checkout*/trunk/KDE/kdebase/workspace/kwin/COMPOSITE_HOWTO COMPOSITE_HOWTO] for some issues with various graphics cards.

Note: When reporting bugreports for KWin compositing, it is useful to check whether Compiz works on the same system.

== XRender mode ==

It is possible to use XRender for compositing instead of the default OpenGL.
XRender mode in general has less features, at the moment it is also considered unstable since it has not received as much testing as OpenGL mode. Some features may be incomplete and it is recommended to use the OpenGL mode if possible. Also note that current XRender implementations (in X/drivers) often perform rather poorly.


== Developers ==

KWin provides support for writing compositing effects that may be loaded into KWin as plugins. These effects communicate with the KWin core using C++ API specially designed for this purpose, making effects not directly dependent on the KWin core or changes in it.

At the time of the KDE4.0 release, since compositing support is still under heavy development, this API is considered unstable and subject to change. If you write your own effect plugin, you may need to recompile it after a KWin update. KWin will however detect incompatible versions and will not load such plugins (automatic, you do not need to provide any code for it).
As the compositing support becomes more stabilized, this API will be kept backwards and binary compatible just like with other KDE libraries.

At the time of the KDE4.0 release, API for compositing effects is unfortunately only sparsely documented. Developers interested in writing compositing effects for KWin are suggested to use [http://websvn.kde.org/trunk/KDE/kdebase/workspace/kwin/effects/ source code of effects] shipped with KWin (the Howto effect in test/ directory as the starting point) and/or ask on the [https://mail.kde.org/mailman/listinfo/kwin KWin mailing list].

Links to various KWin-related documents are available at [http://techbase.kde.org/Projects/KWin techbase.kde.org] .


== FAQ ==

=== Why not Compiz? ===

It is possible to use Compiz instead of KWin with KDE, however KWin remains the default window manager. The option of replacing KWin with Compiz had been evaluated before work on compositing features of KWin started and the conclusion was, in short, that it would lead to a lot of work and duplicated
effort.

To answer in more detail, several technical things need to be explained. Both KWin and Compiz are a combined window manager and compositing manager. Window manager functionality takes care of all aspects of handling windows, such as their placement, selecting the active one and so on. This functionality is crucial for a desktop - without a window manager it would be very difficult
to perform most operations with windows. Compositing manager functionality, on the other hand, can be considered optional - while it brings many new features, it is still possible very well to use a desktop (such as with KWin in KDE3).

The reasons to add compositing support to KWin instead of using Compiz include:

1) Compiz at the present time is very likely the most advanced compositing manager with many features, with a headstart when compared with KWin, however, this cannot be said about Compiz as the window manager, where KWin has the advantage of being a much more tested codebase, providing a more stable, well-tested and robust window manager with many features. Given that, as stated above, window manager functionality is considered to be more important, it would be unwise to force all KDE users to a change that would likely mean regressions in many aspects.

These regressions would include lesser integration with KDE, visual and behavioral changes (the 'KDE window decorator' shipped with Compiz only mimics the look of KWin's decorations, but does not provide the same functionality, even the Alt+F3 popup menu visibly differs), possible introduction of problems that have already been fixed in KWin, missing features that have already been implemented in KWin, and so on. Developing, testing and bugfixing a window
manager can be very demanding work and repeating all the work done on KWin again for Compiz would presumably require a lot of effort. As such, claims that KWin is 'reinventing the wheel' are missing the point, since Compiz, being a relatively new window manager, is reinventing at least as much,
if not more, from other window managers including KWin,

Also, given that there can be only one window manager and one compositing manager at a time, there would be no possible way to remedy these problems by somehow running Compiz and KWin together.

2) Compiz currently does not work at all when compositing is not possible, thus requiring a fallback window manager for such case. This in practice would mean that KDE developers would be required to work on improving Compiz and would have to keep KWin at least for maintenance as the fallback for Compiz, thus having two window managers for KDE. Besides the developer work of taking care of two window managers this would also bring many user problems resulting from two different window managers, with differences in the look and feel, feature sets, and bugs.

It should be also noted that Metacity, GNOME's window manager, has not been dropped in favour of Compiz either, but is still, to our knowledge, under development and adding compositing features to it is a work in progress.

=== Why not use plugins from Compiz? ===

This option was considered in the past as well. After examination of Compiz code the conclusion was that this is technically almost impossible. Compiz plugins appear to be merely parts of Compiz that are separated from its core, but which still heavily depend on it - there are even plugins that appear to copy and paste parts of the Compiz core and modify it. Making it possible to use such plugins from KWin would essentially require KWin to become Compiz.


=== Why add compositing support to KWin when Compiz is better ? ===

There can be different ideas about what better means, but regardless of that, the main aim of KWin is not to replace Compiz. Many users have asked for compositing support in KDE, and, as explained in 'Why not Compiz?', the best way to achieve that is considered to be adding compositing support to KWin. KWin aims to provide compositing support, focusing on providing useful compositing features and basic visual effects, while keeping its other strengths.