NAME

       vga_runinbackground - enable running of the program while there is no VGA access

SYNOPSIS

       #include <vga.h>

       void vga_runinbackground(int stat);

DESCRIPTION

       Enable/disable background running of a graphics program.

       stat = 1
              enables

       stat = 0
              disables

       Normally,  the  program  is suspended while not in the current virtual console. A program can only safely
       run in the background if it doesn't do any video access during this time.

       As of version 1.2.11 this was changed by Pekka T. Alaruikka  <alaruik@cc.hut.fi>  &  Michael  Friman  <no
       email>  The support for this must be enabled in Makefile.cfg of svgalib (which it is by default). Several
       ways to  support  this  may  exist  internally.   As  of  now,  only  one  using  proc-fs  works.   Using
       vga_runinbackground(VGA_GOTOBACK,   void   (*goto)())   and   vga_runinbackground(VGA_COMEFROMBACK,  void
       (*comefrom)()) with function pointers to functions void goto(void) and void comefrom(void) you can  setup
       function  to  be  called  when your program goes to background mode and when it comes back to foreground.
       These can be changed at any time, and passing NULL as function disables the feature.

       Both these new features require a vga_runinbackground_version(3) of 1 or higher. You should check and not
       call it when the svgalib in use returns 0.  Also, when writing applications, check with

       #ifdef VGA_GOTOBACK
           /* code using vga_runinbackground(VGA_GOTOBACK, goto) */
       #else
           /* code using no goto or comefrom function */
       #endif

       if you are compiling with an svgalib that supports this feature, and try to rearrange your source to work
       without it when an svgalib version prior to 1.2.11 is used.

       The function should be called  right  after  vga_init(3).   The  bg_test(6)  demos  shows  the  principle
       operation.

       Please  note  that background capabilities are in VERY early stages. Please do not expect that EVERYTHING
       works flawlessly when background abilities are enabled in your program.

EXAMPLE

       vga_init();
       vga_setmode(G320x200x256);
       if (vga_runinbackground_version() == 1)
            vga_runinbackground(1);

NOTES

       Before a program is left background capable, it should be tested well. Most programs will work just well.

       When the program is in background, it can read IO-devices (except keyboard).  This can cause harm, if the
       programmer does not take this int account. I.e. in games using a joystick or/and mouse  device  the  game
       continues reading joystick or/and mouse as it would be on foreground.

       The  mouse  can  be  made  working  correctly  also  in  background,  but this means that svgalib must be
       configured to use gpm mouse driver.

       More information about gpm-linux can be founded from latest gpm packet (by Alessandro Rubini).

       The goto and comefrom routines provide a way to overcome this restriction.

       There are so far two different methods for background running. The first method use  mmap  function  with
       FIXED  option,  which  is  not  recommended  by mmap's man page.  It has some probability to fail. But it
       allows programs to think that graphics memory is always present.

       The second method is just let the functions to write directly graphics memory's save-buffer.  This  means
       that  the memory area where graphics information is changes for the program. The program must always know
       where to write. This type of action needs much more  work  and  leaves  probably  always  room  for  race
       conditions.

       Hopefully the first method proves to be good enough and second method can be left away.

       Neither  method  allows the use of the graphics card's registers in background.  When registers are used,
       vc switching is disabled, but the request are queued.  Vc switching is done as soon as possible.

       Generally, accelerated functions will probably cause problems, except when they are implemented carefully
       to check for availability of the cards registers.

       User programs should generally not use the graphics registers directly. But if program needs to  use  the
       registers,  it  has  to  check  if it is in background or not. In the background state it can not use the
       registers. For testing the vga_oktowrite(3) function can be used.  During  register  access  the  virtual
       console must be locked. A possible code fragment might look like:

       vga_lockvc();
       if (vga_oktowrite()) {
          /* Register operations. */
       } else {
          /* Registers can not be used. Alternative action. */
       }
       vga_unlockvc();

ADVANCED NOTES

   Installation
       Background  capability  is  enabled  in  svgalib  by  setting  BACKGROUND=y  and  disabled  by commenting
       #BACKGROUND=y in Makefile.cfg before compiling svgalib. Background capable svgalib is  more  stable  with
       all  programs.  Programs do not have to use background abilities even when they are available. As of this
       writing, all precompiled svgalib binaries are background capable by default.   NOTICE:  proc-fs  must  be
       mounted for background capability.

   Status of the background feature
       Background  capability  in svgalib is in an early stagei of development.  There has been done lot of work
       for it, but probably not everything will work perfectly. This applies only  to  programs  which  actually
       enabled background running with vga_runinbackground(3).

       The    vga_drawline(3),    vga_drawpixel(3),    vga_getclolors(3),   vga_getpixel(3),   vga_screenoff(3),
       vga_screenon(3), vga_setegacolor(3), vga_setrgbcolor(3), vga_setcolor(3), vga_setpage(3) and vga_clear(3)
       functions appear to work and calling vga_setmode(3)  is  safe  too  but  cannot  change  modes  while  in
       background. The remaining svgalib and vgagl function should work too but are not well tested.

       Calling accelerated functions will most probably cause harm though this is worked on.

       Please report problems to Pekka (see AUTHOR section).

   Programming within svgalib
       When  coding  within svgalib, there are same restrictions as in user programs.  SVGA registers can not be
       used while in background. The svgalibrary has  internal  functions  for  locking  and  unlocking  virtual
       console switching __svgalib_dont_switch_vt_yet() and __svgalib_is_vt_switching_needed().  These functions
       are  not  meant to be called from user program.  vga_unlockvc(3) can not release vc switching if internal
       svgalib locking is used. This is for safety.  The procedure for registers are similar  to  the  procedure
       for user programs:

       void vga_super_new_function(void) {
           __svgalib_dont_switch_vt_yet();
           if (vga_oktowrite()) {
               /* Register operations. */
           } else {
               /* Registers can not be used. Alternative action. */
           }
           __svgalib_is_vt_switching_needed();
       }

SEE ALSO

       svgalib(7),   vgagl(7),   libvga.config(5),  bg_test(6),  vga_accel(3),  vga_bitblt(3),  vga_blitwait(3),
       vga_fillblt(3),  vga_hlinelistblt(3),  vga_imageblt(3),  vga_init(3),  vga_lockvc(3),   vga_oktowrite(3),
       vga_runinbackground_version(3),        vga_safety_fork(3),       vga_setchipset(3),       vga_setpage(3),
       vga_setreadpage(3), vga_setwritepage(3), vga_unlockvc(3)

AUTHOR

       This  manual  page  was  edited  by  Michael  Weller  <eowmob@exp-math.uni-essen.de>.  The  function  was
       implemented and documented by Pekka T. Alaruikka <alaruik@cc.hut.fi> & Michael Friman <no email>.

Svgalib (>= 1.2.11)                               27 July 1997                            vga_runinbackground(3)