| Home
| Previous
| Next
| Up

GM_setModeExt

Switches to a fullscreen or windowed graphics mode

Declaration

ibool MGLAPI GM_setModeExt(
GM_modeInfo *info,
ibool windowed,
int pages,
int refreshRate,
ibool forceSysMem,
ibool stereo)

Prototype In

gm/gm.h

Parameters

info | Structure describing the mode to initialize
windowed | True if the mode should be in a window
pages | Number of pages for hardware buffering
refreshRate | Desired refresh rate for fullscreen display mode
forceSysMem | Flag to force a system memory buffer for all drawing
stereo | True to enable stereo rendering

Return Value

True on success, false on error

Description

This function sets a graphics mode for the game given the passed in mode information. If the windowed parameter is set to true, a windowed mode will be set otherwise a fullscreen graphics mode will be set. You must pass in one of the modes listed in the GMDC modeList returned from GM_init to this function. When the Game Framework switches to the windowed equivalent to a fullscreen graphics mode, we search for the closest 1:1 aspect ratio window size for the mode that corresponds to the fullscreen mode chosen. Hence for a 320x200 fullscreen mode we choose a 320x240 window size, for 320x400 and 320x480 we choose a 320x240 window size and for 640x350 and 640x400 we choose a 640x480 window size. This way we won't end up with a window on the desktop that is not a 1:1 aspect ratio and desktop modes are generally 1:1 aspect ratio.

The number of pages passed in is used to allocate the specified number of hardware video memory pages for multi-buffering and may be any value. The Game Framework will however lower this value to the maximum that the hardware supports, and if only 1 hardware page is available a system memory back buffer will be created automatically. Hence if you want to always try and use triple buffering if available, pass a value of 3 when you call this function.

The refresh rate parameter is used to select a desired refresh rate for the fullscreen display mode. If that refresh rate cannot be achieved due to hardware constraints, the next lowest available refresh rate will be used. If you wish to use the user default setting for the refresh rate (always a good idea unless you need refresh control, such as for stereo), simply pass in a value of MGL_DEFAULT_REFRESH.

The stereo flag is used to enable support for either software or hardware stereo modes in the MGL. This will fail if the underlying hardware device does not support stereo capabilities. Stereo can be used with OpenGL using Mesa, SGI OpenGL, SciTech DirectGL or Microsoft OpenGL (Microsoft OpenGL requires a stereo ready OpenGL driver to be installed).

Note also that the Game Framework automatically handles switching between windowed and fullscreen modes on the fly. By default the Game Framework contains code to provide two methods of switching to fullscreen modes when running in windowed modes:

1 | When the user hits the Alt-Enter key combination
2 | When the user clicks the Maximise button on the games title bar

Likewise when the game is running in a fullscreen mode and the user hits the Alt-Enter key, the video mode will automatically be switched to windowed mode. Unless you have registered a mode switch callback with GM_setModeSwitchFunc, on the fly switching between fullscreen and windowed modes is disabled.

Note: You may call this function while already in a windowed or fullscreen graphics mode, which will cause the current graphics mode to be changed on the fly.

Note: If you wish to force the Game Framework to always create a system memory buffer for rendering, regardless of how many display pages are available, set the forceSysMem field to true when calling this function. Note also that if you have requested multiple buffers, all those buffers will still be used so you will see no tearing, however all rendering will be performed to a system buffer which will be copied to the screen when you swap the buffers with GM_swapBuffers.

Drawing directly to a hardware linear framebuffer is usually extremely fast and will provide the most efficient method of rendering. However if your rendering requires reads from the framebuffer (for effects such as blending), this will be very slow over the PCI bus and your code will be faster if you force a system member back buffer.

Note: If the user dynamically switches the resolution or color depth of the windows desktop while your application is running, if you have registered a mode switch callback with the Game Framework (via GM_setModeSwitchFunc) then the Game Framework will switch to a new windowed mode to cause the memory back buffers to be re-allocated for the most optimal format for the Windows display mode.

See Also

GM_init, GM_setModeSwitchFunc

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