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.

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:

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.

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.

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.

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.

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.