Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages


home | help
glut(3GLUT)			     GLUT			   glut(3GLUT)

       glut - an introduction to the OpenGL Utility Toolkit

       #include	<GL/glut.h>

       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:

	      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 ob-

	      Support for bitmap and stroke fonts.

	      Miscellaneous window management  functions,  including  managing

       An  ANSI	 C implementation of GLUT for the X Window System has been im-
       plemented by the	author.	Windows	NT and OS/2 versions of	GLUT are  also

       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 sys-
       tem  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 spec-
       ify how rendering windows are created and manipulated. IRIS  GL's  win-
       dowing  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.	 Expe-
       rience 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 be-
       cause 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 portabil-
       ity  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 pro-
       grammers	expect,	like pop-up menus and overlays.

       GLUT is designed	to fill	the need for a window system independent  pro-
       gramming	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 rou-
       tines 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 font handles.

       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 dependen-
       cies 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 win-
       dow 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 identi-
       fiers.  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	struc-
       ture  may  be difficult.	The advantage of a builtin event dispatch loop
       is simplicity.

       GLUT contains routines for rendering fonts and geometric	objects,  how-
       ever  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 ini-
	      tial window creation state are controlled	by these routines.

       Beginning Event Processing.
	      This routine enters GLUT's event processing loop.	 This  routine
	      never  returns, and it continuously calls	GLUT callbacks as nec-

       Window Management.
	      These routines create and	control	windows.

       Overlay Management.
	      These routines establish and manage overlays for windows.

       Menu Management.
	      These routines create and	control	pop-up menus.

       Callback	Registration.
	      These routines register callbacks	to be called by	the GLUT event
	      processing loop.

       Color Index Colormap Management.
	      These  routines  allow the manipulation of color index colormaps
	      for windows.

       State Retrieval.
	      These routines allows programs to	retrieve state from GLUT.

       Font Rendering.
	      These routines allow rendering of	stroke and bitmap fonts.

       Geometric Shape Rendering.
	      These routines allow the rendering of 3D geometric  objects  in-
	      cluding 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  in-
       crease  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.

       Integer identifiers in GLUT begin with one, not zero. So	window identi-
       fiers,  menu identifiers, and menu item indexes are based from one, not

       In GLUT's 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 used.

       The header files	for GLUT should	be included in GLUT programs with  the
       following include directive:

       #include	<GL/glut.h>

       Because	a  very	 large	window system software vendor (who will	remain
       nameless) has an	apparent inability to appreciate that OpenGL's 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 header files.

       The ANSI	C GLUT library archive is typically named  libglut.a  on  Unix
       systems.	 GLUT  programs	need to	link with the system's 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	imple-
       mentation  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, glutChange-
       ToSubMenu,   glutCopyColormap,	glutCreateMenu,	  glutCreateSubWindow,
       glutCreateWindow,  glutDestroyMenu,  glutDestroyWindow,	glutDeviceGet,
       glutDialsFunc,  glutDisplayFunc,	 glutEntryFunc,	 glutEstablishOverlay,
       glutExtensionSupported, glutFullScreen, glutGet,	glutGetColor, glutGet-
       Modifiers, glutIdleFunc,	glutInit, glutInitDisplayMode, glutInitWindow-
       Position, glutKeyboardFunc, glutLayerGet, glutMainLoop, glutMenuStatus-
       Func, glutMotionFunc, glutMouseFunc,  glutOverlayDisplayFunc,  glutPop-
       Window,	glutPositionWindow,  glutPostOverlayRedisplay,	glutPostRedis-
       play, glutRemoveMenuItem, glutRemoveOverlay,  glutReshapeFunc,  glutRe-
       shapeWindow,  glutSetColor,  glutSetCursor, glutSetMenu,	glutSetWindow,
       glutSetWindowTitle,  glutShowOverlay,  glutShowWindow,	glutSolidCone,
       glutSolidCube,  glutSolidDodecahedron,  glutSolidIcosahedron, glutSoli-
       dOctahedron,  glutSolidSphere,  glutSolidTeapot,	 glutSolidTetrahedron,
       glutSolidTorus,	  glutSpaceballButtonFunc,    glutSpaceballMotionFunc,
       glutSpaceballRotateFunc,	 glutSpecialFunc,  glutStrokeCharacter,	 glut-
       StrokeWidth,  glutSwapBuffers,  glutTabletButtonFunc, glutTabletMotion-
       Func, glutTimerFunc, glutUseLayer, glutVisibilityFunc,

       Mark Kilgard, Programming OpenGL	for the	X Window System,  Addison-Wes-
       ley, 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 (

GLUT				      3.7			   glut(3GLUT)


Want to link to this manual page? Use this URL:

home | help