OpenGLUT Documentation
Introduction | Documentation | Examples | Proposals | Authors | Copying | Todo | Bugs | Links

Window Management
[OpenGLUT API Reference]


int glutCreateSubWindow (int parentID, int x, int y, int w, int h)
int glutCreateWindow (const char *title)
void glutDestroyWindow (int windowID)
void glutFullScreen (void)
int glutGetWindow (void)
void * glutGetWindowData (void)
void glutHideWindow (void)
void glutIconifyWindow (void)
void glutInitDisplayMode (unsigned int displayMode)
void glutInitDisplayString (const char *displayMode)
void glutInitWindowPosition (int x, int y)
void glutInitWindowSize (int width, int height)
void glutPopWindow (void)
void glutPositionWindow (int x, int y)
void glutPostRedisplay (void)
void glutPostWindowRedisplay (int windowID)
void glutPushWindow (void)
void glutReshapeWindow (int width, int height)
void glutSetCursor (int cursorID)
void glutSetIconTitle (const char *title)
void glutSetWindow (int ID)
void glutSetWindowData (void *data)
void glutSetWindowTitle (const char *title)
void glutShowWindow (void)
void glutSwapBuffers (void)
void glutWarpPointer (int x, int y)

Detailed Description

There are two kinds of windows available using OpenGLUT:

Each window has a unique identifier and OpenGL rendering context.

This section describes the OpenGLUT API interface for creating, managing and closing windows. The section Window Callbacks describes the callback handlers that applications can provide to customise the behaviour of each window.

The desired position and size of a window is specified by glutInitWindowPosition() and glutInitWindowSize(). The display mode is specified by glutInitDisplayMode() or glutInitDisplayString() including RGBA color, double buffering, depth buffering and stencil buffering.

Once created with glutCreateWindow() windows can be controlled using:

A window is closed by calling glutDestroyWindow().

An application may open multiple top-level windows, each with optional subwindows. The current window is usually managed by the OpenGLUT event loop, but also be explicitly controlled:

OpenGLUT also provides the ability for application data to be associated with each window:

Function Documentation

int glutCreateSubWindow int  parentID,
int  x,
int  y,
int  w,
int  h

Create a subwindow.

parentID Parent window identifier
x Horizontal position of subwindow
y Vertical position of subwindow
w Width of subwindow
h Height of subwindow
In almost every regard that is important to you, a subwindow is like a top-level window. It has a window id; it has its own set of event callbacks; you can render to it; you are notified of its creation; ...

A subwindow lives inside of some other window (possibly a top-level window, possibly another subwindow). Because of this, it generally only interacts with other windows of your own creation, hence it is not subjected to a window manager. This is the primary source for its differences from a top-level window:

  • There are no borders or decorations.
  • There is no title bar, hence no title.
  • Requests tend to be acted on a little more directly, without interference from a window manager.
  • The subwindow inherits the display mode of its parent.

Like a top-level window, you must register a display callback function if you wish to use glutMainloop().

A notable case where this function can fail is for offscreen windows. A coherent concept of a subwindow of an offscreen window would introduce more complication than is presently believed to be worthwhile. Attempting such a window presently just fails. Failure is denoted by a 0 window id being returned.

Subwindows can be very useful for partitioning a window into GUI elements: They have their own input callbacks, so you don't have to figure out which window an event is for. Graphics are clipped to the boundaries of your subwindows, so you do not need to worry much about where your drawing goes. Because windows and subwindows work almost identically from the perspective of a GLUT program, it is relatively easy to move a cluster of related controls into a separate top-level window---or, conversely, embed what was a top-level window inside of another window. OpenGLUT can also report some basic statistics about your (sub)window, relieving you of the duty of tracking all of that information for yourself.

See also:
glutCreateWindow(), glutDestroyWindow(), glutCreateMenuWindow()

int glutCreateWindow const char *  title  ) 

Create a new top-level window.

