MGL_setSuspendAppCallback

Sets the fullscreen suspend application callback function.

Declaration

void MGLAPI MGL_setSuspendAppCallback(
MGL_suspend_cb_t saveState)
typedef int (MGLAPIP MGL_suspend_cb_t)(MGLDC *dc,int flags)

Prototype In

mgraph.h

Parameters

saveState | New suspend app callback to be used.

Description

This function is used to register an application suspend callback function. This is used in fullscreen modes under Windows and is called by MGL when the application's fullscreen window has lost the input focus and the system has returned to the normal GUI desktop. The focus can be lost due to the user hitting a System Key combination such as Alt-Tab or Ctrl-Esc which forces your fullscreen application into the background. The MGL takes care of all the important details such as saving and restoring the state of the hardware, so all your suspend application callback needs to do is save the current state of your program so that when the request is made to re-activate your application, you can redraw the screen and continue from where you left off.

When the MGL detects that your application has been suspended it will call the registered callback with a combination of the following flags:

Flag | Meaning
MGL_DEACTIVATE | This flag will be sent when your application has lost the input focus and has been suspended.
MGL_REACTIVATE | This flag will be sent when the user re-activates your fullscreen application again indicating that the fullscreen mode has now been restored and the application must redraw the display ready to continue on.

By default if you have not installed a suspend callback handler, the MGL will simply restore the display to the original state with the screen cleared to black when the application is re-activated. If your application is a game or animation that is continuously updating the screen, you won't need to do anything as the next frame in the animation will re-draw the screen correctly.

If your application is caching bitmaps in offscreen video memory however, all of the bitmaps will need to be restored to the offscreen display device context when the application is restored (the offscreen memory will be cleared to black also).

Note: By the time your callback is called, the display memory may have already been lost under DirectDraw. Hence you cannot save and restore the contents of the display memory, but must be prepared to redraw the entire display when the callback is called with the MGL_REACTIVATE flag set.

Copyright © 2002 SciTech Software, Inc. Visit our web site at http://www.scitechsoft.com