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

FreeBSD Manual Pages

  
 
  

home | help
svgalib(7)		      Svgalib User Manual		    svgalib(7)

NAME
       svgalib - a low level graphics library for linux

TABLE OF CONTENTS
       0. Introduction
       1. Installation
       2. How to use svgalib
       3. Description of svgalib functions
       4. Overview of supported	SVGA chipsets and modes
       5. Detailed comments on certain device drivers
       6. Goals
       7. References (location of latest version, apps etc.)
       8. Known	bugs

0. INTRODUCTION
       This  is	 a  low	 level graphics	library	for Linux, originally based on
       VGAlib 1.2 by Tommy Frandsen. VGAlib supported a	number of standard VGA
       graphics	 modes,	 as  well  as  Tseng  ET4000 high resolution 256-color
       modes. As of now, support for many more chipsets	has  been  added.  See
       section 4 Overview of supported SVGA chipsets and modes

       It  supports  transparent  virtual  console switching, that is, you can
       switch consoles to and from  text  and  graphics	 mode  consoles	 using
       alt-[function  key].  Also,  svgalib corrects most of VGAlib's textmode
       corruption behaviour by catching	SIGSEGV, SIGFPE, SIGILL, and other fa-
       tal  signals  and  ensuring  that a program is running in the currently
       visible virtual console before setting a	graphics mode.

       Note right here that SIGUSR1 and	SIGUSR2	are  used  to  manage  console
       switching  internally  in  svgalib.   You can not use them in your pro-
       grams. If your program needs to use one of those	signals,  svgalib  can
       be compiled to use other	signals, by editing libvga.h

       This  version  includes	code to	hunt for a free	virtual	console	on its
       own in case you are not starting	the program from one (but instead over
       a  network or modem login, from within screen(1)	or an xterm(1)).  Pro-
       vided there is a	free console, this succeeds if you are root or if  the
       svgalib	calling	 user own the current console. This is to avoid	people
       not using the console being able	to fiddle with it.  On	graceful  exit
       the  program  returns to	the console from which it was started.	Other-
       wise it remains in text mode at the VC which svgalib allocated to allow
       you  to	see any	error messages.	In any case, any I/O the svgalib makes
       in text mode (after calling vga_init(3))	will also take place  at  this
       new console.

       Alas,  some games misuse	their suid root	privilege and run as full root
       process.	svgalib	cannot detect this and allows Joe Blow User to open  a
       new  VC	on  the	console. If this annoys	you, ROOT_VC_SHORTCUT in Make-
       file.cfg	allows you to disable allocating a new	VC  for	 root  (except
       when he owns the	current	console) when you compile svgalib. This	is the
       default.

       When the	library	is used	by a program at	run-time, first	the chipset is
       detected	and the	appropriate driver is used. This means that a graphics
       program will work on any	card that is supported by svgalib, if the mode
       it  uses	 is supported by the chipset driver for	that card. The library
       is upwardly compatible with VGAlib.

       The set of drawing functions provided by	svgalib	itself is limited (un-
       changed	from  VGAlib)  and  unoptimized;  you can however use vga_set-
       page(3) and vga_getgraphmem(3) (which points  to	 the  64K  VGA	frame-
       buffer)	in a program or	graphics library.  A fast external framebuffer
       graphics	library	for linear and banked 1, 2, 3 and 4  bytes  per	 pixel
       modes is	included (it also indirectly supports planar VGA modes). It is
       documented in vgagl(7).

       One obvious application of the library is a picture viewer. Several are
       available,  along  with animation viewers. See the 7. References	at the
       end of this document.

       I have added a simple VGA textmode font restoration  utility  (restore-
       font(1))	 which	may help if you	suffer from XFree86 textmode font cor-
       ruption.	It can also be used to change the textmode font. It comes with
       some other textmode utilities: restoretextmode(1) (which	saves/restores
       textmode	registers), restorepalette(1), and the script textmode(1).  If
       you  run	 the  savetextmode(1)  script  to save textmode	information to
       /tmp, you'll be able to restore textmode	 by  running  the  textmode(1)
       script.

1. INSTALLATION
       Installation  is	 easy in general but there are many options and	things
       you should keep in mind.	This document however assumes that svgalib  is
       already installed.

       If  you need information	on installation	see 0-INSTALL which comes with
       the svgalib distribution.

       However,	even after installation	of the library you might need to  con-
       figure svgalib using the	file /etc/vga/libvga.config.  Checkout section
       4 Overview of supported SVGA chipsets and  modes	 and  libvga.config(5)
       for information.

