Python bindings for OpenGL

The GL Toolbox (gltbx) provides Python bindings for OpenGL GL_* and GLU_* defines, and gl*() and glu*() functions. The original C interfaces are preserved as much as possible. Except for the functions that may appear between calls of glBegin() and glEnd(), OpenGL errors are converted to Python exceptions (RuntimeError). All functions support Python keyword arguments.

The gltbx is part of the cctbx project hosts at: http://cctbx.sourceforge.net/

See also:

• http://www.opengl.org/
• http://pyopengl.sourceforge.net/

Requirements

In addition to the gltbx sources, the following are required:

• OpenGL headers and runtime libraries in standard places (e.g. /usr/include and /usr/lib)
• Python 2.2 or higher (http://www.python.org/)
• Boost source code, version 1.32.0 or higher (http://www.boost.org/)

Note that only the Boost sources are required. It is not necessary to run the Boost.Build system.

Platforms

The gltbx extensions are known to compile on these platforms:

• Windows 2000/XP, Visual C++ 7.1 (Intel Xeon)
• Redhat Linux 7.3, 8.0, 9.0, Enterprise Workstation 3 (Intel Xeon)
• Fedora Core 3 (AMD Opteron)
• Mac OS X 10.3, Xcode 1.5 (Apple G5)
• Tru64 Unix, cxx 6.5-042 (HP Alpha)
• IRIX 6.5, MIPSpro 7.3.1.3 (SGI Mips)

License

BSD-style open source. For details see LICENSE.txt and COPYRIGHT.txt.

Implementation

The primary OpenGL man pages were copied via wget from http://www.opengl.org/ (see wget_opengl_specs.csh). The Python script extract_opengl_specs.py was used to automatically generate the file opengl_specs.txt. This derived file is in the CVS and in the distribution.

Another set of Python scripts is used to generate Boost.Python wrappers based on the information in opengl_specs.txt; this step takes only fractions of a second. The Boost.Python wrappers are compiled to Python extension modules using a C++ compiler. Depending on the platform and the number of available CPUs this takes between 1 and 10 minutes and results in two extension modules, gltbx_gl_ext.so and gltbx_glu_ext.so. These modules are imported via two small Python scripts, gl.py and glu.py. For example:

from gltbx.gl import *
from gltbx.glu import *
error = glGetError()
print gluErrorString(error=error)

OpenGL functions with pointer arguments are handled like this (see wx_scene.py):

model = [0]*16
glGetDoublev(GL_MODELVIEW_MATRIX, model)

Some functions expect strings instead of Python lists, e.g.:

glTexImage2D(
  GL_TEXTURE_2D, 0, GL_RGBA, self.stripeImageWidth,1,0,
  GL_RGBA, GL_UNSIGNED_BYTE, [self.stripeImage])

Non-const pointers require the Python string to be passed via a list with one element, as above. On return the original string is replaced with a new instance. Const pointers also accept Python strings directly.

Currently the handling of improper pointer arguments is not safe for all function. See the TODO list below. However, if the correct arguments are passed everything should work as expected.

Examples

Two simple examples of using the gltbx with wxPython (http://www.wxpython.org/) are included: wx_scene.py and wx_cube.py. These are known to work under Windows 2000/XP using wxPython2.6-win32-unicode-2.6.1.0-py24.exe.

The gltbx extensions are also expected to work with wxPython under Unix but this has not been tested. It should also be possible to use the gltbx extensions in combination with window systems other than wxPython, but this has also not been tested.

gltbx source code

The gltbx source code is available via CVS or as complete bundles:

• CVS: http://cctbx.cvs.sourceforge.net/cctbx/gltbx/
• Bundles: http://cci.lbl.gov/gltbx/

Installation

Unpack the most recent gltbx_####_##_##_####.tar.gz in an empty directory (####_##_##_#### is a time stamp). This creates the subdirectories:

scons
libtbx
boost_adaptbx
gltbx

For information about SCons see: http://www.scons.org/ .

Create a build directory:

mkdir build
cd build

Initialize the build directory:

python ../libtbx/configure.py boost=../boost_1_32_0 gltbx

Replace ../boost_1_32_0 with the proper path name. If the Boost sources are not installed already, visit the Boost Download page and unpack the sources in the same directory as the gltbx sources.

The libtbx/configure.py command above creates the subdirectories:

build/bin # sh dispatchers for commands to be used
build/lib # target directory for shared libraries and Python extensions
build/gltbx # automatically generated Boost.Python wrappers for OpenGL

The libtbx/configure.py command also creates several setpaths* files. Source the correct file for your shell, e.g.:

source setpaths.csh

All this does is add build/bin to $PATH, thereby enabling the command for compilation:

libtbx.scons

This works similar to the good old make command, but uses SCons instead. SCons supports parallel compilation. E.g. if 4 CPUs are available:

libtbx.scons -j 4

If all goes well, the compilation finishes with lines like these:

scons: done building targets.
usr+sys time: 1.13 seconds
wall clock time: 2 minutes 39.38 seconds (159.38 seconds total)

At this point the installation is complete. If wxPython is installed try:

python ../gltbx/wx_scene.py

To use the gltbx installation in a new shell, source the appropriate setpaths script.

The Windows build procedure is very similar. Simply replace slashes by backslashes and enter setpaths instead of source setpaths.csh.

See also: http://cctbx.sourceforge.net/current_cvs/installation.html

Pick and choose

The gltbx extension modules in build/lib are relocatable, i.e. can be copied to other places outside the gltbx installation. However, the Boost.Python runtime library (e.g. build/lib/libboost_python.so) has to be copied along with the extensions.

The gltbx source code including the auto-generated files in build/gltbx can also be copied to places outside the gltbx. All C++ files are platform independent and could be used in other build systems. It would also be easy to make the source code generators independent of the libtbx module if there is an interest.

Prioritized TODO list (help appreciated!)

• All gl*() and glu*() functions are wrapped, but some functions throw "not implemented" exceptions (cd build/gltbx; grep 'not implemented' *.cpp). Special code has to be added to replace these exceptions. The special code should be included in the Python script generating the function wrappers, generate_functions_bpl.py (look for special_wrappers and special_wrapper_bodies to see some examples).
• Many functions taking pointers as arguments do not verify that the passed data arrays have the correct size. If data of the wrong size are passed, this can result in segmentation faults or bus errors. Special code to check expected sizes of pointees has to be added, throwing exceptions that can be handled in Python.
• Currently three gl*() functions are disabled because they are not available on all platforms listed above. Proper defines have to be added to enable these functions on platforms where they are available.

Motivation

The main motivation for us was to simplify our build process, and to minimize additional dependencies. Since we distribute our software to non-programmers as source code it is important to us that the build procedure is fully automatic and self-contained. We are already heavily using Boost.Python and wxPython, and our cross-platform libtbx build system enables us to add extensions without intruding into Python installations. In contrast to PyOpenGL, with the gltbx we don't have to worry about Numeric and GLUT installations and compatibilities.

Contact

Please send suggestions and problem reports to: cctbx@cci.lbl.gov