                       Installing and using Compiz Fusion

  Manolis Kiagias

   <manolis@FreeBSD.org>

   Revision: 43126

   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.

   Last modified on 2013-11-07 by gabor.
   Abstract

   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).

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

   Table of Contents

   1. Introduction

   2. Setting up the FreeBSD nVidia driver

   3. Configuring xorg.conf for desktop effects

   4. Installing and configuring Compiz Fusion

   5. Troubleshooting Compiz Fusion

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 (e.g.,
   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.                                   