2. HOW TO USE SVGALIB
       For  basic  svgalib  usage  (no	mouse,	no  raw	keyboard) add #include
       <vga.h> at the beginning	your program.  Use vga_init(3) as  your	 first
       svgalib call. This will give up root privileges right after initializa-
       tion, making setuid-root	binaries relatively safe.

       The function vga_getdefaultmode(3) checks the environment variable  SV-
       GALIB_DEFAULT_MODE  for	a  default mode, and returns the corresponding
       mode number. The	environment string can either be a mode	 number	 or  a
       mode  name as in	(G640x480x2, G640x480x16, G640x480x256 , G640x480x32K,
       G640x480x64K, G640x480x16M).  As	an example, to set the default	graph-
       ics mode	to 640x480, 256	colors,	use:

       export SVGALIB_DEFAULT_MODE=G640x480x256

       on  the bash(1) command line. If	a program needs	just a linear VGA/SVGA
       resolution (as required by vgagl(7)), only modes	where bytesperpixel in
       the vga_modeinfo	structure returned by vga_getmodeinfo(3) is greater or
       equal to	1 should be accepted (this is 0	for tweaked  planar  256-color
       VGA modes).

       Use  vga_setmode(graphicsmode)  to  set	a  graphics mode. Use vga_set-
       mode(TEXT) to restore textmode before program exit.

       Programs	that use svgalib must #include<vga.h>; if they	also  use  the
       external	 graphics  library  vgagl(7), you must also #include<vgagl.h>.
       Linking must be done with -lvga (and -lvgagl before -lvga, if  vgagl(7)
       is  used).  You	can  save  binary space	by removing the	unused chipset
       drivers in Makefile.cfg if you only use specific	chipsets. However this
       reduces	the  flexibility  of svgalib and has a significant effect only
       when you	use the	static libraries. You should better use	the shared li-
       braries and these will load only	the really used	parts anyway.

       Functions  in  the  vgagl(7)  library  have the prefix gl_.  Please see
       vgagl(7)	for details.

       There are demos with sources available which will also help to get  you
       started,	 in  recommended  order	 of  interest: vgatest(6), keytest(6),
       mousetest(6),  eventtest(6),  forktest(6),  bg_test(6),	scrolltest(6),
       speedtest(6),  fun(6),  spin(6),	 testlinear(6),	lineart(6), testgl(6),
       accel(6), testaccel(6), plane(6), and wrapdemo(6).

       Debugging your programs will turn out to	be rather  difficult,  because
       the svgalib application can not restore textmode	when it	returns	to the
       debugger.

       Happy are the users with	a serial terminal, X-station, or  another  way
       to log into the machine from network. These can use

       textmode	</dev/ttyN

       on the console where the	program	runs and continue.

       However,	 the  vga_flip(3) function allows you to switch	to textmode by
       entering	a call to it blindly into  your	 debugger  when	 your  program
       stops  in  graphics  mode.   vga_flip(3)	is not very robust though. You
       shall not call it when svgalib is not yet initialized or	in textmode.

       Before continuing your program, you must	then call vga_flip(3) again to
       return  to  graphics  mode. If the program will not make	any screen ac-
       cesses or svgalib calls before it returns to the	debugger, you can omit
       that, of	course.

       This  will  only	 work if your program and the debugger run in the same
       virtual linux console.

