1vga_runinbackground(3) Svgalib User Manual vga_runinbackground(3)
2
6 vga_runinbackground - enable running of the program while there is no
7 VGA access
8
10 #include <vga.h>
11 void vga_runinbackground(int stat);
13
16 Enable/disable background running of a graphics program.
17 stat = 1
19 enables
20 stat = 0
22 disables
23 Normally, the program is suspended while not in the current virtual
25 console. A program can only safely run in the background if it doesn't
26 do any video access during this time.
27 As of version 1.2.11 this was changed by Pekka T. Alaruikka
29 <alaruik@cc.hut.fi> & Michael Friman <no email> The support for this
30 must be enabled in Makefile.cfg of svgalib (which it is by default).
31 Several ways to support this may exist internally. As of now, only one
32 using proc-fs works. Using vga_runinbackground(VGA_GOTOBACK, void
33 (*goto)()) and vga_runinbackground(VGA_COMEFROMBACK, void (*come‐
34 from)()) with function pointers to functions void goto(void) and void
35 comefrom(void) you can setup function to be called when your program
36 goes to background mode and when it comes back to foreground. These can
37 be changed at any time, and passing NULL as function disables the fea‐
38 ture.
39 Both these new features require a vga_runinbackground_version(3) of 1
41 or higher. You should check and not call it when the svgalib in use
42 returns 0. Also, when writing applications, check with
43 #ifdef VGA_GOTOBACK
45 /* code using vga_runinbackground(VGA_GOTOBACK, goto) */
46 #else
47 /* code using no goto or comefrom function */
48 #endif
49 if you are compiling with an svgalib that supports this feature, and
51 try to rearrange your source to work without it when an svgalib version
52 prior to 1.2.11 is used.
53 The function should be called right after vga_init(3). The bg_test(6)
55 demos shows the principle operation.
56 Please note that background capabilities are in VERY early stages.
58 Please do not expect that EVERYTHING works flawlessly when background
59 abilities are enabled in your program.
60
63 vga_init();
64 vga_setmode(G320x200x256);
65 if (vga_runinbackground_version() == 1)
66 vga_runinbackground(1);
67
70 Before a program is left background capable, it should be tested well.
71 Most programs will work just well.
72 When the program is in background, it can read IO-devices (except key‐
74 board). This can cause harm, if the programmer does not take this int
75 account. I.e. in games using a joystick or/and mouse device the game
76 continues reading joystick or/and mouse as it would be on foreground.
77 The mouse can be made working correctly also in background, but this
79 means that svgalib must be configured to use gpm mouse driver.
80 More information about gpm-linux can be founded from latest gpm packet
82 (by Alessandro Rubini).
83 The goto and comefrom routines provide a way to overcome this restric‐
85 tion.
86 There are so far two different methods for background running. The
88 first method use mmap function with FIXED option, which is not recom‐
89 mended by mmap's man page. It has some probability to fail. But it
90 allows programs to think that graphics memory is always present.
91 The second method is just let the functions to write directly graphics
93 memory's save-buffer. This means that the memory area where graphics
94 information is changes for the program. The program must always know
95 where to write. This type of action needs much more work and leaves
96 probably always room for race conditions.
97 Hopefully the first method proves to be good enough and second method
99 can be left away.
100 Neither method allows the use of the graphics card's registers in back‐
102 ground. When registers are used, vc switching is disabled, but the
103 request are queued. Vc switching is done as soon as possible.
104 Generally, accelerated functions will probably cause problems, except
106 when they are implemented carefully to check for availability of the
107 cards registers.
108 User programs should generally not use the graphics registers directly.
110 But if program needs to use the registers, it has to check if it is in
111 background or not. In the background state it can not use the regis‐
112 ters. For testing the vga_oktowrite(3) function can be used. During
113 register access the virtual console must be locked. A possible code
114 fragment might look like:
115 vga_lockvc();
117 if (vga_oktowrite()) {
118 /* Register operations. */
119 } else {
120 /* Registers can not be used. Alternative action. */
121 }
122 vga_unlockvc();
123
126 Installation
127 Background capability is enabled in svgalib by setting BACKGROUND=y and
128 disabled by commenting #BACKGROUND=y in Makefile.cfg before compiling
129 svgalib. Background capable svgalib is more stable with all programs.
130 Programs do not have to use background abilities even when they are
131 available. As of this writing, all precompiled svgalib binaries are
132 background capable by default. NOTICE: proc-fs must be mounted for
133 background capability.
134 Status of the background feature
137 Background capability in svgalib is in an early stagei of development.
138 There has been done lot of work for it, but probably not everything
139 will work perfectly. This applies only to programs which actually
140 enabled background running with vga_runinbackground(3).
141 The vga_drawline(3), vga_drawpixel(3), vga_getclolors(3), vga_get‐
143 pixel(3), vga_screenoff(3), vga_screenon(3), vga_setegacolor(3),
144 vga_setrgbcolor(3), vga_setcolor(3), vga_setpage(3) and vga_clear(3)
145 functions appear to work and calling vga_setmode(3) is safe too but
146 cannot change modes while in background. The remaining svgalib and
147 vgagl function should work too but are not well tested.
148 Calling accelerated functions will most probably cause harm though this
150 is worked on.
151 Please report problems to Pekka (see AUTHOR section).
153 Programming within svgalib
156 When coding within svgalib, there are same restrictions as in user pro‐
157 grams. SVGA registers can not be used while in background. The svgali‐
158 brary has internal functions for locking and unlocking virtual console
159 switching __svgalib_dont_switch_vt_yet() and __svgalib_is_vt_switch‐
160 ing_needed(). These functions are not meant to be called from user
161 program. vga_unlockvc(3) can not release vc switching if internal
162 svgalib locking is used. This is for safety. The procedure for regis‐
163 ters are similar to the procedure for user programs:
164 void vga_super_new_function(void) {
166 __svgalib_dont_switch_vt_yet();
167 if (vga_oktowrite()) {
168 /* Register operations. */
169 } else {
170 /* Registers can not be used. Alternative action. */
171 }
172 __svgalib_is_vt_switching_needed();
173 }
174
177 svgalib(7), vgagl(7), libvga.config(5), bg_test(6), vga_accel(3),
178 vga_bitblt(3), vga_blitwait(3), vga_fillblt(3), vga_hlinelistblt(3),
179 vga_imageblt(3), vga_init(3), vga_lockvc(3), vga_oktowrite(3), vga_run‐
180 inbackground_version(3), vga_safety_fork(3), vga_setchipset(3),
181 vga_setpage(3), vga_setreadpage(3), vga_setwritepage(3),
182 vga_unlockvc(3)
183
186 This manual page was edited by Michael Weller <eowmob@exp-math.uni-
187 essen.de>. The function was implemented and documented by Pekka T.
188 Alaruikka <alaruik@cc.hut.fi> & Michael Friman <no email>.
189Svgalib (>= 1.2.11) 27 July 1997 vga_runinbackground(3)