gluX - cross platform easy OpenGL eXtension Loading

Version 1.6 (updated 2004-03-02)

What is gluX ?

GluX is a cross-platform easy-to-use OpenGL extension loader. It offers a very simple mechanism for loading and using OpenGL extensions. It allows your code to compile under Windows and Linux even if your video card doesn't support the OpenGL extensions used by your program: at run time, gluX will detect if required extensions are present or not.

OpenGL extension loading with gluX

There is two main cases:

Your program cannot run without required extensions.

Your program can have different behaviors depending on available extensions.

If your program cannot run without required extensions

The simplest way to load an extension is to do the following: (sample/sample0.cpp)

#include <GL/gl.h>
#include <GL/glut.h>
#include <glux.h>

// declare GL_NV_vertex_program extension as required
GLUX_REQUIRE(GL_NV_vertex_program);

void main(int argc,char **argv)
{
  GLuint vprog;
  
  // init openGL (with glut)
  glutInit(&argc, argv);
  glutInitWindowSize(640, 480);
  glutInitDisplayMode(GLUT_RGBA | GLUT_DOUBLE | GLUT_DEPTH | GLUT_ALPHA);
  
  // init gluX
  gluxInit();
  
  // if we are here, GL_NV_vertex_program is available !
  // gluX has already stopped the execution if one of the required extensions
  // is not available.

  // let's call some vertex program stuff (just for example)
  cerr << "Calling glGenProgramsNV ..." << endl;
  glGenProgramsNV(1,&vprog);
  cerr << "Calling glBindProgramNV ..." << endl;
  glBindProgramNV(GL_VERTEX_PROGRAM_NV, vprog);
  cerr << "Done." << endl;

}

As the extensions are required, gluX will end the execution if one or more extensions are not available.

If your program can have different behaviors depending on available extensions

You can load an extension and manually test if it is available. This can be useful to implement the same effect on various hardware. For an example in a video game you want graphics to be as good as possible. If your program detects a pixel shader extension it can render a beautiful bump-mapping, if not it can emulate the effect with standard OpenGL functionalities. The following code demonstrates how to use gluX to test if an extension is available: (sample/sample2.cpp)

#include <GL/gl.h>
#include <GL/glut.h>
#include <glux.h>

// declare extensions that you want to load
GLUX_LOAD(GL_NV_vertex_program);
GLUX_LOAD(GL_SUN_mesh_array);

void main(int argc,char **argv)
{
  // init openGL (with glut)
  glutInit(&argc, argv);
  glutInitWindowSize(640, 480);
  glutInitDisplayMode(GLUT_RGBA | GLUT_DOUBLE | GLUT_DEPTH | GLUT_ALPHA);
  
  // init gluX
  gluxInit();
  
  cerr << "gluX does not stop if a loaded extension is not available." << endl;
  if (GLUX_IS_AVAILABLE(GL_SUN_mesh_array) == GLUX_AVAILABLE)
    cerr << endl << "GL_SUN_mesh_array is available" << endl;
  else
    cerr << endl << "GL_SUN_mesh_array is *not* available" << endl;
  if (GLUX_IS_AVAILABLE(GL_NV_vertex_program) == GLUX_AVAILABLE)
    cerr << endl << "GL_NV_vertex_program is available" << endl;
  else
    cerr << endl << "GL_NV_vertex_program is *not* available" << endl;
  
  cerr << endl << "Done." << endl;
}

If both ?

gluX can handle both cases together. Required extensions should be declared with GLUX_REQUIRE, the other should be loaded with GLUX_LOAD. If one of required extensions is missing, the program will not run. If multiple files include GLUX_LOAD and GLUX_REQUIRE instructions for the same extension, only GLUX_REQUIRE is considered. This mechanism supports static linkage of objects or static libraries.

DEVL extensions

Sometimes, when an extension is in development the driver hides it: Functions are present but the extension is not declared as available by the driver. To load development extensions (marked as DEVL by gluX), call gluxInit with the GLUX_DEVL flag. Be aware that these extensions may not work properly.

Loading all extensions

In some cases you may want your program to load all the extensions. This can be done easily by including <glux_load_all.h> instead of <glux.h>. Then you can use the macro GLUX_IS_AVAILABLE to check whether an extension is available at runtime.

Extension status

At startup gluX displays the status of each required/loaded extension. The different status are:

```
[ OK ] GL_ARB_extension
```
Extension is available
```
[FAIL] GL_ARB_extension
```
Extension is not available
```
[DEVL] GL_ARB_extension
```
Extension seems to be available (functions are present but the extension is not declared as available by the driver). See DEVL extensions for more information.
```
[XXXX] GL_ARB_extension
```
Extension is available but has been disabled to emulate a profile. See gluX Extension Profiles for more information.

glux namespace

To avoid conflicts all functions loaded by gluX are in the glux namespace. By default, the header <glux.h> declares

using namespace glux;