title Title for created window
This function sends a request for a window to be constructed. OpenGLUT immediately constructs a data structure to track further events with the window, on the theory that eventually the window manager will get back to us with a real window. This allows us to begin registering callbacks immediately.

In fact, you must register a display callback via glutDisplayFunc() before you enter glutMainLoop().

For onscreen windows, you should not depend upon the window concretely existing or being visibile until you are told that it exists and is visible via a registered callback.

The return value is an int. It should be positive for valid windows or 0 if failure occurred for some reason (Though traditional GLUT tends to bail out and abort rather than returning errors.) The integer is your window id. Old GLUT promises that these integers are ``small''; we do not reuse old ids, but do produce them sequentially.

You can change the title later via glutSetWindowTitle().

See also:
glutDestroyWindow(), glutCreateSubWindow(), glutSetWindowTitle(), glutCreateMenuWindow()

void glutDestroyWindow int  windowID  ) 

Destroy a window and associated subwindows.

windowID Window identifier
After this function is invoked, the only further event that may be delivered for your window is the one for its destruction. All other events should be discarded.

Once a window has been destroyed, further attempts to use the window named by windowID are undefined. OpenGLUT generally tries to be sensible, and should not recycle the dead windowID, but you should treat a destroyed window much like a pointer to deallocated memory and try not to use it.

See also:

void glutFullScreen void   ) 

Resize the current window to cover the entire screen.

The glutFullScreen() function resizes the window to cover the entire screen and hide window decorations such as title bars and icons.

The desktop resolution is not affected by a call to glutReshapeWindow() or glutFullScreen().

The size of windows is ultimately determined by the windowing system. Therefore, a fullscreen request by an OpenGLUT application may not necessarily succeed or take immediate effect.

Not applicable to offscreen or subwindows.

See also:
glutInit(), glutInitWindowPosition(), glutInitWindowSize(), glutGet(), glutPositionWindow() and glutReshapeWindow()

int glutGetWindow void   ) 

Return the current window identifier, 0 if undefined.

glutGetWindow() returns the window id of the current window. This is useful, e.g., if you have a generic function that is used with several windows and it needs to temporarily change to another window. (There is no window stack for you to use with pushes and pops. Do not be confused by glutPushWindow() and glutPopWindow(); those pushes and pops are not stack-related!)

One cause for the function to return 0 is if you have called glutDestroyWindow() on the current window and have done nothing to set a new window as current.

See also:

void* glutGetWindowData void   ) 

Get the user data for the current window.

This function will return whatever void* value is associated with the current window via glutSetWindowData(). This is NULL if you did not associate a pointer with your window. This can be useful in a situation where you have a single callback function performing services for many windows. You could keep track of the window ids in a global list and search for the current window in that list. But this is quicker than searching a data structure, and allows you to avoid the use of globals for this.

See also:

void glutHideWindow void   ) 

Make the current window hidden.

Even if a window is ``open'', it need not be visible. It may be convenient to hide a window rather than to close it, if you want to re-display the window at the same location and size, later. Redefining all of the OpenGLUT features of a window and adding its window id to your tracking when re-opening a window may also be bothersome. So, rather than destroying it, you can simply ask for it to be hidden.

See also:

void glutIconifyWindow void   ) 

Iconify the current window.

Applies only to onscreen, top-level windows.

Not guaranteed to have any effect; effect may be arbitrarily delayed.

There is no callback that specifically tells you when (or if) your window is iconified.

Most window systems have some kind of ``minimized'' or ``iconified'' state for windows. All systems currently supported by OpenGLUT do so. The exact meaning of iconification is somewhat system-dependant, but this makes a request of the window system to place the window into this state.

Graphic output is usually suspended in this form. User input may be partially or wholly suspended.

If and when your window is iconified by the window system, it may be uniconified at any time by the system. This usually happens at the request of a user. Because of this, you should not use this function to hide a window. Rather, it is to help unclutter the user's display, and is more or less consensual with the user. Use glutHideWindow() if you want to hide the window entirely.

