fgdata/Docs/source/opengl.tex

%%
%% getstart.tex -- Flight Gear documentation: Installation and Getting Started
%% Chapter file
%%
%% Written by Michael Basler % Bernhard Buckel, starting September 1998.
%%
%% Copyright (C) 2002 Michael Basler (pmb@epost.de)
%%                  & Bernhard Buckel (buckel@wmad95.mathematik.uni-wuerzburg.de)
%%
%% This program is free software; you can redistribute it and/or
%% modify it under the terms of the GNU General Public License as
%% published by the Free Software Foundation; either version 2 of the
%% License, or (at your option) any later version.
%%
%% This program is distributed in the hope that it will be useful, but
%% WITHOUT ANY WARRANTY; without even the implied warranty of
%% MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
%% General Public License for more details.
%%
%% You should have received a copy of the GNU General Public License
%% along with this program; if not, write to the Free Software
%% Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
%%
%% $Id: opengl.tex,v 0.6 2002/09/09 michael
%% (Log is kept at end of this file)
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\chapter{Some words on OpenGL graphics drivers\label{opengl}}
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\markboth{\thechapter.\hspace*{1mm} GETTING THE ENGINE}{\thesection\hspace*{1mm}
INSTALLING DRIVERS}

\FlightGear{}'s graphics engine is based on a \Index{graphics library} called
\Index{OpenGL}. Its primary advantage is its platform independence, i.\,e., programs
written with \Index{OpenGL} support can be compiled and executed on several platforms,
given the proper drivers having been installed in advance. Thus, independent of if you
want to run the binaries only or if you want to compile the program yourself you must
have some sort of \Index{OpenGL} support installed for your \Index{video card}.

A good review  on OpenGL drivers\index{OpenGL drivers} can be found at
\medskip