3. DESCRIPTION OF SVGALIB FUNCTIONS
       Each function has its own section 3 manual page.	For a  list  of	 vgagl
       functions see vgagl(7).

   Initialization
       vga_init(3)
	      -	initialize svgalib library.
       vga_disabledriverreport(3)
	      -	makes svgalib not emit any startup messages.
       vga_claimvideomemory(3)
	      -	declare	the amount of video memory used.
       vga_safety_fork(3)
	      -	start a	parallel process to restore the	console	at a crash.
       vga_setchipset(3)
	      -	force chipset.
       vga_setchipsetandfeatures(3)
	      -	force chipset and optional parameters.

   Inquire hardware configuration
       vga_getmousetype(3)
	      -	returns	the mouse type configured.
       vga_getcurrentchipset(3)
	      -	returns	the current SVGA chipset.
       vga_getmonitortype(3)
	      -	returns	the monitor type configured.

   Setting video modes
       vga_setmode(3)
	      -	sets a video mode.
       vga_setdisplaystart(3)
	      -	set the	display	start address.
       vga_setlogicalwidth(3)
	      -	set the	logical	scanline width.
       vga_setlinearaddressing(3)
	      -	switch to linear addressing mode.
       vga_setmodeX(3)
	      -	try to set Mode	X-like memory organization .
       vga_ext_set(3)
	      -	set and	query several extended features.
       vga_screenoff(3), vga_screenon(3)
	      -	turn generation	of the video signal on or off.

   Get video mode information
       vga_getxdim(3), vga_getydim(3), vga_getcolors(3)
	      -	return the current screen resolution.
       vga_white(3)
	      -	return the color white in the current screen resolution.
       vga_getcurrentmode(3)
	      -	returns	the current video mode.
       vga_hasmode(3)
	      -	returns	if a video mode	is supported.
       vga_getmodeinfo(3)
	      -	returns	pointer	to mode	information structure for a mode.
       vga_getdefaultmode(3)
	      -	returns	the default graphics mode number.
       vga_lastmodenumber(3)
	      -	returns	the last video mode number.
       vga_getmodename(3)
	      -	return a name for the given video mode.
       vga_getmodenumber(3)
	      -	return a number	for the	given video mode.

   Drawing primitives
       vga_clear(3)
	      -	clear the screen.
       vga_setcolor(3)
	      -	set the	current	color.
       vga_setrgbcolor(3)
	      -	set the	current	color.
       vga_setegacolor(3)
	      -	set the	current	color.
       vga_drawpixel(3)
	      -	draw a pixel on	the screen.
       vga_drawscanline(3)
	      -	draw a horizontal line of pixels.
       vga_drawscansegment(3)
	      -	draw a horizontal line of pixels.
       vga_drawline(3)
	      -	draw a line on the screen.
       vga_getpixel(3)
	      -	get a pixels value from	the screen.
       vga_getscansegment(3)
	      -	get a list of consecutive pixel	values.
       vga_waitretrace(3)
	      -	wait for vertical retrace.

   Basic (non raw) keyboard I/O
       vga_getch(3)
	      -	wait for a key.
       vga_getkey(3)
	      -	read a character from the keyboard without waiting.
       vga_waitevent(3)
	      -	wait for various I/O events.

   Direct VGA memory access
       vga_setpage(3)
	      -	set the	64K SVGA page number.
       vga_setreadpage(3)
	      -	set the	64K SVGA page number.
       vga_setwritepage(3)
	      -	set the	64K SVGA page number.
       vga_getgraphmem(3)
	      -	returns	the address of the VGA memory.
       vga_copytoplanar256(3)
	      -	copy linear pixmap into	Mode X video memory.
       vga_copytoplanar16(3)
	      -	copy linear pixmap into	VGA 16 color mode video	memory.
       vga_copytoplane(3)
	      -	 copy  linear pixmap to	some planes of VGA 16 color mode video
	      memory.

   Manage color	lookup tables
       vga_setpalette(3)
	      -	set a color in the color lookup	table.
       vga_getpalette(3)
	      -	get a color in the color lookup	table.
       vga_setpalvec(3)
	      -	sets colors in the color lookup	table.
       vga_getpalvec(3)
	      -	gets colors from the color lookup table.

   Mouse handling
       vga_setmousesupport(3)
	      -	enable mouse support.
       mouse_init(3), mouse_init_return_fd(3)
	      -	specifically initialize	a mouse.
       mouse_close(3)
	      -	explicitly close a mouse.
       mouse_update(3)
	      -	updates	the mouse state.
       mouse_waitforupdate(3)
	      -	wait for an mouse update.
       mouse_setscale(3)
	      -	sets a mouse scale factor.
       mouse_setwrap(3)
	      -	set what happens at the	mouse boundaries.
       mouse_setxrange(3), mouse_setyrange(3)
	      -	define the boundaries for the mouse cursor.
       mouse_getx(3), mouse_gety(3), mouse_getbutton(3)
	      -	query the mouse	state.
       mouse_setposition(3)
	      -	set the	current	mouse position.
       mouse_getposition_6d(3),	mouse_setposition_6d(3), mouse_setrange_6d(3)
	      -	provide	an interface to	3d mice.
       mouse_seteventhandler(3), mouse_setdefaulteventhandler(3)
	      -	set a mouse event handler.

   Raw keyboard	handling
       keyboard_init(3), keyboard_init_return_fd(3)
	      -	initialize the keyboard	to raw mode.
       keyboard_close(3)
	      -	return the keyboard to normal operation	from raw mode.
       keyboard_update(3), keyboard_waitforupdate(3)
	      -	process	raw keyboard events.
       keyboard_translatekeys(3)
	      -	modify scancode	mappings in raw	keyboard mode.
       keyboard_keypressed(3)
	      -	check if a key is pressed when in raw keyboard mode.
       keyboard_getstate(3)
	      -	get a pointer to a buffer holding the state of all keys	in raw
	      keyboard mode.
       keyboard_clearstate(3)
	      -	reset the state	of all keys when in raw	keyboard mode.
       keyboard_seteventhandler(3), keyboard_setdefaulteventhandler(3)
	      -	define an event	handler	for keyboard events in raw mode.

   Joystick handling
       joystick_init(3)
	      -	initialize and calibrate joysticks.
       joystick_close(3)
	      -	close a	joystick device.
       joystick_update(3)
	      -	query and process joystick state changes.
       joystick_sethandler(3), joystick_setdefaulthandler(3)
	      -	define own joystick even handler.
       joystick_getnumaxes(3), joystick_getnumbuttons(3)
	      -	query the capabilities of a joystick.
       joystick_getaxis(3), joystick_getbutton(3)
	      -	query the state	of a joystick.
       joystick_button1|2|3|4(3),  joystick_getb1|2|3|4(3), joystick_x|y|z(3),
       joystick_getx|y|z(3)
	      -	convenience macros to query the	joystick position.

   Accelerator interface (new style)
       vga_accel(3)
	      -	calls the graphics accelerator.

   Accelerator interface (old style)
       vga_bitblt(3)
	      -	copy pixmap on screen using an accelerator.
       vga_fillblt(3)
	      -	fill rectangular area in video memory with a single color.
       vga_hlinelistblt(3)
	      -	draw horizontal	scan lines.
       vga_imageblt(3)
	      -	copy a rectangular pixmap from system memory to	video memory.
       vga_blitwait(3)
	      -	wait for any accelerator operation to finish.

   Controlling VC switches
       vga_lockvc(3)
	      -	disables virtual console switching for safety.
       vga_unlockvc(3)
	      -	re-enables virtual console switching.
       vga_oktowrite(3)
	      -	indicates whether the program has direct access	to the SVGA.
       vga_runinbackground(3)
	      -	enable running of the program while there is no	VGA access.
       vga_runinbackground_version(3)
	      -	returns	the version of the current background support.

   Debugging aids
       vga_dumpregs(3)
	      -	dump the contents of the SVGA registers.
       vga_gettextfont(3), vga_puttextfont(3)
	      -	get/set	the font used in text mode.
       vga_gettextmoderegs(3), vga_settextmoderegs(3)
	      -	get/set	the vga	state used in text mode.
       vga_flip(3)
	      -	toggle between text and	graphics mode.
       vga_setflipchar(3)
	      -	set the	character causing a vga_flip().

