Overlays
[OpenGLEAN API Reference]

Collaboration diagram for Overlays:

Functions
void	glutEstablishOverlay (void)
void	glutHideOverlay (void)
int	glutLayerGet (GLenum eWhat)
void	glutPostOverlayRedisplay (void)
void	glutPostWindowOverlayRedisplay (int ID)
void	glutRemoveOverlay (void)
void	glutShowOverlay (void)
void	glutUseLayer (GLenum layer)

---

Detailed Description

Some windows may be able to handle one or more overlays. That is, some windows may be able to have a secondary bitmap that is placed over the normal display. This allows two or more bitmapped images to be displayed in a single window without directly intefering with one other---beyond the fact that one may obscure the other. The value here is that then the overlain bitmap may be removed or hidden and the underlain graphics will appear without requiring a redraw.

Old GLUT only supported indexed color for overlays. freeglut ignores all overlay requests. OpenGLEAN has inherited freeglut's and OpenGLUT's treatment. The current leaning is to remove the stub support for overlays. After 5 years of work in freeglut, and nearly a year for OpenGLUT, at this writing, neither ancestor of OpenGLEAN has bothered to implement overlays; while they might be nice to have, there is no code ready to go, and OpenGLEAN's first order of business is to trim away deadwood.

---

Function Documentation

void glutEstablishOverlay (  void   )

Creates an overlay. Creates an overlay associated with the current window. Note: Unimplemented. Old GLUT would terminate the program when an overlay was not possible. freeglut ignores the request; OpenGLEAN ignores the request as well. See also: glutRemoveOverlay(), glutUseLayer(), glutPostOverlayRedisplay(), glutPostWindowOverlayRedisplay(), glutShowOverlay(), glutHideOverlay()

void glutHideOverlay (  void   )

Make an overlay invisible. Causes a visible overlay to become invisible. Applies to the current window. Note: Unimplemented. See also: glutEstablishOverlay(), glutRemoveOverlay(), glutUseLayer(), glutPostOverlayRedisplay(), glutPostWindowOverlayRedisplay(), glutShowOverlay()

int glutLayerGet (  GLenum  eWhat  )

Allows you to get some overlay state/option variables. Parameters: eWhat  Enumerated parameter ID. Returns some useful information about layers. Or, it would be useful if layers were implemented... eWhat may be given any of the following values: GLUT_HAS_OVERLAY GLUT_LAYER_IN_USE GLUT_NORMAL_DAMAGED 0 unless the window system has told us that the normal layer is damaged (glutPostRedisplay() does not affect this). GLUT_OVERLAY_DAMAGED Returns -1 if no layer in use. GLUT_OVERLAY_POSSIBLE GLUT_TRANSPARENT_INDEX Returns -1 if no layer in use. All information relates to the current window and any overlay that it may have. It is a fatal error to call this function without properly initializing OpenGLEAN via glutInit(). A -1 is returned if the parameter to glutLayerGet() is unknown; in certain other cases noted above, a -1 is also returned if no layer is in use. The fatal error can probably be dropped, though the code is a little sloppy about FALSE, -1, and valid return values. Here, -1 seems to be the preferred way to indicate TRUE, though it is also the default value. See also: glutSetOption(), glutGet(), glutDeviceGet(), glutGetModifiers() Todo: Probably we should merge the below sections unless and until layer support is actually added. Todo: Should be set when the window is damaged; should not be set just for glutPostRedisplay().

void glutPostOverlayRedisplay (  void   )

Posts a redispaly against the layer for the current window. For the current window, tells OpenGLEAN that you wish to have your OverlayDisplay callback invoked. Note: Unimplemented. See also: glutEstablishOverlay(), glutRemoveOverlay(), glutUseLayer(), glutPostWindowOverlayRedisplay(), glutShowOverlay(), glutHideOverlay(), glutOverlayDisplayFunc(), glutPostRedisplay()

void glutPostWindowOverlayRedisplay (  int  ID  )

Posts a redisplay to the indicated window's layer. Parameters: ID  A window ID. This function lets you post an overlay update to the overlay of any arbitrary window. Note: Unimplemented. See also: glutEstablishOverlay(), glutRemoveOverlay(), glutUseLayer(), glutPostOverlayRedisplay(), glutShowOverlay(), glutHideOverlay(), glutOverlayDisplayFunc(), glutPostRedisplay()

void glutRemoveOverlay (  void   )

Removes an overlay. Removes the overlay associated with the current window. Note: Unimplemented. See also: glutEstablishOverlay(), glutUseLayer(), glutPostOverlayRedisplay(), glutPostWindowOverlayRedisplay(), glutShowOverlay(), glutHideOverlay()

void glutShowOverlay (  void   )

Make an overlay visible. Causes a previously-hidden overlay to become apparent. Applies to the current window. Note: Unimplemented. See also: glutEstablishOverlay(), glutRemoveOverlay(), glutUseLayer(), glutPostOverlayRedisplay(), glutPostWindowOverlayRedisplay(), glutHideOverlay()

void glutUseLayer (  GLenum  layer  )

Allows you to switch between normal and layer mode. Parameters: layer  Whether to be in a layer or in the normal window. By default, OpenGLEAN operates in "normal" mode, with respect to layers. If you have a layer open and wish to operate on the layer, you must use glutUseLayer(). layer can take on the following values, indicating the layer mode to use: GLUT_NORMAL GLUT_LAYER Note: Unimplemented. It is unclear what the consequences are if you are in GLUT_OVERLAY mode and switch to another (or the same) window via glutSetWindow(). What if the target has a layer? What if it doesn't? See also: glutEstablishOverlay(), glutRemoveOverlay(), glutPostOverlayRedisplay(), glutPostWindowOverlayRedisplay(), glutShowOverlay(), glutHideOverlay()

Supported in part by SourceForge.net.

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