Provided by: libsvga1-dev_1.4.3-31_i386 bug

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>.