4. OVERVIEW OF SUPPORTED SVGA CHIPSETS AND MODES
   VGA and compatibles
       320x200x256, and	the series of 16-color	and  non-standard  planar  256
       color modes supported by	VGAlib,	as well	as 720x348x2.

   ALI2301
       Supports	640x480x256, 800x600x256, 1024x768x256 SVGA modes

   AT3D	(AT25)
       Also  known  as Promotion at25. Popular as the 2D part of a voodoo rush
       card. As	of this	writing	there are  a  few  known  problems  with  this
       driver. Read below.

   ARK Logic ARK1000PV/2000PV
       Full  support,  limited RAMDAC support. Only ARK1000PV tested. Supports
       Clocks and Ramdac lines in config file.

   ATI SVGA (VGA Wonder	and friends)
       This is no real driver. I do not	support	any  new  modes.   However  it
       saves  additional card setup and	thus allows use	of the plain VGA modes
       even when you are using non standard text modes.	It is possible to  en-
       force use of this driver	even on	ATI Mach32 but not very	useful.

   ATI Mach32
       The  driver  by	Michael	Weller supports	all ATI	BIOS-defined modes and
       more... It hits the best	out of your card.  Some	 modes	may  not  have
       nice  default timings but it uses the ATI's EEPROM for custom config or
       allows to specify modes in libvga.config(5).  Some problems  may	 occur
       with  quite some	third party cards (usually on board) Mach32 based con-
       trollers	as they	do not completely conform to the Mach32	 data  sheets.
       Check out svgalib.mach32(7) (and	libvga.config(5)).

   ATI Mach64 (rage)
       A driver	for ATi	Mach64 based cards with	internal DAC.

   Chips  and  Technologies  chipsets  65525,  65535, 65546, 65548, 65550, and
       65554 (usually in laptops).
       This server was written using the SVGALIB patch from Sergio and	Angelo
       Masci as	a starting point. This version of the code resembled the XFree
       server code that	was used up to XFree 3.1.2. As such it	was  incapable
       of  programming	the  clocks,  using linear addressing, Hi-Color, True-
       Color modes or the hardware acceleration. All of	 these	features  have
       since  been  added  to  the code.  The 64200 and	64300 chips are	unsup-
       ported, however these chips are very similar to the 6554x  chips	 which
       are supported.

   Cirrus Logic	GD542x/3x
       All  the	 modes,	including 256 color, 32K/64K color, 16M	color (3 bytes
       per pixel) and 32-bit pixel 16M color modes (5434). Some	 bitblt	 func-
       tions are supported.  The driver	doesn't	work with mode dumps, but uses
       a SVGA abstraction with mode timings like the X drivers.

   Genoa(?) GVGA6400 cards.
       Supported.

   Hercules Stingray 64/Video
       Is supported as an ARK2000PV

   NV3 driver for the Riva128.
       This driver was written by Matan	Ziv-Av and is derived from the XFree86
       driver by David J. Mckay. It lacks 24bit	modes (can the card do them at
       all?), acceleration support and pageflipping in threeDKit is broken.

   Oak Technologies OTI-037/67/77/87
       Driver by Christopher Wiles; includes 32K color modes for OTI-087.

   S3
       The driver is not complete, but should work on a	number	of  cards/RAM-
       DACs, and 640x480x256 should work on most card. The best	support	is for
       a 801/805 with AT&T20C490-compatible RAMDAC, and	S3-864	+  SDAC.   All
       256/32K/64K/16M	works  for  them  (within the bounds of	video memory &
       ramdac restrictions).

       The supported cards include S3 Virge and	S3 Trio64 cards.

       None of the acceleration	function is supported yet.

       The chip	level code should work with the	964/868/968, but  most	likely
       the card	they come on would use an unsupported ramdac/clock chip.  Sup-
       port for	these chips is slowly being added.

       Clocks and Ramdac lines in libvga.config(5) supported.

       The maximum pixel clock (in MHz)	of the ramdac can be set using a  Dac-
       speed  line  in the config file.	A reasonable default is	assumed	if the
       Dacspeed	line is	omitted.  Clocks should	be the	same  as  in  XFree86.
       Supported  ramdac  IDs:	Sierra32K,  SC15025,  SDAC, GenDAC, ATT20C490,
       ATT20C498, IBMRGB52x.

       Example:
       Clocks 25.175 28.3 40 70	50 75 36 44.9 0	118 77 31.5 110	65 72 93.5
       Ramdac att20c490
       DacSpeed	85

       Also supported, at least	in combination with the	SC15025/26A ramdac, is
       the  ICD	2061A clock chip.  Since it cannot be autodetected you need to
       define it in the	config file using a Clockchip line. As there is	no way
       to  read	 the  current settings out of the 2061,	you have the option to
       specify the frequency used when switching back to text mode  as	second
       argument	in the Clockchip line.

       This  is	 especially  required if your text mode	is an 132 column mode,
       since these modes use a clock from the  clock  chip,  while  80	column
       modes use a fixed clock of 25 MHz.  The text mode frequency defaults to
       40 MHz, if omitted.

       Example:
       ClockChip icd2061a 40.0

   Trident TVGA	8900C/9000 (and	possibly also 8800CS/8900A/B)  and  also  TVGA
       9440
       Derived	from  tvgalib  by  Toomas  Losin.  TVGA	 9440  support	by ARK
       <ark@lhq.com, root@ark.dyn.ml.or>.

       Supports	640x480x256, 800x600x256, 1024x768x256 (interlaced and non-in-
       terlaced)  Might	 be  useful  to	add 16-color modes (for	those equipped
       with a 512K TVGA9000) for the 8900 and 9000 cards.

       320x200x{32K, 64K, 16M},	640x480x{256, 32K,  64K,  16M},	 800x600x{256,
       32K,  64K,  16M}, 1024x768x{16, 256}, 800x600x{16, 256, 32K, 64K} modes
       are supported for the TVGA 9440.

       Autodetection can be forced with	a:

	      chipset TVGA memory flags

       line in the config file.

       memory is the amount of VGA memory in KB, flags is  composed  of	 three
       bits:

	      bit2 = false, bit1 = false
		     force 8900.

	      bit2 = false, bit1 = true
		     force 9440.

	      bit2 = true, bit1	= false
		     force 9680.

	      bit0 = true
		     force noninterlaced.

	      bit0 = false
		     force  interlaced	which  only  matters on	8900's with at
		     least 1M since there is no	512K interlaced	 mode  on  the
		     8900 or any of the	other cards.

   Tseng ET4000/ET4000W32(i/p)
       Derived	from  VGAlib;  not  the	same register values.  ET4000 register
       values are not compatible; see svgalib.et4000(7).

       Make sure the colors are	right in hicolor  mode;	 the  vgatest  program
       should draw the same color bars for 256 and hicolor modes (the DAC type
       is defined at compilation  in  et4000.regs  or  the  dynamic  registers
       file).	ET4000/W32  based cards	usually	have an	AT&T or	Sierra 15025/6
       DAC. With recent	W32p based cards, you might have some  luck  with  the
       AT&T  DAC  type.	  If the high resolution modes don't work, you can try
       dumping the registers in	DOS using the program in the et4000/ directory
       and putting them	in a file (/etc/vga/libvga.et4000 is parsed at runtime
       if DYNAMIC is defined in	 Makefile.cfg  at  compilation	(this  is  de-
       fault)).

       Supported    modes    are   640x480x256,	  800x600x256,	 1024x768x256,
       640x480x32K, 800x600x32K, 640x480x16M, etc.

       Reports of ET4000/W32i/p	functionality are welcome.

       There may be a problem with the way the hicolor DAC  register  is  han-
       dled;  dumped  registers	 may  use  one of two timing methods, with the
       value written to	the register for a particular DAC for a	 hicolor  mode
       (in  vgahico.c)	being  correct for just	one of the these methods. As a
       consequence some	dumped resolutions may work while others don't.

   Tseng ET6000
       Most modes of which the card is capable are supported.  The 8 15	16  24
       and 32 bit modes	are supported.

       The  ET6000 has a built in DAC and there	is no problem coming from that
       area. The ET6000	is capable  of	acceleration,  but  this  as  well  as
       sprites are not yet implemented in the driver.

       The  driver now uses modelines in libvga.config for user	defined	modes.
       It is sometimes useful to add a modeline	for a  resolution  which  does
       not display well.  For example, the G400x600 is too far to the right of
       the screen using	standard modes.	 This is  corrected  by	 including  in
       libvga.config the line

       Modeline	"400x600@72"  25.000 400  440  488  520	  600  639  644	 666

       More examples are given below.

       This driver was provided	by Don Secrest.

   VESA
       Please  read  README.vesa  and  README.lrmi  in doc subdirectory	of the
       standard	distribution.

       Go figure! I turned off autodetection in	the release, as	a broken  bios
       will  be	 called	 too, maybe crashing the machine. Enforce VESA mode by
       putting a chipset VESA in the end of your libvga.config(5).

       Note that it will leave protected mode and call the cards bios  opening
       the door	to many	hazards.

