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

#include <vga.h>

void vga_runinbackground(int stat);

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.

vga_init();

vga_setmode(G320x200x256);

if (vga_runinbackground_version() == 1)

vga_runinbackground(1);

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();

Installation

Status of the background feature

Programming within svgalib

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)

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