Manual Reference Pages - GLUT (3)
glut - an introduction to the OpenGL Utility Toolkit
The OpenGL Utility Toolkit (GLUT) is a programming interface with ANSI C and FORTRAN bindings for writing
window system independent OpenGL programs. The toolkit supports the following functionality:
An ANSI C implementation of GLUT for the X Window System has been
implemented by the author. Windows NT and OS/2 versions of GLUT are
Multiple windows for OpenGL rendering.
Callback driven event processing.
Sophisticated input devices.
An idle routine and timers.
A simple, cascading pop-up menu facility.
Utility routines to generate various solid and wire frame objects.
Support for bitmap and stroke fonts.
Miscellaneous window management functions, including managing overlays.
One of the major accomplishments in the specification of OpenGL
was the isolation of window system dependencies from OpenGLs
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
GLs 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 GLs 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 GLs 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 OpenGLs utility. Learning native window system APIs such as the X
Window Systems 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 programs OpenGL rendering code, the program itself
will be window system dependent.
Testing and documenting OpenGLs 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. No pointers are
returned. The only pointers passed into GLUT are pointers to character
strings (all strings passed to GLUT are copied, not referenced) and opaque
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
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:
Command line processing, window system initialization, and initial
window creation state are controlled by these routines.
Beginning Event Processing.
This routine enters GLUTs event processing loop. This routine never
returns, and it continuously calls GLUT callbacks as necessary.
These routines create and control windows.
These routines establish and manage overlays for windows.
These routines create and control pop-up menus.
These routines register callbacks to be called by the GLUT event
Color Index Colormap Management.
These routines allow the manipulation of color index colormaps for
These routines allows programs to retrieve state from GLUT.
These routines allow rendering of stroke and bitmap fonts.
Geometric Shape Rendering.
These routines allow the rendering of 3D geometric objects including
spheres, cones, icosahedrons, and teapots.
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 OpenGLs
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.
Integer identifiers in GLUT begin with one, not zero. So window
identifiers, menu identifiers, and menu item indexes are based from
one, not zero.
In GLUTs ANSI C binding, for most routines, basic types (int,
char*) are used as parameters. In routines where the parameters are
directly passed to OpenGL routines, OpenGL types (GLfloat) are
The header files for GLUT should be included in GLUT programs
with the following include directive:
Because a very large window system software vendor (who will
remain nameless) has an apparent inability to appreciate that
OpenGLs API is independent of their window system API, portable
ANSI C GLUT programs should not directly include <GL/gl.h> or
<GL/glu.h>. Instead, ANSI C GLUT programs should rely on
<GL/glut.h> to include the necessary OpenGL and GLU related
The ANSI C GLUT library archive is typically named libglut.a on
Unix systems. GLUT programs need to link with the systems OpenGL
and GLUT libraries (and any libraries these libraries potentially
depend on). A set of window system dependent libraries may also be
necessary for linking GLUT programs. For example, programs using
the X11 GLUT implementation typically need to link with Xlib, the X
extension library, possibly the X Input extension library, the X
miscellaneous utilities library, and the math library. An example
X11/Unix compile line would look like:
cc -o foo foo.c -lglut -lGLU -lGL -lXmu -lXi -lXext -lX11 -lm
glutAddMenuEntry, glutAddSubMenu, glutAttachMenu, glutBitmapCharacter,
glutBitmapWidth, glutButtonBoxFunc, glutChangeToMenuEntry,
glutChangeToSubMenu, glutCopyColormap, glutCreateMenu,
glutCreateSubWindow, glutCreateWindow, glutDestroyMenu,
glutDestroyWindow, glutDeviceGet, glutDialsFunc, glutDisplayFunc,
glutEntryFunc, glutEstablishOverlay, glutExtensionSupported,
glutFullScreen, glutGet, glutGetColor, glutGetModifiers, glutIdleFunc,
glutInit, glutInitDisplayMode, glutInitWindowPosition,
glutKeyboardFunc, glutLayerGet, glutMainLoop, glutMenuStatusFunc,
glutMotionFunc, glutMouseFunc, glutOverlayDisplayFunc, glutPopWindow,
glutPositionWindow, glutPostOverlayRedisplay, glutPostRedisplay,
glutRemoveMenuItem, glutRemoveOverlay, glutReshapeFunc,
glutReshapeWindow, glutSetColor, glutSetCursor, glutSetMenu,
glutSetWindow, glutSetWindowTitle, glutShowOverlay, glutShowWindow,
glutSolidCone, glutSolidCube, glutSolidDodecahedron,
glutSolidIcosahedron, glutSolidOctahedron, glutSolidSphere,
glutSolidTeapot, glutSolidTetrahedron, glutSolidTorus,
glutSpaceballRotateFunc, glutSpecialFunc, glutStrokeCharacter,
glutStrokeWidth, glutSwapBuffers, glutTabletButtonFunc,
glutTabletMotionFunc, glutTimerFunc, glutUseLayer, glutVisibilityFunc,
Mark Kilgard, Programming OpenGL for the X Window System, Addison-Wesley, ISBN 0-201-48359-9, 1996.
Mark Kilgard, The OpenGL Utility Toolkit (GLUT) Programming Interface API Version 3 (the official GLUT specification).
Main GLUT page
GLUT Frequently Asked Question list
The OpenGL Utility Toolkit (GLUT) Programming Interface API Version 3
OpenGL and X: An OpenGL Toolkit article (PostScript)
Mark J. Kilgard (email@example.com)
Visit the GSP FreeBSD Man Page Interface.
Output converted with manServer 1.07.