home *** CD-ROM | disk | FTP | other *** search
/ Chip 2001 August - Disc 2 / chip_20018102_hu.iso / linux / X-4.1.0 / doc / readme.dri < prev    next >
Text File  |  2001-06-27  |  47KB  |  1,236 lines
  1.                                DRI User Guide
  2.  
  3.           VA Linux Systems, Inc. Professional Services - Graphics.
  4.  
  5.                                  3 May 2001
  6.  
  7. 1.  Preamble
  8.  
  9. 1.1  Copyright
  10.  
  11. Copyright ⌐ 2000-2001 by VA Linux Systems, Inc.  All Rights Reserved.
  12.  
  13. Permission is granted to make and distribute verbatim copies of this document
  14. provided the copyright notice and this permission notice are preserved on all
  15. copies.
  16.  
  17. 1.2  Trademarks
  18.  
  19. OpenGL is a registered trademark and SGI is a trademark of Silicon Graphics,
  20. Inc.  Unix is a registered trademark of The Open Group.  The `X' device and X
  21. Window System are trademarks of The Open Group.  XFree86 is a trademark of
  22. The XFree86 Project.  Linux is a registered trademark of Linus Torvalds.
  23. Intel is a registered trademark of Intel Corporation.  3Dlabs, GLINT, and
  24. Oxygen are either registered trademarks or trademarks of 3Dlabs Inc. Ltd.
  25. 3dfx, Voodoo3, Voodoo4, and Voodoo5 are registered trademarks of 3dfx Inter-
  26. active, Incorporated.  Matrox is a registered trademark of Matrox Electronic
  27. Systems Ltd.  ATI Rage and Radeon are registered trademarks of ATI Technolo-
  28. gies, Inc.  All other trademarks mentioned are the property of their respec-
  29. tive owners.
  30.  
  31. 2.  Introduction
  32.  
  33. With XFree86 4.0 and the Direct Rendering Interface (DRI), hardware acceler-
  34. ated 3D graphics can be considered a standard feature on Linux workstations.
  35. Support for other operating systems, such as FreeBSD, is underway.
  36.  
  37. This document describes how to use the DRI system and troubleshoot problems
  38. which may occur.  Readers should have a basic understanding of Linux, X and
  39. OpenGL.  See the resources section at the end for more documentation and
  40. software downloads.
  41.  
  42. This document does not cover compilation or installation of XFree86 4.0.  It
  43. is assumed that you've already installed a Linux distribution which includes
  44. XFree86 4.0 or that you're an experienced Linux developer who has compiled
  45. the DRI for himself.  DRI download, compilation and installation instructions
  46. can be found at http://dri.sourceforge.net/DRIcompile.html
  47.  
  48. Edits, corrections and updates to this document may be mailed to brianp@val-
  49. inux.com.
  50.  
  51. 3.  Supported Architectures & Hardware
  52.  
  53. 3.1  CPU Architectures
  54.  
  55. The architectures currently supported by the DRI have grown from the initial
  56. Intel i386 systems to now include the Alpha Processor and the Sun SPARC
  57. machines.
  58.  
  59. Intel's SSE (a.k.a. Katmai) instructions are used in optimized vertex trans-
  60. formation functions in Mesa-based drivers.  This requires a recent Linux ker-
  61. nel both at compile and runtime.  See the DRI Compile Guide for compile-time
  62. requirements.  At runtime a check is made to determine if the CPU can execute
  63. SSE instructions.  They're disabled otherwise.
  64.  
  65. AMD's 3DNow! instructions are also used in optimized vertex transformation
  66. functions in the Mesa-based DRI drivers.  3DNow! is supported in most ver-
  67. sions of Linux.  Like the SSE optimizations, a runtime check is made to
  68. determine if the CPU can execute 3DNow! instructions.
  69.  
  70. Alpha-based systems can use Compaq's optimized math library for improved 3D
  71. performance.  See the DRI Compilation Guide for details.
  72.  
  73. 3.2  Graphics Hardware
  74.  
  75. XFree86 4.0 (or later versions) includes 3D acceleration for the following
  76. graphics hardware:
  77.  
  78.    o 3dfx, supported on Intel x86, AMD and Alpha:
  79.  
  80.         o Voodoo5 5500
  81.  
  82.         o Voodoo4 4500
  83.  
  84.         o Voodoo3 3500 TV
  85.  
  86.         o Voodoo3 3000 AGP
  87.  
  88.         o Voodoo3 3000 PCI
  89.  
  90.         o Voodoo3 2000 AGP
  91.  
  92.         o Voodoo3 2000 PCI
  93.  
  94.         o Voodoo Banshee
  95.  
  96.         o Velocity 100/200
  97.  
  98.      There are many configurations of 3dfx cards on the market.  Not all have
  99.      been tested.
  100.  
  101.    o Matrox, supported on Intel x86 and AMD:
  102.  
  103.         o Matrox G200
  104.  
  105.         o Matrox G400
  106.  
  107.    o Intel i810 (motherboard chipset)
  108.  
  109.         o i810
  110.  
  111.         o i810-dc100
  112.  
  113.         o i810e
  114.  
  115.    o ATI Rage 128, supported on Intel x86 and AMD:
  116.  
  117.         o Rage Fury
  118.  
  119.         o Rage Magnum
  120.  
  121.         o XPERT 2000
  122.  
  123.         o XPERT 128
  124.  
  125.         o XPERT 99
  126.  
  127.         o All-in-Wonder 128
  128.  
  129.      Note that both PCI and AGP versions of Rage 128 based cards are sup-
  130.      ported at this time.
  131.  
  132.    o ATI Radeon, supported on Intel x86 and AMD:
  133.  
  134.         o Radeon SDR AGP
  135.  
  136.         o Radeon DDR AGP
  137.  
  138.    o 3Dlabs, supported on Intel x86 and AMD:
  139.  
  140.         o Oxygen GMX 2000 (MX/Gamma based).  Note:  this driver is no longer
  141.           being actively developed.
  142.  
  143. Support for other hardware is underway.  Most of the DRI development work is
  144. funded by contracts with IHVs.  These contracts often prevent us from
  145. announcing drivers before they're released.  Queries about upcoming drivers
  146. may not be answerable.
  147.  
  148. 4.  Prerequisite Software
  149.  
  150.    o The DRI is available in XFree86 4.0 and later.
  151.  
  152.    o Some hardware drivers require specific versions of the Linux kernel for
  153.      AGP support, etc.  See section 10 for specifics.
  154.  
  155.    o You DO NOT need to install Mesa separately.  The parts of Mesa needed
  156.      for hardware acceleration are already in the XFree86/DRI project.
  157.  
  158. 5.  Kernel Modules
  159.  
  160. 3D hardware acceleration requires a DRI kernel module that's specific to your
  161. graphics hardware.
  162.  
  163. The DRI kernel module version must exactly match your running kernel version.
  164. Since there are so many versions of the kernel, it's difficult to provide
  165. precompiled kernel modules.
  166.  
  167. While the Linux source tree includes the DRI kernel module sources, the lat-
  168. est DRI kernel sources will be found in the DRI source tree.
  169.  
  170. See the DRI Compilation Guide for information on compiling the DRI kernel
  171. modules.
  172.  
  173. XFree86 4.0.1 added automatic kernel module loading to the X server.  On
  174. Linux, the X server uses modprobe to load kernel modules.  In Linux 2.4.x the
  175. DRM kernel modules should be kept in /lib/modules/2.4.x/ker-
  176. nel/driver/char/drm/ for automatic loading to work.
  177.  
  178. Optionally, DRM kernel modules can be loaded manually with insmod prior to
  179. starting the X server.
  180.  
  181. You can verify that the kernel module was installed with lsmod, checking the
  182. X server startup log, and checking that /proc/dri/0 exists.
  183.  
  184. 6.  XF86Config file
  185.  
  186. The XFree86 configuration file is usually found in /etc/X11/XF86Config.  This
  187. section describes the parts which must be specially set for the DRI.
  188.  
  189. First, the XF86Config file must load the GLX and DRI modules:
  190.  
  191.           Section "Module"
  192.           ...
  193.           # This loads the GLX module
  194.               Load       "glx"
  195.           # This loads the DRI module
  196.               Load       "dri"
  197.           EndSection
  198.  
  199. Next, the DRI section can be used to restrict access to direct rendering.  A
  200. client can only use direct rendering if it has permission to open the
  201. /dev/dri/card? file(s).  The permissions on these DRI device files is con-
  202. trolled by the "DRI" section in the XF86Config file.
  203.  
  204. If you want all of the users on your system to be able to use direct-render-
  205. ing, then use a simple DRI section like this:
  206.  
  207.           Section "DRI"
  208.                Mode 0666
  209.           EndSection
  210.  
  211. This section will allow any user with a current connection to the X server to
  212. use direct rendering.
  213.  
  214. If you want to restrict the use of direct-rendering to a certain group of
  215. users, then create a group for those users by editing the /etc/group file on
  216. your system.  For example, you may want to create a group called xf86dri and
  217. place two users (e.g., fred and jane) in that group.  To do that, you might
  218. add the following line to /etc/group:
  219.  
  220.              xf86dri:x:8000:fred,jane
  221.  
  222. You have to be careful that the group id (8000 in this example) is unique.
  223.  
  224. Then you would use the following DRI section:
  225.  
  226.              Section "DRI"
  227.                   Group "xf86dri"
  228.                   Mode 0660
  229.              EndSection
  230.  
  231. This would limit access to direct-rendering to those users in the xf86dri
  232. group (fred and jane in this example).  When other users tried to use direct
  233. rendering, they would fall back to unaccelerated indirect rendering.
  234.  
  235. [Note that there is a known bug in XFree86 4.0 that prevents some changes to
  236. the DRI section from taking effect.  Until this bug is fixed, if you change
  237. the DRI section, please also remove the /dev/dri directory with the rm -rf
  238. /dev/dri command.]
  239.  
  240. Finally, the XF86Config file needs Device and Screen sections specific to
  241. your hardware.  Look in section 10: Hardware-Specific Information and Trou-
  242. bleshooting for details.
  243.  
  244. 7.  Memory usage
  245.  
  246. Using the 3D features of a graphics card requires more memory than when it's
  247. just used as a 2D device.  Double buffering, depth buffering, stencil
  248. buffers, textures, etc. all require extra graphics memory.  These features
  249. may require four times the memory used for a simple 2D display.
  250.  
  251. If your graphics card doesn't have a lot of memory (less than 16MB, for exam-
  252. ple), you may have to reduce your screen size and/or color depth in order to
  253. use 3D features.  Reducing the screen resolution will also leave more space
  254. for texture images, possibly improving 3D performance.  If, for example, you
  255. play Quake3 at 1024x768 but start your display at 1600x1200 you might con-
  256. sider restarting X at 1024x768 in order to maximize your texture memory
  257. space.
  258.  
  259. The documentation included with your card should have information about maxi-
  260. mum screen size when using 3D.
  261.  
  262. 8.  Using 3D Acceleration
  263.  
  264. This section describes how to link your application with libGL.so and verify
  265. that you are in fact using 3D acceleration.
  266.  
  267. 8.1  libGL.so
  268.  
  269. Your OpenGL program must link with the libGL.so.1.2 library provided by
  270. XFree86 4.0.  The libGL.so.1.2 library contains a GLX protocol encoder for
  271. indirect/remote rendering and DRI code for accessing hardware drivers.  In
  272. particular, be sure you're not using libGL.so from another source such as
  273. Mesa or the Utah GLX project.
  274.  
  275. Unless it was built in a special way, the libGL.so library does not contain
  276. any 3D hardware driver code.  Instead, libGL.so dynamically loads the appro-
  277. priate 3D driver during initialization.
  278.  
  279. Most simple OpenGL programs also use the GLUT and GLU libraries.  A source
  280. for these libraries is listed in the Resources section below.
  281.  
  282. 8.2  Compiling and linking an OpenGL program
  283.  
  284. A simple GLUT/OpenGL program may be compiled and linked as follows:
  285.  
  286.              gcc program.c -I/usr/local/include -L/usr/local/lib -L/usr/X11R6/lib -lglut -lGLU -lGL -o program
  287.  
  288. The -I option is used to specify where the GL/glut.h (and possibly the
  289. GL/gl.h and GL/glu.h) header file may be found.
  290.  
  291. The -L options specify where the libglut.so and the X libraries are located.
  292. libGL.so and libGLU.so should be in /usr/lib, as specified by the
  293. Linux/OpenGL ABI standard.
  294.  
  295. The -lglut -lGLU -lGL arguments specify that the application should link with
  296. the GLUT, GLU and GL libraries, in that order.
  297.  
  298. 8.3  Running your OpenGL program
  299.  
  300. Simply typing ./program in your shell should execute the program.
  301.  
  302. If you get an error message such as
  303.  
  304.              gears: error in loading shared libraries: libGL.so.1: cannot
  305.              open shared object file: No such file or directory
  306.  
  307. if means that the libGL.so.1 file is not the right location.  Proceed to the
  308. trouble shooting section.
  309.  
  310. 8.4  libOSMesa.so
  311.  
  312. OSMesa (Off-Screen Mesa) is an interface and driver for rendering 3D images
  313. into a user-allocated block of memory rather than an on-screen window.  It
  314. was originally developed for Mesa before Mesa became part of the XFree86/DRI
  315. project.  It can now be used with the XFree86/DRI libGL.so as well.
  316.  
  317. libOSMesa.so implements the OSMesa interface and it must be linked with your
  318. application if you want to use the OSMesa functions.  You must also link with
  319. libGL.so.  For example:
  320.  
  321.              gcc osdemo.c -lOSMesa -lGLU -lGL -o osdemo
  322.  
  323. In stand-alone Mesa this interface was compiled into the monolithic libGL.so
  324. (formerly libMesaGL.so) library.  In XFree86 4.0.1 and later this interface
  325. is implemented in a separate library.
  326.  
  327. 8.5  glxinfo
  328.  
  329. glxinfo is a useful program for checking which version of libGL you're using
  330. as well as which DRI-based driver.  Simply type glxinfo and examine the
  331. OpenGL vendor, renderer, and version lines.  Among the output you should see
  332. something like this:
  333.  
  334.                OpenGL vendor string: VA Linux Systems, Inc.
  335.                OpenGL renderer string: Mesa DRI Voodoo3 20000224
  336.                OpenGL version string: 1.2 Mesa 3.4
  337.  
  338. or this:
  339.  
  340.                OpenGL vendor string: VA Linux Systems, Inc.
  341.                OpenGL renderer string: Mesa GLX Indirect
  342.                OpenGL version string: 1.2 Mesa 3.4
  343.  
  344. The first example indicates that the 3dfx driver is using Voodoo3 hardware.
  345. The second example indicates that no hardware driver was found and indirect,
  346. unaccelerated rendering is being used.
  347.  
  348. If you see that indirect rendering is being used when direct rendering was
  349. expected, proceed to the troubleshooting section.
  350.  
  351. glxinfo also lists all of the GLX-enhanced visuals available so you can
  352. determine which visuals are double-bufferd, have depth (Z) buffers, stencil
  353. buffers, accumulation buffers, etc.
  354.  
  355. 8.6  Environment Variables
  356.  
  357. The libGL.so library recognizes three environment variables.  Normally, none
  358. of them need to be defined.  If you're using the csh or tcsh shells, type
  359. setenv VARNAME value to set the variable.  Otherwise, if you're using sh or
  360. bash, type export VARNAME=value.
  361.  
  362.   1.  LIBGL_DEBUG, if defined will cause libGL.so to print error and diagnos-
  363.       tic messages.  This can help to solve problems.  Setting LIBGL_DEBUG to
  364.       verbose may provide additional information.
  365.  
  366.   2.  LIBGL_ALWAYS_INDIRECT, if defined this will force libGL.so to always
  367.       use indirect rendering instead of hardware acceleration.  This can be
  368.       useful to isolate rendering errors.
  369.  
  370.   3.  LIBGL_DRIVERS_PATH can be used to override the default directories
  371.       which are searched for 3D drivers.  The value is one or more paths sep-
  372.       arated by colons.  In a typical XFree86 installation, the 3D drivers
  373.       should be in /usr/X11R6/lib/modules/dri/ and LIBGL_DRIVERS_PATH need
  374.       not be defined.  Note that this feature is disabled for set-uid pro-
  375.       grams.  This variable replaces the LIBGL_DRIVERS_DIR env var used in
  376.       XFree86 4.0.
  377.  
  378.   4.  MESA_DEBUG, if defined, will cause Mesa-based 3D drivers to print user
  379.       error messages to stderr.  These are errors that you'd otherwise detect
  380.       by calling glGetError.
  381.  
  382. Mesa-based drivers (this includes most of the drivers listed above) also
  383. observe many of the existing Mesa environment variables.  These include the
  384. MESA_DEBUG and MESA_INFO variables.
  385.  
  386. 9.  General Trouble Shooting
  387.  
  388. This section contains information to help you diagnose general problems.  See
  389. below for additional information for specific hardware.
  390.  
  391. 9.1  Bus Mastering
  392.  
  393. DMA-based DRI drivers (that's most DRI drivers) cannot function unless bus
  394. mastering is enabled for your graphics card.  By default, some systems don't
  395. having bus mastering on.  You should enable it in your BIOS.
  396.  
  397. Alternately, you can check the status of bus mastering and change the setting
  398. from within Linux.  There may be similar procedures for other operating sys-
  399. tems.
  400.  
  401. Run lspci (as root) and find the information describing your graphics
  402. adapter.  For example:
  403.  
  404.          00:00.0 Host bridge: Intel Corporation 440BX/ZX - 82443BX/ZX Host bridge (rev 03)
  405.          00:01.0 PCI bridge: Intel Corporation 440BX/ZX - 82443BX/ZX AGP bridge (rev 03)
  406.          00:07.0 ISA bridge: Intel Corporation 82371AB PIIX4 ISA (rev 02)
  407.          00:07.1 IDE interface: Intel Corporation 82371AB PIIX4 IDE (rev 01)
  408.          00:07.2 USB Controller: Intel Corporation 82371AB PIIX4 USB (rev 01)
  409.          00:07.3 Bridge: Intel Corporation 82371AB PIIX4 ACPI (rev 02)
  410.          00:11.0 Ethernet controller: Intel Corporation 82557 [Ethernet Pro 100] (rev 08)
  411.          00:12.0 SCSI storage controller: Symbios Logic Inc. (formerly NCR) 53c895 (rev 02)
  412.          00:14.0 Multimedia audio controller: Ensoniq ES1371 [AudioPCI-97] (rev 08)
  413.          01:00.0 VGA compatible controller: 3Dfx Interactive, Inc.: Unknown device 0009 (rev 01)
  414.  
  415. The bus, device, and function number comprise the device id, which is conven-
  416. tionally written in the form bus:dev.func, or in this case 01:00.0.
  417.  
  418. Use the setpci command to examine bit two of register 4 for your graphics
  419. card.  This will indicate whether or not bus mastering is enabled.
  420.  
  421.              setpci -s 01:00.0 4.w
  422.  
  423. A hexadecimal value will be printed.  Convert the least significant digit to
  424. binary.  For example, if you see 3, that's 0011 in binary (bit two is 0).  If
  425. you see 7, that's 0111 in binary (bit two is 1).  In the first example, bus
  426. mastering is disabled.  It's enabled in the second example.
  427.  
  428. The following shell script will enabled bus mastering for your graphics card
  429. and host bridge.  Run it as root.
  430.  
  431.          #!/bin/bash
  432.          dev=01:00.0   # change as appropriate
  433.          echo Enabling bus mastering on device $dev
  434.          setpci -s $dev 4.w=$(printf %x $((0x$(setpci -s $dev 4.w)|4)))
  435.          dev=00:00.0
  436.          echo Enabling bus mastering on host bridge $dev
  437.          setpci -s $dev 4.w=$(printf %x $((0x$(setpci -s $dev 4.w)|4)))
  438.  
  439. You can check if this worked by running the first setpci command again.
  440.  
  441. 9.2  The X Server
  442.  
  443.   1.  Before you start the X server, verify the appropriate 3D kernel module
  444.       is installed.  Type lsmod and look for the appropriate kernel module.
  445.       For 3dfx hardware you should see tdfx, for example.
  446.  
  447.   2.  Verify you're running XFree86 4.0 (or newer) and not an older version.
  448.       If you run xdpyinfo and look for the following line near the top:
  449.  
  450.                        vendor release number:    4000
  451.  
  452.   3.  Verify that your XF86Config file (usually found at /etc/X11/XF86Config)
  453.       loads the glx and dri modules and has a DRI section.
  454.  
  455.       See the Software Resources section below for sample XF86Config files.
  456.  
  457.   4.  Examine the messages printed during X server startup and check that the
  458.       DRM module loaded.  Using the Voodoo3 as an example:
  459.  
  460.                    (==) TDFX(0): Write-combining range (0xf0000000,0x2000000)
  461.                    (II) TDFX(0): Textures Memory 7.93 MB
  462.                    (0): [drm] created "tdfx" driver at busid "PCI:1:0:0"
  463.                    (0): [drm] added 4096 byte SAREA at 0xc65dd000
  464.                    (0): [drm] mapped SAREA 0xc65dd000 to 0x40013000
  465.                    (0): [drm] framebuffer handle = 0xf0000000
  466.                    (0): [drm] added 1 reserved context for kernel
  467.                    (II) TDFX(0): [drm] Registers = 0xfc000000
  468.                    (II) TDFX(0): visual configs initialized
  469.                    (II) TDFX(0): Using XFree86 Acceleration Architecture (XAA)
  470.                            Screen to screen bit blits
  471.                            Solid filled rectangles
  472.                            8x8 mono pattern filled rectangles
  473.                            Indirect CPU to Screen color expansion
  474.                            Solid Lines
  475.                            Dashed Lines
  476.                            Offscreen Pixmaps
  477.                            Driver provided NonTEGlyphRenderer replacement
  478.                            Setting up tile and stipple cache:
  479.                                    10 128x128 slots
  480.                    (==) TDFX(0): Backing store disabled
  481.                    (==) TDFX(0): Silken mouse enabled
  482.                    (0): X context handle = 0x00000001
  483.                    (0): [drm] installed DRM signal handler
  484.                    (0): [DRI] installation complete
  485.                    (II) TDFX(0): direct rendering enabled
  486.  
  487.   5.  After the X server has started, verify that the required X server
  488.       extensions are loaded.  Run xdpyinfo and look for the following entries
  489.       in the extensions list:
  490.  
  491.                   GLX
  492.                   SGI-GLX
  493.                   XFree86-DRI
  494.  
  495. 9.3  Linking, running and verifying 3D acceleration
  496.  
  497. After you've verified that the X server and DRI have started correctly it's
  498. time to verify that the GL library and hardware drivers are working cor-
  499. rectly.
  500.  
  501.   1.  Verify that you're using the correct libGL.so library with ldd.  The
  502.       /usr/lib and /usr/X11R6/lib directories are expected locations for
  503.       libGL.so.
  504.  
  505.       Example:
  506.  
  507.                    % ldd /usr/local/bin/glxinfo
  508.                            libglut.so.3 => /usr/local/lib/libglut.so.3 (0x40019000)
  509.                            libGLU.so.1 => /usr/local/lib/libGLU.so.1 (0x40051000)
  510.                            libGL.so.1 => /usr/lib/libGL.so.1 (0x40076000)
  511.                            libXmu.so.6 => /usr/X11R6/lib/libXmu.so.6 (0x402ee000)
  512.                            libXi.so.6 => /usr/X11R6/lib/libXi.so.6 (0x40301000)
  513.                            libm.so.6 => /lib/libm.so.6 (0x40309000)
  514.                            libc.so.6 => /lib/libc.so.6 (0x40325000)
  515.                            libX11.so.6 => /usr/X11R6/lib/libX11.so.6 (0x40419000)
  516.                            libXt.so.6 => /usr/X11R6/lib/libXt.so.6 (0x404bd000)
  517.                            libSM.so.6 => /usr/X11R6/lib/libSM.so.6 (0x40509000)
  518.                            libICE.so.6 => /usr/X11R6/lib/libICE.so.6 (0x40512000)
  519.                            libXext.so.6 => /usr/X11R6/lib/libXext.so.6 (0x40529000)
  520.                            libvga.so.1 => /usr/lib/libvga.so.1 (0x40537000)
  521.                            libpthread.so.0 => /lib/libpthread.so.0 (0x4057d000)
  522.                            /lib/ld-linux.so.2 => /lib/ld-linux.so.2 (0x40000000)
  523.  
  524.   2.  You may also double check that libGL.so is in fact DRI-capable.  Run
  525.       strings libGL.so.1.2 | grep DRI and look for symbols prefixed with
  526.       "XF86DRI", such as "XF86DRIQueryExtension".
  527.  
  528.   3.  To be safe one should run ldconfig after installing libGL.so to be sure
  529.       the runtime loader will find the proper library.
  530.  
  531.   4.  Verify that the appropriate 3D driver is in /usr/X11R6/lib/modules/dri/
  532.       For example, the 3dfx driver will be named tdfx_dri.so.
  533.  
  534.   5.  Set the LIBGL_DEBUG environment variable.  This will cause libGL.so to
  535.       print an error message if it fails to load a DRI driver.  Any error
  536.       message printed should be self-explanatory.
  537.  
  538.   6.  Run glxinfo.  Note the line labeled "OpenGL renderer string".  It
  539.       should have a value which starts with "Mesa DRI" followed by the name
  540.       of your hardware.
  541.  
  542.   7.  Older Linux OpenGL applications may have been linked against Mesa's GL
  543.       library and will not automatically use libGL.so.  In some cases, making
  544.       symbolic links from the Mesa GL library to libGL.so.1 will solve the
  545.       problem:
  546.  
  547.                    ln -s libGL.so.1 libMesaGL.so.3
  548.  
  549.       In other cases, the application will have to be relinked against the
  550.       new XFree86 libGL.so.
  551.  
  552.       It is reported that part of the problem is that running ldconfig will
  553.       silently rewrite symbolic links based on the SONAME field in libraries.
  554.  
  555. If you're still having trouble, look in the next section for information spe-
  556. cific to your graphics card.
  557.  
  558. 10.  Hardware-Specific Information and Troubleshooting
  559.  
  560. This section presents hardware-specific information for normal use and trou-
  561. bleshooting.
  562.  
  563. 10.1  3dfx Banshee, Voodoo3, Voodoo4 and Voodoo5 Series
  564.  
  565. 10.1.1  Requirements
  566.  
  567. The 3dfx DRI driver requires special versions of the 3dfx Glide library.
  568. Different versions of Glide are needed for Banshee/Voodoo3 than for
  569. Voodoo4/5.  The Glide libraries can be downloaded from the DRI website.
  570.  
  571. 10.1.2  Configuration
  572.  
  573. Your XF86Config file's device section must specify the tdfx device.  For
  574. example:
  575.  
  576.              Section "Device"
  577.                  Identifier  "Voodoo3"
  578.                  VendorName  "3dfx"
  579.                  Driver      "tdfx"
  580.              EndSection
  581.  
  582. Or,
  583.  
  584.              Section "Device"
  585.                  Identifier  "Voodoo5"
  586.                  VendorName  "3dfx"
  587.                  Driver      "tdfx"
  588.              EndSection
  589.  
  590. The Screen section should then reference the Voodoo device:
  591.  
  592.           Section "Screen"
  593.               Identifier  "Screen 1"
  594.               Device      "Voodoo3"
  595.               Monitor     "High Res Monitor"
  596.               DefaultDepth 16
  597.               Subsection "Display"
  598.                Depth       16
  599.                Modes       "1280x1024" "1024x768" "800x600" "640x480"
  600.                ViewPort    0 0
  601.               EndSubsection
  602.              EndSection
  603.  
  604. Or,
  605.  
  606.           Section "Screen"
  607.               Identifier  "Screen 1"
  608.               Device      "Voodoo5"
  609.               Monitor     "High Res Monitor"
  610.               DefaultDepth 24
  611.               Subsection "Display"
  612.                Depth       16
  613.                Modes       "1280x1024" "1024x768" "800x600" "640x480"
  614.                ViewPort    0 0
  615.               EndSubsection
  616.               Subsection "Display"
  617.                Depth       24
  618.                Modes       "1280x1024" "1024x768" "800x600" "640x480"
  619.                ViewPort    0 0
  620.               EndSubsection
  621.              EndSection
  622.  
  623. The kernel module for 3dfx hardware is named tdfx.o and should be installed
  624. in /lib/modules/2.4.x/kernel/driver/char/drm/.  It will be automatically
  625. loaded by the Xserver if needed.
  626.  
  627. The DRI 3D driver for 3dfx hardware should be in /usr/X11R6/lib/mod-
  628. ules/dri/tdfx_dri.so.  This will be automatically loaded by libGL.so.
  629.  
  630. The Voodoo5 supports 3D rendering in 16 and 32 bpp modes.  When running in
  631. 32bpp mode an 8-bit stencil buffer and 24-bit Z (depth) buffer are offered.
  632. When running in 16bpp mode only a 16-bit Z (depth) buffer is offered and
  633. stencil is implemented in software.
  634.  
  635. A software-based accumulation buffer is available in both 16 and 32bpp modes.
  636.  
  637. 10.1.3  Troubleshooting
  638.  
  639.    o If you try to run an OpenGL application and see an error message similar
  640.      to
  641.  
  642.                 gd error (glide): gd error (glide): grSstSelect:  non-existent SSTgd error (glide): grSstSelect:  non-existent SSTS
  643.  
  644.      it means that you have the wrong version of the Glide library for your
  645.      hardware.
  646.  
  647.    o 3D acceleration for Banshee and Voodoo3 is only supported in the 16
  648.      bit/pixel screen mode.  Use xdpyinfo to verify that all your visuals are
  649.      depth 16.  Edit your XF86Config file if needed.
  650.  
  651.    o The /dev/3dfx device is not used for DRI; it's only for Glide on older
  652.      3dfx hardware.
  653.  
  654.    o Different versions of Glide are needed for Voodoo3 and Voodoo5.  See the
  655.      DRI website's resources page to download the right version of Glide.
  656.  
  657.    o Voodoo4/5 may be run at 24bpp (instead of 32bpp, the default) but 3D
  658.      acceleration is not supported in that mode.  32bpp mode is fully 3D
  659.      accelerated.
  660.  
  661. 10.1.4  Performance and Features
  662.  
  663.    o Normally, buffer swapping in double-buffered applications is synchro-
  664.      nized to your monitor's refresh rate.  This may be overridden by setting
  665.      the FX_GLIDE_SWAPINTERVAL environment variable.  The value of this vari-
  666.      able indicates the maximum number of swap buffer commands can be
  667.      buffered.  Zero allows maximum frame rate.
  668.  
  669.    o On Voodoo4/5, rendering with 16-bits/texel textures is faster than using
  670.      32-bit per texel textures.  The internalFormat parameter to glTexImage2D
  671.      can be used to control texel size.  Quake3 and other games let you con-
  672.      trol this as well.
  673.  
  674.    o The glTexEnv mode GL_BLEND is not directly supported by the Voodoo3
  675.      hardware.  It can be accomplished with a multipass algorithm but it's
  676.      not implemented at this time.  Applications which use that mode, such as
  677.      the Performer Town demo, may become sluggish when falling back to soft-
  678.      ware rendering to render in that mode.
  679.  
  680.    o The Voodoo3/Banshee driver reverts to software rendering under the fol-
  681.      lowing conditions:
  682.  
  683.         o Setting GL_LIGHT_MODEL_COLOR_CONTROL to GL_SEPARATE_SPECULAR_COLOR.
  684.  
  685.         o Enabling line stippling or polygon stippling.
  686.  
  687.         o Enabling point smoothing or polygon smoothing.
  688.  
  689.         o Enabling line smoothing when line width is not 1.0.  That is,
  690.           antialiased lines are done in hardware only when the line width is
  691.           1.0.
  692.  
  693.         o Using 1-D or 3-D texture maps.
  694.  
  695.         o Using the GL_BLEND texture environment.
  696.  
  697.         o Using stencil operations.
  698.  
  699.         o Using the accumulation buffer.
  700.  
  701.         o Using glBlendEquation(GL_LOGIC_OP).
  702.  
  703.         o Using glDrawBuffer(GL_FRONT_AND_BACK).
  704.  
  705.         o Using glPolygonMode(face, GL_POINT) or glPolygonMode(face,
  706.           GL_LINE).
  707.  
  708.         o Using point size attenuation (i.e. GL_DISTANCE_ATTENUATION_EXT).
  709.  
  710.         o Using glColorMask(r, g, b, a) when r!=g or g!=b.
  711.  
  712.    o The Voodoo5 driver reverts to software rendering under the same condi-
  713.      tions Voodoo3 with three exceptions.  First, stencil operations are
  714.      implemented in hardware when the screen is configured for 32 bits/pixel.
  715.      Second, the GL_BLEND texture env mode is fully supported in hardware.
  716.      Third, glColorMask is fully supported in hardware when the screen is
  717.      configured for 32 bits/pixel.
  718.  
  719.    o As of January, 2001 the second VSA-100 chip on the Voodoo5 is not yet
  720.      operational.  Therefore, the board isn't being used to its full capac-
  721.      ity.  The second VSA-100 chip will allow Scan-Line Interleave (SLI) mode
  722.      for full-screen applications and games, potentially doubling the sys-
  723.      tem's fill rate.  When the second VSA-100 chip is activated glGet-
  724.      String(GL_RENDERER) will report Voodoo5 instead of Voodoo4.
  725.  
  726.    o The lowest mipmap level is sometimes miscolored in trilinear- sampled
  727.      polygons.
  728.  
  729.    o The GL_EXT_texture_env_combine extension is supported on the Voodoo4 and
  730.      Voodoo5.
  731.  
  732. 10.1.5  Known Problems
  733.  
  734.    o The lowest mipmap level is sometimes miscolored in trilinear- sampled
  735.      polygons (Voodoo3/Banshee).
  736.  
  737.    o Fog doesn't work with orthographic projections.
  738.  
  739.    o The accuracy of blending operations on Voodoo4/5 isn't always very good.
  740.      If you run Glean, you'll find some test failures.
  741.  
  742.    o The Glide library cannot be used directly; it's only meant to be used
  743.      via the tdfx DRI driver.
  744.  
  745.    o SSystem has problems because of poorly set near and far clipping planes.
  746.      The office.unc Performer model also suffers from this problem.
  747.  
  748. 10.2  Intel i810
  749.  
  750. 10.2.1  Requirements
  751.  
  752. A kernel with AGP GART support (such as Linux 2.4.x) is needed.
  753.  
  754. 10.2.2  Configuration
  755.  
  756. Your XF86Config file's device section must specify the i810 device, and spec-
  757. ify a usable amount of video ram to reserve.
  758.  
  759.              Section "Device"
  760.                  Identifier  "i810"
  761.                  VendorName  "Intel"
  762.                  Driver      "i810"
  763.               Option     "AGPMode" "1"
  764.               VideoRam    10000
  765.              EndSection
  766.  
  767. The Screen section should then reference the i810 device:
  768.  
  769.           Section "Screen"
  770.               Identifier  "Screen 1"
  771.               Device      "i810"
  772.               Monitor     "High Res Monitor"
  773.               DefaultDepth 16
  774.               Subsection "Display"
  775.                Depth       16
  776.                Modes       "1280x1024" "1024x768" "800x600" "640x480"
  777.                ViewPort    0 0
  778.               EndSubsection
  779.              EndSection
  780.  
  781. The kernel module for the i810 is named i810.o and should be installed in
  782. /lib/modules/2.4.x/kernel/driver/char/drm/.  It will be automatically loaded
  783. by the Xserver if needed.
  784.  
  785. The DRI 3D driver for the i810 should be in /usr/X11R6/lib/mod-
  786. ules/dri/i810_dri.so.  This will be automatically loaded by libGL.so.
  787.  
  788. 10.2.3  Troubleshooting
  789.  
  790.    o 3D acceleration for the i810 is only available in the 16 bit/pixel
  791.      screen mode at this time.  32bpp acceleration is not supported by this
  792.      hardware.  Use xdpyinfo to verify that all your visuals are depth 16.
  793.      Edit your XF86Config file if needed.
  794.  
  795.    o The i810 uses system ram for video and 3d graphics.  The X server will
  796.      ordinarily reserve 4mb of ram for graphics, which is too little for an
  797.      effective 3d setup.  To tell the driver to use a larger amount, specify
  798.      a VideoRam option in the Device section of your XF86Config file.  A num-
  799.      ber between 10000 and 16384 seems adequate for most requirements.  If
  800.      too little memory is available for DMA buffers, back and depth buffers
  801.      and textures, direct rendering will be disabled.
  802.  
  803. 10.2.4  Performance and Features
  804.  
  805. Basically all of the i810 features which can be exposed through OpenGL 1.2
  806. are implemented.  However, the following OpenGL features are implemented in
  807. software and will be slow:
  808.  
  809.    o Stencil buffer and accumulation buffer operations
  810.  
  811.    o Blend subtract, min/max and logic op blend modes
  812.  
  813.    o glColorMask when any mask is set to false
  814.  
  815.    o GL_SEPARATE_SPECULAR_COLOR lighting mode
  816.  
  817.    o glDrawBuffer(GL_FRONT_AND_BACK)
  818.  
  819.    o Using 1D or 3D textures
  820.  
  821.    o Using texture borders
  822.  
  823. 10.3  Matrox G200 and G400
  824.  
  825. 10.3.1  Requirements
  826.  
  827. A kernel with AGP GART support (such as Linux 2.4.x) is needed.
  828.  
  829. 10.3.2  Configuration
  830.  
  831. Your XF86Config file's device section must specify the mga device:
  832.  
  833.              Section "Device"
  834.                  Identifier  "MGA"
  835.                  VendorName  "Matrox"
  836.                  Driver      "mga"
  837.               Option     "AGPMode" "1"
  838.               VideoRam    32768
  839.              EndSection
  840.  
  841. The Screen section should then reference the MGA device:
  842.  
  843.           Section "Screen"
  844.               Identifier  "Screen 1"
  845.               Device      "MGA"
  846.               Monitor     "High Res Monitor"
  847.               DefaultDepth 16
  848.               Subsection "Display"
  849.                Depth       16
  850.                Modes       "1280x1024" "1024x768" "800x600" "640x480"
  851.                ViewPort    0 0
  852.               EndSubsection
  853.              EndSection
  854.  
  855. To use a 32bpp screen mode, use this Screen section instead:
  856.  
  857.           Section "Screen"
  858.               Identifier  "Screen 1"
  859.               Device      "MGA"
  860.               Monitor     "High Res Monitor"
  861.               DefaultDepth 24
  862.                  DefaultFbBpp 32
  863.               Subsection "Display"
  864.                Depth       24
  865.                Modes       "1280x1024" "1024x768" "800x600" "640x480"
  866.                ViewPort    0 0
  867.               EndSubsection
  868.              EndSection
  869.  
  870. The kernel module for the G200/G400 is named mga.o and should be installed in
  871. /lib/modules/2.4.x/kernel/driver/char/drm/.  It will be automatically loaded
  872. by the Xserver if needed.
  873.  
  874. The DRI 3D driver for the G200/G400 should be in /usr/X11R6/lib/mod-
  875. ules/dri/mga_dri.so.  This will be automatically loaded by libGL.so.
  876.  
  877. 10.3.3  Performance and Features
  878.  
  879. Software rendering will be used under any of the following conditions:
  880.  
  881.    o Using glDrawBuffer(GL_FRONT_AND_BACK).
  882.  
  883.    o Using point, line, or triangle smoothing.
  884.  
  885.    o Using glLogicOp.
  886.  
  887.    o Using glPolygonStipple or glLineStipple.
  888.  
  889.    o Using 1D or 3D textures.
  890.  
  891.    o Using texture borders.
  892.  
  893.    o Using glDepthFunc(GL_NEVER).
  894.  
  895.    o Using the accumulation buffer.
  896.  
  897. The AGP mode may be set to 1, 2, or 4.  One is used by default.  Higher AGP
  898. speeds may result in unreliable performance depending on your motherboard.
  899.  
  900. Compaq has funded the implementation of AGP accelerated ReadPixels and Draw-
  901. Pixels in this driver.  With this implementation, on a G400 drawing directly
  902. from AGP memory (exported to the client), throughput of up to 1 GB/sec has
  903. been measured.
  904.  
  905. Additionally Compaq's funding has produced several new extensions in Mesa,
  906. including one (packed_depth_stencil_MESA) which enables Read/DrawPixels func-
  907. tionality to operate directly on the packed 24/8 depth/stencil buffers of
  908. this hardware.
  909.  
  910. In order to access this functionality, the application must ensure that all
  911. pixel processing operations are disabled.  There are in addition a fairly
  912. complex set of rules regarding which packing/unpacking modes must be used,
  913. and which data formats are supported, and alignment constraints.  See the
  914. files in lib/GL/mesa/src/drv/mga/DOCS for a summary of these.  The extension
  915. definitions are included in the Mesa 3.4 source distribution.
  916.  
  917. 10.3.4  IRQ Assignment
  918.  
  919. There have been problems in the past with the MGA driver being very sluggish
  920. when the DRI is enabled (to the point of being unusable.)  This is caused by
  921. the graphics card not having an interrupt assigned to it.  The current DRI
  922. trunk will attempt to detect this condition and bail out gracefully.
  923.  
  924. The solution to the above problem is to assign an interrupt to your graphics
  925. card.  This is something you must turn on in your system BIOS configuration.
  926. Please consult your system BIOS manual for instructions on how to enable an
  927. interrupt for your graphics card.
  928.  
  929. 10.3.5  MGA HAL lib
  930.  
  931. MGAHALlib.a is a binary library Matrox has provided for use under Linux to
  932. expose functionality for which they can not provide documentation.  (For
  933. example TV-Out requires MacroVision be enabled on the output.)  This binary
  934. library also sets the pixel/memory clocks to the optimal settings for your
  935. Matrox card.
  936.  
  937. Currently the MGAHAL library is required for the G450 to work.  You can down-
  938. load this from the driver section on Matrox's website: www.matrox.com/mga
  939.  
  940. Here modifications to the DRI build instructions which make the mga ddx
  941. driver use the MGAHAL library:
  942.  
  943.             1.Put the following define in your host.def file
  944.                  #define UseMatroxHal YES
  945.             2. Place mgaHALlib.a in the following directory
  946.                  xc/programs/Xserver/hw/xfree86/drivers/mga/HALlib/
  947.  
  948. You can use DualHead on the G400/G450 DH cards by creating two device sec-
  949. tions which both point to the same BusID.  For most AGP devices the BusID
  950. will be "PCI:1:0:0".  Configure your screen section as you would normally
  951. configure XFree86 4.x Multihead.  It should be noted that currently the sec-
  952. ond head does not support direct rendering.
  953.  
  954. 10.3.6  Known Problems
  955.  
  956. None.
  957.  
  958. 10.4  ATI Rage 128
  959.  
  960. 10.4.1  Requirements
  961.  
  962. A kernel with AGP GART support (such as Linux 2.4.x) is needed.
  963.  
  964. 10.4.2  Configuration
  965.  
  966. Your XF86Config file's device section must specify the ati device:
  967.  
  968.              Section "Device"
  969.                  Identifier  "Rage128"
  970.                  VendorName  "ATI"
  971.                  Driver      "ati"
  972.               Option     "AGPMode" "1"
  973.               Option     "UseCCEFor2D" "false"
  974.              EndSection
  975.  
  976. The Screen section should then reference the Rage 128 device:
  977.  
  978.           Section "Screen"
  979.               Identifier  "Screen 1"
  980.               Device      "Rage128"
  981.               Monitor     "High Res Monitor"
  982.               DefaultDepth 16
  983.               Subsection "Display"
  984.                Depth       16
  985.                Modes       "1280x1024" "1024x768" "800x600" "640x480"
  986.                ViewPort    0 0
  987.               EndSubsection
  988.               Subsection "Display"
  989.                Depth       32
  990.                Modes       "1280x1024" "1024x768" "800x600" "640x480"
  991.                ViewPort    0 0
  992.               EndSubsection
  993.              EndSection
  994.  
  995. The kernel module for the Rage 128 is named r128.o and should be installed in
  996. /lib/modules/2.4.x/kernel/driver/char/drm/.  It will be automatically loaded
  997. by the Xserver if needed.
  998.  
  999. The DRI 3D driver for the Rage 128 should be in /usr/X11R6/lib/mod-
  1000. ules/dri/r128_dri.so.  This will be automatically loaded by libGL.so.
  1001.  
  1002. You may also set your screen depth to 32 for 32bpp mode.
  1003.  
  1004. 10.4.3  Performance and Features
  1005.  
  1006. While PCI Rage 128 based cards are supported, they do not yet support PCI
  1007. GART, so they will not perform as well as their AGP counterparts.
  1008.  
  1009. For AGP cards, the AGP mode may be set to 1, 2, or 4.  One is used by
  1010. default.  Higher AGP speeds may result in unreliable performance depending on
  1011. your motherboard.
  1012.  
  1013. Note that even at 32bpp there is no alpha channel.
  1014.  
  1015. The following OpenGL features are implemented in software and will be slow:
  1016.  
  1017.    o Stencil buffer and accumulation buffer operations
  1018.  
  1019.    o Blend subtract, min/max and logic op blend modes
  1020.  
  1021.    o GL_SEPARATE_SPECULAR_COLOR lighting mode
  1022.  
  1023.    o glDrawBuffer(GL_FRONT_AND_BACK)
  1024.  
  1025.    o Using 1D or 3D textures
  1026.  
  1027.    o Using texture borders
  1028.  
  1029. 10.4.4  Known Problems
  1030.  
  1031. If you experience stability problems you may try setting the UseCCEFor2D
  1032. option to true.  This will effectively disable 2D hardware acceleration.
  1033. Performance will be degraded, of course.
  1034.  
  1035. 10.5  ATI Radeon
  1036.  
  1037. 10.5.1  Requirements
  1038.  
  1039. A kernel with AGP GART support (such as Linux 2.4.x) is needed.
  1040.  
  1041. 10.5.2  Configuration
  1042.  
  1043. Your XF86Config file's device section must specify the ati device:
  1044.  
  1045.              Section "Device"
  1046.                  Identifier  "Radeon"
  1047.                  VendorName  "ATI"
  1048.                  Driver      "ati"
  1049.               Option     "AGPMode" "1"
  1050.              EndSection
  1051.  
  1052. The Screen section should then reference the Radeon device:
  1053.  
  1054.           Section "Screen"
  1055.               Identifier  "Screen 1"
  1056.               Device      "Radeon"
  1057.               Monitor     "High Res Monitor"
  1058.               DefaultDepth 16
  1059.               Subsection "Display"
  1060.                Depth       16
  1061.                Modes       "1280x1024" "1024x768" "800x600" "640x480"
  1062.                ViewPort    0 0
  1063.               EndSubsection
  1064.               Subsection "Display"
  1065.                Depth       32
  1066.                Modes       "1280x1024" "1024x768" "800x600" "640x480"
  1067.                ViewPort    0 0
  1068.               EndSubsection
  1069.              EndSection
  1070.  
  1071. The kernel module for the Radeon is named radeon.o and should be installed in
  1072. /lib/modules/2.4.x/kernel/driver/char/drm/.  It will be automatically loaded
  1073. by the Xserver if needed.
  1074.  
  1075. The DRI 3D driver for the Radeon should be in /usr/X11R6/lib/mod-
  1076. ules/dri/radeon_dri.so.  This will be automatically loaded by libGL.so.
  1077.  
  1078. You may also set your screen depth to 32 for 32bpp mode.
  1079.  
  1080. 10.5.3  Performance and Features
  1081.  
  1082. While this driver supports many of the features of ATI Radeon cards, we do
  1083. not yet fully support the card's TCL features.  This work is progressing, but
  1084. is not yet ready.
  1085.  
  1086. The AGP mode may be set to 1, 2, or 4.  One is used by default.  Higher AGP
  1087. speeds may result in unreliable performance depending on your motherboard.
  1088.  
  1089. The following OpenGL features are implemented in software and will be slow:
  1090.  
  1091.    o Blend subtract, blend min/max and blend logicops
  1092.  
  1093.    o Stencil and accumulation operations
  1094.  
  1095.    o 1D and 3D textures
  1096.  
  1097.    o Texture borders
  1098.  
  1099. The GL_EXT_texture_env_combine, GL_EXT_texture_env_add and GL_EXT_tex-
  1100. ture_env_dot3 extensions are supported (or will be soon supported in the new
  1101. driver based on Mesa 3.5).
  1102.  
  1103. We hope to implement support for the following features in the future:
  1104.  
  1105.    o Vertex transformation, clipping and lighting (TCL)
  1106.  
  1107.    o Hardware stencil buffer
  1108.  
  1109.    o Cube map textures
  1110.  
  1111.    o 3D textures
  1112.  
  1113.    o Three texture units
  1114.  
  1115. 10.5.4  Known Problems
  1116.  
  1117. Certain (early?) revisions of the AMD Irongate chipset have AGPGART problems
  1118. which effect Radeon, and other graphics cards.  The card may work unreliably,
  1119. or not work at all.  If the DRM kernel module is not loaded, the 2D Xserver
  1120. may work.  There's hope that this can be fixed in the future.
  1121.  
  1122. 10.6  3DLabs Oxygen GMX 2000
  1123.  
  1124. The driver for this hardware was experimental and is no longer being devel-
  1125. oped or supported.
  1126.  
  1127. 11.  General Limitations and Known Bugs
  1128.  
  1129. 11.1  OpenGL
  1130.  
  1131. The following OpenGL features are not supported at this time: overlays,
  1132. stereo, hardware-accelerated indirect rendering.
  1133.  
  1134. OpenGL-like functionality is provided with the Mesa library.  XFree86 4.1.0
  1135. uses Mesa 3.4.2.  Subsequent releases of XFree86 will use newer versions of
  1136. Mesa.  When newer versions of Mesa are available, the 3D drivers can be
  1137. updated without reinstalling XFree86 or libGL.so.
  1138.  
  1139. 11.2  GLX
  1140.  
  1141. The GLX 1.3 API is exported but none of the new 1.3 functions are opera-
  1142. tional.
  1143.  
  1144. The new glXGetProcAddressARB function is fully supported.
  1145.  
  1146. GLXPixmap rendering is only supported for indirect rendering contexts.  This
  1147. is a common OpenGL limitation.  Attempting to use a direct rendering context
  1148. with a GLXPixmap will result in an X protocol error.
  1149.  
  1150. 11.3  Debugging
  1151.  
  1152. Debugging DRI drivers with gdb can be difficult because of the locking
  1153. involved.  When debugging OpenGL applications, you should avoid stepping
  1154. inside the GL functions.  If you're trying to debug a DRI driver it's recom-
  1155. mended that you do so remotely, from a second system.
  1156.  
  1157. 11.4  Scheduling
  1158.  
  1159. When you run multiple GL applications at once you may notice poor time slic-
  1160. ing.  This is due to an interaction problem with the Linux scheduler which
  1161. will be addressed in the future.
  1162.  
  1163. 11.5  libGL.so and dlopen()
  1164.  
  1165. A number of popular OpenGL applications on Linux (such as Quake3, HereticII,
  1166. Heavy Gear 2, etc) dynamically open the libGL.so library at runtime with
  1167. dlopen(), rather than linking with -lGL at compile/link time.
  1168.  
  1169. If dynamic loading of libGL.so is not implemented carefully, there can be a
  1170. number of serious problems.  Here are the things to be careful of in your
  1171. application:
  1172.  
  1173.    o Specify the RTLD_GLOBAL flag to dlopen().  If you don't do this then
  1174.      you'll likely see a runtime error message complaining that _glapi_Con-
  1175.      text is undefined when libGL.so tries to open a hardware-specific
  1176.      driver.  Without this flag, nested opening of dynamic libraries does not
  1177.      work.
  1178.  
  1179.    o Do not close the library with dlclose() until after XCloseDisplay() has
  1180.      been called.  When libGL.so initializes itself it registers several
  1181.      callbacks functions with Xlib.  When XCloseDisplay() is called those
  1182.      callback functions are called.  If libGL.so has already been unloaded
  1183.      with dlclose() this will cause a segmentation fault.
  1184.  
  1185.    o Your application should link with -lpthread.  On Linux, libGL.so uses
  1186.      the pthreads library in order to provide thread safety.  There is appar-
  1187.      ently a bug in the dlopen()/dlclose() code which causes crashes if the
  1188.      library uses pthreads but the parent application doesn't.  The only
  1189.      known work-around is to link the application with -lpthread.
  1190.  
  1191. Some applications don't yet incorporate these procedures and may fail.  For
  1192. example, changing the graphics settings in some video games will expose this
  1193. problem.  The DRI developers are working with game vendors to prevent this
  1194. problem in the future.
  1195.  
  1196. 11.6  Bug Database
  1197.  
  1198. The DRI bug database which includes bugs related to specific drivers is at
  1199. the SourceForge DRI Bug Database
  1200.  
  1201. Please scan both the open and closed bug lists to determine if your problem
  1202. has already been reported and perhaps fixed.
  1203.  
  1204. 12.  Resources
  1205.  
  1206. 12.1  Software
  1207.  
  1208. A collection of useful configuration files, libraries, headers, utilities and
  1209. demo programs is available from http://dri.sourceforge.net/res.phtml
  1210.  
  1211. 12.2  Documentation
  1212.  
  1213.    o General OpenGL information is available at the OpenGL Home Page
  1214.  
  1215.    o XFree86 information is available at the XFree86 Home Page
  1216.  
  1217.    o Information about the design of the DRI is available from Precision
  1218.      Insight, Inc.
  1219.  
  1220.    o Visit the DRI project on SourceForge.net for the latest development news
  1221.      about the DRI and 3D drivers.
  1222.  
  1223.    o The DRI Compilation Guide explains how to download, compile and install
  1224.      the DRI for yourself.
  1225.  
  1226. 12.3  Support
  1227.  
  1228.    o The DRI-users mailing list at SourceForge is a forum for people to dis-
  1229.      cuss DRI problems.
  1230.  
  1231.    o In the future there may be IHV and Linux vendor support resources for
  1232.      the DRI.
  1233.  
  1234.      Generated from XFree86: xc/programs/Xserver/hw/xfree86/doc/sgml/DRI.sgml,v 1.24 2001/05/19 00:42:22 dawes Exp $
  1235.  
  1236.