Main Loop
[OpenGLEAN API Reference]

Collaboration diagram for Main Loop:

OpenGLEAN Initialisation and Main Loop

OpenGLEAN's event model is based on callbacks (see the callbacks module). This is inherited from old GLUT in design, and from freeglut and OpenGLUT in implementation. The model works simply by letting you tell OpenGLEAN which function of yours to call when certain events happen. Certain events, such as the redisplay event for updating your window graphics, can be postponed and coalesced so that one redisplay may occur in response to multiple hints to OpenGLEAN that you require a a redisplay. Some events are manufactured by OpenGLEAN, such as timers. Others may be caused by your own request, such as redisplays. Still others may only be caused by external stimulus. More...

Functions
void	glutInit (int *pargc, char **argv)
void	glutLeaveMainLoop (void)
void	glutMainLoop (void)
void	glutMainLoopEvent (void)

---

Detailed Description

OpenGLEAN Initialisation and Main Loop

OpenGLEAN's event model is based on callbacks (see the callbacks module). This is inherited from old GLUT in design, and from freeglut and OpenGLUT in implementation. The model works simply by letting you tell OpenGLEAN which function of yours to call when certain events happen. Certain events, such as the redisplay event for updating your window graphics, can be postponed and coalesced so that one redisplay may occur in response to multiple hints to OpenGLEAN that you require a a redisplay. Some events are manufactured by OpenGLEAN, such as timers. Others may be caused by your own request, such as redisplays. Still others may only be caused by external stimulus.

You have two ways to enter OpenGLEAN's event processing model. One is via glutMainLoop(), and the other is via glutMainLoopEvent().

When OpenGLEAN has dispatched all pending events, it will do one of three things:

• Sleep. This is the default. It allows OpenGLEAN to conserve your computer's resources, freeing up the CPU for other tasks or even allowing your OS to slow the CPU down when usage falls off.
• Call your "idle" function (see glutIdleFunc()). This allows you to specify some activity to be performed when your application is doing nothing else. If you register an idle function and call glutMainLoop(), your program will never rest.
• Exit the event processing. This happens if you either called glutMainLoopEvent() instead of glutMainLoop() (glutMainLoopEvent() resolves all pending events, then returns to you), or if certain specific events occur, such as glutLeaveMainLoop().

Old GLUT did not offer glutMainLoopEvent() nor glutLeaveMainLoop(), and would only exit glutMainLoop() if the user closed one of your windows or if you called exit(). In no case would old GLUT return control to your code by simply returning from glutMainLoop().

freeglut added some mechanisms to control this. One is an explicit glutLeaveMainLoop(). Another is a mode of execution that tells OpenGLEAN what to do if a user closes one of your windows.

OpenGLUT inherited freeglut's variations.

OpenGLEAN inherited that from OpenGLUT.

---

---

Function Documentation

void glutInit (  int *  pargc, char **  argv )

