Functions | |
| 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) |
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:
|
||||||||||||||||||||||||
|
Create a subwindow.
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:
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.
|
|
|
Create a new top-level window.
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().
|
|
|
Destroy a window and associated subwindows.
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.
|
|
|
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.
|
|
|
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.
|
|
|
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.
|
|
|
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.
|
|
|
Iconify the current window.
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.
|
|
|
Set the window creation display mode.
Allowable displayMode is a combination of:
Additionally, the following experimental features are implemented:
The following are defaults:
|
|
|
Set the window creation display mode.
The displayMode parameter is case-sensitive, and tokens are separated by ASCII TABs (\t) and SPACEs.
A special capability name indicating where the value represents the Nth frame buffer configuration matching the description string
|
|
||||||||||||
|
Requests future windows to open at a given position.
|
|
||||||||||||
|
Requests future windows to open at a given width/height..
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).
|
|
|
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.
|
|
||||||||||||
|
Request to change the position of the current window.
|
|
|
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.
|
|
|
Mark an indicated window as needing a redisplay.
|
|
|
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.
|
|
||||||||||||
|
Request changing the size of the current window.
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.
|
|
|
Set the cursor image to be used for the current window.
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.
|
|
|
Requests changing the iconified title of the current window.
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.
|
|
|
Select the current window.
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.
|
|
|
Set the user data for the current window.
|
|
|
Request changing the title of the current 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().
|
|
|
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.
|
|
|
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.
|
|
||||||||||||
|
Moves the mouse pointer to given window coordinates.
|