                   Installing and using Compiz Fusion

  Manolis Kiagias

   <manolis@FreeBSD.org>

   $FreeBSD:
   doc/en_US.ISO8859-1/articles/compiz-fusion/article.sgml,v 1.6
   2008/06/15 15:58:38 keramida Exp $

   Copyright (c) 2008 Manolis Kiagias

   FreeBSD is a registered trademark of the FreeBSD Foundation.

   Many of the designations used by manufacturers and sellers to
   distinguish their products are claimed as trademarks. Where those
   designations appear in this document, and the FreeBSD Project was
   aware of the trademark claim, the designations have been followed
   by the "(TM)" or the "(R)" symbol.

   The Linux world has been overwhelmed lately by what seems to be
   the latest fashion: 3D Desktop effects. While their usefulness is
   rather heavily debated, the wow factor behind the composited
   desktop holds quite well. Several different programs have emerged,
   like Compiz, Beryl, and the latest Compiz Fusion. You do not need
   to miss these effects when using FreeBSD. These instructions will
   help you install and configure your system for the latest 3D
   desktop experience using Compiz Fusion and nVidia drivers (if
   applicable).

     --------------------------------------------------------------

1 Introduction

   While installing Compiz Fusion from the Ports Collection is a
   rather trivial task, configuring it requires a few more steps that
   are not described in the port's documentation. This article will
   help you configure your Xorg server for composite operation, setup
   your nVidia card, and finally guide you to the final steps for
   executing the compiz program itself.

   After reading this article, you will know:

     * How to setup the latest nVidia driver (if required) for your
       system.

     * How to setup your xorg.conf file for desktop composition.

     * How to install and configure Compiz Fusion using the
       Ports Collection.

     * How to troubleshoot common problems associated with desktop
       effects.

     --------------------------------------------------------------

2 Setting up the FreeBSD nVidia driver

   Desktop effects can cause quite a load on your graphics card. If
   you are using an nVidia-based graphics card, you will need to
   install and configure the proprietary FreeBSD driver that is
   suitable for your system. If you are using another card, that you
   know can handle desktop effects, you may skip this section and
   continue with the xorg.conf configuration.

     --------------------------------------------------------------

  2.1 Determining the correct driver to use

   There are various versions of the nVidia drivers in the
   Ports Collection. The correct one to use depends on the actual
   model (and age) of your graphics card:

     * The latest versions of nVidia cards are supported by the
       x11/nvidia-driver port.

     * nVidia cards like the GeForce 2MX/3/4 series are supported by
       the 96XX series of drivers, available in the
       x11/nvidia-driver-96xx port.

     * Even older cards, like GeForce and RIVA TNT are supported by
       the 71XX series of drivers, available in the
       x11/nvidia-driver-71xx port.

   In fact, nVidia provides detailed information on which card is
   supported by which driver. This information is available directly
   on their web site: http://www.nvidia.com/object/IO_32667.html.

     --------------------------------------------------------------

  2.2 Installing the nVidia driver

   Having determined the correct driver to use for your card,
   installation is as simple as installing any other port.

     Note: Make sure to update your ports tree using your favorite
     method (like csup, CVSup or portsnap) before you install any
     application from the ports system. Graphics drivers and the
     desktop effects programs are under heavy development, and are
     updated regularly.

   For example, to install the latest driver:

 # cd /usr/ports/x11/nvidia-driver
 # make install clean

   The driver will create a kernel module, which should be loaded at
   system startup. You will need to add the following line to the
   /boot/loader.conf file:

 nvidia_load="YES"

     Note: You may attempt to immediately load the kernel module into
     the running kernel by issuing a command like kldload nvidia,
     however it has been noted that the latest versions of Xorg will
     not function properly if the driver is not loaded at boot time.
     After editing /boot/loader.conf, a reboot is recommended.

   With the kernel module loaded, you normally only need to change a
   single line in your xorg.conf file to enable the proprietary
   driver:

   Find the following line in /etc/X11/xorg.conf:

 Driver      "nv"

   and change it to:

 Driver      "nvidia"

   Start your GUI as usual, and you should be greeted by the nVidia
   splash. Everything should work as usual. Note, that at this point
   you have only set up Xorg to use the nVidia driver, but further
   configuration is needed before you can actually use 3D desktop
   effects. This is described in the following sections.

     Note: Although not strictly necessary, you may also wish to
     install x11/nvidia-xconfig and x11/nvidia-settings ports. The
     former can assist you in writing settings to /etc/X11/xorg.conf
     from the command line, and the latter will allow you to modify
     screen settings from a GUI while running the Xorg system.

     --------------------------------------------------------------

