OpenGLEAN
OpenGLEAN User Support
Home page | Introduction | Documentation | Files | Examples | Proposals | Authors | Links


OpenGLEAN Development
Summary | CVS | (discussion via home page) | (contact via home page) | (suggestion box) | License | Todo | Bugs

Window Management
[OpenGLEAN API Reference]

Collaboration diagram for Window Management:


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)

Detailed Description

OpenGLEAN's primary purpose in life is to provide a portable, simple access to native window systems---including OpenGL rendering capabilities. A window can be thought of as a rectangular array of pixels, to which some display mode options can be attached. Some windows can be placed onscreen, for user interaction. Other windows may be simply containers for offscreen graphics---loaded from some source, or rendered algorithmically.

One way to divide OpenGLEAN windows is by these two categories:

...this is a good place to start, but will be seen to hardly be exhaustive of OpenGLEAN's options.

Each window has a unique identifier and OpenGL rendering context.

This section describes the OpenGLEAN 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 OpenGLEAN event loop, but also be explicitly controlled:

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

Of special note about window coordinates and dimensions (extracted from a freeglut comment formerly embedded in the og_state.c source file, with some editing):

There is considerable confusion about the "right thing to do" concerning window size and position. GLUT itself is not consistent between WIN32 and UNIX_X11. Since platform independence is a virtue, it was decided to break with GLUT's behaviour.

Under UNIX_X11, it is obviously not possible to get the window border sizes in order to subtract them off the window's initial position, until some time after the window has been created. Therefore it was decided to take the following behavior, on both UNIX_X11 and WIN32:

OpenGLEAN is at some liberty to change the latter point, perhaps. Because the window system can ignore or alter a client's request for window position and size, it is meaningless to query the window status until the window is open. At that time, we should be able to get full information about the window.

One further caveat: I have seen window managers that put the title bar on the side of the window. I believe that I have even seen managers that move the title bar dynamically if the size of the window changes (or perhaps the title lengths/shortens). All bets are off if the window manager is changed or reconfigured between the time that you get the coords and the time that you use them.

Todo:
At some point, the API should be revised so that one can make a more meaningful query/request pattern to restore window size/position. We should be able to do better than the current situation.

----

OpenGLEAN has numerous data structures that must be initialized before use. Additionally, OpenGLEAN supports some interaction with the user and environment during initialization---for example, setting the window size and position. In the same family, there are a few functions for letting the program set default values and make requests.

The glutInit*() functions cover these needs.

Bear in mind that:

Function Documentation

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

Create a subwindow.

Parameters:
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 "normal" 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. Future OpenGLEAN versions may support offscreen subwindows. It is formally undefined whether the parent window contents are maintained "behind" subwindows (this allows a fairly natural way to implement offscreen subwindows: Make them simply offscreen windows, with an attachment to their parent).

Offscreen subwinodws may be useful for testing complex applications without rendering to onscreen graphics.

This routine can also return 0 (i.e., fail) if the parentID parent window cannot be found.

Regardless of cause, failure by this function is denoted by a 0 window id being returned.