5. DETAILED COMMENTS ON	CERTAIN	DEVICE DRIVERS
       This  section  contains	detailed information by	the authors on certain
       chipsets.

   AT3D	(AT25)
       Also known as Promotion at25. Popular as	the 2D part of a  voodoo  rush
       card.

       I  have written a driver	for this chipset, based	on the XF86 driver for
       this chipset.

       The programs that work with this	driver include all the programs	in the
       demos directory,	zgv and	dvisvga	(tmview).

       I believe it should be easy to make it work on AT24, AT6422.

   ATI Mach32
       Please see svgalib.mach32(7).

   ATI Mach64
       The  rage.c  driver works only on mach64	based cards with internal DAC.
       The driver might	misdetect the base frequency the card uses, so if when
       setting	any svgalib modes the screen blanks, or	complains about	out of
       bound frequencies, or the display is unsynced, then try adding the  op-
       tion RageDoubleClock to the config file.

   Chips  and  Technologies  chipsets  65525,  65535, 65546, 65548, 65550, and
       65554 (usually in laptops).
       Please see svgalib.chips(7).

   Tseng ET4000/ET4000W32(i/p)
       Please see svgalib.et4000(7).

   Tseng ET6000
       I have only 2 Mbytes of memory on my ET6000 card, so I am not  able  to
       get  all	 possible modes	running. I haven't even	tried to do all	of the
       modes which I am	capable	of doing, but I	am confident that I can	manage
       more  modes  when  I have time. I have enough modes working to make the
       card useful, so I felt it was worth while to add	the driver to  svgalib
       now.

       Linear  graphics	 is  working on	this card, both	with and without BACK-
       GROUND enabled, and vga_runinbackground works.

       I decided it was	best to	quit working on	more modes and try to get  ac-
       celeration and sprites working.

       My  et6000  card	is on a	PCI bus.  The card will	run on a vesa bus, but
       since I don't have one on my machine I couldn't develop vesa  bus  han-
       dling.  I quit if the bus is a vesa bus.

       I  check	for an et6000 card, which can be unequivocally identified. The
       et4000 driver does not properly identify	et4000 cards.  It  thinks  the
       et6000 card is an et4000, but can only run it in	vga modes.

       I have found the	following four modelines to be useful in libvga.config
       or in ~/.svgalibrc for proper display of	some modes.

       Modeline	"512x384@79" 25.175 512	560 592	640  384 428 436 494
       Modeline	"400x300@72" 25.000 400	456 472	520  300 319 332 350  DOUBLES-
       CAN
       Modeline	"512x480@71" 25.175 512	584 600	656  480 500 510 550
       Modeline	"400x600@72" 25.000 400	440 488	520  600 639 644 666

       Don Secrest <secrest@uiuc.edu> Aug 21, 1999

   Oak Technologies OTI-037/67/77/87
       First  a	 few  comments	of me (Michael Weller <eowmob@exp-math.uni-es-
       sen.de>):

       As of this writing (1.2.8) fixes	were made to the oak driver  by	 Frodo
       Looijaard  <frodol@dds.nl>  to  reenable	OTI-067	support. It is unknown
       right now if they might have broken OTI-087 support. The	author of  the
       '87  support  Christopher  Wiles	 <wileyc@moscow.com> owns no longer an
       OTI-087 card and	can thus  no  longer  give  optimal  support  to  this
       driver.	Thus  you might	be better off contacting me or Frodo for ques-
       tions. If you are a knowledgeable OTI-087 user and experience  problems
       you  are	 welcome  to provide fixes.  No	user of	a OTI-087 is currently
       known to	me, so if you are able to fix problems with the	driver	please
       do so (and contact me) as noone else can.

       Michael.

       Now back	to the original	Oak information:

       The original OTI	driver,	which supported	the OTI-067/77 at 640x480x256,
       has been	augmented with the following features:

       1)     Supported	resolutions/colors have	been expanded to  640x480x32K,
	      800x600x256/32K, 1024x768x256, and 1280x1024x16.

       2)     The  OTI-087  (all  variants) is now supported.  Video memory is
	      correctly	recognized.

       The driver as it	exists now is somewhat schizoid.  As the '87  incorpo-
       rates a completely different set	of extended registers, I found it nec-
       essary to split its routines from the others.  Further, I did not  have
       access  to  either  a '67 or a '77 for testing the new resolutions.  If
       using them causes your monitor/video card to fry, your dog to bite you,
       and so forth, I warned you.  The	driver works on	my '87,	and that's all
       I guarantee.  Period.

       Heh.  Now, if someone wants to try them out ... let  me	know  if  they
       work.

       New from	last release:

       32K  modes  now	work for 640x480 and 800x600.  I found that the	Sierra
       DAC information in VGADOC3.ZIP is, well,	wrong.	But, then  again,  the
       information for the '87 was wrong also.

       64K  modes  do  not  work.   I can't even get Oak's BIOS	to enter those
       modes.

       I have included a 1280x1024x16 mode, but	I haven't tested it.  My moni-
       tor can't handle	that resolution.  According to the documentation, with
       2 megs the '87 should be	able to	do  an	interlaced  1280x1024x256  ...
       again,  I  couldn't get the BIOS	to do the mode.	 I haven't 2 megs any-
       way, so there it	sits.

       I have included routines	for entering and leaving  linear  mode.	  They
       should work, but	they don't.  It	looks like a pointer to	the frame buf-
       fer is not being	passed to SVGALIB.  I've been fighting with  this  one
       for  a month.  If anyone	wants to play with this, let me	know if	it can
       be make to work.	 I've got exams	that I need to pass.

       Tidbit: I pulled	the extended register info  out	 of  the  video	 BIOS.
       When  the  information  thus  obtained  failed  to work,	I procured the
       OTI-087 data book.  It appears that Oak's video BIOS sets various modes
       incorrectly  (e.g.  setting  8-bit color	as 4, wrong dot	clock frequen-
       cies, etc.).  Sort of makes me wonder ...

       Christopher M. Wiles (a0017097@wsuaix.csc.wsu.edu)
       12 September 1994