See also:
glutSetIconTitle(), glutHideWindow(), and glutShowWindow()

void glutInitDisplayMode unsigned int  displayMode  ) 

Set the window creation display mode.

displayMode Requested display mode bitmask.
glutInitDisplayMode() allows you to control the mode for subsequent OpenGLUT windows.

Allowable displayMode is a combination of:

    Red, green, blue framebuffer.

    Red, green, blue, alpha framebuffer.

    Indexed color framebuffer.

    Single-buffered mode.

    Double-buffered mode.

    Accumulation buffer.

    Alpha channel.

    Depth buffering.

    Stencil buffering.

    Multisampling mode. (not always available)

    Left and right framebuffers.

    Greyscale color mode.

Additionally, the following experimental features are implemented:

    Offscreen windows are very much like onscreen windows that have been dragged off of the edge of the screen. The biggest issue is that offscreen windows do not support subwindows. Other than that, onscreen windows that are dragged off of the edge may not store graphics that you render (while GLUT_OFFSCREEN windows do), and there is no way to drag an offscreen window onscreen for user interaction.

    Borderless windows are very experimental, and their precise behavior is not set in stone. See also glutCreateMenuWindow().

The following are defaults:


GLUT_OFFSCREEN windows do not work with nVidia cards/drivers. (Both Win32 and X11)

GLUT_BORDERLESS seems to vary by the window manager on X11, though twm (for example) performs very similarly to WIN32. But KDE's window manager (for example) does not let you send keystrokes to borderless windows without OpenGLUT hacks.

Some display mode features were introduced by OpenGLUT.

Not all features or combinations of features are valid for all platforms.

There is no way to change the display mode of an open window.

See also:
glutCreateMenuWindow(), glutInit(), glutInitWindowSize(), glutInitWindowPosition(), glutInitDisplayString(), glutSwapBuffers()

void glutInitDisplayString const char *  displayMode  ) 

Set the window creation display mode.

displayMode Requested display mode string.
glutInitDisplayString() permits you to define a display mode for subsequent windows that you open. In most regards, control is at least as fine as with glutInitDisplaymode().

The displayMode parameter is case-sensitive, and tokens are separated by ASCII TABs (\t) and SPACEs.

  • index
    Enables GLUT_INDEX.

  • luminance

  • red
    Number of red channel bits.

  • green
    Number of green channel bits.

  • blue
    Number of blue channel bits.

  • alpha
    Number of alpha channel bits. Enables GLUT_ALPHA.

  • rgb
    Number of RGB channel bits, no aplha bits. Enables GLUT_RGB.

  • rgba
    Number of RGBA channel bits. Enables GLUT_RGBA.

  • depth
    Number of depth buffer bits.

  • stencil
    Number of stencil buffer bits.

  • double
    Enables GLUT_DOUBLE.

  • single
    Enables GLUT_SINGLE.

  • stereo
    Enables GLUT_STEREO.

  • acca
    Number of RGBA accumulation bits. Enables GLUT_ACCUM.

  • acc
    Number of RGB accumulation bits. Enables GLUT_ACCUM.

  • samples
    Number of samples for GLX's SGIS_Multisample. Enables GLUT_MULTISAMPLE.

  • buffer
    [TODO] Sets bits in index mode?

  • conformant
    [TODO] Conformant with what? Enables GLUT_DEPTH.

  • slow
    [TODO] Indicates if a frame-buffer is slow.

  • num
    [TODO] Appears to select a frame-buffer configuration by number from an unspecified list. Probably very non-portable.

A special capability name indicating where the value represents the Nth frame buffer configuration matching the description string

  • win32pdf
    Win32 specific: Pixel Format Descriptor

  • win32pfd
    Win32 specific: Pixel Format Descriptor

  • xvisual
    X11 specific: X Visual

  • xstaticgray
    X11 specific: "staticgray" mode.

  • xgrayscale
    X11 specific: "grayscale" mode.

  • xstaticcolor
    X11 specific: "staticcolor" mode.

  • xpseudocolor
    X11 specific: "pseudocolor" mode.

  • xtruecolor
    X11 specific: "trueolor" mode.

  • xdirectcolor
    X11 specific: "directcolor" mode.