It is a fatal error to call this function without first initializing OpenGLEAN via glutInit(). It is also a fatal error to call this function without having a current window.

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. OpenGLEAN 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()
Todo:
Consider implementing subwindows as a "mode" or "style" of a more generic window creation interface. (The parentID could then be omitted and instead we'd use the current window.)

int glutCreateWindow (  const char *  title  ) 
 

Create a new top-level window.

Parameters:
title Title for created window
This function sends a request for a window to be constructed. OpenGLEAN 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().

A return value of 0 indicates an error. (By default, OpenGLEAN's glutCreateWindow() only returns if it will succeed.)

It is a fatal error to call this function without first initializing OpenGLEAN via glutInit().

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

void glutDestroyWindow (  int  windowID  ) 
 

Destroy a window and associated subwindows.

Parameters:
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. OpenGLEAN 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.

It is a fatal error to call this function without first properly initializing OpenGLEAN via glutInit().

See also:
glutCreateWindow()
Todo:
Is this safe if we are not initialized yet?
Todo:
Clean this up.

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.

It is a fatal error either to call this function without first properly initializing OpenGLEAN via glutInit() or to call this function without a current window.

Note:
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 OpenGLEAN application may not necessarily succeed or take immediate effect.

Not applicable to offscreen or subwindows.

See also:
glutInit(), glutInitWindowPosition(), glutInitWindowSize(), glutGet(), glutPositionWindow() and glutReshapeWindow()
Bug:
It is reported that some window managers (under X) do not let a fullscreen window cover up, e.g., icons. This can probably be handled by making the fullscreen window unmanaged. Alternatively, "stay on top" might work, but "stay on top" has to be tweaked for every window manager and doesn't work on most.

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.

It is a fatal error to call this function without first initializing OpenGLEAN via glutInit().

See also:
glutSetWindow()

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.

It is a fatal error either to call this function without first properly initializing OpenGLEAN via glutInit() or to call this function without a current window.

See also:
glutInit(), glutSetWindowData()

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 OpenGLEAN 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.

It is a fatal error either to call this function without first properly initializing OpenGLEAN via glutInit() or to call this function without a current window.

See also:
glutShowWindow()

void glutIconifyWindow (  void   ) 
 

Iconify the current window

Most window systems have some kind of ``minimized'' or ``iconified'' state for windows. All systems currently supported by OpenGLEAN 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.

It is a fatal error either to call this function without first properly initializing OpenGLEAN via glutInit() or to call this function without a current window.

Note:
Applies only to onscreen, top-level windows.

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

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

There is no glutUnIconifyWindow(). In practice, glutShowWindow() can serve that end.

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

void glutInitDisplayMode (  unsigned int  displayMode  ) 
 

Set the window creation display mode.

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

Allowable displayMode is a combination of:

  • GLUT_RGB Red, green, blue framebuffer.
  • GLUT_RGBA Red, green, blue, alpha framebuffer.
  • GLUT_INDEX Indexed color framebuffer.
  • GLUT_SINGLE Single-buffered mode.
  • GLUT_DOUBLE Double-buffered mode.
  • GLUT_ACCUM Accumulation buffer.
  • GLUT_ALPHA Alpha channel.
  • GLUT_DEPTH Depth buffering.
  • GLUT_STENCIL Stencil buffering.
  • GLUT_MULTISAMPLE Multisampling mode. (not always available)
  • GLUT_STEREO Left and right framebuffers.
  • GLUT_LUMINANCE Greyscale color mode.

Additionally, the following experimental features are implemented:

  • GLUT_OFFSCREEN 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.

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

The following are defaults:

  • GLUT_RGB
  • GLUT_SINGLE

Note:
Some display mode features were introduced by OpenGLEAN.

glutInitDisplayString() should, in theory, be able to do everything that glutInitDisplaymode() does, and more. glutInitDisplayMode() is limited to a field of bitflags, in an int. Portably, the most that that can be counted upon to hold is 16 bits, though in practice 32 bits is probably safe. glutInitDisplayString() is open-ended in its capacity, as it takes a NUL terminated string. The downside of glutInitDisplayString() is that there is no compile-time check for validity---but if the options are staticly known at compile-time, you can at least test your application rigorously. For dynamic mode selections, the issue is less clear, though the flexibility of the string-based interface makes it likely that that will be the preferred mechanism for future growth.

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()
Bug:
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 OpenGLEAN hacks.

void glutInitDisplayString (  const char *  displayMode  ) 
 

Set the window creation display mode.

Parameters:
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.

  • offscreen Enables GLUT_OFFSCREEN.
  • index Enables GLUT_INDEX.
  • luminance Enables GLUT_LUMINANCE. Enables GLUT_STENCIL.
  • 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 Sets bits in index mode?
  • conformant Conformant with what? Enables GLUT_DEPTH.
  • slow Indicates if a frame-buffer is slow?
  • num Appears to select a frame-buffer configuration by number from an unspecified list. Possibly a step towards a portable variation of xvisual and win32pfd.
  • win32pdf (DEPRECATED) Win32 specific: Pixel Format Descriptor. (This is a historic typo from freeglut; OpenGLUT fixed it.)
  • 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.

Additionally, the following are experimental.

  • aux Sets exactly 1 aux. buffer. (We need to upgrade this function to old GLUT's level of support so that we can say things like aux=1.) In the meantime, perhaps a noaux option could be added to set 0 aux. buffers?

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

The mode string must be fully specified everytime. It may be better to store the previous state and let this function turn on/off specific modes. A corresponding query then may be required.

See also:
glutInit(), glutInitWindowPosition(), glutInitWindowSize(), glutInitDisplayMode()
Todo:
GLUT_BORDERLESS is not represented.

offscreen is not tested.

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.

void glutInitWindowPosition (  int  x,
int  y
) 
 

Requests future windows to open at a given position.

Parameters:
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..

Parameters:
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 OpenGLEAN 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.

It is a fatal error either to call this function without first properly initializing OpenGLEAN via glutInit() or to call this function without a current window.

Note:
The z-order of top-level windows is ultimately managed by the windowing system. Therefore, a push or pop request by an OpenGLEAN 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 a change to the position of the current window.

Parameters:
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.

It is a fatal error either to call this function without first properly initializing OpenGLEAN via glutInit() or to call this function without a current window.

Note:
The position of top-level windows is ultimately determined by the windowing system. Therefore, a position request by an OpenGLEAN 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()
Bug:
Menu windows should probably reposition relative to their parents.

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 OpenGLEAN that you want to redraw your graphics. Multiple calls to this function may be coalesced by OpenGLEAN to avoid excessive invocation of your drawing support.

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

It is a fatal error either to call this function without properly initializing OpenGLEAN via glutInit() or to call this function without a current window.

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

void glutPostWindowRedisplay (  int  windowID  ) 
 

Mark an indicated window as needing a redisplay.

Parameters:
windowID The OpenGLEAN 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.

It is a fatal error to call this function without properly initializing OpenGLEAN via glutInit().

Note:
If the requested windowID cannot be mapped to a window, this silently does nothing. Perhaps we should print a warning, or even exit with an error message?
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 OpenGLEAN 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.

It is a fatal error either to call this function without first properly initializing OpenGLEAN via glutInit() or to call this function without a current window.

Note:
The z-order of top-level windows is ultimately managed by the windowing system. Therefore, a push or pop request by an OpenGLEAN 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.

Parameters:
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. Do not count on the size changing at all until you get a reshape callback. And always check the actual size passed to your reshape.

Does not enforce relations between windows and subwindow size/position.

It is a fatal error either to call this function without first properly initializing OpenGLEAN via glutInit() or to call this function without a current window.

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

void glutSetCursor (  int  cursorID  ) 
 

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

Parameters:
cursorID Name of desired cursor.
For the current window, requests that the mouse-cursor be one of a set of predefined images. The request may fail, resulting in a reasonable default choice being made. The GLUT symbolic constant IDs are:

  • GLUT_CURSOR_RIGHT_ARROW
  • GLUT_CURSOR_LEFT_ARROW
  • GLUT_CURSOR_INFO
  • GLUT_CURSOR_DESTROY
  • GLUT_CURSOR_HELP
  • GLUT_CURSOR_CYCLE
  • GLUT_CURSOR_SPRAY
  • GLUT_CURSOR_WAIT
  • GLUT_CURSOR_TEXT
  • GLUT_CURSOR_CROSSHAIR
  • GLUT_CURSOR_UP_DOWN
  • GLUT_CURSOR_LEFT_RIGHT
  • GLUT_CURSOR_TOP_SIDE
  • GLUT_CURSOR_BOTTOM_SIDE
  • GLUT_CURSOR_LEFT_SIDE
  • GLUT_CURSOR_RIGHT_SIDE
  • GLUT_CURSOR_TOP_LEFT_CORNER
  • GLUT_CURSOR_TOP_RIGHT_CORNER
  • GLUT_CURSOR_BOTTOM_RIGHT_CORNER
  • GLUT_CURSOR_BOTTOM_LEFT_CORNER

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 OpenGLEAN 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---this relationship is dynamic, so that changing the parent window will change all direct children with GLUT_CURSOR_INHERRIT.

It is a fatal error either to call this function without properly initializing OpenGLEAN via glutInit() or to call this function without a current window.

Todo:
Presently on X11, if we fail to create the new cursor, we behave as if GLUT_CURSOR_INHERIT were requested. We should probably leave the cursor unchanged. Before I tighten this up too much, I should determine what we can truly guarnatee with WIN32.
Note:
The X branch of OpenGLEAN does not do thorough error checking.

The X branch of OpenGLEAN 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. OpenGLEAN actually rewrites your cursor choice, at present, rather than silently pretending that you said something else. This is not what GLUT, or freeglut (now), do.

Out of range cursorID values generate warnings.

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

Consider importing the cursor-caching that freeglut has recently added. Useful for those special corner cases where you're running your application remotely and don't want to keep re-generating the cursor over a network link.
Bug:
Some cursorID values are not yet supported on WIN32.

void glutSetIconTitle (  const char *  title  ) 
 

Requests changing the iconified title of the current window.

Parameters:
title New window title
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.

It is a fatal error either to call this function without first properly initializing OpenGLEAN via glutInit() or to call this function without a current window.

Note:
Effect is system-dependant.

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.

Parameters:
ID Window identifier
Sets the current window to ID.

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

Many OpenGLEAN callback operations are tied to a window. When your callback is invoked, OpenGLEAN 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 OpenGLEAN invokes that callback you should always use glutSetWindow() to select the appropriate window before doing any OpenGL rendering or doing any OpenGLEAN window-related operations.

Even though in some cases you may be able to avoid this stipulation, it is best to always follow it. One reason is the lack of promise from OpenGLEAN to maintain any particular current window setting. Another reason is that your application may grow to use more windows, and you may find that as OpenGLEAN talks to each of your several windows (or you try to manage them), implicit assumptions about current window values may no longer hold.

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.

To determine success, it is necessary to call glutGetWindow() and see if the new current window matches the one that you requested.

It is a fatal error to call this function without first initializing OpenGLEAN via glutInit().

See also:
glutGetWindow()

void glutSetWindowData (  void *  data  ) 
 

Set the user data for the current window.

Parameters:
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 OpenGLEAN normally will provide.

It is a fatal error either to call this function without first properly initializing OpenGLEAN via glutInit() or to call this function without a current window.

See also:
glutInit(), glutGetWindowData()

void glutSetWindowTitle (  const char *  title  ) 
 

Request changing the title of the current window.

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

Most window systems display a title for every (normal) 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 OpenGLEAN 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().

It is a fatal error either to call this function without first properly initializing OpenGLEAN via glutInit() or to call this function without a current window.

Note:
Only for managed, onscreen, top-level windows.

Not all window systems display titles.

May be ignored or delayed by window manager.

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.

It is a fatal error either to call this function without first properly initializing OpenGLEAN via glutInit() or to call this function without a current window.

Note:
There are at least 3 concepts of visiblity: Obscuring by other windows; "unmapping", and iconification. (Iconification is also called "minimization" on some systems.) These three are a bit muddled in the current API.
See also:
glutHideWindow(), glutPopWindow(), glutPushWindow(), glutWindowStatusFunc()

void glutSwapBuffers (  void   ) 
 

Swaps the buffers for the current window.

This function signals to OpenGLEAN that you are done drawing to the current window for now. If your window is double-buffered (GLUT_DOUBLE param to glutInitDisplayMode()), then OpenGLEAN 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.

It is a fatal error either to call this function without properly initializing OpenGLEAN via glutInit() or to call this function without a current window.

Note:
This function has little or no effect for GLUT_SINGLE.

Frame rate is now calculated for all windows if you call glutSwapBuffers() on them.

See also:
glutPostRedisplay(), glutPostOverlayRedisplay(), glutPostWindowRedisplay(), glutPostWindowOverlayRedisplay(), glutInitDisplaymode()
Todo:
How does this interact with overlays?

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

Here is the call graph for this function:

void glutWarpPointer (  int  x,
int  y
) 
 

Moves the mouse pointer to given window coordinates.

Parameters:
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.

It is a fatal error either to call this function without properly initializing OpenGLEAN via glutInit() or to call this function without a current window.

Note:
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 programmer, to be aware of.

On X, the operation may be buffered. To ensure that the effect is had, XFlush() is needed. This normally happens implicity by the event processing. If you use glutMainLoopEvent(), and call this function outside of glutMainLoopEvent(), the effect may be delayed.




SourceForge.net Logo Supported in part by SourceForge.net.

Generated on Fri Sep 16 20:15:34 2005 for OpenGLEAN by doxygen 1.4.3
The OpenGLEAN project is hosted by olib.org and SourceForge.