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),
       exsample(3alleg4), exstream(3alleg4), exswitch(3alleg4)

Allegro                                           version 4.4.3                 set_display_switch_mode(3alleg4)