Conflicting modes, such as single and double have the same interaction as for glutInitDisplayMode().

GLUT_BORDERLESS and GLUT_OFFSCREEN are not represented.

Not all features appear to be implemented. In particular, numeric parameters and comparator specifications are lacking. See GLUT 3.7 sources for example.

PyOpenGL glutInitDisplayString documentation.

See also:
glutInit(), glutInitWindowPosition(), glutInitWindowSize(), glutInitDisplayMode()

void glutInitWindowPosition int  x,
int  y

Requests future windows to open at a given position.

x X coordinate.
y Y coordinate.
This function allows you to request an initial position for future windows.

See also:
glutPositionWindow(), glutInit(), glutInitWindowSize(), glutInitDisplayMode(), glutInitDisplayString(), glutGet()

void glutInitWindowSize int  width,
int  height

Requests future windows to open at a given width/height..

width Width of future windows.
height Height of future windows.
This function allows you to request initial dimensions for future windows.

There is a callback function to inform you of the new window shape (whether initially opened, changed by your glutReshapeWindow() request, or changed directly by the user).

See also:
glutReshapeWindow(), glutInit(), glutInitWindowPosition(), glutInitDisplayMode(), glutInitDisplayString(), glutReshapeFunc(), glutGet()

void glutPopWindow void   ) 

Request to raise the current window to the top.

Request that the current window be ``popped'' to the top.

A window can be in front of or behind other windows, as determined by the z-order from front to back. Top-level OpenGLUT windows can be placed at the front or back of the z-order by means of the glutPopWindow() and glutPushWindow() API functions.

A z-order also applies to the subwindows of a top-level window. While the z-order of top-level windows can usually be adjusted by the user, subwindow z-order is controlled entirely by the application.

If this has any effect on your window's visibility, you should receive a glutWindowStatusFunc() callback and a glutDisplayFunc() callback.

The z-order of top-level windows is ultimately managed by the windowing system. Therefore, a push or pop request by an OpenGLUT application may not necessarily succeed or take immediate effect.

Not applicable to offscreen windows.

See also:
glutCreateWindow(), glutDisplayFunc(), glutPushWindow(), glutWindowStatusFunc()

void glutPositionWindow int  x,
int  y

Request to change the position of the current window.

x Requested horizontal position of the current window
y Requested vertical position of the current window
The glutPositionWindow() function requests that the window system position a top-level or subwindow relative to the top-left corner. Subwindows are typically resized and repositioned in response to window resize events.

The position of top-level windows is ultimately determined by the windowing system. Therefore, a position request by an OpenGLUT application may not necessarily succeed.

May not take immediate effect; wait for the callback.

Not applicable to offscreen windows.

See also:
glutInit(), glutInitWindowPosition(), glutReshapeFunc(), and glutCreateSubWindow()

void glutPostRedisplay void   ) 

Mark the current window as needing a redisplay.

Whenever circumstances indicate that your window is in need of being redisplayed, you may call glutPostRedisplay() to tell OpenGLUT that you want to redraw your graphics. Multiple calls to this function may be coalesced by OpenGLUT to avoid excessive invocation of your drawing support.

The ultimate effect of this function is to call your Display callback for the current window.

See also:
glutPostWindowRedisplay(), glutPostOverlayRedisplay(), glutPostWindowOverlayRedisplay(), glutSwapBuffers(), glutDisplayFunc()

void glutPostWindowRedisplay int  windowID  ) 

Mark an indicated window as needing a redisplay.

windowID The OpenGLUT window id to be affected.
Similar to glutPostRedisplay(), except that instead of affecting the current window, this function affects an arbitrary window, indicated by the windowID parameter.

