kwin/COMPOSITE_HOWTO

This file describes how to set up kwin_composite. Note that since it is still
a work in progress, this file may possibly get out of date at times.


See file HACKING for details on developing KWin, including building
    the kwin_composite branch.
See file COMPOSITE_TODO for a list of things that still need to be done.
See effects/howto.* for a HOWTO on writting effects.
See documentation in source (mainly in scene.cpp) for description
    of the design of the compositing framework.

After starting, KWin's debug output also says which compositing backend it uses, e.g.
"OpenGL compositing". If it does not, most probably your X is not configured properly.

nVidia:
===========

8xxx drivers and newer work, only 9xxx and later drivers provide TFP (texture_from_pixmap)
functionality.

You need in xorg.conf

Option "AddARGBGLXVisuals" "True"

in 'Section "Screen"' and also the XComposite extension enabled:

Section "Extensions"
 Option "Composite" "Enable"
EndSection

Issues:
-------

When switching away from the X session KWin freezes in nvidia's OpenGL library
    - turn off GLVSync option (see below)
TFP mode (see GLMode) below crashes with windows with certain sizes (32x32)
    - use SHM mode
    - already fixed in development version of drivers
Refresh rate is slower than it should be
    - nvidia drivers use refresh rate to work around some X limitations
    - disable DynamicTwinView (see nvidia README)
    - should(?) be fixed with drivers updated for xrandr1.2


ATI:
========

The radeon driver should work for R200 chips, it's worse with R300 chips.
TODO - fglrx - no idea

You need in xorg.conf the XComposite extension enabled:

Section "Extensions"
 Option "Composite" "Enable"
EndSection

Also using

Option "XaaNoOffscreenPixmaps" "true"

in 'Section "Screen"' may improve performance for non-TFP (texture_from_pixmap) modes.

For the TFP mode AIGLX needs to work. With AIGLX direct rendering should be be disabled
(see GLDirect below, with X.org older than 7.2 "export LIBGL_ALWAYS_INDIRECT=1" before
running kwin may be necessary).


Intel:
=======

TODO - no idea. Possibly similar to ATI.


Configuration options:
======================

All general configuration option are in group [Translucency] in kwinrc config file:

UseTranslucency=<true|false> - enables/disables compositing support
GLMode=<TFP|SHM|Fallback> - selects texture creating mode
RefreshRate=<number> - manually specified refresh rate, should be usually automatically detected
GLAlwaysRebind=<true|false> - may increase speed with some graphics cards
GLDirect=<true|false> - enables/disables direct rendering
GLVSync=<true|false> - enables/disables synchronizing with monitor refresh

ShowFPSEffect:
Options are in group [EffectShowFps] in kwinrc config file:
Alpha=<number 0.0-1.0> - transparency
X=<number> - X position, negative is from the right edge, -10000 is exactly right edge
Y=<number> = Y position, the same like X


Effects:
========

Which modules are enabled is currently set by config value Load in group [Effects] in kwinrc config file.
Effects are named like the class, without the Effect suffix (e.g. Load=ShowFps,Fade). There is
no depedency checking implemented yet.