DRI Users Guide : Using 3D Acceleration
Previous: X Server Start-up
Next: General Trouble Shooting

6. Using 3D Acceleration

This section describes how to link your application with libGL.so and verify that you are in fact using 3D acceleration.

6.1. libGL.so

Your OpenGL program must link with the libGL.so.1.2 library provided by XFree86 4.0. The libGL.so.1.2 library contains a GLX protocol encoder for indirect/remote rendering and DRI code for accessing hardware drivers. In particular, be sure you're not using libGL.so from another source such as Mesa or the Utah GLX project.

Unless it was built in a special way, the libGL.so library does not contain any 3D hardware driver code. Instead, libGL.so dynamically loads the appropriate 3D driver during initialization.

Most simple OpenGL programs also use the GLUT and GLU libraries. A source for these libraries is listed in the Resources section below.

6.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, libGLU.so and X libraries are located.

The -lglut -lGLU -lGL arguments specify that the application should link with the GLUT, GLU and GL libraries.

6.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.

6.4. 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: Precision Insight, Inc.
          OpenGL renderer string: Mesa DRI Voodoo3 20000224
          OpenGL version string: 1.2 Mesa 3.3 beta

or this:

          OpenGL vendor string: Precision Insight, Inc.
          OpenGL renderer string: Mesa GLX Indirect
          OpenGL version string: 1.2 Mesa 3.3 beta

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. Here you can determine which visuals may have depth buffers, stencil buffers, accumulation buffers, etc.

6.5. 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 diagnostic messages. This can help to solve problems.
  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_DIR can be used to override the default directory which is searched for 3D drivers. In a typical XFree86 installation, the 3D drivers should be in /usr/X11R6/lib/modules/dri/. This environment variable can be used to specify a different directory. Note that this feature is disabled for set-uid programs.

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.

DRI Users Guide : Using 3D Acceleration
Previous: X Server Start-up
Next: General Trouble Shooting