See also:
glutPostRedisplay(), glutPostOverlayRedisplay(), glutPostWindowOverlayRedisplay(), glutSwapBuffers(), glutDisplayFunc(), glutCreateWindow(), glutCreateSubWindow()

void glutPushWindow void   ) 

Request to lower the current window to the bottom.

This function requests that the current window be ``pushed'' to the back.

A window can be in front of or behind other windows, as determined by the z-order from front to back. Top-level OpenGLUT windows can be placed at the front or back of the z-order by means of the glutPopWindow() and glutPushWindow() API functions.

A z-order also applies to the subwindows of a top-level window. While the z-order of top-level windows can usually be adjusted by the user, subwindow z-order is controlled entirely by the application.

There may not be an immediate effect to this function. Wait for the glutWindowStatusFunc() callback to tell you about whatever obscured/visible status your window achieves.

The z-order of top-level windows is ultimately managed by the windowing system. Therefore, a push or pop request by an OpenGLUT application may not necessarily succeed or take immediate effect.

Not applicable to offscreen windows.

See also:
glutPopWindow(), glutWindowStatusFunc()

void glutReshapeWindow int  width,
int  height

Request changing the size of the current window.

width Requested width of the current window
height Requested height of the current window
The glutReshapeWindow() function adjusts the width and height of the current window, if it is an onscreen top-level or subwindow. Subwindows are typically resized and repositioned in response to window resize events.

The window system may delay or even alter your request. Use the glutReshapeFunc() callback registration for the window if you want

If you try to make a subwindow smaller than its parent, the parent will not grow to accomodate the child.

Add support for offscreen windows.
See also:
glutInit(), glutInitWindowSize(), glutReshapeFunc() and glutCreateSubWindow()

void glutSetCursor int  cursorID  ) 

Set the cursor image to be used for the current window.

cursorID Name of desired cursor.
For the current window, sets the mouse-cursor to one of a set of predefined images. The GLUT symbolic constant IDs are:


Additionally, there are the following special cases:

GLUT_CURSOR_FULL_CROSSHAIR This cursor, where supported, draws a crosshair the full width and height of the display. It may be mapped by OpenGLUT to the GLUT_CURSOR_CROSSHAIR, however.

GLUT_CURSOR_NONE Turn the mouse cursor invisibile.

GLUT_CURSOR_INHERIT Take the cursor that the parent window provides.

The X branch of OpenGLUT does not do thorough error checking.

The X branch of OpenGLUT always converts FULL_CROSSHAIR to CROSSHAIR. This is acceptable, but if a host system supports a fullscreen crosshair, it would be nice to support that.

Out of range cursorID values generate warnings.

Has no visible effect if the current window is of type GLUT_OFFSCREEN .

Some cursorID values are not yet supported on WIN32.

void glutSetIconTitle const char *  title  ) 

Requests changing the iconified title of the current window.

title New window title
Effect is system-dependant.
Requests that the window system change the title of the icon (or whatever) that is displayed when the current window is in iconified mode.

As discussed under glutIconifyWindow(), most window systems allow a window to be placed in some kind of minimized, or iconified, state. In that state, the normal interior of the window is likely to be obscured, and the only clue about the window contents may be the window title.

There Exactly what "iconified" means is system dependant. Iconification may not be supported, or the title may not be available---or legible. Avoid putting essential information into the icon title.
See also:
glutSetWindowTitle(), glutIconifyWindow()

void glutSetWindow int  ID  ) 

Select the current window.

ID Window identifier
Sets the current window to ID.

All OpenGL rendering goes to the current window. Many OpenGLUT functions also implicitly use the current window.

Many OpenGLUT callback operations are tied to a window. When your callback is invoked, OpenGLUT will set that particular window to be the current window. However, some callbacks---such as that registered via glutIdleFunc()---do not have associated windows. If a callback is not associated to a particular window, then when OpenGLUT invokes that callback you should always use glutSetWindow() to select the appropriate window before doing any OpenGL rendering or doing any OpenGLUT window-related operations.

