OpenGLEAN's gleandev Project

0.6 development

gleandev - The joy of gleaning.

gleandev joystick demo

Introduction

OpenGLEAN is an open source project to enhance the GLUT API. gleandev is a natural step in that process: A major focus of OpenGLEAN is to reduce the weight of the core API by splitting off or deleting features that are unrelated or ill-conceived. The joystick API as GLUT originally defined it is one such feature---along with which can fairly naturally go the various other non-mouse, non-keyboard devices that GLUT has traditionally supported.

gleandev takes up the reins for the non-standard devices. Most of the devices were not implemented in the codebase, freeglut via OpenGLUT, from which OpenGLEAN derives, so primarily the support is centering around the joystick API. In gleandev, the pseudo-event approach that GLUT took to handling these devices is discarded in favor of direct polling---this simplifies the library and provides the client with a behavior pattern closer to what is truly happening with the hardware.

Motivation

• See the OpenGLEAN home page for why OpenGLEAN exists.
• The GLUT API suffers from numerous unrelated and some ill-conceived features. Some of these features are de facto GLUT features that GLUT was experimenting with when GLUT stopped development.
• Excepting the mouse and keyboard support, all of the device support in the core library was polled and could be accessed without any of the other OpenGLEAN data structures---i.e. there was no reason to tie it into the core library.
• Experimenting with joystick or other device support may result in rapid incompatible versioning of the associated library version number. Pulling this support into a separate library allows that to take place without forcing core library updates.
• There is no known, well-separated portable joystick (or other misc. device API) that can be called from C and which has a liberal (non-GPL, non-LGPL) license---much less one that is actively maintained. The closest kin is freeglut or OpenGLUT but both of those suffer from a mixture of excess bloat and legacy API limitations.
• freeglut, in particular, is mired in GLUT compatibility, so do not expect innovations from that quarter.

Part of the GLUT family

• GLUT by Mark Kilgard, originally implemented on SGI systems, later ported to Win32 by Nate Robins. If you have old GLUT programs and they work for you, there's no reason to uninstall GLUT.
• freeglut by Pawel W. Olszta and others, a compatible open source implementation of GLUT. Best installed as "freeglut", but defaults to installing as "glut"---i.e., it defaults to overwriting the original GLUT. Useful if you want to run old GLUT programs and Mark Kilgard's GLUT has bugs that you are unable or unwilling to solve. Even freeglut's current project administrator has said he discourages the use of freeglut for new code.
• OpenGLUT, a fork of freeglut. Useful if you want new features but want to minimize the amount of old features lost.
• OpenGLEAN, an enhanced and slimmed down version of OpenGLUT. Willing to break with tradition to make a better library, OpenGLEAN is the least likely member of the GLUT family to support your old, traditional GLUT applications. It is also hoped to be most likely to support your future needs and to be the least afflicted with old cruft that new applications will never need. But OpenGLEAN is definitely not ABI compatible with old GLUT, and has significant source-level changes planned.
• glean Regrettably, I have found that there is an old project called "glean". It has no relation to OpenGLEAN. glean is a benchmarking suite for graphics cards, it seems. glean seems to be mostly dead; it hasn't had much/any activity in 3 years, with a number of files most recently modified 5 years ago, as of this writing. Given that glean does not seem to be an API and seems to be dead/obscure, and that I've set up OpenGLEAN already...I simply note that there is an unfortunate near-miss in the name-space.

Why gleandev?

In mid 2003, the principle author of OpenGLEAN encountered a serious, crashing bug with GLUT. This was motivation to look for alternatives. Soon after, the author was working on freeglut to enhance its GLUT compatibility. However, as the author sought to advance the API, not merely kill off and replace old GLUT, the author eventually was asked to help co-found the OpenGLUT project. That project made some significant advances, but it was not possible to reach consensus about removing legacy features from OpenGLUT. As that was the author's primary reason for creating a fork, the author butted heads with the other co-founder and eventually had to choose between abandoning one of the most important points of the fork, having ugly and unending arguments, or forking the codebase yet again.

The result was to create the OpenGLEAN project. The intent was to quickly reorient the new project, fix some open issues, and remove the legacy features. As one may expect, however, this progress was not as quick as one may wish.

