DRI User Guide VA Linux Systems, Inc. Professional Services - Graphics. 15 June 2001 1. Preamble 1.1 Copyright Copyright © 2000-2001 by VALinux 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 reg- istered trademark of The Open Group. The ‘X’ device and X Window System aretrademarks of The Open Group. XFree86 is a registered trademark of The XFree86 Project, Inc. Linux is a regis- tered trademark of Linus Torvalds. Intel is a registered trademark of Intel Corporation. 3Dlabs, GLINT,and Oxygen areeither registered trademarks or trademarks of 3Dlabs Inc. Ltd. 3dfx, Voodoo3, Voodoo4, and Voodoo5 areregistered trademarks of 3dfx Interactive, Incorporated. Matrox is a registered trademark of Matrox Electronic Systems Ltd. ATIRage and Radeon are registered trademarks of ATI Technologies, Inc. All other trademarks mentioned arethe property of their respective owners. 2. Introduction With XFree86 4.x and the Direct Rendering Interface (DRI), hardwareaccelerated 3D graphics can be considered a standardfeatureonLinux 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 moredocumentation and softwaredownloads. 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’reanexperi- enced 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@tungstengrah- pics.com>. 3. Supported Architectures & Hardware DRI User Guide 1 DRI User Guide 2 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 areused in optimized vertex transformation functions in Mesa-based drivers. This requires a recent Linux kernel 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’redisabled otherwise. AMD’s 3DNow! instructions arealso used in optimized vertex transformation functions in the Mesa-based DRI drivers. 3DNow! is supported in most versions of Linux. Like the SSE opti- mizations, 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: • 3dfx, supported on Intel x86, AMD and Alpha: • Voodoo5 5500 • Voodoo4 4500 • Voodoo3 3500 TV • Voodoo3 3000 AGP • Voodoo3 3000 PCI • Voodoo3 2000 AGP • Voodoo3 2000 PCI • Voodoo Banshee • Velocity 100/200 Thereare many configurations of 3dfx cards on the market. Not all have been tested. • Matrox, supported on Intel x86 and AMD: • Matrox G200 • Matrox G400 • Intel i810/i815/i830 (motherboardchipsets) • i810 • i810-dc100 • i810e • i815 • i830 • ATIRage 128, supported on Intel x86, AMD and Alpha: • Rage Fury • Rage Magnum DRI User Guide 3 • XPERT2000 • XPERT128 • XPERT99 • All-in-Wonder 128 • Rage 128 PCI (Alpha-based systems) Note that both PCI and AGP versions of Rage 128 based cards aresupported at this time. • ATIRadeon, supported on Intel x86, AMD and Alpha: • Radeon SDR AGP • Radeon DDR AGP • Radeon 32MB SDR PCI (Alpha-based systems) • Radeon 7000, M6 (RV100) • Radeon 7200 (R100) • Radeon 7500, M7 (RV200) • Radeon 8500, 9100 (R200) • Radeon 9000, M9 (RV250) • 3Dlabs, supported on Intel x86 and AMD: • Oxygen GMX 2000 (MX/Gamma based). Note: this driver is no longer being actively developed. Support for other hardwareisunderway. Most of the DRI development work is funded by con- tracts with IHVs. These contracts often prevent us from announcing drivers beforethey’re released. Queries about upcoming drivers may not be answerable. 4. Prerequisite Software • The DRI is available in XFree86 4.0 and later. • Some hardwaredrivers requirespecific versions of the Linux kernel for AGP support, etc. See section 10 for specifics. • You DO NOT need to install Mesa separately. The parts of Mesa needed for hardware acceleration arealready in the XFree86/DRI project. 5. Kernel Modules 3D hardwareacceleration 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 thereare 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 latest 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/kernel/drivers/char/drm/ for automatic loading to work. Optionally,DRM kernel modules can be loaded manually with insmod prior to starting the X DRI User Guide 4 server. Youcan 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 controlled by the "DRI" section in the XF86Config file. If you want all of the users on your system to be able to use direct-rendering, 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)inthat group. Todo that, you might add the following line to /etc/group: xf86dri:x:8000:fred,jane Youhave 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 unaccel- erated indirect rendering. [Note that thereisaknown 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 Troubleshooting for details. DRI User Guide 5 7. Memoryusage Using the 3D features of a graphics cardrequires morememory than when it’s just used as a 2D device. Double buffering, depth buffering, stencil buffers, textures, etc. all requireextra graphics memory. These features may requirefour times the memory used for a simple 2D display. If your graphics carddoesn’t have a lot of memory (less than 16MB, for example), you may have to reduce your screen size and/or color depth in order to use 3D features. Reducing the screen resolution will also leave morespace for textureimages, 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 texturememory space. The documentation included with your cardshould have information about maximum screen size when using 3D. 8. Using 3D Acceleration This section describes how to link your application with libGL.so and verify that you areinfact 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 indirect/remote rendering and DRI code for accessing hardwaredrivers. In particular,besureyou’renot 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 hardwaredriver code. Instead, libGL.so dynamically loads the appropriate 3D driver during initialization. Most simple OpenGL programs also use the GLUT and GLU libraries. Asource for these libraries is listed in the Resources section below. 8.2 Compiling and linking an OpenGL program Asimple 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 wherethe GL/glut.h (and possibly the GL/gl.h and GL/glu.h) header file may be found.