NAME¶
set_display_switch_mode - Tells Allegro how the program handles background
switching.
SYNOPSIS¶
#include <allegro.h>
int set_display_switch_mode(int mode);
DESCRIPTION¶
Sets how the program should handle being switched into the background, if the
user tabs away from it. Not all of the possible modes will be supported by
every graphics driver on every platform. The available modes are:
SWITCH_NONE
Disables switching. This is the default in single-tasking systems like DOS. It
may be supported on other platforms, but you should use it with caution,
because your users won't be impressed if they want to switch away from your
program, but you don't let them!
SWITCH_PAUSE
Pauses the program whenever it is in the background. Execution will be resumed
as soon as the user switches back to it. This is the default in most
fullscreen multitasking environments, for example the Linux console, but not
under Windows.
SWITCH_AMNESIA
Like SWITCH_PAUSE, but this mode doesn't bother to remember the contents of
video memory, so the screen, and any video bitmaps that you have created, will
be erased after the user switches away and then back to your program. This is
not a terribly useful mode to have, but it is the default for the fullscreen
drivers under Windows because DirectDraw is too dumb to implement anything
better.
SWITCH_BACKGROUND
The program will carry on running in the background, with the screen bitmap
temporarily being pointed at a memory buffer for the fullscreen drivers. You
must take special care when using this mode, because bad things will happen if
the screen bitmap gets changed around when your program isn't expecting it
(see below).
SWITCH_BACKAMNESIA
Like SWITCH_BACKGROUND, but this mode doesn't bother to remember the contents of
video memory (see SWITCH_AMNESIA). It is again the only mode supported by the
fullscreen drivers under Windows that lets the program keep running in the
background.
Note that you should be very careful when you are using graphics routines in the
switching context: you must always call acquire_screen() before the start of
any drawing code onto the screen and not release it until you are completely
finished, because the automatic locking mechanism may not be good enough to
work when the program runs in the background or has just been raised in the
foreground.
RETURN VALUE¶
Returns zero on success, invalidating at the same time all callbacks previously
registered with set_display_switch_callback(). Returns -1 if the requested
mode is not currently possible.
SEE ALSO¶
set_display_switch_callback(3alleg4),
get_display_switch_mode(3alleg4),
exmidi(3alleg4),
exswitch(3alleg4)