\web{http://www.flightgear.org/Hardware}.
 \medskip

 \noindent
 Specific information is collected for windows at
  \medskip

\web{http://www.x-plane.com/SYSREQ/v5ibm.html}
 \medskip

 \noindent
 and for Macintosh at
  \medskip

\web{http://www.x-plane.com/SYSREQ/v5mac.html}.
 \medskip

%%Bernhard, 21.02.1999,25.06.1999
 \noindent
An excellent place to look for documentation about Linux and 3-D accelerators is the {\it
Linux \Index{Quake} HOWTO} at
 \medskip

\web{http://www.linuxquake.com}.
 \medskip

\noindent
 This should be your first aid in case something goes wrong with your Linux 3-D setup.

Unfortunately, there are so many graphics boards, chips and drivers out there that we are
unable to provide a complete description for all systems. Given the present market
dominance of NVIDIA combined with the fact that their chips have indeed been proven
powerful for running \FlightGear{}$\!$, we will concentrate on NVIDIA
drivers\index{NVIDIA!drivers} in what follows.

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\section{NVIDIA chip based cards under \Index{Linux}\label{nvidialinux}}
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
Recent \Index{Linux} distributions include and install anything needed to run OpenGL
programs under \Index{Linux}. Usually there is no need to install anything else.

If for whatever reason this does not work, you may try to download the most recent
drivers from the NVIDIA site at
 \medskip

\web{http://www.nvidia.com/Products/Drivers.nsf/Linux.html}
 \medskip

 \noindent
At present, this page has drivers for all NVIDIA chips for the following Linux
distributions:\index{NVIDIA!Linux drivers} RedHat 7.1, Redhat 7.0, Redhat 6.2, Redhat
6.1, Mandrake 7.1, Mandrake 7.2, SuSE 7.1, SuSE 7.0 in several formats (.rpm, .tar.gz).
These drivers support OpenGL natively and do not need any additional stuff.

The page named above contains a detailed \texttt{README and Installation Guide} giving a
step-by-step description, making it unnecessary to copy the material here.

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\section{NVIDIA chip based cards under \Index{Windows}\label{nvidiawindows}}
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

Again, you may first try the drivers coming with your graphics card. Usually they should
include \Index{OpenGL} support. If for whatever reason the maker of your board did not
include this feature into the driver, you should install the \Index{Detonator reference
drivers}\index{NVIDIA!Windows drivers} made by \Index{NVIDIA} (which might be a good idea
anyway). These are available in three different versions (Windows 95/98/ME, Windows 2000,
Windows NT) from
 \medskip

  \web{http://www.nvidia.com/products.nsf/htmlmedia/detonator3.html}
  \medskip

\noindent
 Just read carefully the Release notes to be found on that page. Notably do not
forget to uninstall your present driver and install a standard VGA graphics adapter
before switching to the new NVIDIA drivers first.


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\section{3DFX chip based cards under \Index{Windows}\label{3dfxwindows}}
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

With the Glide drivers no longer provided by 3DFX there seems to be little chance to get
it running (except to find older OpenGL drivers somewhere on the net or privately). All
pages which formerly provided official support or instructions for 3DFX are gone now. For
an alternative, you may want to check the next section, though.


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\section{An alternative approach for Windows users}
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

There is now an attempt to build a program which detects the graphics chip on your board
and automatically installs the appropriate OpenGL drivers. This is called \Index{OpenGL
Setup} and is presently in beta stage. It's home page can be found at
\medskip

\web{http://www.glsetup.com/}.
\medskip

We did not try this ourselves, but would suggest it for those completely lost.

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\section{3DFX chip based cards under \Index{Linux}\label{3dfxlinux}}
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

%% MAS, 19.06.2001
Notably, with \Index{3DFX} now having been taken over by \Index{NVIDIA}, manufacturer's
support already has disappeared. However with XFree86-4.x (with x at least being greater
than 1) Voodoo3 cards are known to be pretty usable in 16 bit color mode. Newer cards
should work fine as well. If you are still running a version of Xfree86 3.X and run into
problems, consider an upgrade. The recent distributions by Debian or SuSE have been
reported to work well.

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\section{ATI chip based cards under \Index{Linux}\index{ATI}\label{atilinux}}
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

There is support for \Index{ATI} chips in XFree86-4.1 and greater. Lots of
AGP boards based on the Rage128 chip - from simple Rage128 board to ATI
Xpert2000 - are mostly usable for FlightGear. Since XFree86-4.1 you can use
early Radeon chips - up to Radeon7500 with XFree86-4.2.

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\section{Building your own OpenGL support under \Index{Linux}\index{OpenGL}\label{ownopengl}}
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

Setting up proper OpenGL support\index{OpenGL!Linux} with a recent Linux distribution should be
pretty simple. As an example \Index{SuSE} ships everything you need plus some small
shell scripts to adjust the missing bits automagically. If you just want to
execute pre-built binaries of FlightGear, then you're done by using the
supplied \FlightGear{} package plus the mandantory runtime libraries (and
kernel modules). The package manager will tell you which ones to choose.

In case you want to run a self-made kernel, you want to compile \FlightGear{}
yourself, you're tweaking your X server configuration file yourself or you
even run a homebrewed Linux ''distribution'' (this means, you want to compile
everything yourself), this chapter might be useful for you.

Now let's have a look at the parts that build OpenGL support on Linux. First
there's a Linux kernel with support for your graphics adapter.

Examples on which graphics hardware is supported natively by Open Source
drivers are provided on
\medskip

\noindent
\web{http://dri.sourceforge.net/status.phtml}.
\medskip

There are a few graphics chip families that are not directly or no more than
partly supported by \Index{XFree86}, the X window implementation on Linux, because
vendors don't like to provide programming information on their chips. In
these cases - notably IBM/DIAMOND/now: \Index{ATI} FireGL graphics boards and \Index{NVIDIA}
GeForce based cards - you depend on the manufacturers will to follow the
ongoing development of the XFree86 graphics display infrastructure. These
boards might prove to deliver impressing performance but in many cases -
considering the CPU's speed you find in today's PC's - you have many choices
which all lead to respectable performance of \FlightGear{}.

As long as you use a distribution provided kernel, you can expect to find
all necessary kernel modules at the appropriate location. If you compile the
kernel yourself, then you have to take care of two sub-menus in the kernel
configuration menu. You'll find them in the ''Character devices'' menu.
Please notice that AGP support is not compulsory for hardware accelerated
OpenGL support on Linux. This also works quite fine with some PCI cards
(\Index{3dfx} Voodoo3 PCI for example, in case you still own one). Although every
modern PC graphics card utilizes the AGP 'bus' for fast data transfer.

Besides ''\Index{AGP Support}'' for your chipset - you might want to ask your
mainboard manual which one is on - you definitely want to activate ''Direct
Rendering Manager'' for your graphics board. Please note that recent releases
of XFree86 - namely 4.1.0 and higher might not be supported by the DRI
included in older Linux kernels. Also newer 2.4.x kernels from 2.4.8 up to
2.4.17 do not support DRI in XFree86-4.0.x.

After building and installing your kernel modules and the kernel itself this
task might be completed by loading the 'agpgart' module manually or, in case
you linked it into the kernel, by a reboot in purpose to get the new kernel
up and running. While booting your kernel on an AGP capable mainboard you
may expect boot messages like this one:
\medskip

\begin{ttfamily}
\noindent
> Linux agpgart interface v0.99 (c) Jeff Hartmann\\
> gpgart: Maximum main memory to use for agp memory: 439M\\
> agpgart: Detected Via Apollo Pro chipset\\
> agpgart: AGP aperture is 64M @ 0xe4000000
\end{ttfamily}
\medskip

If you don't encounter such messages on Linux kernel boot, then you might
have missed the right chip set. Part one of activation hardware accelerated OpenGL support on your Linux system is now completed.

The second part consists of configuring your \Index{X server} for OpenGL. This is
not a big deal as it simply consists of to instructions to load the
appropriate modules on startup of the X server.
This is done by editing the configuration file \texttt{/etc/X11/XF86Config}. Today's
Linux distributions are supposed to provide a tool that does this job for
you on your demand. Please make sure there are these two instructions:
\medskip


 \texttt{Load ''glx''}
 
 \texttt{Load ''dri''}
\medskip

\noindent
in the ''Module'' section your \Index{X server} configuration file. If everything is
right the X server will take care of loading the appropriate Linux kernel
module for DRI support of your graphics card. The right Linux kernel module
name is determined by the 'Driver' statement in the ''Device'' section of the
XF86Config. Please see three samples on how such a ''Device'' section should
look like:
\medskip

\begin{ttfamily}
\noindent
  Section ''Device''
    
  
    BoardName  	''3dfx Voodoo3 PCI'' 
        
    BusID  	''0:8:0''
        
    Driver  	''tdfx''
    
    Identifier  ''Device[0]''
    
    Screen  	0
    
    VendorName  ''3Dfx''
    
 
\noindent   
  EndSection
  \medskip

\noindent   
  Section ''Device''
  
  
    BoardName  	''ATI Xpert2000 AGP''
    
    BusID  	''1:0:0''
    
    Driver  	''ati''
    
    Option	''AGPMode'' ''1''
    
    Identifier  ''Device[0]''
    
    Screen  	0
    
    VendorName  ''ATI''
    
 \noindent   
  EndSection
 \medskip

\noindent   
  Section ''Device''
  
    BoardName    ''ATI Radeon 32 MB DDR AGP''
    
    BusID        ''1:0:0''
    
    Driver       ''radeon''
    
    Option	 ''AGPMode'' ''4''
    
    Identifier   ''Device[0]''
    
    Screen       0
    
    VendorName   ''ATI''
    
\noindent   
  EndSection
  \medskip
  \end{ttfamily}

By using the Option ''AGPMode'' you can tune AGP performance as long as the
mainboard and the graphics card permit. The BusID on \Index{AGP} systems should
always be set to ''1:0:0'' - because you only have one AGP slot on your board
- whereas the \Index{PCI} BusID differs with the slot your graphics card has been
applied to. 'lspci' might be your friend in desperate situations. Also a
look at the end of /var/log/XFree86.0.log, which should be written on X
server startup, should point to the PCI slot where your card resides.

This has been the second part of installing hardware accelerated OpenGL
support on your Linux box.

The third part carries two subparts: First there are the OpenGL runtime
libraries,\index{OpenGL!runtime libraries} sufficient to run existing appliactions. For compiling FlightGear you also need the suiting developmental headers.
As compiling the whole X window system is not subject to this abstract we
expect that your distribution ships the necessary libraries and headers. In
case you told your package manager to install some sort of OpenGL support
you are supposed to find some OpenGL test utilities, at least there should
be 'glxinfo' or 'gl-info'.

These command-line utilities are useful to say if the previous steps where
successfull. If they refuse to start, then your package manager missed
something because he should have known that these utilities usually depend
on the existence of OpenGL runtime libraries. If they start, then you're one
step ahead. Now watch the output of this tool and and have a look at the
line that starts with

\Index{OpenGL renderer string}:

If you find something like
\medskip

  \texttt{OpenGL renderer string: FireGL2 / FireGL3 (Pentium3)}
  \medskip

\noindent
or
\medskip

  \texttt{OpenGL renderer string: Mesa DRI Voodoo3 20000224}
  \medskip

\noindent
or
\medskip

  \texttt{OpenGL renderer string: Mesa DRI Radeon 20010402}
    
  \texttt{AGP 4x x86}
  \medskip

  \texttt{OpenGL renderer string: Mesa GLX Indirect}
  \medskip

\noindent
mind the word 'Indirect', then it's you who missed something, because OpenGL
gets dealt with in a software library running solely on your CPU. In this
case you might want to have a closer look at the preceding paragraphs of
this chapter. Now please make sure all necessary libraries are at their
proper location.
You will need three OpenGL libraries for running \FlightGear{}. In most cases
you will find them in /usr/lib/:

\texttt{/usr/lib/libGL.so.1}

\texttt{/usr/lib/libGLU.so.1}

\texttt{/usr/lib/libglut.so.3}

These may be the libraries itself or symlinks to appropriate libraries
located in some other directories. Depending on the distribution you use
these libraries might be shipped in different packages. \Index{SuSE} for example
ships libGL in package 'xf86\_glx', libGLU in 'xf86glu' and libglut in
'mesaglut'. Additionally for \FlightGear{} you need libplib which is part of
the 'plib' package.

For compiling \FlightGear{} yourself - as already mentioned - you need the
appropriate header files which often reside in /usr/include/GL/. Two are
necessary for libGL and they come in - no, not 'xf86glx-devel' (o.k., they
do but they do not work correctly) but in 'mesa-devel':
\medskip

\texttt{/usr/include/GL/gl.h}

\texttt{/usr/include/GL/glx.h}
\medskip

\noindent
One comes with libGLU in 'xf86glu-devel':
\medskip

\texttt{/usr/include/GL/glu.h}
\medskip

and one with libglut in 'mesaglut-devel'
\medskip

\texttt{/usr/include/GL/glut.h}
\medskip

The 'plib' package comes with some more libraries and headers that are too
many to be mentioned here. If all this is present and you have a comfortable
compiler environment, then you are ready to compile \FlightGear{} and enjoy the
result.


Further information on \Index{OpenGL} issues of specific \Index{XFree86} releases is
available here:
\medskip

\underline{http://www.xfree86.org/{$<$}RELEASE NUMBER{$>$}/DRI.html}

\medskip

\noindent
Additional reading on \Index{DRI}:
\medskip

\web{http://www.precisioninsight.com/piinsights.html}
\medskip

\noindent
In case you are missing some 'spare parts':
\medskip

\web{http://dri.sourceforge.net/res.phtml}


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\section{OpenGL on Macintosh}\index{OpenGL!Macintosh}
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

OpenGL is pre-installed on Mac OS 9.x and later. You may find a newer version than the one installed for \Index{Mac OS 9.x} at
\medskip

\web{http://www.apple.com/opengl}
\medskip

You should receive the updates automatically for \Index{Mac OSX}.


 \noindent
 \textbf{One final word:} We would recommend that you test your \Index{OpenGL} support
 with one of the programs that accompany the drivers, to be absolutely confident
that it is functioning well. There are also many little programs, often available as
screen savers, that can be used for testing.  It is important that you are confident in
your graphics acceleration because \FlightGear{} will try to run the card as fast as
possible. If your drivers aren't working well, or are unstable, you will have difficulty
tracking down the source of any problems and have a frustrating time.

%% Revision 0.00  1998/09/08  michael
%% Initial revision for version 0.53.
%% incl. Linux stuff from b buckel
%% Revision 0.01  1998/09/20  michael
%% several extensions and corrections
%% revision 0.10  1998/10/01  michael
%% added 3dfx stuff from b. buckel
%% final proofreading for release
%% revision 0.11  1998/11/01  michael
%% Remark on mini-OpenGL drivers
%% revision 0.12  1999/03/07  bernhard
%% Complete rewrite of 3DFX/Linux part
%% revision 0.12  1999/03/07  michael
%% Added Riva TNT Win95
%% Added 3DFX Win95
%% revision 0.20  1999/06/04  michael
%% corrections of links
%% revision 0.21 1999/06/30 bernhard
%% updated and expanded 3DFX/Linux
%% revision 0.3 2000/04/20 michael
%% Minor corrections, mainly on software rendering
%% revision 0.31 2000/05/01 michael
%% Added remarks on OpenGL/Matrox by Alex Perry
%% revision 0.5 2002/01/01 michael/martin
%% completely shortened and rewritten
%% removed all stuff old cards, notably 3DFX related
%% added new description for NVIDIA cards
%% removed section on software rendering - no longer useful,
%% added OpenGL setup
%% Section ATI chip based cards under Linux by Martin
%% revision 0.6 2002/01/01 michael
%% removed numerous spelling errors :-(