<?xml version="1.0" encoding="iso-8859-1"?>
<!DOCTYPE article PUBLIC "-//FreeBSD//DTD DocBook XML V5.0-Based Extension//EN"
	"http://www.FreeBSD.org/XML/share/xml/freebsd50.dtd">
<article xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0" xml:lang="en">
  <info><title>Installing and using Compiz&nbsp;Fusion</title>
    

    <author><personname><firstname>Manolis</firstname><surname>Kiagias</surname></personname><affiliation>
	<address><email>manolis@FreeBSD.org</email></address>
      </affiliation></author>

    <copyright>
      <year>2008</year>
      <holder role="mailto:manolis@FreeBSD.org">Manolis Kiagias</holder>
    </copyright>

    <pubdate>$FreeBSD$</pubdate>

    <releaseinfo>$FreeBSD$</releaseinfo>

    <legalnotice xml:id="trademarks" role="trademarks">
      &tm-attrib.freebsd;
      &tm-attrib.general;
    </legalnotice>

    <abstract>
      <para>One way to increase the pleasantness of using a desktop
	computer is by having nice 3D effects.
	This article walks through the installation
	<application>Compiz</application> which is one example
	program which to produce nice effects.  It assumes the use of
	nVidia drivers, although these are not required.</para>
    </abstract>
  </info>

  <sect1 xml:id="introduction">
    <title>Introduction</title>

    <para>While installing <application>Compiz&nbsp;Fusion</application> from
      the Ports&nbsp;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
      <application>&xorg;</application> server for composite operation,
      setup your nVidia card, and finally guide you to the final steps for
      executing the <command>compiz</command> program itself.</para>

    <para>After reading this article, you will know:</para>

    <itemizedlist>
      <listitem>
	<para>How to setup the latest nVidia driver (if required) for your
	  system.</para>
      </listitem>

      <listitem>
	<para>How to setup your <filename>xorg.conf</filename> file for
	  desktop composition.</para>
      </listitem>

      <listitem>
	<para>How to install and configure
	  <application>Compiz&nbsp;Fusion</application> using the
	  Ports&nbsp;Collection.</para>
      </listitem>

      <listitem>
	<para>How to troubleshoot common problems associated with
	  desktop effects.</para>
      </listitem>
    </itemizedlist>
  </sect1>

  <sect1 xml:id="nvidia-setup">
    <title>Setting up the &os; nVidia driver</title>

    <para>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 &os; 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
      <filename>xorg.conf</filename> configuration.</para>

    <para>
      To determine which nVidia driveris needed see the <link xlink:href="&url.books.faq;/x.html#idp59950544">FAQ question
      on the subject</link>.
    </para>

    <sect2 xml:id="install-driver">
      <title>Installing the nVidia driver</title>

      <para>Having determined the correct driver to use for your card,
	installation is as simple as installing any other package.</para>

      <para>For example, to install the latest driver:</para>

      <screen>&prompt.root; <userinput>pkg install x11/nvidia-driver</userinput></screen>

      <para>The driver will create a kernel module, which needs to be loaded
	at system startup.  Add the following line to
	<filename>/boot/loader.conf</filename>:</para>

      <programlisting>nvidia_load="YES"</programlisting>

      <note>
	<para>To immediately load the kernel module into the
	  running kernel by issuing a command like
	  <command>kldload nvidia</command>, however it has been noted that
	  the some versions of <application>&xorg;</application> will not
	  function properly if the driver is not loaded at boot time.  After
	  editing <filename>/boot/loader.conf</filename>, a reboot is
	  recommended.</para>
      </note>

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

      <para>Find the following line in
	<filename>/etc/X11/xorg.conf</filename>:</para>

      <programlisting>Driver      "nv"</programlisting>

      <para>and change it to:</para>

      <programlisting>Driver      "nvidia"</programlisting>

      <para>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 <application>&xorg;</application> 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.</para>

      <note>
	<para>Although not strictly necessary, you may also wish to install
	  <package>x11/nvidia-xconfig</package> and
	  <package>x11/nvidia-settings</package> ports.  The
	  former can assist you in writing settings to
	  <filename>/etc/X11/xorg.conf</filename> from the command line, and
	  the latter will allow you to modify screen settings from a GUI while
	  running the <application>&xorg;</application> system.</para>
      </note>
    </sect2>
  </sect1>

  <sect1 xml:id="xorg-configuration">
    <title>Configuring xorg.conf for desktop effects</title>

    <para>Before you install and run
      <application>Compiz&nbsp;Fusion</application>, you need to add a few
      settings to <filename>/etc/X11/xorg.conf</filename>:</para>

    <para>Add the following section to enable composite effects:</para>

    <programlisting>Section "Extensions"
Option         "Composite" "Enable"
EndSection</programlisting>

    <para>Locate the <quote>Screen</quote> section which should look similar
      to the one below:</para>

    <programlisting>Section "Screen"
