diff options
Diffstat (limited to 'xorg-server/hw/xfree86/doc/README.DRI')
| -rw-r--r-- | xorg-server/hw/xfree86/doc/README.DRI | 1256 |
1 files changed, 0 insertions, 1256 deletions
diff --git a/xorg-server/hw/xfree86/doc/README.DRI b/xorg-server/hw/xfree86/doc/README.DRI deleted file mode 100644 index 7fc52eb32..000000000 --- a/xorg-server/hw/xfree86/doc/README.DRI +++ /dev/null @@ -1,1256 +0,0 @@ - DRI User Guide - - VA Linux Systems, Inc. Professional Services - Graphics. - - 15 June 2001 - -1. Preamble - -1.1 Copyright - -Copyright 2000-2001 by VA Linux Systems, Inc. All Rights Reserved. - -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. - -1.2 Trademarks - -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 Inter- -active, Incorporated. Matrox is a registered trademark of Matrox Electronic -Systems Ltd. ATI Rage and Radeon are registered trademarks of ATI Technolo- -gies, Inc. All other trademarks mentioned are the property of their respec- -tive owners. - -2. Introduction - -With XFree86 4.x and the Direct Rendering Interface (DRI), hardware acceler- -ated 3D graphics can be considered a standard feature on Linux workstations. -Support for other operating systems, such as FreeBSD, is underway. - -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. - -This document does not cover compilation or installation of XFree86 4.x. It -is assumed that you've already installed a Linux distribution which includes -XFree86 4.x 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 http://dri.sourceforge.net/DRIcompile.html - -Edits, corrections and updates to this document may be mailed to <brian@tung- -stengrahpics.com>. - -3. Supported Architectures & Hardware - -3.1 CPU Architectures - -The architectures currently supported by the DRI have grown from the initial -Intel i386 systems to now include the Alpha Processor and the Sun SPARC -machines. - -Intel's SSE (a.k.a. Katmai) instructions are used in optimized vertex trans- -formation functions in Mesa-based drivers. This requires a recent Linux ker- -nel both at compile and runtime. See the DRI Compile Guide for compile-time -requirements. At runtime a check is made to determine if the CPU can execute -SSE instructions. They're disabled otherwise. - -AMD's 3DNow! instructions are also used in optimized vertex transformation -functions in the Mesa-based DRI drivers. 3DNow! is supported in most ver- -sions of Linux. Like the SSE optimizations, a runtime check is made to -determine if the CPU can execute 3DNow! instructions. - -Alpha-based systems can use Compaq's optimized math library for improved 3D -performance. See the DRI Compilation Guide for details. - -3.2 Graphics Hardware - -XFree86 4.2 (or later versions) includes 3D acceleration for the following -graphics hardware: - - o 3dfx, supported on Intel x86, AMD and Alpha: - - o Voodoo5 5500 - - o Voodoo4 4500 - - o Voodoo3 3500 TV - - o Voodoo3 3000 AGP - - o Voodoo3 3000 PCI - - o Voodoo3 2000 AGP - - o Voodoo3 2000 PCI - - o Voodoo Banshee - - o Velocity 100/200 - - There are many configurations of 3dfx cards on the market. Not all have - been tested. - - o Matrox, supported on Intel x86 and AMD: - - o Matrox G200 - - o Matrox G400 - - o Intel i810/i815/i830 (motherboard chipsets) - - o i810 - - o i810-dc100 - - o i810e - - o i815 - - o i830 - - o ATI Rage 128, supported on Intel x86, AMD and Alpha: - - o Rage Fury - - o Rage Magnum - - o XPERT 2000 - - o XPERT 128 - - o XPERT 99 - - o All-in-Wonder 128 - - o Rage 128 PCI (Alpha-based systems) - - Note that both PCI and AGP versions of Rage 128 based cards are sup- - ported at this time. - - o ATI Radeon, supported on Intel x86, AMD and Alpha: - - o Radeon SDR AGP - - o Radeon DDR AGP - - o Radeon 32MB SDR PCI (Alpha-based systems) - - o Radeon 7000, M6 (RV100) - - o Radeon 7200 (R100) - - o Radeon 7500, M7 (RV200) - - o Radeon 8500, 9100 (R200) - - o Radeon 9000, M9 (RV250) - - o 3Dlabs, supported on Intel x86 and AMD: - - o Oxygen GMX 2000 (MX/Gamma based). Note: this driver is no longer - being actively developed. - -Support for other hardware is underway. Most of the DRI development work is -funded by contracts with IHVs. These contracts often prevent us from -announcing drivers before they're released. Queries about upcoming drivers -may not be answerable. - -4. Prerequisite Software - - o The DRI is available in XFree86 4.0 and later. - - o Some hardware drivers require specific versions of the Linux kernel for - AGP support, etc. See section 10 for specifics. - - o You DO NOT need to install Mesa separately. The parts of Mesa needed - for hardware acceleration are already in the XFree86/DRI project. - -5. Kernel Modules - -3D hardware acceleration requires a DRI kernel module that's specific to your -graphics hardware. - -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. - -While the Linux source tree includes the DRI kernel module sources, the lat- -est DRI kernel sources will be found in the DRI source tree. - -See the DRI Compilation Guide for information on compiling the DRI kernel -modules. - -XFree86 4.0.1 added automatic kernel module loading to the X server. On -Linux, the X server uses modprobe to load kernel modules. In Linux 2.4.x the -DRM kernel modules should be kept in /lib/modules/2.4.x/ker- -nel/drivers/char/drm/ for automatic loading to work. - -Optionally, DRM kernel modules can be loaded manually with insmod prior to -starting the X server. - -You can verify that the kernel module was installed with lsmod, checking the -X server startup log, and checking that /proc/dri/0 exists. - -6. XF86Config file - -The XFree86 configuration file is usually found in /etc/X11/XF86Config. This -section describes the parts which must be specially set for the DRI. - -First, the XF86Config file must load the GLX and DRI modules: - - Section "Module" - ... - # This loads the GLX module - Load "glx" - # This loads the DRI module - Load "dri" - EndSection - -Next, the DRI section can be used to restrict access to direct rendering. A -client can only use direct rendering if it has permission to open the -/dev/dri/card? file(s). The permissions on these DRI device files is con- -trolled by the "DRI" section in the XF86Config file. - -If you want all of the users on your system to be able to use direct-render- -ing, then use a simple DRI section like this: - - Section "DRI" - Mode 0666 - EndSection - -This section will allow any user with a current connection to the X server to -use direct rendering. - -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 /etc/group file on -your system. For example, you may want to create a group called xf86dri and -place two users (e.g., fred and jane) in that group. To do that, you might -add the following line to /etc/group: - - xf86dri:x:8000:fred,jane - -You have to be careful that the group id (8000 in this example) is unique. - -Then you would use the following DRI section: - - Section "DRI" - Group "xf86dri" - Mode 0660 - EndSection - -This would limit access to direct-rendering to those users in the xf86dri -group (fred and jane in this example). When other users tried to use direct -rendering, they would fall back to unaccelerated indirect rendering. - -[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 /dev/dri directory with the rm -rf -/dev/dri command.] - -Finally, the XF86Config file needs Device and Screen sections specific to -your hardware. Look in section 10: Hardware-Specific Information and Trou- -bleshooting for details. - -7. Memory usage - -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. - -If your graphics card doesn't have a lot of memory (less than 16MB, for exam- -ple), you may have to reduce your screen size and/or color depth in order to -use 3D features. Reducing the screen resolution will also leave more space -for texture images, possibly improving 3D performance. If, for example, you -play Quake3 at 1024x768 but start your display at 1600x1200 you might con- -sider restarting X at 1024x768 in order to maximize your texture memory -space. - -The documentation included with your card should have information about maxi- -mum screen size when using 3D. - -8. Using 3D Acceleration - -This section describes how to link your application with libGL.so and verify -that you are in fact using 3D acceleration. - -8.1 libGL.so - -Your OpenGL program must link with the libGL.so.1.2 library provided by -XFree86. The libGL.so.1.2 library contains a GLX protocol encoder for indi- -rect/remote rendering and DRI code for accessing hardware drivers. In par- -ticular, be sure you're not using libGL.so from another source such as Mesa -or the Utah GLX project. - -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 appro- -priate 3D driver during initialization. - -Most simple OpenGL programs also use the GLUT and GLU libraries. A source -for these libraries is listed in the Resources section below. - -8.2 Compiling and linking an OpenGL program - -A simple GLUT/OpenGL program may be compiled and linked as follows: - - gcc program.c -I/usr/local/include -L/usr/local/lib -L/usr/X11R6/lib -lglut -lGLU -lGL -o program - -The -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. - -The -L options specify where the libglut.so and the X libraries are located. -libGL.so and libGLU.so should be in /usr/lib, as specified by the -Linux/OpenGL ABI standard. - -The -lglut -lGLU -lGL arguments specify that the application should link with -the GLUT, GLU and GL libraries, in that order. - -8.3 Running your OpenGL program - -Simply typing ./program in your shell should execute the program. - -If you get an error message such as - - gears: error in loading shared libraries: libGL.so.1: cannot - open shared object file: No such file or directory - -if means that the libGL.so.1 file is not the right location. Proceed to the -trouble shooting section. - -8.4 libOSMesa.so - -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. It -was originally developed for Mesa before Mesa became part of the XFree86/DRI -project. It can now be used with the XFree86/DRI libGL.so as well. - -libOSMesa.so implements the OSMesa interface and it must be linked with your -application if you want to use the OSMesa functions. You must also link with -libGL.so. For example: - - gcc osdemo.c -lOSMesa -lGLU -lGL -o osdemo - -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. - -8.5 glxinfo - -glxinfo is a useful program for checking which version of libGL you're using -as well as which DRI-based driver. Simply type glxinfo and examine the -OpenGL vendor, renderer, and version lines. Among the output you should see -something like this: - - OpenGL vendor string: VA Linux Systems, Inc. - OpenGL renderer string: Mesa DRI Voodoo3 20000224 - OpenGL version string: 1.2 Mesa 3.4 - -or this: - - OpenGL vendor string: VA Linux Systems, Inc. - OpenGL renderer string: Mesa GLX Indirect - OpenGL version string: 1.2 Mesa 3.4 - -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. - -If you see that indirect rendering is being used when direct rendering was -expected, proceed to the troubleshooting section. - -glxinfo also lists all of the GLX-enhanced visuals available so you can -determine which visuals are double-bufferd, have depth (Z) buffers, stencil -buffers, accumulation buffers, etc. - -8.6 Environment Variables - -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 -setenv VARNAME value to set the variable. Otherwise, if you're using sh or -bash, type export VARNAME=value. - - 1. LIBGL_DEBUG, if defined will cause libGL.so to print error and diagnos- - tic messages. This can help to solve problems. Setting LIBGL_DEBUG to - verbose may provide additional information. - - 2. 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. - - 3. LIBGL_DRIVERS_PATH can be used to override the default directories - which are searched for 3D drivers. The value is one or more paths sep- - arated by colons. In a typical XFree86 installation, the 3D drivers - should be in /usr/X11R6/lib/modules/dri/ and LIBGL_DRIVERS_PATH need - not be defined. Note that this feature is disabled for set-uid pro- - grams. This variable replaces the LIBGL_DRIVERS_DIR env var used in - XFree86 4.0. - - 4. 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 glGetError. - -Mesa-based drivers (this includes most of the drivers listed above) also -observe many of the existing Mesa environment variables. These include the -MESA_DEBUG and MESA_INFO variables. - -9. General Trouble Shooting - -This section contains information to help you diagnose general problems. See -below for additional information for specific hardware. - -9.1 Bus Mastering - -DMA-based DRI drivers (that's most DRI drivers) cannot function unless bus -mastering is enabled for your graphics card. By default, some systems don't -having bus mastering on. You should enable it in your BIOS. - -Alternately, you can check the status of bus mastering and change the setting -from within Linux. There may be similar procedures for other operating sys- -tems. - -Run lspci (as root) and find the information describing your graphics -adapter. For example: - - 00:00.0 Host bridge: Intel Corporation 440BX/ZX - 82443BX/ZX Host bridge (rev 03) - 00:01.0 PCI bridge: Intel Corporation 440BX/ZX - 82443BX/ZX AGP bridge (rev 03) - 00:07.0 ISA bridge: Intel Corporation 82371AB PIIX4 ISA (rev 02) - 00:07.1 IDE interface: Intel Corporation 82371AB PIIX4 IDE (rev 01) - 00:07.2 USB Controller: Intel Corporation 82371AB PIIX4 USB (rev 01) - 00:07.3 Bridge: Intel Corporation 82371AB PIIX4 ACPI (rev 02) - 00:11.0 Ethernet controller: Intel Corporation 82557 [Ethernet Pro 100] (rev 08) - 00:12.0 SCSI storage controller: Symbios Logic Inc. (formerly NCR) 53c895 (rev 02) - 00:14.0 Multimedia audio controller: Ensoniq ES1371 [AudioPCI-97] (rev 08) - 01:00.0 VGA compatible controller: 3Dfx Interactive, Inc.: Unknown device 0009 (rev 01) - -The bus, device, and function number comprise the device id, which is conven- -tionally written in the form bus:dev.func, or in this case 01:00.0. - -Use the setpci command to examine bit two of register 4 for your graphics -card. This will indicate whether or not bus mastering is enabled. - - setpci -s 01:00.0 4.w - -A hexadecimal value will be printed. Convert the least significant digit to -binary. For example, if you see 3, that's 0011 in binary (bit two is 0). If -you see 7, that's 0111 in binary (bit two is 1). In the first example, bus -mastering is disabled. It's enabled in the second example. - -The following shell script will enabled bus mastering for your graphics card -and host bridge. Run it as root. - - #!/bin/bash - dev=01:00.0 # change as appropriate - echo Enabling bus mastering on device $dev - setpci -s $dev 4.w=$(printf %x $((0x$(setpci -s $dev 4.w)|4))) - dev=00:00.0 - echo Enabling bus mastering on host bridge $dev - setpci -s $dev 4.w=$(printf %x $((0x$(setpci -s $dev 4.w)|4))) - -You can check if this worked by running the first setpci command again. - -9.2 The X Server - - 1. Before you start the X server, verify the appropriate 3D kernel module - is installed. Type lsmod and look for the appropriate kernel module. - For 3dfx hardware you should see tdfx, for example. - - 2. Verify you're running XFree86 4.0 (or newer) and not an older version. - If you run xdpyinfo and look for the following line near the top: - - vendor release number: 4000 - - 3. Verify that your XF86Config file (usually found at /etc/X11/XF86Config) - loads the glx and dri modules and has a DRI section. - - See the Software Resources section below for sample XF86Config files. - - 4. Examine the messages printed during X server startup and check that the - DRM module loaded. Using the Voodoo3 as an example: - - (==) 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 - - 5. After the X server has started, verify that the required X server - extensions are loaded. Run xdpyinfo and look for the following entries - in the extensions list: - - GLX - SGI-GLX - XFree86-DRI - -9.3 Linking, running and verifying 3D acceleration - -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 cor- -rectly. - - 1. Verify that you're using the correct libGL.so library with ldd. The - /usr/lib and /usr/X11R6/lib directories are expected locations for - libGL.so. - - Example: - - % 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) - - 2. You may also double check that libGL.so is in fact DRI-capable. Run - strings libGL.so.1.2 | grep DRI and look for symbols prefixed with - "XF86DRI", such as "XF86DRIQueryExtension". - - 3. To be safe one should run ldconfig after installing libGL.so to be sure - the runtime loader will find the proper library. - - 4. Verify that the appropriate 3D driver is in /usr/X11R6/lib/modules/dri/ - For example, the 3dfx driver will be named tdfx_dri.so. - - 5. Set the 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. - - 6. Run 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. - - 7. 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: - - ln -s libGL.so.1 libMesaGL.so.3 - - In other cases, the application will have to be relinked against the - new XFree86 libGL.so. - - It is reported that part of the problem is that running ldconfig will - silently rewrite symbolic links based on the SONAME field in libraries. - -If you're still having trouble, look in the next section for information spe- -cific to your graphics card. - -10. Hardware-Specific Information and Troubleshooting - -This section presents hardware-specific information for normal use and trou- -bleshooting. - -10.1 3dfx Banshee, Voodoo3, Voodoo4 and Voodoo5 Series - -10.1.1 Requirements - -The 3dfx DRI driver requires special versions of the 3dfx Glide library. -Different versions of Glide are needed for Banshee/Voodoo3 than for -Voodoo4/5. The Glide libraries can be downloaded from the DRI website. - -10.1.2 Configuration - -Your XF86Config file's device section must specify the tdfx device. For -example: - - Section "Device" - Identifier "Voodoo3" - VendorName "3dfx" - Driver "tdfx" - EndSection - -Or, - - Section "Device" - Identifier "Voodoo5" - VendorName "3dfx" - Driver "tdfx" - EndSection - -The Screen section should then reference the Voodoo device: - - 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 - -Or, - - 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 - -The kernel module for 3dfx hardware is named tdfx.o and should be installed -in /lib/modules/2.4.x/kernel/drivers/char/drm/. It will be automatically -loaded by the Xserver if needed. - -The DRI 3D driver for 3dfx hardware should be in /usr/X11R6/lib/mod- -ules/dri/tdfx_dri.so. This will be automatically loaded by libGL.so. - -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 16bpp mode only a 16-bit Z (depth) buffer is offered and -stencil is implemented in software. - -A software-based accumulation buffer is available in both 16 and 32bpp modes. - -10.1.3 Troubleshooting - - o If you try to run an OpenGL application and see an error message similar - to - - gd error (glide): gd error (glide): grSstSelect: non-existent SSTgd error (glide): grSstSelect: non-existent SSTS - - it means that you have the wrong version of the Glide library for your - hardware. - - o 3D acceleration for Banshee and Voodoo3 is only supported in the 16 - bit/pixel screen mode. Use xdpyinfo to verify that all your visuals are - depth 16. Edit your XF86Config file if needed. - - o The /dev/3dfx device is not used for DRI; it's only for Glide on older - 3dfx hardware. - - o Different versions of Glide are needed for Voodoo3 and Voodoo5. See the - DRI website's resources page to download the right version of Glide. - - o Voodoo4/5 may be run at 24bpp (instead of 32bpp, the default) but 3D - acceleration is not supported in that mode. 32bpp mode is fully 3D - accelerated. - -10.1.4 Performance and Features - - o Normally, buffer swapping in double-buffered applications is synchro- - nized to your monitor's refresh rate. This may be overridden by setting - the FX_GLIDE_SWAPINTERVAL environment variable. The value of this vari- - able indicates the maximum number of swap buffer commands can be - buffered. Zero allows maximum frame rate. - - o On Voodoo4/5, rendering with 16-bits/texel textures is faster than using - 32-bit per texel textures. The internalFormat parameter to glTexImage2D - can be used to control texel size. Quake3 and other games let you con- - trol this as well. - - o The glTexEnv mode 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 soft- - ware rendering to render in that mode. - - o The Voodoo3/Banshee driver reverts to software rendering under the fol- - lowing conditions: - - o Setting GL_LIGHT_MODEL_COLOR_CONTROL to GL_SEPARATE_SPECULAR_COLOR. - - o Enabling line stippling or polygon stippling. - - o Enabling point smoothing or polygon smoothing. - - o 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. - - o Using 1-D or 3-D texture maps. - - o Using the GL_BLEND texture environment. - - o Using stencil operations. - - o Using the accumulation buffer. - - o Using glBlendEquation(GL_LOGIC_OP). - - o Using glDrawBuffer(GL_FRONT_AND_BACK). - - o Using glPolygonMode(face, GL_POINT) or glPolygonMode(face, - GL_LINE). - - o Using point size attenuation (i.e. GL_DISTANCE_ATTENUATION_EXT). - - o Using glColorMask(r, g, b, a) when r!=g or g!=b. - - o The Voodoo5 driver reverts to software rendering under the same condi- - tions Voodoo3 with three exceptions. First, stencil operations are - implemented in hardware when the screen is configured for 32 bits/pixel. - Second, the GL_BLEND texture env mode is fully supported in hardware. - Third, glColorMask is fully supported in hardware when the screen is - configured for 32 bits/pixel. - - o As of January, 2001 the second VSA-100 chip on the Voodoo5 is not yet - operational. Therefore, the board isn't being used to its full capac- - ity. The second VSA-100 chip will allow Scan-Line Interleave (SLI) mode - for full-screen applications and games, potentially doubling the sys- - tem's fill rate. When the second VSA-100 chip is activated glGet- - String(GL_RENDERER) will report Voodoo5 instead of Voodoo4. - - o The lowest mipmap level is sometimes miscolored in trilinear- sampled - polygons. - - o The GL_EXT_texture_env_combine extension is supported on the Voodoo4 and - Voodoo5. - -10.1.5 Known Problems - - o The lowest mipmap level is sometimes miscolored in trilinear- sampled - polygons (Voodoo3/Banshee). - - o Fog doesn't work with orthographic projections. - - o The accuracy of blending operations on Voodoo4/5 isn't always very good. - If you run Glean, you'll find some test failures. - - o The Glide library cannot be used directly; it's only meant to be used - via the tdfx DRI driver. - - o SSystem has problems because of poorly set near and far clipping planes. - The office.unc Performer model also suffers from this problem. - -10.2 Intel i810 - -10.2.1 Requirements - -A kernel with AGP GART support (such as Linux 2.4.x) is needed. - -10.2.2 Configuration - -Your XF86Config file's device section must specify the i810 device, and spec- -ify a usable amount of video ram to reserve. - - Section "Device" - Identifier "i810" - VendorName "Intel" - Driver "i810" - Option "AGPMode" "1" - VideoRam 10000 - EndSection - -The Screen section should then reference the i810 device: - - 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 - -The kernel module for the i810 is named i810.o and should be installed in -/lib/modules/2.4.x/kernel/drivers/char/drm/. It will be automatically loaded -by the Xserver if needed. - -The DRI 3D driver for the i810 should be in /usr/X11R6/lib/mod- -ules/dri/i810_dri.so. This will be automatically loaded by libGL.so. - -10.2.3 Troubleshooting - - o 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 xdpyinfo to verify that all your visuals are depth 16. - Edit your XF86Config file if needed. - - o 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 num- - ber 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. - -10.2.4 Performance and Features - -Basically all of the i810 features which can be exposed through OpenGL 1.2 -are implemented. However, the following OpenGL features are implemented in -software and will be slow: - - o Stencil buffer and accumulation buffer operations - - o Blend subtract, min/max and logic op blend modes - - o glColorMask when any mask is set to false - - o GL_SEPARATE_SPECULAR_COLOR lighting mode - - o glDrawBuffer(GL_FRONT_AND_BACK) - - o Using 1D or 3D textures - - o Using texture borders - -10.3 Matrox G200 and G400 - -10.3.1 Requirements - -A kernel with AGP GART support (such as Linux 2.4.x) is needed. - -10.3.2 Configuration - -Your XF86Config file's device section must specify the mga device: - - Section "Device" - Identifier "MGA" - VendorName "Matrox" - Driver "mga" - Option "AGPMode" "1" - VideoRam 32768 - EndSection - -The Screen section should then reference the MGA device: - - 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 - -To use a 32bpp screen mode, use this Screen section instead: - - 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 - -The kernel module for the G200/G400 is named mga.o and should be installed in -/lib/modules/2.4.x/kernel/drivers/char/drm/. It will be automatically loaded -by the Xserver if needed. - -The DRI 3D driver for the G200/G400 should be in /usr/X11R6/lib/mod- -ules/dri/mga_dri.so. This will be automatically loaded by libGL.so. - -10.3.3 Performance and Features - -Software rendering will be used under any of the following conditions: - - o Using glDrawBuffer(GL_FRONT_AND_BACK). - - o Using point, line, or triangle smoothing. - - o Using glLogicOp. - - o Using glPolygonStipple or glLineStipple. - - o Using 1D or 3D textures. - - o Using texture borders. - - o Using glDepthFunc(GL_NEVER). - - o Using the accumulation buffer. - -The AGP mode may be set to 1, 2, or 4. One is used by default. Higher AGP -speeds may result in unreliable performance depending on your motherboard. - -Compaq has funded the implementation of AGP accelerated ReadPixels and Draw- -Pixels in this driver. With this implementation, on a G400 drawing directly -from AGP memory (exported to the client), throughput of up to 1 GB/sec has -been measured. - -Additionally Compaq's funding has produced several new extensions in Mesa, -including one (packed_depth_stencil_MESA) which enables Read/DrawPixels func- -tionality to operate directly on the packed 24/8 depth/stencil buffers of -this hardware. - -In order to access this functionality, the application must ensure that all -pixel processing operations are disabled. There are in addition a fairly -complex set of rules regarding which packing/unpacking modes must be used, -and which data formats are supported, and alignment constraints. See the -files in lib/GL/mesa/src/drv/mga/DOCS for a summary of these. The extension -definitions are included in the Mesa 3.4 source distribution. - -10.3.4 IRQ Assignment - -There have been problems in the past with the MGA driver being very sluggish -when the DRI is enabled (to the point of being unusable.) This is caused by -the graphics card not having an interrupt assigned to it. The current DRI -trunk will attempt to detect this condition and bail out gracefully. - -The solution to the above problem is to assign an interrupt to your graphics -card. This is something you must turn on in your system BIOS configuration. -Please consult your system BIOS manual for instructions on how to enable an -interrupt for your graphics card. - -10.3.5 MGA HAL lib - -MGAHALlib.a is a binary library Matrox has provided for use under Linux to -expose functionality for which they can not provide documentation. (For -example TV-Out requires MacroVision be enabled on the output.) This binary -library also sets the pixel/memory clocks to the optimal settings for your -Matrox card. - -Currently the MGAHAL library is required for the G450 to work. You can down- -load this from the driver section on Matrox's website: www.matrox.com/mga - -Here modifications to the DRI build instructions which make the mga ddx -driver use the MGAHAL library: - - 1.Put the following define in your host.def file - #define UseMatroxHal YES - 2. Place mgaHALlib.a in the following directory - xc/programs/Xserver/hw/xfree86/drivers/mga/HALlib/ - -You can use DualHead on the G400/G450 DH cards by creating two device sec- -tions which both point to the same BusID. For most AGP devices the BusID -will be "PCI:1:0:0". Configure your screen section as you would normally -configure XFree86 4.x Multihead. It should be noted that currently the sec- -ond head does not support direct rendering. - -10.3.6 Known Problems - -None. - -10.4 ATI Rage 128 - -10.4.1 Requirements - -A kernel with AGP GART support (such as Linux 2.4.x) is needed. - -10.4.2 Configuration - -Your XF86Config file's device section must specify the ati device: - - Section "Device" - Identifier "Rage128" - VendorName "ATI" - Driver "ati" - Option "AGPMode" "1" - Option "UseCCEFor2D" "false" - EndSection - -The Screen section should then reference the Rage 128 device: - - 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 - -The kernel module for the Rage 128 is named r128.o and should be installed in -/lib/modules/2.4.x/kernel/drivers/char/drm/. It will be automatically loaded -by the Xserver if needed. - -The DRI 3D driver for the Rage 128 should be in /usr/X11R6/lib/mod- -ules/dri/r128_dri.so. This will be automatically loaded by libGL.so. - -You may also set your screen depth to 32 for 32bpp mode. - -10.4.3 Performance and Features - -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. - -For AGP cards, the AGP mode may be set to 1, 2, or 4. One is used by -default. Higher AGP speeds may result in unreliable performance depending on -your motherboard. - -Note that even at 32bpp there is no alpha channel. - -The following OpenGL features are implemented in software and will be slow: - - o accumulation buffer operations - - o stencil, when using a 16bpp screen - - o Blend subtract, min/max and logic op blend modes - - o GL_SEPARATE_SPECULAR_COLOR lighting mode - - o glDrawBuffer(GL_FRONT_AND_BACK) - - o Using 1D or 3D textures - - o Using texture borders - -10.4.4 Known Problems - -If you experience stability problems you may try setting the UseCCEFor2D -option to true. This will effectively disable 2D hardware acceleration. -Performance will be degraded, of course. - -10.5 ATI Radeon - -10.5.1 Requirements - -A kernel with AGP GART support (such as Linux 2.4.x) is needed. - -10.5.2 Configuration - -Your XF86Config file's device section must specify the ati device: - - Section "Device" - Identifier "Radeon" - VendorName "ATI" - Driver "ati" - Option "AGPMode" "1" - EndSection - -The Screen section should then reference the Radeon device: - - Section "Screen" - Identifier "Screen 1" - Device "Radeon" - 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 - -The kernel module for the Radeon is named radeon.o and should be installed in -/lib/modules/2.4.x/kernel/drivers/char/drm/. It will be automatically loaded -by the Xserver if needed. - -The DRI 3D driver for the Radeon should be in /usr/X11R6/lib/mod- -ules/dri/radeon_dri.so. This will be automatically loaded by libGL.so. - -You may also set your screen depth to 32 for 32bpp mode. - -10.5.3 Performance and Features - -While this driver supports many of the features of ATI Radeon cards, we do -not yet fully support the card's TCL features. This work is progressing, but -is not yet ready. - -The AGP mode may be set to 1, 2, or 4. One is used by default. Higher AGP -speeds may result in unreliable performance depending on your motherboard. - -The following OpenGL features are implemented in software and will be slow: - - o Blend subtract, blend min/max and blend logicops - - o Stencil and accumulation operations - - o 1D and 3D textures - - o Texture borders - -The GL_EXT_texture_env_combine, GL_EXT_texture_env_add and GL_EXT_tex- -ture_env_dot3 extensions are supported (or will be soon supported in the new -driver based on Mesa 3.5). - -We hope to implement support for the following features in the future: - - o Vertex transformation, clipping and lighting (TCL) - - o Hardware stencil buffer - - o Cube map textures - - o 3D textures - - o Three texture units - -10.5.4 Known Problems - -Certain (early?) revisions of the AMD Irongate chipset have AGPGART problems -which effect Radeon, and other graphics cards. The card may work unreliably, -or not work at all. If the DRM kernel module is not loaded, the 2D Xserver -may work. There's hope that this can be fixed in the future. - -10.6 3DLabs Oxygen GMX 2000 - -The driver for this hardware was experimental and is no longer being devel- -oped or supported. - -11. General Limitations and Known Bugs - -11.1 OpenGL - -The following OpenGL features are not supported at this time: overlays, -stereo, hardware-accelerated indirect rendering. - -OpenGL-like functionality is provided with the Mesa library. XFree86 4.1.0 -uses Mesa 3.4.2. 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. - -11.2 GLX - -The GLX 1.3 API is exported but none of the new 1.3 functions are opera- -tional. - -The new glXGetProcAddressARB function is fully supported. - -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. - -11.3 Debugging - -Debugging DRI drivers with gdb can be difficult because of the locking -involved. When debugging OpenGL applications, you should avoid stepping -inside the GL functions. If you're trying to debug a DRI driver it's recom- -mended that you do so remotely, from a second system. - -11.4 Scheduling - -When you run multiple GL applications at once you may notice poor time slic- -ing. This is due to an interaction problem with the Linux scheduler which -will be addressed in the future. - -11.5 libGL.so and dlopen() - -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. - -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: - - o 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_Con- - text is undefined when libGL.so tries to open a hardware-specific - driver. Without this flag, nested opening of dynamic libraries does not - work. - - o 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. - - o Your application should link with -lpthread. On Linux, libGL.so uses - the pthreads library in order to provide thread safety. There is appar- - ently 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. - -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. - -11.6 Bug Database - -The DRI bug database which includes bugs related to specific drivers is at -the SourceForge DRI Bug Database - -Please scan both the open and closed bug lists to determine if your problem -has already been reported and perhaps fixed. - -12. Resources - -12.1 Software - -A collection of useful configuration files, libraries, headers, utilities and -demo programs is available from http://dri.sourceforge.net/res.phtml - -12.2 Documentation - - o General OpenGL information is available at the OpenGL Home Page - - o XFree86 information is available at the XFree86 Home Page - - o Information about the design of the DRI is available from Precision - Insight, Inc. - - o Visit the DRI project on SourceForge.net for the latest development news - about the DRI and 3D drivers. - - o The DRI Compilation Guide explains how to download, compile and install - the DRI for yourself. - -12.3 Support - - o The DRI-users mailing list at SourceForge is a forum for people to dis- - cuss DRI problems. - - o In the future there may be IHV and Linux vendor support resources for - the DRI. - - Generated from XFree86: xc/programs/Xserver/hw/xfree86/doc/sgml/DRI.sgml,v 1.28 dawes Exp $ - - |