6. GOALS
       I think the ability to use a VGA/SVGA graphics resolution in  one  vir-
       tual   console,	and  being able	to switch to any other virtual console
       and back	makes a	fairly useful implementation of	graphics modes in  the
       Linux console.

       Programs	 that use svgalib must be setuid root. I don't know how	desir-
       able it is to have this changed;	direct port access can hardly be  done
       without.	 Root  privileges  can now be given up right after initializa-
       tion. I noticed some unimplemented stuff	in  the	 kernel	 header	 files
       that  may  be  useful,  although	 doing all register I/O	via the	kernel
       would incur a significant context-switching  overhead.  An  alternative
       might be	to have	a pseudo /dev/vga device that yields the required per-
       missions	when opened, the device	being readable by  programs  in	 group
       vga.

       It  is important	that textmode is restored properly and reliably; it is
       fairly reliable at the moment, but  fast	 console  switching  back  and
       forth  between  two  consoles running graphics can give problems.  Wild
       virtual console switching also sometimes	corrupts the contents  of  the
       textmode	screen buffer (not the textmode	registers or font).  Also if a
       program crashes it may write into the area  where  the  saved  textmode
       registers  are  stored,	causing	textmode not be	restored correctly. It
       would be	a good idea to somehow store this information in a 'safe' area
       (say  a	kernel buffer).	Note that the vga_safety_fork(3) thing has the
       same idea.

       Currently, programs that	are in graphics	mode are suspended  while  not
       in the current virtual console. Would it	be a good idea to let them run
       in the background, virtualizing framebuffer actions (this should	not be
       too  hard for linear banked SVGA	modes)?	It would be nice to have, say,
       a raytracer with	a real-time display run	in  the	 background  (although
       just using a separate real-time viewing program is much more elegant).

       Anyone wanting to rewrite it all	in a cleaner way (something with load-
       able kernel modules  shouldn't  hurt  performance  with	linear	frame-
       buffer/vgagl type applications) is encouraged.

       Also,  if  anyone  feels	really strongly	about a	low-resource and true-
       color supporting	graphical window environment with cut-and-paste, I be-
       lieve it	would be surprisingly little work to come up with a simple but
       very useful client-server system	with shmem, the	most  useful  applica-
       tions  being  fairly  trivial  to  write	 (e.g.	shell window,	bitmap
       viewer).	    And	many X apps would port trivially.

       This is old information,	please be sure to read svgalib.faq(7)  if  you
       are interested in further goals.

