Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
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
       <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  (*come-
       from)())	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 fea-
       ture.

       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 re-
       turns 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  key-
       board).	 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 restric-
       tion.

       There are so far	two different  methods	for  background	 running.  The
       first  method  use mmap function	with FIXED option, which is not	recom-
       mended by mmap's	man page.  It has some probability to fail. But	it al-
       lows 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 back-
       ground.	When registers are used, vc switching is disabled, but the re-
       quest 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	regis-
       ters.  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 en-
       abled background	running	with vga_runinbackground(3).

       The  vga_drawline(3),  vga_drawpixel(3),	 vga_getclolors(3),   vga_get-
       pixel(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 pro-
       grams.  SVGA registers can not be used while in background. The svgali-
       brary has internal functions for	locking	and unlocking virtual  console
       switching  __svgalib_dont_switch_vt_yet()  and  __svgalib_is_vt_switch-
       ing_needed().  These functions are not meant to	be  called  from  user
       program.	  vga_unlockvc(3) can not release vc switching if internal sv-
       galib 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_run-
       inbackground_version(3),	    vga_safety_fork(3),	    vga_setchipset(3),
       vga_setpage(3),	  vga_setreadpage(3),	vga_setwritepage(3),   vga_un-
       lockvc(3)

AUTHOR
       This manual page	was edited by Michael Weller  <eowmob@exp-math.uni-es-
       sen.de>.	 The  function	was  implemented  and  documented  by Pekka T.
       Alaruikka <alaruik@cc.hut.fi> & Michael Friman <no email>.

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

NAME | SYNOPSIS | DESCRIPTION | EXAMPLE | NOTES | ADVANCED NOTES | SEE ALSO | AUTHOR

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=vga_runinbackground&sektion=3&manpath=FreeBSD+13.0-RELEASE+and+Ports>

home | help