Purge Obsolete Features

This proposal was originally authored for OpenGLUT.

See also: Deprecated API Features, Deleted API Features.

Introduction.

OpenGLEAN has inherited numerous elements of dubious merit. Some may not have been well designed in the first place. Some may have been as well designed as was plausible, but their context has changed. Some have been rendered obsolete or redundant. At least one or two were officially deprecated by Mark Kilgard in the old GLUT 3.6 documentation.

freeglut retained these for compatibility reasons, since freeglut was intended to be used as a drop-in replacement for old GLUT.

For OpenGLUT we hoped to clean out this cruft, but that seems unlikely now.

For OpenGLEAN this is a major goal. These removals will happen sometime after OpenGLEAN's first landmark stable release---tentatively after cutting and releasing "1.0".

This proposal will provide a rough list, to be refined by discussion and reflection. Features may be added or removed from the list in this proposal. Features deleted from the API will also be listed for reference, until such time as some better repository for historic issues is provided.

What It Means.

Normally things are not deprecated until a replacement in functionality is available. However, in order to minimize the number of times that the API changes, I want to chop out deadwood soon. Some of these things have been on their deathbed for a very long time (numerous years), and others are so horribly conceived (glutMouseWheelFunc(), for example, has an unbelievably myopic design for actual implementation) that they are just wastes of bits.

One goal is to produce an OpenGLEAN release with which future releases will be backwards compatible. This means having a kind of sunset on removing features. Another goal is to remove things that in the long run do not belong in a modern GLUT like library.

The list will describe the features that should be deprecated, and explain why they should be deprecated. Deprecation does not necessarily constitute loss of functionality. The deprecated feature might be redundant of something already in-hand. Or a replacement feature might be crafted before or after. In any case, being listed here is merely a step in removal.

The goal is to go through the fire of an incompatible version early and quick, then settle onto a solid API that will remain backwards compatible for a long time. It is felt to be better even to remove a feature now and add it back verbatim (though this is not expected to ever happen) than to hem and haw about the feature for a long time, and possibly remove it anyway---leaving users in doubt of whether to use it and developers in doubt of whether to maintain it.

The List.

Follows is a proposed list of features to be deprecated.

• glutMenuStateFunc() (DELETED) This feature is superceded by the more general and useful glutMenuStatusFunc(). Mark declared this function to be obsolete back in 1996 or so. It's not a bad function, but it is unnecessary.

• Fonts. EXPORTED to gleanfonts The idea in GLUT of having two whole font APIs for less than a dozen total fonts seems odd. The fonts are too few to be truly general, and no means was provided for the user to extend the builtin font data or to access "system" fonts.

• Shapes. EXPORTED to gleanshapes The various shape-drawing routines in GLUT do not seem to have any correlation to the rest of the API. They are a bit hit-or-miss in their features (can you control size? if not, what is the size? can you control mesh density? are they faceted or smooth? do they have texture coordinates?). Why does every shape have two entries ("Solid" and "Wire") rather than taking a parameter to control that?

• Overlay support. This is tentative. If I can get it implemented around the time that I begin major trimming (or anytime before), I'll retain it. If I can't, I'll remove it, and add it back in only if and when it works.

• Video resizing. This is probably going to be a part of replacing game mode, below. This can probably be excised from the gamemode code. Also, on X11 systems there is no standard way to accomplish this. Perhaps using a dlopen(3) of something like SDL would be a good idea (either as a backup, or as the primary/sole way)?

• glutVisibilityFunc() Superceded by another function (glutWindowStatusFunc()). It is not a bad function, but it is unnecessary.

• Joysticks. EXPORTED to gleandev; new API The joystick input model is based on polling. It has nothing to do with the window system on any known platform. I.e., there is no reason to work it into the OpenGLEAN event loop. Nor does it require any special state. You can take the code in joystick.c, and use GLUT timers on your own, or it can be exported to a separate library. Or you can use another library for polling the joystick---say SDL---which probably does a better (and better-tested) job. Other than GLUT compatibility, which OpenGLEAN is willing to break, there is no reason to maintain this in OpenGLEAN.

• Other devices (Spaceball, Tablet, ...). Nominally EXPORTED to gleandev; never implemented in freeglut, so no real code. It would be nice to support these. However, the GLUT approach of a custom callback for each device type feels a little wrong. Also, it seems that the devices---as GLUT supported them---required polling, as did joysticks (see above). The tablet device, at least, was unduly limited by a bad assumption in GLUT (i.e., GLUT assumed that [0,1000] was an adequate resolution). Lastly there simply was no code for these to inherit from freeglut. Future support of these devices is presently pushed to the gleandev sublibrary. Possibly the OpenGLEAN core will someday acquire direct support for these as proper event-driven input devices---but that awaits both design and implementation issues.

