OpenGLEAN
OpenGLEAN Shapes User Support
Home page | Introduction | Documentation | Files | Examples | Proposals | Authors | Links


OpenGLEAN Shapes Development
Summary | CVS | (discussion via home page) | (contact via home page) | (suggestion box) | License | Todo | Bugs

Rename the API

NB: As this is now an independant subproject from OpenGLEAN, I am much more inclined to carry out this proposal for these shapes. But doing so is a low-priority issue at the moment.

Introduction

This proposal is just a random thought for public consumption. freeglut forked the GLUT API and after 5 years of work is still incomplete. OpenGLUT forked the freeglut codebase and provided new man-pages. (freeglut never had any man-pages, relying on the old GLUT man-pages instead.) It turns out that the old GLUT API also had man-pages, though they were never widely distributed.

Now, OpenGLEAN has forked OpenGLUT, and the OpenGLUT man-pages.

The Problem:

Unfortunately, you start to run into collisions if you try to install man-pages for GLUT, OpenGLUT, and OpenGLEAN. Whose glutCreateWindow.[03] do you install? Right now, the answer may seem pretty straightforward: OpenGLUT and OpenGLEAN both normally install man-pages, GLUT man-pages are rare. OpenGLUT and OpenGLEAN provide almost identical man-pages that are fairly complete and which address features not found in old GLUT. So, install either OpenGLUT or OpenGLEAN man pages and forget it, right?

NB: This has largely been dealt with already in OpenGLEAN, as OpenGLEAN installs man-pages to section 3f by default, rather than section 3. This shapes library picks up that behavior, though it did collide with OpenGLEAN. OpenGLEAN has been modified to stop installing the shapes-related man-pages. Further, utnile OpenGLEAN removes the duplicate functions (post-1.0), you must put the openglean.h header inclusion AFTER the gleanshapes.h header inclusion.

The basic problem is that with or without the other OpenGLEAN satellite libraries, and OpenGLEAN itself, this may not be a proper superset nor proper subset of GLUT. Arguably, at present, OpenGLEAN is the most complete and useful substitute for old GLUT. But OpenGLEAN is planning to break backward compatibility. The next best alternative is arguably OpenGLUT, and both OpenGLEAN and OpenGLUT currently install conflicting man page sets.

This is somewhat mollified by a hack: OpenGLEAN installs its man pages into section 3f (traditionally used for FORTRAN pages). Unfortunately, the man-page system doesn't handle very well the idea of one function appearing in multiple libraries.

The Advantage As It Is:

Currently, old programs just work. Skills and knowledge can go back and forth.

Workarounds

There are some workarounds that you can employ, such as using the 3f man-page section, or presuming that one set is in the base-system while another is added only as a package, with a wholly separate directory tree. OpenGLEAN may provide a way for you to specify a non-default library section for OpenGLEAN documentation or to disable man-pages altogether.

Renaming

Renaming the API is relatively easy. Just change all "glut" symbol prefixes to "glean" (and "GLUT" to "GLEAN"). Done. (Warning: It turns out that there is a project called glean that has nothing to do with OpenGLEAN. However, that project appears to be dead and is not a library.)

Coping With the Fallout

If OpenGLEAN's API is renamed to avoid clashing with GLUT/freeglut/OpenGLUT, some optional #define symbols can be added, so that porting between GLUT, freeglut, OpenGLUT, and OpenGLEAN can still be done with a few tweaks to the compilation command-line.

Conclusion

I'm not terribly happy with this idea at present, but it's something that I wanted to put down in writing for reflection. For gleanshapes the likely solution will be to leave things as they are for now. If and when I redefine the shape-drawing API to address other flaws, the old glut*() shape drawing functions may be slated for removal.



SourceForge.net Logo Supported in part by SourceForge.net.

Generated on Fri Sep 9 18:03:39 2005 for OpenGLEAN'sgleanshapes by doxygen 1.4.3
The OpenGLEAN project is hosted by SourceForge.