GLUT Man Pages
glutInit is used to initialize the GLUT library.
void glutInit(int *argcp, char **argv);
glutInit will initialize the GLUT library and negotiate a session with the window system. During this process, glutInit may cause the termination of the GLUT program with an error message to the user if GLUT cannot be properly initialized. Examples of this situation include the failure to connect to the window system, the lack of window system support for OpenGL, and invalid command line options.
glutInit also processes command line options, but the specific options parse are window system dependent.
X Implementation Notes
The X Window System specific options parsed by glutInit
are as follows:
glutInitWindowPosition and glutInitWindowSize set the initial window position and size respectively.
void glutInitWindowSize(int width, int height); void glutInitWindowPosition(int x, int y);
Windows created byglutCreateWindow will be requested to be created with the current initial window position and size.
The initial value of the initial window position GLUT state is -1 and -1. If either the X or Y component to the initial window position is negative, the actual window position is left to the window system to determine. The initial value of the initial window size GLUT state is 300 by 300. The initial window size components must be greater than zero.
The intent of the initial window position and size values is to provide a suggestion to the window system for a window's initial size and position. The window system is not obligated to use this information. Therefore, GLUT programs should not assume the window was created at the specified size or position. A GLUT program should use the window's reshape callback to determine the true size of the window.
glutInitDisplayMode sets the initial display mode.
void glutInitDisplayMode(unsigned int mode);
The initial display mode is used when creating top-level windows, subwindows, and overlays to determine the OpenGL display mode for the to-be-created window or overlay.
Note thatGLUT_RGBA selects the RGBA color model, but it does not request any bits of alpha (sometimes called an alpha buffer or destination alpha) be allocated. To request alpha, specify GLUT_ALPHA. The same applies to GLUT_LUMINANCE.
GLUT_LUMINANCE Implementation Notes
GLUT_LUMINANCE is not supported on most OpenGL platforms.
glutMainLoop enters the GLUT event processing loop.
glutMainLoop enters the GLUT event processing loop. This routine should be called at most once in a GLUT program. Once called, this routine will never return. It will call as necessary any callbacks that have been registered.
glutCreateWindow creates a top-level window.
int glutCreateWindow(char *name);
DescriptionglutCreateWindow creates a top-level window. The name will be provided to the window system as the window's name. The intent is that the window system will label the window with the name.
Implicitly, the current window is set to the newly created window.
Each created window has a unique associated OpenGL context. State changes to a window's associated OpenGL context can be done immediately after the window is created.
The display state of a window is initially for the window to be shown. But the window's display state is not actually acted upon untilglutMainLoop is entered. This means until glutMainLoop is called, rendering to a created window is ineffective because the window can not yet be displayed.
The value returned is a unique small integer identifier for the window. The range of allocated identifiers starts at one. This window identifier can be used when callingglutSetWindow.
X Implementation Notes
The proper X Inter-Client Communication Conventions Manual (ICCCM) top-level properties are established. TheWM_COMMAND property that lists the command line used to invoke the GLUT program is only established for the first window created.
glutPostRedisplay marks the current window as needing to be redisplayed.
Mark the normal plane of current window as needing to be redisplayed. The next iteration throughglutMainLoop, the window's display callback will be called to redisplay the window's normal plane. Multiple calls to glutPostRedisplay before the next display callback opportunity generates only a single redisplay callback. glutPostRedisplay may be called within a window's display or overlay display callback to re-mark that window for redisplay.
Logically, normal plane damage notification for a window is treated as aglutPostRedisplay on the damaged window. Unlike damage reported by the window system, glutPostRedisplay will not set to true the normal plane's damaged status (returned by glutLayerGet(GLUT_NORMAL_DAMAGED).
glutSwapBuffers swaps the buffers of the current window if double buffered.
Performs a buffer swap on the layer in use for the current window. Specifically,glutSwapBuffers promotes the contents of the back buffer of the layer in use of the current window to become the contents of the front buffer. The contents of the back buffer then become undefined. The update typically takes place during the vertical retrace of the monitor, rather than immediately after glutSwapBuffers is called.
An implicitglFlush is done by glutSwapBuffers before it returns. Subsequent OpenGL commands can be issued immediately after calling glutSwapBuffers, but are not executed until the buffer exchange is completed.
If the layer in use is not double buffered,glutSwapBuffers has no effect.
glutCreateMenu creates a new pop-up menu.
int glutCreateMenu(void (*func)(int value));
glutCreateMenu creates a new pop-up menu and returns a unique small integer identifier. The range of allocated identifiers starts at one. The menu identifier range is separate from the window identifier range. Implicitly, the current menu is set to the newly created menu. This menu identifier can be used when calling glutSetMenu.
When the menu callback is called because a menu entry is selected for the menu, the current menu will be implicitly set to the menu with the selected entry before the callback is made.
X Implementation Notes
If available, GLUT for X will take advantage of overlay planes for implementing pop-up menus. The use of overlay planes can eliminate display callbacks when pop-up menus are deactivated. The SERVER_OVERLAY_VISUALS convention  is used to determine if overlay visuals are available.
glutAddMenuEntry adds a menu entry to the bottom of the current menu.
void glutAddMenuEntry(char *name, int value);
glutAddMenuEntry adds a menu entry to the bottom of the current menu. The string name will be displayed for the newly added menu entry. If the menu entry is selected by the user, the menu's callback will be called passing value as the callback's parameter.
glutAddSubMenu adds a sub-menu trigger to the bottom of the current menu.
void glutAddSubMenu(char *name, int menu);
glutAddSubMenu adds a sub-menu trigger to the bottom of the current menu. The string name will be displayed for the newly added sub-menu trigger. If the sub-menu trigger is entered, the sub-menu numbered menu will be cascaded, allowing sub-menu menu items to be selected.
glutDisplayFunc sets the display callback for the current window.
void glutDisplayFunc(void (*func)(void));
glutDisplayFunc sets the display callback for the current window. When GLUT determines that the normal plane for the window needs to be redisplayed, the display callback for the window is called. Before the callback, the current window is set to the window needing to be redisplayed and (if no overlay display callback is registered) the layer in use is set to the normal plane. The display callback is called with no parameters. The entire normal plane region should be redisplayed in response to the callback (this includes ancillary buffers if your program depends on their state).
GLUT determines when the display callback should be triggered based on the window's redisplay state. The redisplay state for a window can be either set explicitly by calling glutPostRedisplay or implicitly as the result of window damage reported by the window system. Multiple posted redisplays for a window are coalesced by GLUT to minimize the number of display callbacks called.
When an overlay is established for a window, but there is no overlay display callback registered, the display callback is used for redisplaying both the overlay and normal plane (that is, it will be called if either the redisplay state or overlay redisplay state is set). In this case, the layer in use is not implicitly changed on entry to the display callback.
See glutOverlayDisplayFunc to understand how distinct callbacks for the overlay and normal plane of a window may be established.
When a window is created, no display callback exists for the window. It is the responsibility of the programmer to install a display callback for the window before the window is shown. A display callback must be registered for any window that is shown. If a window becomes displayed without a display callback being registered, a fatal error occurs. Passing NULL to glutDisplayFunc is illegal as of GLUT 3.0; there is no way to ``deregister'' a display callback (though another callback routine can always be registered).
Upon return from the display callback, the normal damaged state of the window (returned by calling glutLayerGet(GLUT_NORMAL_DAMAGED) is cleared. If there is no overlay display callback registered the overlay damaged state of the window (returned by calling glutLayerGet(GLUT_OVERLAY_DAMAGED) is also cleared.
glutReshapeFunc sets the reshape callback for the current window.
void glutReshapeFunc(void (*func)(int width, int height));
glutReshapeFunc sets the reshape callback for the current window. The reshape callback is triggered when a window is reshaped. A reshape callback is also triggered immediately before a window's first display callback after a window is created or whenever an overlay for the window is established. The width and height parameters of the callback specify the new window size in pixels. Before the callback, the current window is set to the window that has been reshaped.
If a reshape callback is not registered for a window or NULL is passed to glutReshapeFunc (to deregister a previously registered callback), the default reshape callback is used. This default callback will simply call glViewport(0,0,width,height) on the normal plane (and on the overlay if one exists).
If an overlay is established for the window, a single reshape callback is generated. It is the callback's responsibility to update both the normal plane and overlay for the window (changing the layer in use as necessary).
When a top-level window is reshaped, subwindows are not reshaped. It is up to the GLUT program to manage the size and positions of subwindows within a top-level window. Still, reshape callbacks will be triggered for subwindows when their size is changed using glutReshapeWindow.
glutKeyboardFunc sets the keyboard callback for the current window.
void glutKeyboardFunc(void (*func)(unsigned char key, int x, int y));
glutKeyboardFunc sets the keyboard callback for the current window. When a user types into the window, each key press generating an ASCII character will generate a keyboard callback. The key callback parameter is the generated ASCII character. The state of modifier keys such as Shift cannot be determined directly; their only effect will be on the returned ASCII data. The x and y callback parameters indicate the mouse location in window relative coordinates when the key was pressed. When a new window is created, no keyboard callback is initially registered, and ASCII key strokes in the window are ignored. Passing NULL to glutKeyboardFunc disables the generation of keyboard callbacks.
During a keyboard callback, glutGetModifiers may be called to determine the state of modifier keys when the keystroke generating the callback occurred.
Also, see glutSpecialFunc for a means to detect non-ASCII key strokes.
glutMouseFunc sets the mouse callback for the current window.
void glutMouseFunc(void (*func)(int button, int state, int x, int y));
glutMouseFunc sets the mouse callback for the current window. When a user presses and releases mouse buttons in the window, each press and each release generates a mouse callback. The button parameter is one of GLUT_LEFT_BUTTON, GLUT_MIDDLE_BUTTON, or GLUT_RIGHT_BUTTON. For systems with only two mouse buttons, it may not be possible to generate GLUT_MIDDLE_BUTTON callback. For systems with a single mouse button, it may be possible to generate only a GLUT_LEFT_BUTTON callback. The state parameter is either GLUT_UP or GLUT_DOWN indicating whether the callback was due to a release or press respectively. The x and y callback parameters indicate the window relative coordinates when the mouse button state changed. If a GLUT_DOWN callback for a specific button is triggered, the program can assume a GLUT_UP callback for the same button will be generated (assuming the window still has a mouse callback registered) when the mouse button is released even if the mouse has moved outside the window.
If a menu is attached to a button for a window, mouse callbacks will not be generated for that button.
During a mouse callback, glutGetModifiers may be called to determine the state of modifier keys when the mouse event generating the callback occurred.
Passing NULL to glutMouseFunc disables the generation of mouse callbacks.
glutIdleFunc sets the global idle callback.
void glutIdleFunc(void (*func)(void));
glutIdleFunc sets the global idle callback to be func so a GLUT program can perform background processing tasks or continuous animation when window system events are not being received. If enabled, the idle callback is continuously called when events are not being received. The callback routine has no parameters. The current window and current menu will not be changed before the idle callback. Programs with multiple windows and/or menus should explicitly set the current window and/or current menu and not rely on its current setting.
The amount of computation and rendering done in an idle callback should be minimized to avoid affecting the program's interactive response. In general, not more than a single frame of rendering should be done in an idle callback.
Passing NULL to glutIdleFunc disables the generation of the idle callback.
glutTimerFunc registers a timer callback to be triggered in a specified number of milliseconds.
void glutTimerFunc(unsigned int msecs, void (*func)(int value), value);
glutTimerFunc registers the timer callback func to be triggered in at least msecs milliseconds. The value parameter to the timer callback will be the value of the value parameter to glutTimerFunc. Multiple timer callbacks at same or differing times may be registered simultaneously.
The number of milliseconds is a lower bound on the time before the callback is generated. GLUT attempts to deliver the timer callback as soon as possible after the expiration of the callback's time interval.
There is no support for canceling a registered callback. Instead, ignore a callback based on its value parameter when it is triggered.
glutSolidSphere and glutWireSphere render a solid or wireframe sphere respectively.
void glutSolidSphere(GLdouble radius, GLint slices, GLint stacks); void glutWireSphere(GLdouble radius, GLint slices, GLint stacks);
Renders a sphere centered at the modeling coordinates origin of the specifiedradius. The sphere is subdivided around the Z axis into slices and along the Z axis into stacks.
glutSolidCube and glutWireCube render a solid or wireframe cube respectively.
void glutSolidCube(GLdouble size); void glutWireCube(GLdouble size);
glutSolidCube and glutWireCube render a solid or wireframe cube respectively. The cube is centered at the modeling coordinates origin with sides of length size.
glutSolidCone and glutWireCone render a solid or wireframe cone respectively.
void glutSolidCone(GLdouble base, GLdouble height, GLint slices, GLint stacks); void glutWireCone(GLdouble base, GLdouble height, GLint slices, GLint stacks);
glutSolidCone and glutWireCone render a solid or wireframe cone respectively oriented along the Z axis. The base of the cone is placed at Z = 0, and the top at Z = height. The cone is subdivided around the Z axis into slices, and along the Z axis into stacks.
glutSolidTorus and glutWireTorus render a solid or wireframe torus (doughnut) respectively.
void glutSolidTorus(GLdouble innerRadius, GLdouble outerRadius, GLint nsides, GLint rings); void glutWireTorus(GLdouble innerRadius, GLdouble outerRadius, GLint nsides, GLint rings);
glutSolidTorus and glutWireTorus render a solid or wireframe torus (doughnut) respectively centered at the modeling coordinates origin whose axis is aligned with the Z axis.
glutSolidDodecahedron and glutWireDodecahedron render a solid or wireframe dodecahedron (12-sided regular solid) respectively.
void glutSolidDodecahedron(void); void glutWireDodecahedron(void);
glutSolidDodecahedron and glutWireDodecahedron render a solid or wireframe dodecahedron respectively centered at the modeling coordinates origin with a given radius.
glutSolidOctahedron and glutWireOctahedron render a solid or wireframe octahedron (8-sided regular solid) respectively.
void glutSolidOctahedron(void); void glutWireOctahedron(void);
glutSolidOctahedron and glutWireOctahedron render a solid or wireframe octahedron respectively centered at the modeling coordinates origin with a radius of 1.0.
glutSolidTetrahedron and glutWireTetrahedron render a solid or wireframe tetrahedron (4-sided regular solid) respectively.
void glutSolidTetrahedron(void); void glutWireTetrahedron(void);
glutSolidTetrahedron and glutWireTetrahedron render a solid or wireframe tetrahedron respectively centered at the modeling coordinates origin with a given radius.
glutSolidIcosahedron and glutWireIcosahedron render a solid or wireframe icosahedron (20-sided regular solid) respectively.
void glutSolidIcosahedron(void); void glutWireIcosahedron(void);
glutSolidIcosahedron and glutWireIcosahedron render a solid or wireframe icosahedron respectively. The icosahedron is centered at the modeling coordinates origin and has a radius of 1.0.
glutSolidTeapot and glutWireTeapot render a solid or wireframe teapot respectively.
void glutSolidTeapot(GLdouble size); void glutWireTeapot(GLdouble size);
glutSolidTeapot and glutWireTeapot render a solid or wireframe teapot respectively. Both surface normals and texture coordinates for the teapot are generated. The teapot is generated with OpenGL evaluators.