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

State Query
[OpenGLEAN API Reference]

Collaboration diagram for State Query:


Functions

int glutGet (GLenum eWhat)
void glutSetOption (GLenum eWhat, int value)

Detailed Description

OpenGLEAN provides a certain amount of state to track modes of operation as well as status information on various objects such as OpenGLEAN windows. Additionally, there is some static state information about OpenGLEAN itself, and system-dependant state about the underlying window system.

The state module provides some support for modifying OpenGLEAN state, as well as support for querying state.

Function Documentation

int glutGet (  GLenum  eWhat  ) 
 

Allows you to query some general state/option variables.

Parameters:
eWhat Enumerated parameter ID.
This function permits you to query for the current value of many different OpenGLEAN state variables. The current list is:

  • GLUT_ACTION_ON_WINDOW_CLOSE (DREPRECATED) Allows you to do something other than die if the user closes one of your windows.
  • GLUT_DISPLAY_MODE_POSSIBLE Returns 0 if the currently requested window mode is infeasible. ("Display mode" is an unfortunate term, as things such as auxiliary buffers, which are not part of the display mode bit-flags, will affect this.) Success here does not guarantee that the window can open, but failure suggests that you should try with less ambitious feature requests.
  • GLUT_ELAPSED_TIME Returns the milliseconds since OpenGLEAN initialized its timer (generally glutInit() will do this, but requesting the elapsed time will also effectively initialize the timer if that was not already done).
  • GLUT_INIT_DISPLAY_MODE Returns the bitmask corresponding to glutInitDisplayMode().
  • GLUT_INIT_STATE Returns 0 if OpenGLEAN has not been initialized. Otherwise returns non-zero.
  • GLUT_INIT_WINDOW_HEIGHT Returns the current expected/requested height of new windows.
  • GLUT_INIT_WINDOW_WIDTH Returns the current expected/requested width of new windows.
  • GLUT_INIT_WINDOW_X Returns the current expected/requested horizontal position of new windows.
  • GLUT_INIT_WINDOW_Y Returns the current expected/requested vertical position of new windows.
  • GLUT_MENU_NUM_ITEMS Returns the number of menu items on the current menu.
  • GLUT_RENDERING_CONTEXT This variable controls context-sharing when OpenGLEAN opens new windows.
  • GLUT_SCREEN_HEIGHT Returns the height in pixels of the entire display; may be larger than the current video mode.
  • GLUT_SCREEN_HEIGHT_MM Returns the eight in millimeters of the entire display; may be larger than the current video mode.
  • GLUT_SCREEN_WIDTH Returns the width in pixels of the entire display; may be larger than the current video mode.
  • GLUT_SCREEN_WIDTH_MM Returns the width in millimeters of the entire display; may be larger than the current video mode.
  • GLUT_VERSION (DEPRECATED) It's not clear whether this should return a GLUT library version, or the OpenGLEAN version. Encoded as OPENGLEAN_VERSION, below.
  • OPENGLEAN_VERSION The version of OpenGLEAN, encoded as ( 10000*MAJOR ) + ( 100*MINOR ) + PATCH
  • GLUT_WINDOW_ACCUM_ALPHA_SIZE Returns the number of bits to use for an alpha channel in the accumulation buffer for the current window.
  • GLUT_WINDOW_ACCUM_BLUE_SIZE Returns the number of bits to use for a blue channel in the accumulation buffer for the current window.
  • GLUT_WINDOW_ACCUM_GREEN_SIZE Returns the number of bits to use for a green channel in the accumulation buffer for the current window.
  • GLUT_WINDOW_ACCUM_RED_SIZE Returns the number of bits to use for a red channel in the accumulation buffer for the current window.
  • GLUT_WINDOW_ALPHA_SIZE Returns the number of bits to use for an alpha channel for the color buffer in the current window.
  • GLUT_WINDOW_BLUE_SIZE Returns the number of bits to use for a blue channel for the color buffer in the current window.
  • GLUT_WINDOW_BORDER_WIDTH Returns the pixel-width of the window border for the current window
  • GLUT_WINDOW_BUFFER_SIZE Returns the bit-depth of the current window.
  • GLUT_WINDOW_COLORMAP_SIZE Currently returns 0 if you have an RGB window. Otherwise, should return the number of colors in the colormap.
  • GLUT_WINDOW_CURSOR Returns the current GLUT cursor. See glutSetCursor().
  • GLUT_WINDOW_DEPTH_SIZE Returns the number of bits in the depth buffer for the current window.
  • GLUT_WINDOW_DOUBLEBUFFER Returns 0 if the current window is single-buffered; else returns non-zero.
  • GLUT_WINDOW_FORMAT_ID System dependant.
  • GLUT_WINDOW_GREEN_SIZE Returns the number of bits to use for a green channel for the color buffer in the current window.
  • GLUT_WINDOW_HEADER_HEIGHT Returns the pixel-height of the titlebar on top of the current window. (It's not clear if this includes the border, nor what an application should do to deal with title bars placed on the sides of windows, as some windowmanagers do.)
  • GLUT_WINDOW_HEIGHT Returns the pixel height of the current window.
  • GLUT_WINDOW_NUM_CHILDREN Returns the number of children of the current window. It's not clear if this should include menu windows.
  • GLUT_WINDOW_NUM_SAMPLES Returns the number of samples used for multisampling for the current window.
  • GLUT_WINDOW_PARENT Returns the GLUT window id of the parent window of the current window. If there is no current window, or if it has no parent, then 0 is returned.
  • GLUT_WINDOW_RED_SIZE Returns the number of bits to use for a red channel for the color buffer in the current window.
  • GLUT_WINDOW_RGBA Returns 0 if the color buffer for the current window stores indexed colors (a.k.a. paletted colors); returns non-zero if the current window stores RGB information in each pixel.
  • GLUT_WINDOW_STENCIL_SIZE Returns the bit-depth of the stencil buffer for the current window.
  • GLUT_WINDOW_STEREO Returns non-zero if the color buffers for the current window exist in left/right pairs. Else returns 0.
  • GLUT_WINDOW_WIDTH Returns the pixel width of the current window.
  • GLUT_WINDOW_X Returns the horizontal pixel position of the current window.
  • GLUT_WINDOW_Y Returns the vertical pixel position of the current window.

Most of the above are very obvious, and so full documentation is postponed for now.

Additionally, the following are experimental.

  • GLUT_INIT_AUX_BUFFERS Returns the number of aux. buffers for new windows.

With the exception of GLUT_INIT_STATE and GLUT_ELAPSED_TIME, it is a fatal error to call this function without properly initializing OpenGLEAN via glutInit(). If the parameter to glutGet() is unknown, a return of -1 is given, but a -1 return value is not necessarily an error, as window positions may be negative.

Note:
GLUT_WINDOW_DEPTH_SIZE is reported one way on glX, using glXGetConfig(), and another way for WIN32 (using glGetIntegerv()). Probably we should unify these.

GLUT_WINDOW_DOUBLE_BUFFER can probably be unified to use glGetBoolean(), or even to check OpenGLEAN internal state.

See also:
glutSetOption(), glutDeviceGet(), glutGetModifiers(), glutLayerGet()
Todo:
Multisample support (GLUT_WINDOW_NUM_SAMPLES, here).

GLUT_WINDOW_BUFFER_SIZE should be implemented for WIN32.

Add GLUT_WINDOW_AUX_BUFFERS?

It looks like we could use an OPENGLEAN_REQUIRE_WINDOW() macro invocation in addition to OPENGLEAN_REQUIRE_READY().

GLUT_DISPLAY_MODE_POSSIBLE does not need us to run OPENGLEAN_REQUIRE_READY(), does it?

This function is a bit messy, especially the WINCE part. Fix.

Lots of code uses return to hop out. Since it's such a sprawling function, it's easy to be in the middle and not be 100% sure if there's anything important at the end of the function, or if it is safe to just "drop out" of the current case and head for the bottom.

Bug:
ogElapsedTime() returns a long, but glutGet() only is defined to return an int.

void glutSetOption (  GLenum  eWhat,
int  value
) 
 

Allows you to set some general state/option variables.

Parameters:
eWhat Enumerated parameter ID.
value New value.
Stores the value into a state variable named by eWhat.

Allowable eWhat IDs are:

  • GLUT_ACTION_ON_WINDOW_CLOSE (DEPRECATED) A replacement method based on a new window-close callback is expected. Controls what happens when a window is closed by the user or system. GLUT_ACTION_EXIT will immediately exit the application (default). GLUT_ACTION_GLUTMAINLOOP_RETURNS will immediately return from the main loop. GLUT_ACTION_CONTINUE_EXECUTION will contine execution of remaining windows.
  • GLUT_INIT_DISPLAY_MODE An alternate way to set the display mode of new windows.
  • GLUT_INIT_WINDOW_HEIGHT An alternate way to set the height of new windows.
  • GLUT_INIT_WINDOW_WIDTH An alternate way to set the width of new windows.
  • GLUT_INIT_WINDOW_X An alternate way to set the initial horizontal position of new windows.
  • GLUT_INIT_WINDOW_Y An alternate way to set the initial vertical position of new windows.
  • GLUT_RENDERING_CONTEXT Set to either GLUT_CREATE_NEW_CONTEXT or GUT_USE_CURRENT_CONTEXT to indicate whether to share the current OpenGL rendering context with new windows.
  • GLUT_WINDOW_CURSOR Attempt to set the current window's current cursor as if by glutSetCursor().

Additionally, the following are experimental.

  • GLUT_INIT_AUX_BUFFERS Sets the number of aux. buffers for new windows. (default is 0).

It is an error to call this function without having first called glutInit(). Because this would be a pretty basic logic problem, and there is presently no other way to report errors, the error is fatal.

Note:
GLUT_INIT_AUX_BUFFERS on offscreen windows is undefined. (I can't think of a good reason to go either way on this issue. On X11 systems with pbuffers, the code simply doesn't support aux. buffers for offscreen... I should probably allow it and see what is required to make it work with pbuffers (probably trivial).)
See also:
glutGet(), glutDeviceGet(), glutGetModifiers(), glutLayerGet(), glutDestroyWindow(), glutMainLoop(), glutInitDisplayMode(), glutInit(), glutInitWindowSize(), glutInitWindowPosition(), glutSetCursor()

Here is the call graph for this function:




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

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