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