Man

Command Section
vga_runinbackground(3)        Svgalib User Manual       vga_runinbackground(3)

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
       <[email protected]> & 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)()) and vga_runinbackground(VGA_COMEFROMBACK, void
       (*comefrom)()) with function pointers to functions void goto(void) and)()) 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 <[email protected]
       essen.de>. The function was implemented and documented by Pekka T.
       Alaruikka <[email protected]> & Michael Friman <no email>.

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