7. REFERENCES
       The  latest  version  of	 svgalib  can  be  found on sunsite.unc.edu in
       /pub/Linux/libs/graphics	or tsx-11.mit.edu  in  /pub/linux/sources/libs
       as  svgalib-X.X.X.tar.gz.  As of	this writing the latest	version	is sv-
       galib-1.4.1.tar.gz.  There are countless	mirrors	of these  ftp  servers
       in the world. Certainly a server	close to you will carry	it.

       The	 original	VGAlib	     is	      on       tsx-11.mit.edu,
       pub/linux/sources/libs/vgalib12.tar.Z.	tvgalib-1.0.tar.Z  is  in  the
       same directory.

       SLS  has	 long  been  distributing an old version of VGAlib.  Slackware
       keeps a fairly up-to-date version of svgalib, but it may	 be  installed
       in  different directories from what svgalib likes to do by default. The
       current svgalib install tries to	remove most of this. It	 also  removes
       /usr/bin/setmclk	and /usr/bin/convfont, which is	a security risk	if se-
       tuid-root. Actually the recent makefiles	try to do a really good	job to
       cleanup the mess	which some distributions make.

       If  you	want  to recompile the a.out shared library, you will need the
       DLL 'tools' package (found on tsx-11.mit.edu, GCC  dir).	  To  make  it
       work with recent	ELF compiler's you actually need to hand patch it. You
       should probably not try to compile it. Compiling	 the  ELF  library  is
       deadly simple.

       And  here  is  a	 list  of other	references which is horribly outdated.
       There are many more svgalib applications	as  well  as  the  directories
       might  have  changed.   However,	 these will give you a start point and
       names to	hunt for on CD's or in ftp archives.

   Viewers (in /pub/Linux/apps/graphics/viewers	on sunsite.unc.edu):
       spic   Picture viewer; JPG/PPM/GIF; truecolor; scrolling.
       zgv    Full-featured viewer with	nice file selector.
       see-jpeg
	      Shows picture as it is being built up.
       mpeg-linux
	      svgalib port of the Berkeley MPEG	decoder	(mpeg_play);  it  also
	      includes an X binary.
       flip   FLI/FLC player (supports SVGA-resolution).

   Games (in /pub/Linux/games on sunsite.unc.edu):
       bdash  B*lderdash clone with sound.
       sasteroids
	      Very smooth arcade asteroids game.
       yatzy  Neat mouse controlled dice game.
       vga_cardgames
	      Collection of graphical card games.
       vga_gamespack
	      Connect4,	othello	and mines.
       wt     Free state-of-the-art Doom-like engine.
       Maelstrom
	      A	very nice asteroids style game port from Mac.
       Koules A	game. (I've no idea what it looks like)

   Docs
       In the vga directory of the SIMTEL MSDOS	collection, there is a package
       called vgadoc3 which is a collection of VGA/SVGA	register information.

       The XFree86 driver sources distributed with the link-kit	may  be	 help-
       ful.

   Miscellaneous
       There's	an  alternative	RAW-mode keyboard library by Russell Marks for
       use with	svgalib	on sunsite.unc.edu.

       LIBGRX, the extensive framebuffer library by  Csaba  Biegl  distributed
       with  DJGPP,  has  been	ported	to  Linux.  Contact  Hartmut  Schirmer
       (phc27@rz.uni-kiel.d400.de, subject prefix "HARTMUT:"). A  more	up-to-
       date  port  by  Daniel  Jackson	(djackson@icomp.intel.com)  is on sun-
       site.unc.edu.

       The vgalib ghostscript device driver  sources  can  be  found  on  sun-
       site.unc.edu,   /pub/Linux/apps/graphics.    Ghostscript	 patches  from
       Slackware: ftp.cdrom.com, /pub/linux/misc.  gnuplot patches are on sun-
       site.unc.edu.

       Mitch  D'Souza  has  written font functions that	work in	16 color modes
       and can use VGA textmode	(codepage format) fonts; these can be found in
       his  g3fax  package  in sunsite.unc.edu.	 These functions may go	into a
       later version of	svgalib.

8. KNOWN BUGS
       This section is most probably outdated, none of these problems  are  no
       longer reported.

       Using a 132 column textmode may cause graphics modes to fail. Try using
       something like 80x28.

       The console switching doesn't preserve some registers that may be  used
       to draw in planar VGA modes.

       Wild console switching can cause	the text screen	to be corrupted, espe-
       cially when switching between two graphics consoles.

       On ET4000, having run XFree86 may cause high resolution modes  to  fail
       (this is	more XFree86's fault).

       The  Trident  probing  routine in the XFree86 server may	cause standard
       VGA modes to fail after exiting X on a Cirrus. Try putting a  'Chipset'
       line in your Xconfig to avoid the Trident probe,	or use the link	kit to
       build a server without the Trident driver.  Saving  and	restoring  the
       textmode	 registers with	savetextmode/textmode (restoretextmode)	should
       also work. [Note: svgalib now resets the	particular extended  register,
       but  only  if the Cirrus	driver is used (i.e. the chipset is not	forced
       to VGA)]	[This is fixed in XFree86 v2.1]

       Some Paradise VGA cards may not work even in standard  VGA  modes.  Can
       anyone confirm this?

       Piping  data into a graphics program has	problems. I am not sure	why. A
       pity, since zcatting a 5Mb FLC file into	flip on	a 4Mb machine would be
       fun.

       The  tseng3.exe	DOS program include as source in the svgalib distribu-
       tion doesn't recognize any modes	on some	 ET4000	 cards.	  Also	ET4000
       cards  with  a  Acumos/Cirrus  DAC may only work	correctly in 64K color
       mode.

FILES
       /etc/vga/libvga.config
       /etc/vga/libvga.et4000

SEE ALSO
       svgalib.et4000(7), svgalib.chips(7), svgalib.mach32(7), vgagl(7),  lib-
       vga.config(5),  3d(6), accel(6),	bg_test(6), eventtest(6), forktest(6),
       fun(6), keytest(6), lineart(5), mousetest(6), joytest(6),  mjoytest(6),
       scrolltest(6), speedtest(6), spin(6), testaccel(6), testgl(6), testlin-
       ear(6), vgatest(6),  plane(6),  wrapdemo(6),  convfont(1),  dumpreg(1),
       fix132x43(1),  restorefont(1),  restorepalette(1),  restoretextmode(1),
       runx(1),	savetextmode(1), setmclk(1), textmode(1), mach32info(1).

AUTHOR
       There are many authors of svgalib. This	page  was  edited  by  Michael
       Weller  <eowmob@exp-math.uni-essen.de>.	The original documentation and
       most of svgalib was done	by Harm	Hanemaayer <H.Hanemaayer@inter.nl.net>
       though.

Svgalib	1.4.1		       16 December 1999			    svgalib(7)

NAME | TABLE OF CONTENTS | 0. INTRODUCTION | 1. INSTALLATION | 2. HOW TO USE SVGALIB | 3. DESCRIPTION OF SVGALIB FUNCTIONS | 4. OVERVIEW OF SUPPORTED SVGA CHIPSETS AND MODES | 5. DETAILED COMMENTS ON CERTAIN DEVICE DRIVERS | 6. GOALS | 7. REFERENCES | 8. KNOWN BUGS | FILES | SEE ALSO | AUTHOR

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

home | help