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)
    - fixed with 100.14.23 drivers
TFP mode (see GLMode below) doesn't work with windows with certain sizes (32x32)
    - already fixed in latest 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.
The fglrx driver requires XGL for versions older than 8.42.3.

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 disabled
(see GLDirect below, with X.org older than 7.2 "export LIBGL_ALWAYS_INDIRECT=1" before
running kwin may be necessary).


Intel:
=======

It should work with both the i810 and intel drivers.

You need in xorg.conf the XComposite extension enabled:

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

Also in xorg.conf, you need the DRI module loaded, and AIGLX needs to be enabled:

Section "Module"
 Load "dri"
EndSection
Section "ServerFlags"
 Option "AIGLX"
EndSection

DRI also needs some options in xorg.conf (they should be there by default):

Section "DRI"
 Group "video"
 Mode 0660
EndSection

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

Issues:
-------

With the i810 driver, DRI works only on the first running X (if you use second X session,
    compositing won't work there), the intel driver doesn't seem to have this problem.
You may get only white rectangles if DRI is not enabled or fails to initialize
    - check your X log (/var/log/X*) and your xorg.conf


XGL:
=====


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
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:
========

Effects can be enabled/disabled in KConfig module accessible by right-clicking
on a window title, choosing "Configure Window Behaviour" and then
"Window Effects".