|A Haskell binding for GLUT, the OpenGL Utility Toolkit, a window system independent toolkit for writing OpenGL programs. It includes support for the extended functionality available in freeglut (see http://freeglut.sourceforge.net/) and OpenGLUT (see http://openglut.sourceforge.net/), too.|
This documentation is heavily based on the man pages of Mark J. Kilgard's GLUT library.
OpenGL is a trademark of Silicon Graphics, Inc. X Window System is a trademark of X Consortium, Inc. Spaceball is a registered trademark of Spatial Systems, Inc.
The author has taken care in preparation of this documentation but makes no expressed or implied warranty of any kind and assumes no responsibility for errors or omissions. No liability is assumed for incidental or consequential damages in connection with or arising from the use of information or programs contained herein.
The OpenGL Utility Toolkit (GLUT) is a programming interface for writing window system independent OpenGL programs. Currently there are implementations for the X Window System, the Windows family, OS/2, and Mac. The toolkit supports the following functionality:
This documentation serves as both a specification and a programming guide. If you are interested in a brief introduction to programming with GLUT, have a look at the relevant parts of http://www.opengl.org/ and the vast amount of books on OpenGL, most of them use GLUT.
The remainder of this section describes GLUT's design philosophy and usage model. The following sections specify the GLUT routines, grouped by functionality. The final sections discuss usage advice and the logical programmer visible state maintained by GLUT.
One of the major accomplishments in the specification of OpenGL was the isolation of window system dependencies from OpenGL's rendering model. The result is that OpenGL is window system independent.
Window system operations such as the creation of a rendering window and the handling of window system events are left to the native window system to define. Necessary interactions between OpenGL and the window system such as creating and binding an OpenGL context to a window are described separately from the OpenGL specification in a window system dependent specification. For example, the GLX specification describes the standard by which OpenGL interacts with the X Window System.
The predecessor to OpenGL is IRIS GL. Unlike OpenGL, IRIS GL does specify how rendering windows are created and manipulated. IRIS GL's windowing interface is reasonably popular largely because it is simple to use. IRIS GL programmers can worry about graphics programming without needing to be an expert in programming the native window system. Experience also demonstrated that IRIS GL's windowing interface was high-level enough that it could be retargeted to different window systems. Silicon Graphics migrated from NeWS to the X Window System without any major changes to IRIS GL's basic windowing interface.
Removing window system operations from OpenGL is a sound decision because it allows the OpenGL graphics system to be retargeted to various systems including powerful but expensive graphics workstations as well as mass-production graphics systems like video games, set-top boxes for interactive television, and PCs.
Unfortunately, the lack of a window system interface for OpenGL is a gap in OpenGL's utility. Learning native window system APIs such as the X Window System's Xlib or Motif can be daunting. Even those familiar with native window system APIs need to understand the interface that binds OpenGL to the native window system. And when an OpenGL program is written using the native window system interface, despite the portability of the program's OpenGL rendering code, the program itself will be window system dependent.
Testing and documenting OpenGL's functionality lead to the development of the tk and aux toolkits. The aux toolkit is used in the examples found in the OpenGL Programming Guide. Unfortunately, aux has numerous limitations and its utility is largely limited to toy programs. The tk library has more functionality than aux but was developed in an ad hoc fashion and still lacks much important functionality that IRIS GL programmers expect, like pop-up menus and overlays.
GLUT is designed to fill the need for a window system independent programming interface for OpenGL programs. The interface is designed to be simple yet still meet the needs of useful OpenGL programs. Features from the IRIS GL, aux, and tk interfaces are included to make it easy for programmers used to these interfaces to develop programs for GLUT.
GLUT simplifies the implementation of programs using OpenGL rendering. The GLUT application programming interface (API) requires very few routines to display a graphics scene rendered using OpenGL. The GLUT API (like the OpenGL API) is stateful. Most initial GLUT state is defined and the initial state is reasonable for simple programs. The GLUT routines also take relatively few parameters.
The GLUT API is (as much as reasonable) window system independent. For this reason, GLUT does not return any native window system handles, pointers, or other data structures. More subtle window system dependencies such as reliance on window system dependent fonts are avoided by GLUT; instead, GLUT supplies its own (limited) set of fonts.
For programming ease, GLUT provides a simple menu sub-API. While the menuing support is designed to be implemented as pop-up menus, GLUT gives window system leeway to support the menu functionality in another manner (pull-down menus for example).
Two of the most important pieces of GLUT state are the current window and current menu. Most window and menu routines affect the current window or menu respectively. Most callbacks implicitly set the current window and menu to the appropriate window or menu responsible for the callback. GLUT is designed so that a program with only a single window and/or menu will not need to keep track of any window or menu identifiers. This greatly simplifies very simple GLUT programs.
GLUT is designed for simple to moderately complex programs focused on OpenGL rendering. GLUT implements its own event loop. For this reason, mixing GLUT with other APIs that demand their own event handling structure may be difficult. The advantage of a builtin event dispatch loop is simplicity.
GLUT contains routines for rendering fonts and geometric objects, however GLUT makes no claims on the OpenGL display list name space. For this reason, none of the GLUT rendering routines use OpenGL display lists. It is up to the GLUT programmer to compile the output from GLUT rendering routines into display lists if this is desired.
GLUT routines are logically organized into several sub-APIs according to their functionality. The sub-APIs are:
|The GLUT API has undergone several revisions with increasing functionality. This Haskell binding provides access to everything in API version 4, although it is not yet officially finalized. Nevertheless, it provides very useful things like handling full-screen modes and special keys.|
|GLUT window and screen coordinates are expressed in pixels. The upper left hand corner of the screen or a window is (0,0). X coordinates increase in a rightward direction; Y coordinates increase in a downward direction. Note: This is inconsistent with OpenGL's coordinate scheme that generally considers the lower left hand coordinate of a window to be at (0,0) but is consistent with most popular window systems.|
A number of terms are used in a GLUT-specific manner throughout this document. The GLUT meaning of these terms is independent of the window system GLUT is used with. Here are GLUT-specific meanings for the following GLUT-specific terms:
|Produced by Haddock version 0.7|