Identifier     "Screen0"
Device         "Card0"
Monitor        "Monitor0"
...</programlisting>

    <para>and add the following two lines (after <quote>Monitor</quote> will
      do):</para>

    <programlisting>DefaultDepth    24
Option         "AddARGBGLXVisuals" "True"</programlisting>

    <para>Locate the <quote>Subsection</quote> 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:</para>

    <programlisting>SubSection     "Display"
Viewport    0 0
Modes      "1280x1024"
EndSubSection</programlisting>

    <para>A color depth of 24&nbsp;bits is needed for desktop composition,
      change the above subsection to:</para>

    <programlisting>SubSection     "Display"
Viewport    0 0
Depth       24
Modes      "1280x1024"
EndSubSection</programlisting>

    <para>Finally, confirm that the <quote>glx</quote> and
      <quote>extmod</quote> modules are loaded in the <quote>Module</quote>
      section:</para>

    <programlisting>Section "Module"
Load           "extmod"
Load           "glx"
...</programlisting>

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

      <screen>&prompt.root; <userinput>nvidia-xconfig --add-argb-glx-visuals</userinput>
&prompt.root; <userinput>nvidia-xconfig --composite</userinput>
&prompt.root; <userinput>nvidia-xconfig --depth=24</userinput></screen>

      <para>You may wish to run <command>nvidia-xconfig -A | more</command>
	to see a list of all the options offered by the above program.</para>
    </note>
  </sect1>

  <sect1 xml:id="compiz-fusion">
    <title>Installing and configuring Compiz&nbsp;Fusion</title>

    <para>Installing <application>Compiz&nbsp;Fusion</application>
      is as simple as any other package:</para>

    <screen>&prompt.root; <userinput>pkg install x11-wm/compiz-fusion</userinput></screen>

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

    <screen>&prompt.user; <userinput>compiz --replace --sm-disable --ignore-desktop-hints ccp &amp;</userinput>
&prompt.user; <userinput>emerald --replace &amp;</userinput></screen>

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

    <para>You may convert this to a trivial script and have it run at
      startup automatically (e.g. by adding to <quote>Sessions</quote> in
      a <application>GNOME</application> desktop):</para>

    <programlisting>#! /bin/sh
compiz --replace --sm-disable --ignore-desktop-hints ccp &amp;
emerald --replace &amp;</programlisting>

    <para>Save this in your home directory as, for example,
      <filename>start-compiz</filename> and make it executable:</para>

    <screen>&prompt.user; <userinput>chmod +x ~/start-compiz</userinput></screen>

    <para>Then use the GUI to add it to
      <guimenuitem>Startup Programs</guimenuitem>
      (located in <guimenuitem>System</guimenuitem>,
      <guimenuitem>Preferences</guimenuitem>,
      <guimenuitem>Sessions</guimenuitem> on a
      <application>GNOME</application> desktop).</para>

    <para>To actually select all the desired effects and their settings,
      execute (again as a normal user) the
      <application>Compiz&nbsp;Config&nbsp;Settings&nbsp;Manager</application>:</para>

    <screen>&prompt.user; <userinput>ccsm</userinput></screen>

    <note>
      <para>In <application>GNOME</application>, this can also be found in
	the <guimenuitem>System</guimenuitem>,
	<guimenuitem>Preferences</guimenuitem> menu.</para>
    </note>

    <para>If you have selected <quote>gconf support</quote> during the build,
      you will also be able to view these settings using
      <command>gconf-editor</command> under <literal>apps/compiz</literal>.
    </para>
  </sect1>

  <sect1 xml:id="compiz-troubleshooting">
    <title>Troubleshooting Compiz&nbsp;Fusion</title>

    <para>The following section covers frequently asked questions regarding
      problems when running
      <application>Compiz&nbsp;Fusion</application>.</para>

    <qandaset>
      <qandaentry>
	<question xml:id="no-decorations">
	  <para>I have installed
	    <application>Compiz&nbsp;Fusion</application>,
	    and after running the commands you mention, my windows are left
	    without title bars and buttons.  What is wrong?</para>
	</question>

	<answer>
	  <para>You are probably missing a setting in
	    <filename>/etc/X11/xorg.conf</filename>.  Review this file
	    carefully and check especially the <literal>DefaultDepth</literal>
	    and <literal>AddARGBGLXVisuals</literal> directives.</para>
	</answer>
      </qandaentry>

      <qandaentry>
	<question xml:id="xorg-crash">
	  <para>When I run the command to start
	    <application>Compiz&nbsp;Fusion</application>, the X server
	    crashes and I am back at the console.  What is wrong?</para>
	</question>

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

	  <screen>(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.</screen>

	  <para>This is usually the case when you upgrade
	    <application>&xorg;</application>.  You will need to reinstall the
	    <package>x11/nvidia-driver</package> port so
	    glx is built again.</para>
	</answer>
      </qandaentry>
    </qandaset>
  </sect1>
</article>