3 Configuring xorg.conf for desktop effects

   Before you install and run Compiz Fusion, you need to add a few
   settings to /etc/X11/xorg.conf:

   Add the following section to enable composite effects:

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

   Locate the "Screen" section which should look similar to the one
   below:

 Section "Screen"
 Identifier     "Screen0"
 Device         "Card0"
 Monitor        "Monitor0"
 ...

   and add the following two lines (after "Monitor" will do):

 DefaultDepth    24
 Option         "AddARGBGLXVisuals" "True"

   Locate the "Subsection" that refers to the screen resolution that
   you wish to use. For example, if you wish to use 1280x1024, locate
   the section that follows. If the desired resolution does not
   appear in any subsection, you may add the relevant entry by hand:

 SubSection     "Display"
 Viewport    0 0
 Modes      "1280x1024"
 EndSubSection

   A color depth of 24 bits is needed for desktop composition, change
   the above subsection to:

 SubSection     "Display"
 Viewport    0 0
 Depth       24
 Modes      "1280x1024"
 EndSubSection

   Finally, confirm that the "glx" and "extmod" modules are loaded in
   the "Module" section:

 Section "Module"
 Load           "extmod"
 Load           "glx"
 ...

     Note: If you installed the x11/nvidia-xconfig port, you should
     be able to perform most of the above settings by entering the
     following commands (as root):

 # nvidia-xconfig --add-argb-glx-visuals
 # nvidia-xconfig --composite
 # nvidia-xconfig --depth=24

     You may wish to run nvidia-xconfig -A | more to see a list of
     all the options offered by the above program.

     --------------------------------------------------------------

4 Installing and configuring Compiz Fusion

   Installing Compiz Fusion is as simple as any other port:

 # cd /usr/ports/x11-wm/compiz-fusion
 # make install clean

   Make sure to select the "EXTRA" plugins and the "EMERALD" window
   decorator from the options dialog that appears. If you are using
   GNOME, or already have support for gconf in your system, you may
   also wish to select "gconf support". In this way, your effect
   settings will be integrated with the other desktop settings, and
   will be viewable via gconf-editor. Compiz Fusion can however save
   its settings to flat files, if such an integration is not wanted.
   In this case, a .compizconfig directory will be created inside
   your home directory.

   When the installation is finished, start your graphic desktop and
   at a terminal, enter the following commands (as a normal user):

 % compiz --replace --sm-disable --ignore-desktop-hints ccp &
 % emerald --replace &

   Your screen will flicker for a few seconds, as your window manager
   (e.g. Metacity if you are using GNOME) is replaced by
   Compiz Fusion. Emerald takes care of the window decorations (i.e.
   close, minimize, maximize buttons, title bars and so on).

   You may convert this to a trivial script and have it run at
   startup automatically (e.g. by adding to "Sessions" in a GNOME
   desktop):

 #! /bin/sh
 compiz --replace --sm-disable --ignore-desktop-hints ccp &
 emerald --replace &

   Save this in your home directory as, for example, start-compiz and
   make it executable:

 % chmod +x ~/start-compiz

   Then use the GUI to add it to Startup Programs (located in System,
   Preferences, Sessions on a GNOME desktop).

   To actually select all the desired effects and their settings,
   execute (again as a normal user) the
   Compiz Config Settings Manager:

 % ccsm

     Note: In GNOME, this can also be found in the System,
     Preferences menu.

   If you have selected "gconf support" during the build, you will
   also be able to view these settings using gconf-editor under
   apps/compiz.

     --------------------------------------------------------------

5 Troubleshooting Compiz Fusion

   The following section covers frequently asked questions regarding
   problems when running Compiz Fusion.

   5.1. I have installed Compiz Fusion, and after running the
   commands you mention, my windows are left without title bars and
   buttons. What is wrong?

   5.2. When I run the command to start Compiz Fusion, the X server
   crashes and I am back at the console. What is wrong?

   5.1. I have installed Compiz Fusion, and after running the
   commands you mention, my windows are left without title bars and
   buttons. What is wrong?

   You are probably missing a setting in /etc/X11/xorg.conf. Review
   this file carefully and check especially the DefaultDepth and
   AddARGBGLXVisuals directives.

   5.2. When I run the command to start Compiz Fusion, the X server
   crashes and I am back at the console. What is wrong?

   If you check your /var/log/Xorg.0.log file, you will probably find
   error messages during the X startup. The most common would be:

 (EE) NVIDIA(0):     Failed to initialize the GLX module; please check in your X
 (EE) NVIDIA(0):     log file that the GLX module has been loaded in your X
 (EE) NVIDIA(0):     server, and that the module is the NVIDIA GLX module.  If
 (EE) NVIDIA(0):     you continue to encounter problems, Please try
 (EE) NVIDIA(0):     reinstalling the NVIDIA driver.

   This is usually the case when you upgrade Xorg. You will need to
   reinstall the x11/nvidia-driver port so glx is built again.

     --------------------------------------------------------------

           This, and other documents, can be downloaded from
                ftp://ftp.FreeBSD.org/pub/FreeBSD/doc/.

 For questions about FreeBSD, read the documentation before contacting
                        <questions@FreeBSD.org>.
   For questions about this documentation, e-mail <doc@FreeBSD.org>.