. This can be disabled by defining GLUX_EXPLICIT_NAMESPACE before including <glux.h>. In this case, a function glDoSomethingCool should be called with glux::glDoSomethingCool.

gluX Extension Profiles

Very often applications are developed on powerful graphics hardware but are designed to support less powerful hardware (well, the non-hardcore-gamer user :-).

Testing what your application will look like may not be easy: Deactivating extension loading mechanism by commenting some parts of the code is really not a good solution (well, anyone who released an application with his never-seen-before-effect disabled knows what I mean :-)

Therefore gluX now supports extension profiles. The idea is to ask gluX to emulate less powerful hardware by disabling some extensions. Since gluX cannot emulate extensions that your hardware doesn't support, this mechanism works only to emulate hardware whose extension set is included in the installed graphic card extension set (like emulating a GeForce3 with a GeForceFX).

Using a gluX profile

To use a specific gluX extension profile you just need to give the filename of the gluX profile as the second argument of gluxInit(). Some predefined profiles are given in the profiles directory of the gluX distribution.

How to create a gluX profile

The tool gluxinfo, available in the gluX distribution, produces gluX extension profiles when called without any argument. Called with a profile filename as first argument it checks whether the profile is compatible with your current graphics hardware. Some predefined profiles are also given in the profiles directory of the gluX distribution. Feel free to send me more profiles !

Reference

Function or macro	Description	Calling context
gluxInit()	gluX initialization.	It should be called once just after the OpenGL initialization
gluxInit(int <flags>=0)	gluX initialization.	<flags> can be set to GLUX_DEVL to allow development extensions (see DEVL extensions).
*gluxInit(int <flags>=0,const char <profile>=NULL)**	gluX initialization.	<profile> can be set to the filename of a gluX extension profile (see Using a gluX profile).
*GLUX_REQUIRE(ext_name)*	This macro declare that your program requires the ext_name extension to be executed. If the extension is not found, the program will be exited by gluX.	It should be called once in your main .cpp file, outside of any function declaration.
*GLUX_LOAD(ext_name)*	This macro declare that your program should load the ext_name extension. The availability of the extension could be tested with gluxIsAvailable.	It should be called once in your main .cpp file, outside of any function declaration.
*GLUX_IS_AVAILABLE(ext_name)*	This macro test if a loaded extension is available at runtime. It is faster than gluxIsAvailable (see below) because it does not use a string to reference the extension. The constraint is that a GLUX_LOAD or a GLUX_REQUIRE for the extension should be present in the same cpp file.	Call this every time you need to know if an extension is available. As extension availability is tested only once at startup, this macro is fast. This macro is a boolean.
*gluxIsAvailable(ext_name_string)*	Test if a loaded extension is available on the running graphic hardware.	Call this every time you need to know if an extension is available. Extension name should be a null terminated string. For faster testing use GLUX_IS_AVAILABLE macro rather than this function. The function returns GLUX_AVAILABLE if the extension is available, GLUX_NOT_AVAILABLE if not, GLUX_NOT_LOADED if the extension was not loaded by gluX at startup.
*GLUX_IS_DEVL(ext_name)*	This macro test if a loaded extension is in development (not officially available in the driver). It is faster than gluxIsDevl (see below) because it does not use a string to reference the extension. The constraint is that a GLUX_LOAD or a GLUX_REQUIRE for the extension should be present in the same cpp file.	Call this every time you need to know if an extension is in development. As extension status is tested only once at startup, this macro is fast. This macro is a boolean.
*gluxIsDevl(ext_name_string)*	Test if a loaded extension is in development.	Call this every time you need to know if an extension is in development. Extension name should be a null terminated string. For faster testing use GLUX_IS_DEVL macro rather than this function. The function returns GLUX_DEVL if the extension is in development, GLUX_NOT_DEVL if not, GLUX_NOT_LOADED if the extension was not loaded by gluX at startup.

gluX robustness

If you forget to declare an extension with GLUX_REQUIRE or GLUX_LOAD, or simply forget to call gluxInit(), gluX will have a robust behavior: if you call one extension function, the execution will be stopped and gluX will print a message indicating witch function of witch extension failed to execute. (see sample/sample3.cpp).

Troubleshooting

Please read the FAQ.

Where's the mad guy who wrote 200+ extensions loading code ?

gluX is based on a Perl script that parses the OpenGL extension registry and generates the loading code. The only operation needed to update gluX is to launch the automated script: gluX could include any newer extension without any more pain !

Note for SGI users

It seams that the SGI implementation of OpenGL does not provide the glXGetProcAddress function that is needed to compile gluX. As a consequence gluX does not compile on SGI station and is not available on this platform.

Where can I found informations about OpenGL extensions ?

All extension's functions and defines could be found in the OpenGL extension registry.

Is there another libs that can be used to load OpenGL extensions ?

To my knowledge the following libraries allow OpenGL extension loading (if you know another library, please send me a link):

Author

)