12 Usage Advice

There are a number of points to keep in mind when writing GLUT programs. Some of these are strong recommendations, others simply hints and tips.

• Do not change state that will affect the way a window will be drawn in a window's display callback. Your display callbacks should be idempotent.

• If you need to redisplay a window, instead of rendering in whatever callback you happen to be in, call   glutPostRedisplay (or   glutPostRedisplay for overlays). As a general rule, the only code that renders directly to the screen should be in called from display callbacks; other types of callbacks should not be rendering to the screen.

• If you use an idle callback to control your animation, use the visibility callbacks to determine when the window is fully obscured or iconified to determine when not to waste processor time rendering.

• Neither GLUT nor the window system automatically reshape sub-windows. If subwindows should be reshaped to reflect a reshaping of the top-level window, the GLUT program is responsible for doing this.

• Avoid using color index mode if possible. The RGBA color model is more functional, and it is less likely to cause colormap swapping effects.

• Do not call any GLUT routine that affects the current window or current menu if there is no current window or current menu defined. This can be the case at initialization time (before any windows or menus have been created) or if your destroy the current window or current menu. GLUT implementations are not obliged to generate a warning because doing so would slow down the operation of every such routine to first make sure there was a current window or current menu.

• For most callbacks, the current window and/or current menu is set appropriately at the time of the callback. Timer and idle callbacks are exceptions. If your application uses multiple windows or menus, make sure you explicitly you set the current window or menu appropriately using   glutSetWindow or   glutSetMenu in the idle and timer callbacks.

• If you register a single function as a callback routine for multiple windows, you can call   glutGetWindow within the callback to determine what window generated the callback. Likewise,   glutGetMenu can be called to determine what menu.

• By default, timer and idle callbacks may be called while a pop-up menu is active. On slow machines, slow rendering in an idle callback may compromise menu performance. Also, it may be desirable for motion to stop immediately when a menu is triggered. In this case, use the menu entry/exit callback set with   glutMenuStateFunc to track the usage of pop-up menus.

• Do not select for more input callbacks than you actually need. For example, if you do not need motion or passive motion callbacks, disable them by passing NULL to their callback register functions. Disabling input callbacks allows the GLUT implementation to limit the window system input events that must be processed.

• Not every OpenGL implementation supports the same range of frame buffer capabilities, though minimum requirements for frame buffer capabilities do exist. If   glutCreateWindow or   glutCreateSubWindow are called with an initial display mode not supported by the OpenGL implementation, a fatal error will be generated with an explanatory message. To avoid this,   glutGet(GLUT_DISPLAY_MODE_POSSIBLE) should be called to determine if the initial display mode is supported by the OpenGL implementation.

• The Backspace, Delete, and Escape keys generate ASCII characters, so detect these key presses with the   glutKeyboardFunc callback, not with the   glutSpecialFunc callback.

• Keep in mind that when a window is damaged, you should assume all of the ancillary buffers are damaged and redraw them all.

• Keep in mind that after a   glutSwapBuffers, you should assume the state of the back buffer becomes undefined.

• If not using glutSwapBuffers for double buffered animation, remember to use   glFlush to make sure rendering requests are dispatched to the frame buffer. While many OpenGL implementations will automatically flush pending commands, this is specifically not mandated.

• Remember that it is illegal to create or destroy menus or change, add, or remove menu items while a menu (and any cascaded sub-menus) are in use (that is, ``popped up''). Use the menu status callback to know when to avoid menu manipulation.

• It is more efficient to use glutHideOverlay and glutShowOverlay to control the display state of a window's overlay instead of removing and re-establishing an overlay every time an overlay is needed.

• Few workstations have support for multiple simultaneously installed overlay colormaps. For this reason, if an overlay is cleared or otherwise not be used, it is best to hide it using glutHideOverlay to avoid other windows with active overlays from being displayed with the wrong colormap. If your application uses multiple overlays, use glutCopyColormap to promote colormap sharing.

• If you are encountering GLUT warnings or fatal errors in your programs, try setting a debugger break-point in   __glutWarning or   __glutFatalError (though these names are potentially implementation dependent) to determine where within your program the error occurred.

• GLUT has no special routine for exiting the program. GLUT programs should use ANSI C's exit routine. If a program needs to perform special operations before quitting the program, use the ANSI C   onexit routine to register exit callbacks. GLUT will exit the program unilaterally when fatal errors occur or when the window system requests the program to terminate. For this reason, avoid calling any GLUT routines within an exit callback.

• Definitely, definitely, use the -gldebug option to look for OpenGL errors when OpenGL rendering does not appear to be operating properly. OpenGL errors are only reported if you explicitly look for them!