set_display_switch_mode(3)      Allegro manual      set_display_switch_mode(3)



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(3), get_display_switch_mode(3), exmidi(3),
       exswitch(3)



Allegro                          version 4.2.3      set_display_switch_mode(3)
