DRI User Guide : Using 3D Acceleration
Previous: Memory usage
Next: General Trouble Shooting

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

### 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 diagnostic 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 separated 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 programs. 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.

DRI User Guide : Using 3D Acceleration
Previous: Memory usage
Next: General Trouble Shooting