path: root/xc/programs/Xserver/hw/xfree86/doc/sgml/DRI.sgml

<!DOCTYPE linuxdoc PUBLIC "-//XFree86//DTD linuxdoc//EN" [
<!ENTITY % defs SYSTEM "defs.ent"> %defs;
]>

<!-- Created: Mon Feb 28 13:00:00 2000 by brianp@valinux.com -->
<!-- Revised: Fri May 19 09:41:48 2000 by martin@valinux.com -->
<!-- Revised: Tue Aug 22 14:00:00 2000 by brianp@valinux.com -->

  <article>

      <title>DRI User Guide
      <author>
          <htmlurl url="http://www.valinux.com/"
            name="VA Linux Systems, Inc."> Professional Services - Graphics.
      <date>24 October 2000

    <ident>
    $XFree86: xc/programs/Xserver/hw/xfree86/doc/sgml/DRI.sgml,v 1.7 2000/08/28 18:24:15 dawes Exp $
    </ident>

    <toc>

    <sect>Preamble
<p>
      <sect1>Copyright
<p>
          <bf>Copyright &copy; 2000 by VA Linux Systems, Inc.
          All Rights Reserved.</bf>
<p>
          <bf>Permission is granted to make and distribute verbatim copies 
          of this document provided the copyright notice and this permission
          notice are preserved on all copies.</bf>
          
      <sect1>Trademarks