Initialize OpenGLEAN data structures. Parameters: pargc  Pointer to something like main()'s argc. argv  Something like main()'s argv. This function should be called once, near the start of any OpenGLEAN client. It serves two vital roles: It allows OpenGLEAN to initialize internal structures. It allows OpenGLEAN to process command-line arguments to control the initial window position, etc. You should take note of the interaction between glutInit() and the related functions such as glutInitWindowPosition(). OpenGLEAN always uses the most recent configuration information, so if you call glutInit(), then glutInitWindowPosition(), you prevent the user from controlling the initial window position via a command-line parameter. glutInit() will remove from pargc, argv any parameters that it recognizes in the command line. The following command-line parameters are suported: -display display-id This allows connection to an alternate X server. -geometry geometry-spec This takes width, height, and window position. The position is given as a signed value (negative values being distance from the far boundary of the screen). For example, a window geometry of 5x7+11-17 is 5 pixels wide, 7 pixels tall, 11 pixels from the left, and 17 pixels from the bottom edge of the screen. -direct Insist on only OpenGL direct rendering. Direct rendering is normally requested but indirect is normally accepted. -direct is not always available. If both direct and indirect are specified on the command line, the tail-most one determines OpenGLEAN's behavior. See -indirect, -maybe-indirect. -indirect Attempt only indirect OpenGL rendering. -indirect is always available. See -direct, -maybe-indirect. -maybe-indirect Restore the default OpenGLEAN behavior of trying direct rendering first, then falling back to indirect rendering. See -direct, -indirect. -iconic Open the window in iconized form. -gldebug Print any detected OpenGL errors via glutReportErrors(). Presently done at the bottom of glutMainLoopEvent(). -no-warnings Disable the showing of OpenGLEAN warnings (e.g., on standard error consoles). -warnings Show OpenGLEAN warning messages (e.g., on standard error consoles). This is the default. -no-informs Disable showing OpenGLEAN informational messages (e.g., on standard error consoles). This is the default. -informs Show OpenGLEAN informational messages (e.g., on standard error consoles). -sync Synchronize the window system communications a little more heavily. Additionally, this function checks whether the environment variable GLUT_FPS is defined; if so, OpenGLEAN will periodically print the average number of times per second that your program calls glutSwapBuffers(). (If GLUT_FPS appears to represent a number, OpenGLEAN will take it to be the number of milliseconds that you want to pass between each output.) The idea of GLUT_FPS is measure your frame rate, but it is of limited value if you have more than one window. Note: You may be able to get away without calling glutInit() in some cases, but you should rarely if ever need to do so. glutInit() provides essential, standard controls to the end-user and should not be lightly discarded. This is also where OpenGLEAN retrieves your program's name to help tag error and warning messages it may be forced to emit. Lots of code does XFlush() on the X server, regardless of whether -sync is specified. Much of that appears to be required in order to support direct client invocation of glutMainLoopEvent(), regrettably. However, if one calls glutMainLoop(), instead, we might avoid gratuitous XFlush() calls. (That last sentence isn't particularly germain to this function, but there's no better place to make this remark at this time.) Even for glutMainLoopEvent(), we may be able to coalesce many XFlush() calls. See also: glutInitWindowPosition(), glutInitWindowSize(), glutInitDisplayMode(), glutInitDisplayString(), glutCreateWindow(), glutDisplayFunc(), glutMainLoop(), glutMainLoopEvent(), glutReportErrors(), glutSwapBuffers() Todo: Should -sync cause a window system sync at the top of the event loop (or at the open/close of the glutMainEventLoop())?

void glutLeaveMainLoop (  void   )

Breaks out of OpenGLEAN's glutMainLoop() This function allows you to unilaterally tell OpenGLEAN that you are done and wish to exit. This is useful if you have also told OpenGLEAN to return to you rather than to call exit() directly. See also: glutMainLoop(), exit() Todo: Could use longjmp(); see oghTakeActionOnWindowClose(). This would let us terminate the entire loop immediately.

void glutMainLoop (  void   )

The standard GLUT event loop entry point. This is the main driving force for an event-driven OpenGLEAN program. It alternates between calling glutMainLoopEvent() to process pending events and then either sleeping or calling your idle function (see glutIdleFunc()). This function can return, but GLUT's version of this function never returned. And you must do special things to OpenGLEAN to cause OpenGLEAN's version to return. The cross-reference section for this function's documentation should ideally contain every callback, but the list would be tediously long and prone to omissions. It is a fatal error to call this function without properly initializing OpenGLEAN via glutInit(). Note: For OpenGLEAN developers' internal documentation: Runs until the ExecState changes to GLUT_EXEC_STATE_STOP. See also: glutMainLoopEvent(), glutLeaveMainLoop(), glutIdleFunc() Bug: Talking to other message systems (e.g., network layers) can be a bit bothersome under the GLUT event model. Here is the call graph for this function:

void glutMainLoopEvent (  void   )

Dispatches all pending events. The general outline of this function is to first drain the queue of windowsystem events, in most cases dispatching each as it is found. After the queue is empty, we check for timer-based events, coalesced window events (e.g., redisplays), and windows that need to be closed. The cross-reference section for this function's documentation should ideally contain every callback, but the list would be tediously long and prone to omissions. It is a fatal error to call this function without properly initializing OpenGLEAN via glutInit(). Note: Does not necessarily dispatch events that are received after this function starts processing. At first glance, this function may not seem to afford any new capability that you couldn't get with an idle callback or glutLeaveMainLoop(). However there are other GLUT-like libraries that may have their own window event processing loops. Having glutMainLoopEvent() allows you to ask OpenGLEAN to do its work in a batch, then return to whatever processing the other library (or libraries) require. See also: glutIdleFunc(), glutLeaveMainLoop(), glutMainLoop() Here is the call graph for this function:

Supported in part by SourceForge.net.

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