home *** CD-ROM | disk | FTP | other *** search
/ CD Actual 45 / cda45.iso / Linux / XFree86-4.0 / doc / README.DRI < prev    next >
Encoding:
Text File  |  2000-03-09  |  19.7 KB  |  543 lines
  1.                                DRI Users Guide
  2.  
  3.                            Precision Insight, Inc.
  4.  
  5.                                 6 March 2000
  6.  
  7. 1.  Preamble
  8.  
  9. 1.1  Copyright
  10.  
  11. Copyright ⌐ 2000 by Precision Insight, Inc., Cedar Park, Texas.  All Rights
  12. Reserved.
  13.  
  14. Permission is granted to make and distribute verbatim copies of this document
  15. provided the copyright notice and this permission notice are preserved on all
  16. copies.
  17.  
  18. 1.2  Trademarks
  19.  
  20. OpenGL is a registered trademark and SGI is a trademark of Silicon Graphics,
  21. Inc.  Unix is a registered trademark of The Open Group.  The `X' device and X
  22. Window System are trademarks of The Open Group.  XFree86 is a trademark of
  23. The XFree86 Project.  Linux is a registered trademark of Linus Torvalds.
  24. Intel is a registered trademark of Intel Corporation.  3Dlabs, GLINT, and
  25. Oxygen are either registered trademarks or trademarks of 3Dlabs Inc. Ltd.
  26. 3dfx, Voodoo3, Voodoo4, and Voodoo5 are registered trademarks of 3dfx Inter-
  27. active, Incorporated.  All other trademarks mentioned are the property of
  28. their respective owners.
  29.  
  30. 2.  Introduction
  31.  
  32. With XFree86 4.0 and Precision Insight's Direct Rendering Interface (DRI),
  33. hardware accelerated 3D graphics can be considered a standard feature on
  34. Linux workstations.  Support for other operating systems, such as FreeBSD, is
  35. 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.
  45.  
  46. 3.  Supported Hardware
  47.  
  48. 3D acceleration is currently only available for systems with Intel-compatible
  49. CPUs.  Support for Alpha, and perhaps other CPUs, should be available in the
  50. future.
  51.  
  52. XFree86 4.0 includes 3D acceleration for the following graphics hardware:
  53.  
  54.    o 3dfx:
  55.  
  56.         o Voodoo3 3500 TV
  57.  
  58.         o Voodoo3 3000 AGP
  59.  
  60.         o Voodoo3 3000 PCI
  61.  
  62.         o Voodoo3 2000 AGP
  63.  
  64.         o Voodoo3 2000 PCI
  65.  
  66.         o Voodoo Banshee
  67.  
  68.         o Velocity 100/200
  69.  
  70.      There are many configurations of 3dfx cards on the market.  Not all have
  71.      been tested.
  72.  
  73.    o 3Dlabs Oxygen GMX 2000 (MX/Gamma based)
  74.  
  75. Support for the following hardware is underway:
  76.  
  77.    o Intel i810
  78.  
  79.    o Matrox G400
  80.  
  81.    o ATI Rage 128
  82.  
  83.    o 3dfx Voodoo4 and Voodoo5 series
  84.  
  85. 4.  Prerequisite Software
  86.  
  87.    o XFree86 4.0
  88.  
  89.    o Linux kernel 2.2.x (later kernels will be supported in the near future,
  90.      and may be required for some chipsets)
  91.  
  92. Mesa 3.3 (beta) is included with XFree86 4.0; there is no need to download
  93. the stand-alone Mesa distribution.
  94.  
  95. 5.  X Server Start-up
  96.  
  97. This section describes the steps needed to start the X server with 3D accel-
  98. eration support.
  99.  
  100. 5.1  Kernel module
  101.  
  102. Before starting the X server you must install the correct kernel module for
  103. your hardware.
  104.  
  105. This can be done by executing the following as root:
  106.  
  107.              insmod XXX/drivername.o
  108.  
  109. For example, on 3dfx hardware, the kernel module is called tdfx.o so you you
  110. would type insmod XXX/tdfx.o
  111.  
  112. Verify that the kernel module was installed by checking that /proc/dri/0
  113. exists.
  114.  
  115. 5.2  XF86Config file
  116.  
  117. First, the XF86Config file must load the GLX and DRI modules:
  118.  
  119.           Section "Module"
  120.           ...
  121.           # This loads the GLX module
  122.               Load       "glx"
  123.           # This loads the DRI module
  124.               Load       "dri"
  125.           EndSection
  126.  
  127. Next, the DRI section can be used to restrict access to direct rendering.
  128.  
  129. If you want all of the users on your system to be able to use direct-render-
  130. ing, then use a simple DRI section:
  131.  
  132.           Section "DRI"
  133.                Mode 0666
  134.           EndSection
  135.  
  136. This section will allow any user with a current connection to the X server to
  137. use direct rendering.
  138.  
  139. If you want to restrict the use of direct-rendering to a certain group of
  140. users, then create a group for those users by editing the /etc/group file on
  141. your system.  For example, you may want to create a group called xf86dri and
  142. place two users (e.g., fred and jane) in that group.  To do that, you might
  143. add the following line to /etc/group:
  144.  
  145.              xf86dri:x:8000:fred,jane
  146.  
  147. You have to be careful that the group id (8000 in this example) is unique.
  148.  
  149. Then you would use the following DRI section:
  150.  
  151.              Section "DRI"
  152.                   Group "xf86dri"
  153.                   Mode 0660
  154.              EndSection
  155.  
  156. This would limit access to direct-rendering to those users in the xf86dri
  157. group (fred and jane in this example).  When other users tried to use direct
  158. rendering, they would fall back to unaccelerated indirect rendering.
  159.  
  160. [Note that there is a known bug in XFree86 4.0 that prevents some changes to
  161. the DRI section from taking effect.  Until this bug is fixed, if you change
  162. the DRI section, please also remove the /dev/dri directory with the rm -rf
  163. /dev/dri command.]
  164.  
  165. Next, the Device section of the XF86Config file must describe your particular
  166. hardware.  For example, here's the Device section for a 3dfx Voodoo3 card:
  167.  
  168.              Section "Device"
  169.                  Identifier  "Voodoo3"
  170.                  VendorName  "3dfx"
  171.                  Driver      "tdfx"
  172.              EndSection
  173.  
  174. Finally, the Screen section of the XF86Config file may have to be specially
  175. configured as well.  For example, Voodoo3 hardware acceleration is only
  176. available in 16bpp mode.
  177.  
  178.           Section "Screen"
  179.               Identifier  "Screen 1"
  180.               Device      "Voodoo3"
  181.               Monitor     "High Res Monitor"
  182.               DefaultDepth 16
  183.               Subsection "Display"
  184.                Depth       16
  185.                Modes       "1280x1024" "1024x768" "800x600" "640x480"
  186.                ViewPort    0 0
  187.               EndSubsection
  188.              EndSection
  189.  
  190. If there are errors in the XF86Config file, the X server will log errors to
  191. the file /var/log/XFree86.0.log
  192.  
  193. 5.3  Memory usage
  194.  
  195. Using the 3D features of a graphics card requires more memory than when it's
  196. just used as a 2D device.  Double buffering, depth buffering, stencil
  197. buffers, textures, etc. all require extra graphics memory.  These features
  198. may require four times the memory used for a simple 2D display.
  199.  
  200. If your graphics card doesn't have a lot of memory (less than 16MB, for exam-
  201. ple), you may have to reduce your screen size and/or color depth in order to
  202. use 3D features.
  203.  
  204. The documentation included with your card should have information about maxi-
  205. mum screen size when using 3D.
  206.  
  207. 6.  Using 3D Acceleration
  208.  
  209. This section describes how to link your application with libGL.so and verify
  210. that you are in fact using 3D acceleration.
  211.  
  212. 6.1  libGL.so
  213.  
  214. Your OpenGL program must link with the libGL.so.1.2 library provided by
  215. XFree86 4.0.  The libGL.so.1.2 library contains a GLX protocol encoder for
  216. indirect/remote rendering and DRI code for accessing hardware drivers.  In
  217. particular, be sure you're not using libGL.so from another source such as
  218. Mesa or the Utah GLX project.
  219.  
  220. Unless it was built in a special way, the libGL.so library does not contain
  221. any 3D hardware driver code.  Instead, libGL.so dynamically loads the appro-
  222. priate 3D driver during initialization.
  223.  
  224. Most simple OpenGL programs also use the GLUT and GLU libraries.  A source
  225. for these libraries is listed in the Resources section below.
  226.  
  227. 6.2  Compiling and linking an OpenGL program
  228.  
  229. A simple GLUT/OpenGL program may be compiled and linked as follows:
  230.  
  231.              gcc program.c -I/usr/local/include -L/usr/local/lib -L/usr/X11R6/lib -lglut -lGLU -lGL -o program
  232.  
  233. The -I option is used to specify where the GL/glut.h (and possibly the
  234. GL/gl.h and GL/glu.h) header file may be found.
  235.  
  236. The -L options specify where the libglut.so, libGLU.so and X libraries are
  237. located.
  238.  
  239. The -lglut -lGLU -lGL arguments specify that the application should link with
  240. the GLUT, GLU and GL libraries.
  241.  
  242. 6.3  Running your OpenGL program
  243.  
  244. Simply typing ./program in your shell should execute the program.
  245.  
  246. If you get an error message such as
  247.  
  248.              gears: error in loading shared libraries: libGL.so.1: cannot
  249.              open shared object file: No such file or directory
  250.  
  251. if means that the libGL.so.1 file is not the right location.  Proceed to the
  252. trouble shooting section.
  253.  
  254. 6.4  glxinfo
  255.  
  256. glxinfo is a useful program for checking which version of libGL you're using
  257. as well as which DRI-based driver.  Simply type glxinfo and examine the
  258. OpenGL vendor, renderer, and version lines.  Among the output you should see
  259. something like this:
  260.  
  261.                OpenGL vendor string: Precision Insight, Inc.
  262.                OpenGL renderer string: Mesa DRI Voodoo3 20000224
  263.                OpenGL version string: 1.2 Mesa 3.3 beta
  264.  
  265. or this:
  266.  
  267.                OpenGL vendor string: Precision Insight, Inc.
  268.                OpenGL renderer string: Mesa GLX Indirect
  269.                OpenGL version string: 1.2 Mesa 3.3 beta
  270.  
  271. The first example indicates that the 3dfx driver is using Voodoo3 hardware.
  272. The second example indicates that no hardware driver was found and indirect,
  273. unaccelerated rendering is being used.
  274.  
  275. If you see that indirect rendering is being used when direct rendering was
  276. expected, proceed to the troubleshooting section.
  277.  
  278. glxinfo also lists all of the GLX-enhanced visuals available.  Here you can
  279. determine which visuals may have depth buffers, stencil buffers, accumulation
  280. buffers, etc.
  281.  
  282. 6.5  Environment Variables
  283.  
  284. The libGL.so library recognizes three environment variables.  Normally, none
  285. of them need to be defined.  If you're using the csh or tcsh shells, type
  286. setenv VARNAME value to set the variable.  Otherwise, if you're using sh or
  287. bash, type export VARNAME=value.
  288.  
  289.   1.  LIBGL_DEBUG, if defined will cause libGL.so to print error and diagnos-
  290.       tic messages.  This can help to solve problems.
  291.  
  292.   2.  LIBGL_ALWAYS_INDIRECT, if defined this will force libGL.so to always
  293.       use indirect rendering instead of hardware acceleration.  This can be
  294.       useful to isolate rendering errors.
  295.  
  296.   3.  LIBGL_DRIVERS_DIR can be used to override the default directory which
  297.       is searched for 3D drivers.  In a typical XFree86 installation, the 3D
  298.       drivers should be in /usr/X11R6/lib/modules/dri/.  This environment
  299.       variable can be used to specify a different directory.  Note that this
  300.       feature is disabled for set-uid programs.
  301.  
  302. Mesa-based drivers (this includes most of the drivers listed above) also
  303. observe many of the existing Mesa environment variables.  These include the
  304. MESA_DEBUG and MESA_INFO variables.
  305.  
  306. 7.  General Trouble Shooting
  307.  
  308. This section contains information to help you diagnose general problems.  See
  309. below for additional information for specific hardware.
  310.  
  311. 7.1  Starting the X server
  312.  
  313.   1.  Before you start the X server, verify the appropriate 3D kernel module
  314.       is installed.  Type lsmod and look for the appropriate kernel module.
  315.       For 3dfx hardware you should see tdfx, for example.
  316.  
  317.   2.  Verify you're running XFree86 4.0 and not an older version.  If you run
  318.       xdpyinfo and look for the following line near the top:
  319.  
  320.                        vendor release number:    4000
  321.  
  322.   3.  Verify that your XF86Config file (usually found at /etc/X11/XF86Config)
  323.       loads the glx and dri modules and has a DRI section.
  324.  
  325.       See the Software Resources section below for sample XF86Config files.
  326.  
  327.   4.  Examine the messages printed during X server startup and check that the
  328.       DRM module loaded.  Using the Voodoo3 as an example:
  329.  
  330.                    (==) TDFX(0): Write-combining range (0xf0000000,0x2000000)
  331.                    (II) TDFX(0): Textures Memory 7.93 MB
  332.                    (0): [drm] created "tdfx" driver at busid "PCI:1:0:0"
  333.                    (0): [drm] added 4096 byte SAREA at 0xc65dd000
  334.                    (0): [drm] mapped SAREA 0xc65dd000 to 0x40013000
  335.                    (0): [drm] framebuffer handle = 0xf0000000
  336.                    (0): [drm] added 1 reserved context for kernel
  337.                    (II) TDFX(0): [drm] Registers = 0xfc000000
  338.                    (II) TDFX(0): visual configs initialized
  339.                    (II) TDFX(0): Using XFree86 Acceleration Architecture (XAA)
  340.                            Screen to screen bit blits
  341.                            Solid filled rectangles
  342.                            8x8 mono pattern filled rectangles
  343.                            Indirect CPU to Screen color expansion
  344.                            Solid Lines
  345.                            Dashed Lines
  346.                            Offscreen Pixmaps
  347.                            Driver provided NonTEGlyphRenderer replacement
  348.                            Setting up tile and stipple cache:
  349.                                    10 128x128 slots
  350.                    (==) TDFX(0): Backing store disabled
  351.                    (==) TDFX(0): Silken mouse enabled
  352.                    (0): X context handle = 0x00000001
  353.                    (0): [drm] installed DRM signal handler
  354.                    (0): [DRI] installation complete
  355.                    (II) TDFX(0): direct rendering enabled
  356.  
  357.   5.  After the X server has started, verify that the required X server
  358.       extensions are loaded.  Run xdpyinfo and look for the following entries
  359.       in the extensions list:
  360.  
  361.                   GLX
  362.                   SGI-GLX
  363.                   XFree86-DRI
  364.  
  365. 7.2  Linking, running and verifying 3D acceleration
  366.  
  367. After you've verified that the X server and DRI have started correctly it's
  368. time to verify that the GL library and hardware drivers are working cor-
  369. rectly.
  370.  
  371.   1.  Verify that you're using the correct libGL.so library with ldd.  The
  372.       /usr/lib and /usr/X11R6/lib directories are expected locations for
  373.       libGL.so.
  374.  
  375.       Example:
  376.  
  377.                    % ldd /usr/local/bin/glxinfo
  378.                            libglut.so.3 => /usr/local/lib/libglut.so.3 (0x40019000)
  379.                            libGLU.so.1 => /usr/local/lib/libGLU.so.1 (0x40051000)
  380.                            libGL.so.1 => /usr/lib/libGL.so.1 (0x40076000)
  381.                            libXmu.so.6 => /usr/X11R6/lib/libXmu.so.6 (0x402ee000)
  382.                            libXi.so.6 => /usr/X11R6/lib/libXi.so.6 (0x40301000)
  383.                            libm.so.6 => /lib/libm.so.6 (0x40309000)
  384.                            libc.so.6 => /lib/libc.so.6 (0x40325000)
  385.                            libX11.so.6 => /usr/X11R6/lib/libX11.so.6 (0x40419000)
  386.                            libXt.so.6 => /usr/X11R6/lib/libXt.so.6 (0x404bd000)
  387.                            libSM.so.6 => /usr/X11R6/lib/libSM.so.6 (0x40509000)
  388.                            libICE.so.6 => /usr/X11R6/lib/libICE.so.6 (0x40512000)
  389.                            libXext.so.6 => /usr/X11R6/lib/libXext.so.6 (0x40529000)
  390.                            libvga.so.1 => /usr/lib/libvga.so.1 (0x40537000)
  391.                            libpthread.so.0 => /lib/libpthread.so.0 (0x4057d000)
  392.                            /lib/ld-linux.so.2 => /lib/ld-linux.so.2 (0x40000000)
  393.  
  394.   2.  You may also double check that libGL.so is in fact DRI-capable.  Run
  395.       strings libGL.so.1.2 | grep DRI and look for symbols prefixed with
  396.       "XF86DRI", such as "XF86DRIQueryExtension".
  397.  
  398.   3.  To be safe one should run ldconfig after installing libGL.so to be sure
  399.       the runtime loader will find the proper library.
  400.  
  401.   4.  Verify that the appropriate 3D driver is in /usr/X11R6/lib/modules/dri/
  402.       For example, the 3dfx driver will be named tdfx_dri.so.
  403.  
  404.   5.  Set the LIBGL_DEBUG environment variable.  This will cause libGL.so to
  405.       print an error message if it fails to load a DRI driver.  Any error
  406.       message printed should be self-explanatory.
  407.  
  408.   6.  Run glxinfo.  Note the line labeled "OpenGL renderer string".  It
  409.       should have a value which starts with "Mesa DRI" followed by the name
  410.       of your hardware.
  411.  
  412.   7.  Older Linux OpenGL applications may have been linked against Mesa's GL
  413.       library and will not automatically use libGL.so.  In some cases, making
  414.       symbolic links from the Mesa GL library to libGL.so.1 will solve the
  415.       problem:
  416.  
  417.                    ln -s libGL.so.1 libMesaGL.so.3
  418.  
  419.       In other cases, the application will have to be relinked against the
  420.       new XFree86 libGL.so.
  421.  
  422.       It is reported that part of the problem is that running ldconfig will
  423.       silently rewrite symbolic links based on the SONAME field in libraries.
  424.  
  425. If you're still having trouble, look in the next section for information spe-
  426. cific to your graphics card.
  427.  
  428. 8.  Hardware-Specific Information and Troubleshooting
  429.  
  430. This section presents hardware-specific information for normal use and trou-
  431. bleshooting.
  432.  
  433. 8.1  3dfx Voodoo3
  434.  
  435. 8.1.1  Troubleshooting
  436.  
  437.    o 3D acceleration for Voodoo3 is only supported in the 16 bit/pixel screen
  438.      mode.  Use xdpyinfo to verify that all your visuals are depth 16.  Edit
  439.      your XF86Config file if needed.
  440.  
  441. 8.1.2  Performance
  442.  
  443.    o Normally, buffer swapping in double-buffered applications is synchro-
  444.      nized to your monitor's refresh rate.  This may be overridden by setting
  445.      the FX_GLIDE_SWAPINTERNVAL environment variable.  The value of this
  446.      variable indicates the maximum number of swap buffer commands can be
  447.      buffered.  Zero allows maximum frame rate.
  448.  
  449.    o The glTexEnv mode GL_BLEND is not directly supported by the 3dfx hard-
  450.      ware.  It can be accomplished with a multipass algorithm but it's not
  451.      implemented at this time.  Applications which use that mode, such as the
  452.      Performer Town demo, may become sluggish when falling back to software
  453.      rendering to render in that mode.
  454.  
  455. 8.1.3  Known Problems
  456.  
  457.    o SSystem has problems because of poorly set near and far clipping planes.
  458.      The office.unc Performer model also suffers from this problem.
  459.  
  460. 8.2  Intel i810
  461.  
  462. 8.3  Matrox G400
  463.  
  464. 8.4  ATI Rage 128
  465.  
  466. 8.5  3DLabs Oxygen GMX 2000
  467.  
  468. The driver for this hardware was experimental and is no longer being devel-
  469. oped or supported.
  470.  
  471. 9.  Limitations and Known Bugs
  472.  
  473. 9.1  OpenGL
  474.  
  475. The following OpenGL features are not supported at this time: overlays,
  476. stereo, hardware-accelerated indirect rendering.
  477.  
  478. OpenGL-like functionality is provided with the Mesa library.  XFree86 4.0
  479. uses a beta version Mesa 3.3.  When newer versions of Mesa are available, the
  480. 3D drivers can be updated without reinstalling XFree86 or libGL.so.
  481.  
  482. 9.2  GLX
  483.  
  484. The GLX 1.3 API is exported but none of the new 1.3 functions are opera-
  485. tional.
  486.  
  487. The new glXGetProcAddressARB function is fully supported.
  488.  
  489. 9.3  Signal Handling
  490.  
  491. There are several understood, but unresolved problems relating to hardware
  492. locking and signal handling.  Hitting CTRL-z to suspend a 3D application can
  493. sometimes cause the X server to lock-up if executing device driver code at
  494. that moment.  Also, using a debugger to step through OpenGL/Mesa device
  495. driver functions code could cause a lock-up.  These problems will be fixed in
  496. the future.
  497.  
  498. 9.4  Scheduling
  499.  
  500. When you run multiple GL applications at once you may notice poor time slic-
  501. ing.  This is due to an interaction problem with the Linux scheduler which
  502. will be addressed in the future.
  503.  
  504. 9.5  Bug Database
  505.  
  506. The DRI bug database which includes bugs related to specific drivers is at
  507. the SourceForge DRI Bug Database
  508.  
  509. Please scan both the open and closed bug lists to determine if your problem
  510. has already been reported and perhaps fixed.
  511.  
  512. 10.  Resources
  513.  
  514. 10.1  Software
  515.  
  516. A collection of useful configuration files, libraries, headers, utilities and
  517. demo programs is available from http://dri.source-
  518. forge.net/resources/resources.html
  519.  
  520. 10.2  Documentation
  521.  
  522.    o General OpenGL information is available at the OpenGL Home Page
  523.  
  524.    o XFree86 information is available at the XFree86 Home Page
  525.  
  526.    o Information about the design of the DRI is available from Precision
  527.      Insight, Inc.
  528.  
  529.    o Visit the DRI project on SourceForge.net for the latest development news
  530.      about the DRI and 3D drivers.
  531.  
  532. 10.3  Support
  533.  
  534.    o The DRI-users mailing list at SourceForge is a forum for people to dis-
  535.      cuss DRI problems.
  536.  
  537.    o XXX IHV support?
  538.  
  539.    o XXX Linux distro support?
  540.  
  541.      Generated from XFree86: xc/programs/Xserver/hw/xfree86/doc/sgml/DRI.sgml,v 1.3 2000/03/08 05:38:41 dawes Exp $
  542.  
  543.