One of the key aspects to separate from OpenGLEAN is the pseudo-event device-polling that GLUT provided for devices ranging from joysticks to graphics tablets. The device support in OpenGLEAN resulted in bloat as well as complications to essentially unrelated code. E.g., the event loop needed to set aside a step to check if any windows had any joystick callbacks registered; since joysticks were polled (internally) by the library, that would alter the way that OpenGLEAN would sleep.

There was no reason that the exact GLUT API could not have been done by completely separate code, using GLUT timers. In fact, that was contemplated as part of the gleandev library (at the time aiming to be called "gleanjoy"). That may eventually be done, yet, but on reflection even that is more complication than is really needed. Very few, if any, real applications would find the GLUT API any easier than a more direct gleandevGet*() API---other, of course, than those applications already using the old GLUT API and hence needing some simple conversion. Meanwhile, implementing, testing, debugging, and enhancing the library would be complicated, as in some cases would be client debugging, to recreate the GLUT API.

While contemplating this, the remaining devices were recognized as having the same characteristics as the joystick devices. The only difference being that, as OpenGLEAN starts from the freeglut base, OpenGLEAN has joystick support but no support for other devices.

Features

At this point, the library is still taking fairly large evolutionary steps. However, the GLUT device support can be considered not to have advanced at all since GLUT stopped supporting it, until now. gleandev offers these enhancements:

• An OpenGL-style gleandevGet*() and gleandevSet*() suite of functions.
• Multiple joysticks.
• In principle as many axes and buttons as the joysticks claim to have can be supported.
• Growth potential on the other devices (esp. tablets).
• New devices are possible---the codebase is living and open to innovation.
• Separated from unrelated libraries so that you can upgrade a shared library version of gleandev without updating everything that uses, say, the core OpenGLEAN library.
• Unlike GLUT, the code is open source. Unlike many other libraries, the code is under a liberal license so that you may use it more generally. In particular, the code is not under the GPL or LGPL licenses, but rather under the MIT license.
• Documentation is provided; the original GLUT library did not have all of the latest features documented, and freeglut depends upon GLUT man-pages for documentation. OpenGLEAN inherits, and improves upon, the OpenGLUT library documentation.
• Generally is good for---indeed, intended for---use by new code with and by more serious applications.
• Careful maintenance of the libtool versioning. OpenGLEAN can't claim perfection, but is being perhaps more nit-picky than some.
• Use enum instead of #define for defining many integer constants. This may help with debugging (depending on the compiler/debugger) as #define processing in principle is done before the main compiler pass.
• All non-API library-global symbols are declared {static} so that applications can't reach around the API to abuse the library. (Hey, it's open source. If you really don't like an API restriction, copy the code, modify it, and build the modified code directly into your application, or fork the codebase.)

(The second and third points are features of the way that the API is outlined, though support is still developing. The last fourth and fifth points are features of the fact that gleandev is willing to grow and is a living project.)

Plans:

• Automated testing.
• Perhaps de-linting, and use of other tools to eliminate potential, subtle bugs.
• Enhance, e.g., the tablet API to something more modern, and add either specific device types or generic scalar/boolean sensor arrays. (E.g., temperature probes.)
• ...well, there's a healthy list in the project TODO file. You can't see it from the web pages. The disposition of that file with respect to the web and "installed" documentation is undecided at this point.

In addition, some API proposals are on the table: OpenGLEAN API Proposals.

Using OpenGLEAN

Documentation

Detailed API and example documentation is available from the SourceForge project interface for OpenGLEAN.

Download

Currently, development releases are made from time to time. See the gleandev file download section, e.g., at the OpenGLEAN SourceForge interface.

Developers

The current development version of gleandev is under some degree of flux. It is not source-compatible with the device APIs for other GLUT family members.

Input (no pun intended) is especially welcome to this sub-project. For the right mix of ability and interest, the project could be spun off entirely to a separate project under separate project management.

CVS

The core OpenGLEAN is maintained in a private CVS tree; the satellite libraries are being set up in their own CVS trees, however, on the OpenGLEAN SourceForge CVS server.

Supported in part by SourceForge.net.

Generated on Fri Sep 9 18:01:30 2005 for gleandev by doxygen 1.4.3
The OpenGLEAN project is hosted in part by SourceForge.