• Game mode. This feature was never documented by old GLUT. OpenGLEAN received a partial implementation (also undocumented) from freeglut/OpenGLUT. That version has always been fraught with bugs. On UNIX_X11 systems, it cannot work reliably---freeglut/OpenGLUT/OpenGLEAN rely upon an unofficial hack to do video mode changes on XFree86 (and no other X server). On some XFree86 systems, the video card driver has bugs in setting the resolution and can have disasterous impact, rendering the video display unusable. On some systems (any X besides XFree86, and even XFree86 if a compile-time option is selected), the video mode may not change, though game mode will otherwise appear to "work". making it impossible for applications to know what subset of game mode features they have gained. Additionally, having to manually encode the request as a string, then having OpenGLEAN decode the string, seems like a classic case of over-engineering.
  
  Most, if not all, of the problems would go away if the numerous components of game mode were decoupled. With a separate function for each component---and total failure or total success being the only outcomes---programs could reliably ask for what they need. Each function could take perhaps one or two numeric parameters, rather than having to parse a string.
  
  This present proposal does not seek to define how to redesign game mode. It is merely intended to present the case for why the current API is unworkable, and to list game mode as something that may be removed.
  
  A functioning replacement design would be welcome.

• glutCloseFunc(), glutWMCloseFunc(), GLUT_ACTION_ON_WINDOW_CLOSE OpenGLEAN inherited two mutually redundant callbacks and a somewhat thorny state-variable that freeglut added for allowing programs to handle their windows being closed. These features should be replaced by a simpler mechanism, such as is outlined in the Window Close API Proposal. The glutCloseFunc() API is a bad function design, but perhaps forgivably so, but having two copies and stacking on a global state-twiddle is too rickety.

• glutMouseWheelFunc() This function was very poorly designed. In mid to late 2003, a then-freeglut developer (Richard Rauch) suggested some explicit mouse wheel support, and the first idea that came to mind was to just create a +1/-1 "tick" callback. Later investigation showed that wheels varied significantly in the size of "ticks", so that a "stroke" of the finger could be very different for the same user on two different mice. WIN32 also has a mechanism for reporting the size of a "tick" it seems. In spring of 2004, wheels with no tactile "ticks" at all were seen in stores (the tick resolution reported by those mice is unknown). Despite criticism, and a workable existing alternative, freeglut's management forced Richard's original (and quickly retracted) bad design into freeglut. adopted glutMouseWheelFunc() as it stands today. A client application can get exactly the same functionality by allowing OpenGLEAN to report the "wheel ticks" as pseudo buttons. The freeglut glutMouseWheelFunc() is deprecated in favor of the traditional method. A usable API will be designed to address wheels. Better ideas were foreseen almost immediately, so why this broken API was grasped so firmly by freeglut is a mystery.

• The old GLUT style menu functions. These functions, such as glutAddMenu(), were easy to support in old GLUT under X. freeglut decided not to use OS menu functions in order to produce more consistant menus across platforms. The freeglut menu system is fraught with bugs, so that it is a little better than usable, but not acceptable in a serious or frequently used application.
  
  As discussed in Menu Window Proposal, the freeglut implementation is anomalous in that it is a relatively complex part of the freeglut code, and drives its fingers into the freeglut main event loop. Mark Kilgard's GLUT avoided adding complexities like that. As OpenGLEAN does not aim to be an all-singing, all-dancing GUI library---but does aim to be a library upon which such a GUI library may be built---it is felt best to remove the freeglut menu support code and use the Menu Window Proposal API that I proposed, designed, and implemented in OpenGLUT in 2004. Either a new menu API based upon a less intrusive use of GLUT events, or a new core event API feature to more generally allow clients to access the OpenGLEAN event loop, seem like better options. With either approach, menu support can be migrated to a satellite library. The OpenGLEAN project would like to see a more powerful, general GUI library, based on C, grow up around the elements that OpenGLEAN provides; menus seem a natural part of such a library.

Supported in part by SourceForge.net.

Generated on Fri Sep 16 20:15:32 2005 for OpenGLEAN by doxygen 1.4.3
The OpenGLEAN project is hosted by olib.org and SourceForge.