There may be cases when you can get away with assuming that the current window is unchanged since some prior time, but OpenGLUT has considerable liberaty with respect to when it invokes your functions. Also, your program may add more windows or more operations on other windows as you develop it.

Lastly, this is a convenient way to select among multiple windows for drawing without actually waiting for that window's display callback. Simply set the current window and draw immediately. This is not always advisable, but may be practical.

It is an error to set the current window to a non-existant window (e.g., one that you have closed). A warning will be printed on stderr if you try to do so, and the current window should be unchanged.

See also:

void glutSetWindowData void *  data  ) 

Set the user data for the current window.

data Arbitrary client-supplied pointer.
This associates an arbitrary void* value with the current window. This is especially useful in client-side callbacks that service many windows, if the client needs to know more about the window than OpenGLUT normally will provide.

See also:

void glutSetWindowTitle const char *  title  ) 

Request changing the title of the current window.

title New window title
Only for managed, onscreen, top-level windows.

Not all window systems display titles.

May be ignored or delayed by window manager.

glutSetWindowTitle() requests that the window system change the title of the window.

Normally a window system displays a title for every top-level window in the system. The initial title is set when you call glutCreateWindow(). By means of this function you can set the titles for your top-level OpenGLUT windows.

Some window systems do not provide titles for windows, in which case this function may have no useful effect.

Because the effect may be delayed or lost, you should not count on the effect of this function. However, it can be a nice touch to use the window title bar for a one-line status bar in some cases. Use discretion.

If you just want one title for the window over the window's entire life, you should set it when you open the window with glutCreateWindow().

See also:
glutCreateWindow(), glutSetIconTitle()

void glutShowWindow void   ) 

Request that the current window be visible.

glutShowWindow() requests that the window system make the current window visible.

This is generally not necessary. When you create a window, it will normally become visible. Unless you specifically hide it, it will remain visible. Though visible, of course, it may be covered by other windows; that would be an issue for window stacking order not visibility.

When, and if, your window's visibility status changes, you may find out via a glutWindowStatusFunc() callback.

See also:
glutHideWindow(), glutPopWindow(), glutPushWindow(), glutWindowStatusFunc()

void glutSwapBuffers void   ) 

Swaps the buffers for the current window.

This function signals to OpenGLUT that you are done drawing to the current window for now. If your window is double-buffered (GLUT_DOUBLE param to glutInitDisplayMode()), then OpenGLUT will swap the front buffer with the back buffer.

This also computes your current frame-rate and prints the result on stderr if indicated by the GLUT_FPS environment variable. The computed value is not necessarily the total frame rate, if you have multiple windows, as the statistic is the total number of buffer-swaps for the entire program.

This function has no effect if your window is GLUT_SINGLE .

Frame rate is only calculated for double-buffered windows.

How does this interact with overlays?

Consider making GLUT_FPS keep per-window stats in a multi-window program.

See also:
glutPostRedisplay(), glutPostOverlayRedisplay(), glutPostWindowRedisplay(), glutPostWindowOverlayRedisplay(), glutInitDisplaymode()

void glutWarpPointer int  x,
int  y

Moves the mouse pointer to given window coordinates.

x Window X coord for mouse.
y Window Y coord for mouse.
glutWarpPointer() moves the mouse pointer to window-relative coordinates given by x and y.

x and y are relative to current window.

Not applicable for GLUT_OFFSCREEN windows.

Warping means moving, just as if the user had manually moved the mouse. This can generate mouse-motion callbacks. If your callback then moves the pointer again, you may end up in an endless loop. There is some discussion about changing this, but at present this is just a caveat for you, the user, to be aware of.

OpenGLUT Development @ Sourceforge
Homepage | Summary | Files | CVS | Forums | Lists | Bugs | RFE

Generated on Sat Feb 5 01:47:28 2005 for OpenGLUT by doxygen
The OpenGLUT project is hosted by