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

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
        

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