<p>
          OpenGL is a registered trademark and SGI is a trademark of
          Silicon Graphics, Inc.
          Unix is a registered trademark of The Open Group.
          The `X' device and X Window System are trademarks of The Open Group.
          XFree86 is a trademark of The XFree86 Project.
          Linux is a registered trademark of Linus Torvalds.
          Intel is a registered trademark of Intel Corporation.
          3Dlabs, GLINT, and Oxygen are either registered trademarks or
          trademarks of 3Dlabs Inc. Ltd.
          3dfx, Voodoo3, Voodoo4, and Voodoo5 are registered trademarks of
          3dfx Interactive, Incorporated.
	  Matrox is a registered trademark of Matrox Electronic Systems Ltd.
	  ATI Rage is a registered trademark of ATI Technologies, Inc.
          All other trademarks mentioned are the property of their
          respective owners.

    <sect>Introduction
<p>
        With XFree86 4.0 and the Direct Rendering Interface
        (DRI), hardware accelerated 3D graphics can be considered a standard
        feature on Linux workstations.
        Support for other operating systems, such as FreeBSD, is underway.
      <p>
        This document describes how to use the DRI system and troubleshoot
        problems which may occur.
        Readers should have a basic understanding of Linux, X and OpenGL.
        See the resources section at the end for more documentation and
	software downloads.
      <p>
        This document does not cover compilation or installation of
        XFree86 4.0.
        It is assumed that you've already installed a Linux distribution which
        includes XFree86 4.0 or that you're an experienced Linux developer
        who has compiled the DRI for himself.
        DRI download, compilation and installation instructions can be found
        at <htmlurl url="http://dri.sourceforge.net/DRIcompile.html"
           name="http://dri.sourceforge.net/DRIcompile.html">
      <p>
        Edits, corrections and updates to this document may be mailed
        to brianp@valinux.com.


    <sect>Supported Hardware
<p>
        3D acceleration is currently only available for systems with
        Intel-compatible CPUs.
        Support for Alpha, and perhaps other CPUs, should be available in the
        future.
      <p>
        XFree86 4.0 (or later versions) includes 3D acceleration for the
        following graphics hardware:

        <itemize>
          <item>3dfx:
            <itemize>
              <item>Voodoo5 5500
              <item>Voodoo3 3500 TV
              <item>Voodoo3 3000 AGP
              <item>Voodoo3 3000 PCI
              <item>Voodoo3 2000 AGP
              <item>Voodoo3 2000 PCI
              <item>Voodoo Banshee
              <item>Velocity 100/200
            </itemize>
            There are many configurations of 3dfx cards on the market.
            Not all have been tested.
          <item>Matrox:
            <itemize>
	      <item>Matrox G200
	      <item>Matrox G400
            </itemize>
          <item>Intel i810
            <itemize>
              <item>i810
              <item>i810-dc100
              <item>i810e
            </itemize>
	  <item>ATI Rage 128
            <itemize>
              <item>Rage Fury AGP
              <item>Rage Magnum AGP
              <item>XPERT 2000 AGP
              <item>XPERT 128 AGP
	      <item>XPERT 99 AGP
	      <item>All-in-Wonder 128 AGP
            </itemize>
	    The PCI versions of these cards also have minimal support.
	    Note that there are also Rage 128 Pro based boards on the
	    market, and these are not yet supported.
          <item>3Dlabs Oxygen GMX 2000 (MX/Gamma based)
        </itemize>

      <p>
        Support for other hardware is underway.
      <p>


    <sect>Prerequisite Software
<p>
        <itemize>
          <item>The DRI is available in XFree86 4.0 and later.
          <item>Some hardware drivers require specific versions of the
                Linux kernel for AGP support, etc.
                See section 10 for specifics.
          <item>You <em>DO NOT</em> need to install Mesa separately.
                The parts of Mesa needed for hardware acceleration are
                already in the XFree86/DRI project.
        </itemize>


    <sect>Kernel Modules
    <p>
      3D hardware acceleration requires a DRI kernel module that's
      specific to your graphics hardware.
      <P>
      The DRI kernel module version must exactly match your running kernel
      version.
      Since there are so many versions of the kernel, it's difficult to
      provide precompiled kernel modules.
      <p>
      While the Linux source tree includes the DRI kernel module sources,
      the latest DRI kernel sources will be found in the DRI source tree.
      <p>
      See the DRI Compilation Guide for information on compiling the DRI
      kernel modules.
      <p>
      XFree86 4.0.1 added automatic kernel module loading to the X server.
      On Linux, the X server uses modprobe to load kernel modules.
      The DRM kernel modules should be in /lib/modules/KERNEL-VERSION/misc/
      for automatic loading to work.
      <p>
      Optionally, DRM kernel modules can be loaded manually with insmod
      prior to starting the X server.
      <p>
      You can verify that the kernel module was installed with lsmod,
      checking the X server startup log, and checking that /proc/dri/0
      exists. 

      <sect>XF86Config file
      <p>
        The XFree86 configuration file is usually found in
        <tt>/etc/X11/XF86Config</tt>.
        This section describes the parts which must be specially set for
        the DRI.
      <p>
        First, the XF86Config file must load the GLX and DRI modules:

        <verb>
	Section "Module"
	...
	# This loads the GLX module
	    Load       "glx"
	# This loads the DRI module
	    Load       "dri"
	EndSection
        </verb>

        Next, the DRI section can be used to restrict access to direct
        rendering.
        <p>
        If you want all of the users on your system to be able to use
        direct-rendering, then use a simple DRI section:
        <verb>
	Section "DRI"
	     Mode 0666
	EndSection
        </verb>
        <p>
        This section will allow any user with a current connection to the X
        server to use direct rendering.
        <p>
        If you want to restrict the use of direct-rendering to a
        certain group of users, then create a group for those users by
        editing the <tt>/etc/group</tt> file on your system.
        For example, you may want to create a group called <tt>xf86dri</tt>
        and place two users (e.g., <tt>fred</tt> and <tt>jane</tt>) in
        that group.
        To do that, you might add the following line to <tt>/etc/group</tt>:
        <verb>
        xf86dri:x:8000:fred,jane
        </verb>
        You have to be careful that the group id (8000 in this example)
        is unique.
        <p>
        Then you would use the following DRI section:
        <verb>
        Section "DRI"
             Group "xf86dri"
             Mode 0660
        EndSection
        </verb>
        This would limit access to direct-rendering to those users in the
        <tt>xf86dri</tt> group (<tt>fred</tt> and <tt>jane</tt> in this
        example).  When other users tried to use direct rendering, they
        would fall back to unaccelerated indirect rendering.
        <p>
        [Note that there is a known bug in XFree86 4.0 that prevents some
        changes to the DRI section from taking effect.  Until this bug is
        fixed, if you change the DRI section, please also remove the
        <tt>/dev/dri</tt> directory with the <tt>rm -rf /dev/dri</tt>
        command.]
        <p>
        Finally, the XF86Config file needs <tt>Device</tt> and
        <tt>Screen</tt> sections specific to your hardware.
        Look in section 10: <em>Hardware-Specific Information and
        Troubleshooting</em> for details.

    <sect>Memory usage
<p>
        Using the 3D features of a graphics card requires more memory
        than when it's just used as a 2D device.
        Double buffering, depth buffering, stencil buffers, textures,
        etc. all require extra graphics memory.
        These features may require four times the memory used for a simple
        2D display.
        <p>
        If your graphics card doesn't have a lot of memory (less than 16MB,
        for example), you may have to reduce your screen size and/or
        color depth in order to use 3D features.
        <p>
        The documentation included with your card should have information
        about maximum screen size when using 3D.


    <sect>Using 3D Acceleration
<p>
        This section describes how to link your application with libGL.so
        and verify that you are in fact using 3D acceleration.

      <sect1>libGL.so
<p>
          Your OpenGL program must link with the libGL.so.1.2 library provided
          by XFree86 4.0.
          The libGL.so.1.2 library contains a GLX protocol encoder for
          indirect/remote rendering and DRI code for accessing hardware
          drivers.
          In particular, be sure you're not using libGL.so from another
          source such as Mesa or the Utah GLX project.
        <p>
          Unless it was built in a special way, the libGL.so library does
          not contain any 3D hardware driver code.
          Instead, libGL.so dynamically loads the appropriate 3D driver
          during initialization.
        <p>
          Most simple OpenGL programs also use the GLUT and GLU libraries.
          A source for these libraries is listed in the Resources
          section below.

      <sect1>Compiling and linking an OpenGL program
<p>
          A simple GLUT/OpenGL program may be compiled and linked as follows:
        <verb>
        gcc program.c -I/usr/local/include -L/usr/local/lib -L/usr/X11R6/lib -lglut -lGLU -lGL -o program
        </verb>
        <p>
          The <tt/-I/ option is used to specify where the GL/glut.h (and
          possibly the GL/gl.h and GL/glu.h) header file may be found.
        <p>
          The <tt/-L/ options specify where the libglut.so, libGLU.so and
          X libraries are located.
        <p>
          The <tt/-lglut -lGLU -lGL/ arguments specify that the application
          should link with the GLUT, GLU and GL libraries.

      <sect1>Running your OpenGL program
<p>
          Simply typing ./program in your shell should execute the program.
        <p>
          If you get an error message such as
        <verb>
        gears: error in loading shared libraries: libGL.so.1: cannot
        open shared object file: No such file or directory
        </verb>
          if means that the libGL.so.1 file is not the right location.
          Proceed to the trouble shooting section.          

      <sect1>libOSMesa.so
<p>
          OSMesa (Off-Screen Mesa) is an interface and driver for rendering
          3D images into a user-allocated block of memory rather than an
          on-screen window.
<p>
          libOSMesa.so implements the OSMesa interface and must be linked
          with your application if you want to use the OSMesa functions.
          You must also link with libGL.so.  For example:
        <verb>
        gcc osdemo.c -L/usr/X11R6/lib -lOSMesa -lGLU -lGL -o osdemo
        </verb>
<p>
          In stand-alone Mesa this interface was compiled into the monolithic
          libGL.so (formerly libMesaGL.so) library.
          In XFree86 4.0.1 and later this interface is implemented in a
          separate library.
<p>

      <sect1>glxinfo
<p>
          glxinfo is a useful program for checking which version of
          libGL you're using as well as which DRI-based driver.
          Simply type <tt/glxinfo/ and examine the OpenGL vendor, renderer,
          and version lines.
          Among the output you should see something like this:
        <p>
        <verb>
          OpenGL vendor string: Precision Insight, Inc.
          OpenGL renderer string: Mesa DRI Voodoo3 20000224
          OpenGL version string: 1.2 Mesa 3.3 beta
        </verb>
        <p>
          or this:
        <p>
        <verb>
          OpenGL vendor string: Precision Insight, Inc.
          OpenGL renderer string: Mesa GLX Indirect
          OpenGL version string: 1.2 Mesa 3.3 beta
        </verb>
        <p>
          The first example indicates that the 3dfx driver is using
          Voodoo3 hardware.
          The second example indicates that no hardware driver was
          found and indirect, unaccelerated rendering is being used.
        <p>
          If you see that indirect rendering is being used when direct
          rendering was expected, proceed to the troubleshooting section.
        <p>
          <tt/glxinfo/ also lists all of the GLX-enhanced visuals available.
          Here you can determine which visuals may have depth buffers, stencil
          buffers, accumulation buffers, etc.

      <sect1>Environment Variables
<p>
          The libGL.so library recognizes three environment variables.
          Normally, none of them need to be defined.
          If you're using the csh or tcsh shells, type
          <tt/setenv VARNAME value/ to set the variable.
          Otherwise, if you're using sh or bash, type
          <tt/export VARNAME=value/.
          <enum>
            <item>
              <tt/LIBGL_DEBUG/, if defined will cause libGL.so to print error
              and diagnostic messages.
              This can help to solve problems.
              Setting <tt/LIBGL_DEBUG/ to <tt/verbose/ may provide additional
              information.
	    <item>
	      <tt/LIBGL_ALWAYS_INDIRECT/, if defined this will force libGL.so
	      to always use indirect rendering instead of hardware
              acceleration.
	      This can be useful to isolate rendering errors.
	    <item>
	      <tt/LIBGL_DRIVERS_PATH/ can be used to override the default
	      directories which are searched for 3D drivers.
              The value is one or more paths separated by colons.
	      In a typical XFree86 installation, the 3D drivers should be in
	      /usr/X11R6/lib/modules/dri/ and <tt/LIBGL_DRIVERS_PATH/ need
              not be defined.
	      Note that this feature is disabled for set-uid programs.
              This variable replaces the <tt/LIBGL_DRIVERS_DIR/ env var used
              in XFree86 4.0.
            <item>
              <tt/MESA_DEBUG/, if defined, will cause Mesa-based 3D drivers
              to print user error messages to stderr.
              These are errors that you'd otherwise detect by calling
              <tt>glGetError</tt>.
	  </enum>
        <p>
          Mesa-based drivers (this includes most of the drivers listed
          above) also observe many of the existing Mesa environment variables.
          These include the <tt/MESA_DEBUG/ and <tt/MESA_INFO/ variables.


    <sect>General Trouble Shooting
<p>
        This section contains information to help you diagnose general
         problems.
         See below for additional information for specific hardware.

      <sect1>The X Server
<p>
	<enum>
	  <item>
	    Before you start the X server, verify the appropriate 3D kernel
	    module is installed.
	    Type <tt/lsmod/ and look for the appropriate kernel module.
	    For 3dfx hardware you should see <tt/tdfx/, for example.

	  <item>
	    Verify you're running XFree86 4.0 (or newer) and not an
            older version.
            If you run <tt/xdpyinfo/ and look for the following line near
            the top:
        <verb>
            vendor release number:    4000
        </verb>

	  <item>
	    Verify that your XF86Config file (usually found at
	    /etc/X11/XF86Config) loads the glx and dri modules and
	    has a DRI section.
	    <p>
	    See the Software Resources section below for sample
            XF86Config files.

          <item>
            Examine the messages printed during X server startup and check
            that the DRM module loaded.
            Using the Voodoo3 as an example:
        <verb>
        (==) TDFX(0): Write-combining range (0xf0000000,0x2000000)
        (II) TDFX(0): Textures Memory 7.93 MB
        (0): [drm] created "tdfx" driver at busid "PCI:1:0:0"
        (0): [drm] added 4096 byte SAREA at 0xc65dd000
        (0): [drm] mapped SAREA 0xc65dd000 to 0x40013000
        (0): [drm] framebuffer handle = 0xf0000000
        (0): [drm] added 1 reserved context for kernel
        (II) TDFX(0): [drm] Registers = 0xfc000000
        (II) TDFX(0): visual configs initialized
        (II) TDFX(0): Using XFree86 Acceleration Architecture (XAA)
                Screen to screen bit blits
                Solid filled rectangles
                8x8 mono pattern filled rectangles
                Indirect CPU to Screen color expansion
                Solid Lines
                Dashed Lines
                Offscreen Pixmaps
                Driver provided NonTEGlyphRenderer replacement
                Setting up tile and stipple cache:
                        10 128x128 slots
        (==) TDFX(0): Backing store disabled
        (==) TDFX(0): Silken mouse enabled
        (0): X context handle = 0x00000001
        (0): [drm] installed DRM signal handler
        (0): [DRI] installation complete
        (II) TDFX(0): direct rendering enabled
        </verb>

	  <item>
	    After the X server has started, verify that the required X server
	    extensions are loaded.
	    Run <tt/xdpyinfo/ and look for the following entries in the
	    extensions list:
        <verb>
	  GLX
	  SGI-GLX
	  XFree86-DRI
        </verb>

        </enum>

      <sect1>Linking, running and verifying 3D acceleration
<p>
          After you've verified that the X server and DRI have started
          correctly it's time to verify that the GL library and hardware
          drivers are working correctly.

        <enum>
          <item>
	    Verify that you're using the correct libGL.so library with
            <tt/ldd/.
            The /usr/lib and /usr/X11R6/lib directories are expected
            locations for libGL.so.
            <p>
              Example:
        <verb>
        % ldd /usr/local/bin/glxinfo
                libglut.so.3 => /usr/local/lib/libglut.so.3 (0x40019000)
                libGLU.so.1 => /usr/local/lib/libGLU.so.1 (0x40051000)
                libGL.so.1 => /usr/lib/libGL.so.1 (0x40076000)
                libXmu.so.6 => /usr/X11R6/lib/libXmu.so.6 (0x402ee000)
                libXi.so.6 => /usr/X11R6/lib/libXi.so.6 (0x40301000)
                libm.so.6 => /lib/libm.so.6 (0x40309000)
                libc.so.6 => /lib/libc.so.6 (0x40325000)
                libX11.so.6 => /usr/X11R6/lib/libX11.so.6 (0x40419000)
                libXt.so.6 => /usr/X11R6/lib/libXt.so.6 (0x404bd000)
                libSM.so.6 => /usr/X11R6/lib/libSM.so.6 (0x40509000)
                libICE.so.6 => /usr/X11R6/lib/libICE.so.6 (0x40512000)
                libXext.so.6 => /usr/X11R6/lib/libXext.so.6 (0x40529000)
                libvga.so.1 => /usr/lib/libvga.so.1 (0x40537000)
                libpthread.so.0 => /lib/libpthread.so.0 (0x4057d000)
                /lib/ld-linux.so.2 => /lib/ld-linux.so.2 (0x40000000)
        </verb>

	  <item>
	    You may also double check that libGL.so is in fact DRI-capable.
	    Run <tt/strings libGL.so.1.2 | grep DRI/ and look for
            symbols prefixed with "XF86DRI", such as "XF86DRIQueryExtension".

          <item>
            To be safe one should run <tt/ldconfig/ after installing libGL.so
            to be sure the runtime loader will find the proper library.

	  <item>
	    Verify that the appropriate 3D driver is in
	    /usr/X11R6/lib/modules/dri/
            For example, the 3dfx driver will be named <tt/tdfx_dri.so/.

          <item>
            Set the <tt/LIBGL_DEBUG/ environment variable.
            This will cause libGL.so to print an error message if it fails
            to load a DRI driver.
            Any error message printed should be self-explanatory.

	  <item>
	    Run <tt/glxinfo/.  Note the line labeled "OpenGL renderer string".
	    It should have a value which starts with "Mesa DRI" followed by
	    the name of your hardware.

          <item>
            Older Linux OpenGL applications may have been linked against
            Mesa's GL library and will not automatically use libGL.so.
            In some cases, making symbolic links from the Mesa GL library
            to libGL.so.1 will solve the problem:
        <verb>
        ln -s libGL.so.1 libMesaGL.so.3
        </verb>
            In other cases, the application will have to be relinked
            against the new XFree86 libGL.so.
            <P>
            It is reported that part of the problem is that running
            <tt/ldconfig/ will silently rewrite symbolic links based
            on the SONAME field in libraries.
	</enum>

      <p>
        If you're still having trouble, look in the next section for
        information specific to your graphics card.



    <sect>Hardware-Specific Information and Troubleshooting
<p>
        This section presents hardware-specific information for normal
        use and troubleshooting.

      <sect1>3dfx Voodoo3 Series
<p>
        <sect2>Dependencies
<p>
          The Voodoo3 DRI driver requires a special versions of
          the 3dfx Glide library.
          It can be downloaded from the DRI website.
<p>
        <sect2>Configuration
<p>
            Your XF86Config file's device section must specify the
            <tt>tdfx</tt> device:
            <verb>
        Section "Device"
            Identifier  "Voodoo3"
            VendorName  "3dfx"
            Driver      "tdfx"
        EndSection
            </verb>
            The Screen section should then reference the Voodoo3 device:
            <verb>
	Section "Screen"
	    Identifier  "Screen 1"
	    Device      "Voodoo3"
	    Monitor     "High Res Monitor"
	    DefaultDepth 16
	    Subsection "Display"
		Depth       16
		Modes       "1280x1024" "1024x768" "800x600" "640x480"
		ViewPort    0 0
	    EndSubsection
        EndSection
            </verb>
          <p>
            The kernel module for the Voodoo3 is named <tt>tdfx.o</tt> and
	    should be installed in /lib/modules/KERNEL-VERSION/misc/.
            It will be automatically loaded by the Xserver if needed.
          <p>
	    The DRI 3D driver for the Voodoo3 hould be in
	    <tt>/usr/X11R6/lib/modules/dri/tdfx_dri.so</tt>.
            This will be automatically loaded by libGL.so.
          <p>

        <sect2>Troubleshooting
<p>
          <itemize>
            <item>
              If you try to run an OpenGL application and see an error message
              similar to
              <verb>
              gd error (glide): gd error (glide): grSstSelect:  non-existent SSTgd error (glide): grSstSelect:  non-existent SSTS
              </verb>
              it means that you have the wrong version of the Glide library
              for your hardware.
            <item>
              3D acceleration for Voodoo3 is only supported in the 16
              bit/pixel screen mode.
              Use <tt/xdpyinfo/ to verify that all your visuals are depth 16.
              Edit your XF86Config file if needed.
           <item>
              The <tt>/dev/3dfx</tt> device is not used for DRI; it's only for
              Glide on older 3dfx hardware.
          </itemize>

        <sect2>Performance
<p>
          <itemize>
            <item>
              Normally, buffer swapping in double-buffered applications is
              synchronized to your monitor's refresh rate.
              This may be overridden by setting the <tt/FX_GLIDE_SWAPINTERNVAL/
              environment variable.
              The value of this variable indicates the maximum number of
              swap buffer commands can be buffered.
              Zero allows maximum frame rate.
            <item>
              The <tt/glTexEnv/ mode <tt/GL_BLEND/ is not directly supported
              by the Voodoo3 hardware.
              It can be accomplished with a multipass algorithm but it's not
              implemented at this time.
              Applications which use that mode, such as the Performer Town
              demo, may become sluggish when falling back to software
              rendering to render in that mode.
            <item>
              The Voodoo3/Banshee driver reverts to software rendering under
              the following conditions:
              <itemize>
                <item>
                  Setting <tt/GL_LIGHT_MODEL_COLOR_CONTROL/ to
                  <tt/GL_SEPARATE_SPECULAR_COLOR/.
                <item>
                  Enabling line stippline or polygon stippling.
                <item>
                  Enabling point smoothing or polygon smoothing.
                <item>
                  Enabling line smoothing when line width is not 1.0.
                  That is, antialiased lines are done in hardware only when
                  the line width is 1.0.
                <item>
                  Using 1-D or 3-D texture maps.
                <item>
                  Using the GL_BLEND texture environment.
                <item>
                  Using stencil operations.
                <item>
                  Using the accumulation buffer.
                <item>
                  Using <tt/glBlendEquation(GL_LOGIC_OP)/.
                <item>
                  Using <tt/glDrawBuffer(GL_FRONT_AND_BACK)/.
                <item>
                  Using <tt/glPolygonMode(face, GL_POINT)/ or
                  <tt/glPolygonMode(face, GL_LINE)/.
                <item>
                  Using point size attenuation
                  (i.e. <tt/GL_DISTANCE_ATTENUATION_EXT/).
                <item>
                  Using <tt/glColorMask(r, g, b, a)/ when r!=g or g!=b.
              </itemize>
          </itemize>

        <sect2>Known Problems
<p>
          <itemize>
            <item>
              The Glide library cannot be used directly; it's only meant to
              be used via the tdfx DRI driver.
            <item>
              SSystem has problems because of poorly set near and far
              clipping planes.
              The office.unc Performer model also suffers from this problem.
            <item>
              The lowest mipmap level is sometimes miscolored in trilinear-
              sampled polygons.
          </itemize>


      <sect1>3dfx Voodoo5 Series
<p>
        <sect2>Dependencies
<p>
          The Voodoo5 DRI driver requires a special versions of
          the 3dfx Glide library, different than that used for Voodoo3
          hardware.
          It can be downloaded from the DRI website.
<p>
        <sect2>Configuration
<p>
            Your XF86Config file's device section must specify the
            <tt>tdfx</tt> device:
            <verb>
        Section "Device"
            Identifier  "Voodoo5"
            VendorName  "3dfx"
            Driver      "tdfx"
        EndSection
            </verb>
            The Screen section should then reference the Voodoo3 device:
            <verb>
	Section "Screen"
	    Identifier  "Screen 1"
	    Device      "Voodoo5"
	    Monitor     "High Res Monitor"
	    DefaultDepth 24
	    Subsection "Display"
		Depth       16
		Modes       "1280x1024" "1024x768" "800x600" "640x480"
		ViewPort    0 0
	    EndSubsection
	    Subsection "Display"
		Depth       24
		Modes       "1280x1024" "1024x768" "800x600" "640x480"
		ViewPort    0 0
	    EndSubsection
        EndSection
            </verb>
          <p>
            The kernel module for the Voodoo5 is named <tt>tdfx.o</tt> and
	    should be installed in /lib/modules/KERNEL-VERSION/misc/.
            It will be automatically loaded by the Xserver if needed.
          <p>
	    The DRI 3D driver for the Voodoo5 hould be in
	    <tt>/usr/X11R6/lib/modules/dri/tdfx_dri.so</tt>.
            This will be automatically loaded by libGL.so.
          <p>
            The Voodoo5 supports 3D rendering in 16 and 32 bpp modes.
            When running in 32bpp mode an 8-bit stencil buffer and 24-bit
            Z (depth) buffer are offered.
            When running in 32bpp mode only a 16-bit Z (depth) buffer is
            offered and stencil is implemented in software.
          <p>
            A software-based accumulation buffer is available in both
            16 and 32bpp modes.
          <p>

        <sect2>Troubleshooting
<p>
          <itemize>
           <item>
              The <tt>/dev/3dfx</tt> device is not used for DRI; it's only for
              Glide on older 3dfx hardware.
           <item>
              Different versions of Glide are needed for Voodoo3 and Voodoo5.
              See the DRI website's resources page to download the right
              version of Glide.
          </itemize>

        <sect2>Performance
<p>
          <itemize>
            <item>
              Normally, buffer swapping in double-buffered applications is
              synchronized to your monitor's refresh rate.
              This may be overridden by setting the <tt/FX_GLIDE_SWAPINTERNVAL/
              environment variable.
              The value of this variable indicates the maximum number of
              swap buffer commands can be buffered.
              Zero allows maximum frame rate.
            <item>
              Rendering with 16-bit per texel textures is faster than using
              32-bit per texel textures.  The <tt/internalFormat/ parameter
              to <tt/glTexImage2D/ can be used to control texel size.
            <item>
              The Voodoo5 driver reverts to software rendering under the
              same conditions Voodoo3 with three exceptions.
              First, stencil operations are implemented in hardware when the
              screen is configured for 32 bits/pixel.
              Second, the <tt/GL_BLEND/ texture env mode is fully supported in
              hardware.
              Third, <tt/glColorMask/ is fully supported in hardware when
              the screen is configured for 32 bits/pixel.
          </itemize>
        <sect2>Known Problems
<p>
          <itemize>
            <item>
              The Glide library cannot be used directly; it's only meant to
              be used via the tdfx DRI driver.
            <item>
              24bpp screen modes are supported by the hardware but not by
              the current driver.  32bpp is fully supported.
            <item>
              As of October, 2000 the second VSA-100 chip on the Voodoo5 is
              not yet operational.
              Therefore, the board isn't being used to its full capacity.
              The second VSA-100 chip will allow Scan-Line Interleave (SLI)
              mode for full-screen applications and games, potentially doubling
              the system's fill rate.
          </itemize>


      <sect1>Intel i810
        <p>
        <sect2>Dependencies
          <p>
          A Linux kernel with AGP GART support is required.
          The 2.2.x kernel series does not have AGP GART support.
          The 2.4.x test kernels have AGP GART and have been tested
          with the i810.
          <p>

        <sect2>Configuration
          <p>
          Your XF86Config file's device section must specify the
          <tt>i810</tt> device, and specify a usable amount of video
          ram to reserve.
          <verb>
        Section "Device"
            Identifier  "i810"
            VendorName  "Intel"
            Driver      "i810"
	    VideoRam    10000
        EndSection
            </verb>
            The Screen section should then reference the i810 device:
            <verb>
	Section "Screen"
	    Identifier  "Screen 1"
	    Device      "i810"
	    Monitor     "High Res Monitor"
	    DefaultDepth 16
	    Subsection "Display"
		Depth       16
		Modes       "1280x1024" "1024x768" "800x600" "640x480"
		ViewPort    0 0
	    EndSubsection
        EndSection
            </verb>
          <p>
            The kernel module for the i810 is named <tt>i810.o</tt> and
	    should be installed in /lib/modules/KERNEL-VERSION/misc/.
            It will be automatically loaded by the Xserver if needed.
          <p>
	    The DRI 3D driver for the i810 should be in
	    <tt>/usr/X11R6/lib/modules/dri/i810_dri.so</tt>.
            This will be automatically loaded by libGL.so.

        <sect2>Troubleshooting
<p>
          <itemize>
            <item>
              3D acceleration for the i810 is only available in the 16
              bit/pixel screen mode at this time.  32bpp acceleration is
	      not supported by this hardware.
              Use <tt/xdpyinfo/ to verify that all your visuals are depth 16.
              Edit your XF86Config file if needed.
            <item>
	      The i810 uses system ram for video and 3d graphics.  The X
	      server will ordinarily reserve 4mb of ram for graphics,
	      which is too little for an effective 3d setup.  To tell
	      the driver to use a larger amount, specify a VideoRam
	      option in the Device section of your XF86Config file.  A
	      number between 10000 and 16384 seems adequate for most
	      requirements.  If too little memory is available for DMA
	      buffers, back and depth buffers and textures, direct
	      rendering will be disabled.
          </itemize>

<p>

      <sect1>Matrox G200 and G400
      <p>
        <sect2>Dependencies
        <p>
          A Linux kernel with AGP GART support (such as the 2.4.x test
          kernels) is needed.
          <p>
        <sect2>Configuration
        <p>
          Your XF86Config file's device section must specify the
          <tt>mga</tt> device:  
          <verb>
        Section "Device"
            Identifier  "MGA"
            VendorName  "Matrox"
            Driver      "mga"
	    VideoRam    32768
        EndSection
            </verb>
            The Screen section should then reference the MGA device:
            <verb>
	Section "Screen"
	    Identifier  "Screen 1"
	    Device      "MGA"
	    Monitor     "High Res Monitor"
	    DefaultDepth 16
	    Subsection "Display"
		Depth       16
		Modes       "1280x1024" "1024x768" "800x600" "640x480"
		ViewPort    0 0
	    EndSubsection
        EndSection
            </verb>
            To use a 32bpp screen mode, use this <tt>Screen</tt> section
            instead:
            <verb>
	Section "Screen"
	    Identifier  "Screen 1"
	    Device      "MGA"
	    Monitor     "High Res Monitor"
	    DefaultDepth 24
            DefaultFbBpp 32
	    Subsection "Display"
		Depth       24
		Modes       "1280x1024" "1024x768" "800x600" "640x480"
		ViewPort    0 0
	    EndSubsection
        EndSection
            </verb>

          <p>
            The kernel module for the G200/G400 is named <tt>mga.o</tt> and
	    should be installed in /lib/modules/KERNEL-VERSION/misc/.
            It will be automatically loaded by the Xserver if needed.
          <p>
	    The DRI 3D driver for the G200/G400 should be in
	    <tt>/usr/X11R6/lib/modules/dri/mga_dri.so</tt>.
            This will be automatically loaded by libGL.so.

        <sect2>Performance
<p>
          No data at this time.

        <sect2>Known Problems
<p>
          <itemize>
            <item>
	      Multitexture is currently disabled on the G400 to work
	      around a hardware lockup bug.  This should be restored in
	      a subsequent release.
            <item>
	      32bpp mode has not been tested on the G400 at this time.
          </itemize>


      <sect1>ATI Rage 128
      <p>
        <sect2>Dependencies
        <p>
          A Linux kernel with AGP GART support (such as the 2.4.x test
          kernels) is needed.
          <p>
        <sect2>Configuration
        <p>
          Your XF86Config file's device section must specify the
          <tt>r128</tt> device:
          <verb>
        Section "Device"
            Identifier  "Rage128"
            VendorName  "ATI"
            Driver      "r128"
        EndSection
            </verb>
            The Screen section should then reference the Rage 128 device:
            <verb>
	Section "Screen"
	    Identifier  "Screen 1"
	    Device      "Rage128"
	    Monitor     "High Res Monitor"
	    DefaultDepth 16
	    Subsection "Display"
		Depth       16
		Modes       "1280x1024" "1024x768" "800x600" "640x480"
		ViewPort    0 0
	    EndSubsection
	    Subsection "Display"
		Depth       32
		Modes       "1280x1024" "1024x768" "800x600" "640x480"
		ViewPort    0 0
	    EndSubsection
        EndSection
            </verb>
          <p>
            The kernel module for the Rage 128 is named <tt>r128.o</tt> and
	    should be installed in /lib/modules/KERNEL-VERSION/misc/.
            It will be automatically loaded by the Xserver if needed.
          <p>
	    The DRI 3D driver for the Rage 128 should be in
	    <tt>/usr/X11R6/lib/modules/dri/r128_dri.so</tt>.
            This will be automatically loaded by libGL.so.
          <p>
            You may also set your screen depth to 32 for 32bpp mode.
          <p>

        <sect2>Performance
<p>
          While PCI Rage 128 based cards are supported, they do not yet
          support PCI GART, so they will not perform as well as their
          AGP counterparts.

        <sect2>Known Problems
<p>
          DGA is not yet supported in the ATI Rage 128 X server.  This
          feature will be added in a future release.


      <sect1>3DLabs Oxygen GMX 2000
<p>
          The driver for this hardware was experimental and is no longer being
          developed or supported.


    <sect>General Limitations and Known Bugs
<p>
      <sect1>OpenGL
<p>
          The following OpenGL features are not supported at this time:
          overlays, stereo, hardware-accelerated indirect rendering.
        <p>
          OpenGL-like functionality is provided with the Mesa library.
          XFree86 4.0.1 uses Mesa 3.3.
          Subsequent releases of XFree86 will use newer versions of Mesa.
          When newer versions of Mesa are available, the 3D drivers can
          be updated without reinstalling XFree86 or libGL.so.

      <sect1>GLX
<p>
          The GLX 1.3 API is exported but none of the new 1.3 functions
          are operational.
        <p>
          The new <tt/glXGetProcAddressARB/ function is fully supported.
        <p>
          GLXPixmap rendering is only supported for indirect rendering
          contexts.  This is a common OpenGL limitation.  Attempting
          to use a direct rendering context with a GLXPixmap will result
          in an X protocol error.
        <p>

      <sect1>Signal Handling
<p>
          There are several understood, but unresolved problems relating
          to hardware locking and signal handling.
          Hitting CTRL-z to suspend a 3D application can sometimes cause
          the X server to lock-up if executing device driver code at that
          moment.
          Also, using a debugger to step through OpenGL/Mesa device driver
          functions code could cause a lock-up.
          These problems will be fixed in the future.

      <sect1>Scheduling
<p>
          When you run multiple GL applications at once you may notice poor
          time slicing.
          This is due to an interaction problem with the Linux scheduler
          which will be addressed in the future.


      <sect1>libGL.so and dlopen()
<p>
          A number of popular OpenGL applications on Linux (such as Quake3,
          HereticII, Heavy Gear 2, etc) dynamically open the libGL.so
          library at runtime with dlopen(), rather than linking with -lGL
          at compile/link time.
<p>
          If dynamic loading of libGL.so is not implemented carefully, there
          can be a number of serious problems.
          Here are the things to be careful of in your application:
          <itemize>
          <item>Specify the RTLD_GLOBAL flag to dlopen().
            If you don't do this then you'll likely see a runtime error message
            complaining that _glapi_Context is undefined when libGL.so
            tries to open a hardware-specific driver.
            Without this flag, <em>nested</em> opening of dynamic libraries
            does not work.
          <item>Do not close the library with dlclose() until after
            XCloseDisplay() has been called.
            When libGL.so initializes itself it registers several callbacks
            functions with Xlib.
            When XCloseDisplay() is called those callback functions are
            called.
            If libGL.so has already been unloaded with dlclose() this will
            cause a segmentation fault.
          <item>
            Your application should link with -lpthread.
            On Linux, libGL.so uses the pthreads library in order to provide
            thread safety.
            There is apparently a bug in the dlopen()/dlclose() code which
            causes crashes if the library uses pthreads but the parent
            application doesn't.
            The only known work-around is to link the application with
            -lpthread.
          </itemize>

          Some applications don't yet incorporate these procedures and
          may fail.
          For example, changing the graphics settings in some video games
          will expose this problem.
          The DRI developers are working with game vendors to prevent this
          problem in the future.


      <sect1>Bug Database
<p>
          The DRI bug database which includes bugs related to specific
          drivers is at the
          <htmlurl url="http://sourceforge.net/bugs/?group_id=387"
           name="SourceForge DRI Bug Database">
        <p>
          Please scan both the open and closed bug lists to determine if your
          problem has already been reported and perhaps fixed.


    <sect>Resources
<p>
      <sect1>Software
<p>
          A collection of useful configuration files, libraries, headers,
          utilities and demo programs is available from
          <htmlurl url="http://dri.sourceforge.net/resources/resources.html"
                   name="http://dri.sourceforge.net/resources/resources.html">

      <sect1>Documentation
<p>
        <itemize>
          <item>General OpenGL information is available at the
            <htmlurl url="http://www.opengl.org" name="OpenGL Home Page">
          <item>XFree86 information is available at the
            <htmlurl url="http://www.xfree86.org" name="XFree86 Home Page">
          <item>Information about the design of the DRI is available from
            <htmlurl url="http://www.precisioninsight.com/piinsights.html"
            name="Precision Insight, Inc.">
          <item>Visit the <htmlurl url="http://dri.sourceforge.net"
            name="DRI project on SourceForge.net"> for the latest development
            news about the DRI and 3D drivers.
          <item>The <htmlurl url="http://dri.sourceforge.net/DRIcompile.html"
            name="DRI Compilation Guide"> explains how to download, compile
            and install the DRI for yourself.
        </itemize>

      <sect1>Support
<p>
        <itemize>
          <item>
            The DRI-users mailing list at
            <htmlurl url="http://sourceforge.net/mail/?group_id=387"
            name="SourceForge"> is a forum for people to discuss DRI problems.
          <item>
            In the future there may be IHV and Linux vendor support resources
            for the DRI.
        </itemize>

  </article>


  <!-- Local Variables: -->
  <!-- fill-column: 72  -->
  <!-- End:             -->