Страницы справочника OS X

Эта страница руководства является частью версии 5.0 Инструментов XCode

Читать страницы руководства

glut(3GLUT)                                         GLUT                                         glut(3GLUT)



NAME
       glut - an introduction to the OpenGL Utility Toolkit

SYNOPSIS
       #include <GLUT/glut.h>

       #include <GL/glut.h>

DESCRIPTION
       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 objects.

              Support for bitmap and stroke fonts.

              Miscellaneous window management functions, including managing overlays.

       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 also available.

BACKGROUND
       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 speci-fication specification
       fication 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 window-ing windowing
       ing 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 win-dowing windowing
       dowing interface.

       Removing window system operations from OpenGL is a sound decision because it allows the OpenGL graph-ics graphics
       ics 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  televi-sion, television,
       sion, and PCs.

       Unfortunately,  the lack of a window system interface for OpenGL is a gap in OpenGL's utility. Learn-ing Learning
       ing 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 func-tionality functionality
       tionality 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.

PHILOSPHY
       GLUT  simplifies the implementation of programs using OpenGL rendering. The GLUT application program-ming programming
       ming 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 refer-enced) referenced)
       enced) 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 sys-tem system
       tem 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 imple-ments implements
       ments 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  dis-play display
       play  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:

       Initialization.
              Command  line  processing, window system initialization, and initial 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  continu-ously continuously
              ously calls GLUT callbacks as necessary.

       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 including spheres, cones, icosahe-drons, icosahedrons,
              drons, and teapots.

CONVENTIONS
       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 consid-ers considers
       ers  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 GLUT's ANSI C binding, for most routines, basic types (int, char*) are used as parameters. In rou-tines routines
       tines 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 inabil-ity inability
       ity  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 pro-grams. programs.
       grams. 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

SEE ALSO
       glutAddMenuEntry(3G), glutAddSubMenu(3G), glutAttachMenu(3G), glutBitmapCharacter(3G),  glutBitmapWidth(3G),  glutButton-BoxFunc(3G), glutButtonBoxFunc(3G),
       BoxFunc(3G), glutChangeToMenuEntry(3G), glutChangeToSubMenu(3G), glutCopyColormap(3G), glutCreateMenu(3G), glutCreateSub-Window(3G), glutCreateSubWindow(3G),
       Window(3G), glutCreateWindow(3G), glutDestroyMenu(3G), glutDestroyWindow(3G), glutDeviceGet(3G), glutDialsFunc(3G),  glutDis-playFunc(3G), glutDisplayFunc(3G),
       playFunc(3G), glutEntryFunc(3G), glutEstablishOverlay(3G), glutExtensionSupported(3G), glutFullScreen(3G), glutGet(3G), glut-GetColor(3G), glutGetColor(3G),
       GetColor(3G),  glutGetModifiers(3G),  glutIdleFunc(3G),  glutInit(3G),  glutInitDisplayMode(3G),  glutInitWindowPosition(3G),
       glutKeyboardFunc(3G), glutLayerGet(3G), glutMainLoop(3G), glutMenuStatusFunc(3G), glutMotionFunc(3G), glutMouseFunc(3G), glu-tOverlayDisplayFunc(3G), glutOverlayDisplayFunc(3G),
       tOverlayDisplayFunc(3G), glutPopWindow(3G), glutPositionWindow(3G), glutPostOverlayRedisplay(3G),  glutPostRedisplay(3G),
       glutRemoveMenuItem(3G),  glutRemoveOverlay(3G), glutReshapeFunc(3G), glutReshapeWindow(3G), glutSetColor(3G), glutSetCur-sor(3G), glutSetCursor(3G),
       sor(3G), glutSetMenu(3G), glutSetWindow(3G), glutSetWindowTitle(3G), glutShowOverlay(3G), glutShowWindow(3G),  glutSolidCone(3G),
       glutSolidCube(3G),  glutSolidDodecahedron(3G),  glutSolidIcosahedron(3G),  glutSolidOctahedron(3G),  glutSolidSphere(3G),
       glutSolidTeapot(3G), glutSolidTetrahedron(3G), glutSolidTorus(3G), glutSpaceballButtonFunc(3G),  glutSpaceballMotion-Func(3G), glutSpaceballMotionFunc(3G),
       Func(3G),   glutSpaceballRotateFunc(3G),  glutSpecialFunc(3G),  glutStrokeCharacter(3G),  glutStrokeWidth(3G),  glutSwap-Buffers(3G), glutSwapBuffers(3G),
       Buffers(3G), glutTabletButtonFunc(3G), glutTabletMotionFunc(3G), glutTimerFunc(3G), glutUseLayer(3G), glutVisibilityFunc(3G),


REFERENCES
       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).

WEB REFERENCES
       Main GLUT page
       http://www.opengl.org/resources/libraries/glut/

       GLUT Frequently Asked Question list
       http://www.opengl.org/resources/libraries/glut/faq/

       The OpenGL Utility Toolkit (GLUT) Programming Interface API Version 3
       http://www .opengl.org/documentation/specs/glut/spec3/spec3.html
       http://www .opengl.org/documentation/specs/glut/glut-3.spec.ps.gz
       http://www .opengl.org/documentation/specs/glut/glut-3.spec.pdf


AUTHOR
       Mark J. Kilgard (mjk@nvidia.com)



GLUT                                                 3.7                                         glut(3GLUT)