


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 cor-
       rects  most  of	VGAlib's textmode corruption behaviour by
       catching SIGSEGV, SIGFPE, SIGILL, and other fatal  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  man-
       age  console switching internally in svgalib.  You can not
       use them in your programs.

       This version includes code to hunt for a free virtual con-
       sole  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)).  Provided 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 con-
       sole from which it was started.	Otherwise 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 priviledge 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 Makefile.cfg allows
       you to disable allocating a new VC for root  (except  when



Svgalib 1.3.0		   8 April 1998				1





svgalib(7)	       Svgalib User Manual	       svgalib(7)


       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 (unchanged from VGAlib) and unoptimized;	 you  can
       however	use  vga_setpage(3) and vga_getgraphmem(3) (which
       points to the 64K VGA framebuffer) in a program or  graph-
       ics 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 view-
       ers. See the 7. References at the end of this document.

       I have added a simple VGA textmode font restoration  util-
       ity  (restorefont(1))  which  may  help if you suffer from
       XFree86 textmode font corruption. 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    configure	  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



Svgalib 1.3.0		   8 April 1998				2





svgalib(7)	       Svgalib User Manual	       svgalib(7)


       root privileges right after initialization, making setuid-
       root binaries relatively safe.

       The function vga_getdefaultmode(3) checks the  environment
       variable	 SVGALIB_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 graphics 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_setmode(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 signifi-
       cant effect only when you use the  static  libraries.  You
       should better use the shared libraries 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 recomended order of	interest:
       vgatest(6),  keytest(6), mousetest(6), eventtest(6), fork-
       test(6), bg_test(6), scrolltest(6), speedtest(6),  fun(6),
       spin(6), testlinear(6), testgl(6), accel(6), testaccel(6),
       planukit(6), and wrapdemo(6).

       Debugging your programs will turn out to be rather  diffi-
       cult,  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




Svgalib 1.3.0		   8 April 1998				3





svgalib(7)	       Svgalib User Manual	       svgalib(7)


       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 debug-
       ger 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 pro-
       gram will not make any screen accesses  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  it's 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.



Svgalib 1.3.0		   8 April 1998				4





svgalib(7)	       Svgalib User Manual	       svgalib(7)


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





Svgalib 1.3.0		   8 April 1998				5





svgalib(7)	       Svgalib User Manual	       svgalib(7)


   Basic (non raw) keyboard I/O
       vga_getch(3)
	      - wait for a key.
       vga_getkey(3)
	      -	 read a character from the keyboard without wait-
	      ing.
       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.



Svgalib 1.3.0		   8 April 1998				6





svgalib(7)	       Svgalib User Manual	       svgalib(7)


       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), key-
	      board_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),
	      joy- stick_x|y|z(3), joystick_getx|y|z(3)
	      - convenience macros to query  the  joystick  posi-
	      tion.

   Accelerator interface (new style)




Svgalib 1.3.0		   8 April 1998				7





svgalib(7)	       Svgalib User Manual	       svgalib(7)


       vga_accel(3)
	      - calls the graphics accelerator.

   Accelerator interface (old style)
       vga_bitblt(3)
	      - copy pixmap on screen using an accelerator.
       vga_fillblt(3)
	      - file rectangular area in video memory with a sin-
	      gle 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.






Svgalib 1.3.0		   8 April 1998				8





svgalib(7)	       Svgalib User Manual	       svgalib(7)


   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  stan-
       dard  text  modes.  It  is possible to enforce 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
       controllers as they  do	not  completely	 conform  to  the
       Mach32 data sheets.  Check out svgalib.mach32(7) (and lib-
       vga.config(5)).


   ATI Mach64
       THIS IS A NON-FUNCTIONAL DRIVER. USE AT OWN RISK.

       Support for 640x480x256@60hz is being worked on.	  At  the
       moment it is only supposed to work with a the ATI WinTurbo
       2MB VRAM VLB RAMDAC ATI68860.


   Chips and Technologies chipsets 65525,  65535,  65546,  65548,
       65550, and 65554 (usually in laptops).
       This  server was written using the SVGALIB patch from Ser-
       gio 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 unsupported, however these chips are very  simi-
       lar to the 6554x chips which are supported.



Svgalib 1.3.0		   8 April 1998				9





svgalib(7)	       Svgalib User Manual	       svgalib(7)


   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 functions 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
       <zivav@cs.bgu.ac.il>  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	pageflip-
       ping 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/RAMDACs,  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.  Support  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 Dacspeed 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.



Svgalib 1.3.0		   8 April 1998			       10





svgalib(7)	       Svgalib User Manual	       svgalib(7)


       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  (inter-
       laced  and non-interlaced) 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  com-
       posed of three bits:

	      bit2 = false, bit1 = false
		     force 8900.

	      bit2 = false, bit1 = true
		     force 9440.





Svgalib 1.3.0		   8 April 1998			       11





svgalib(7)	       Svgalib User Manual	       svgalib(7)


	      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  vgat-
       est  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
       default)).

       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 regis-
       ter is handled; dumped registers may use one of two timing
       methods, with the value written to the register for a par-
       ticular DAC for a hicolor mode (in vgahico.c)  being  cor-
       rect  for  just one of the these methods. As a consequence
       some dumped resolutions may work while others don't.


   Tseng ET6000
       At present the supported modes are:

       320x200x32K    640x480x256     640x480x32K     640x480x64K
       640x480x16M     800x600x256     800x600x32K    800x600x64K
       1024x768x256

       The ET6000 has a built in DAC and there is no problem com-
       ming  from  that	 area. The ET6000 is capable of accelera-
       tion, but this is not yet implemented in the driver.  Once
       acceleration is working, more modes will be developed.



Svgalib 1.3.0		   8 April 1998			       12





svgalib(7)	       Svgalib User Manual	       svgalib(7)


       The  driver  is written so that new modes may be developed
       using the optional /etc/vga/libvga.et6000 file  which  may
       be configured. This is discussed in svgalib.et6000(7).

       This driver was provided by Don Secrest.


   VESA
       This    driver	 was	provided    by	  Matan	   Ziv-Av
       <zivav@CS.bgu.ac.il> and is not too well tested. I'm  also
       not sure which kernels are required.

       The  ability  to	 call  16  bit	BIOS comes from a package
       called lrmi that Matan lost the URL for, but is	available
       from <http://www.arava.co.il/at3d/lrmi-0.1.tar.gz>

       This  package  includes a program called vbetest. On a STB
       Velocity 128, both vbetest and the  driver  work.   On  an
       AT25  card  and a CL-5446 card both vbetest and the driver
       don't work.

       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.  This  is  the
       Microsoft  way  to do things, hence expect Microsoft style
       operation.


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.

       There are still the following problems:

	      *	     Svga  320x200   modes   don't   work.   (but
		     320x200x8, vga works).



Svgalib 1.3.0		   8 April 1998			       13





svgalib(7)	       Svgalib User Manual	       svgalib(7)


	      *	     Pageflipping (in threeDKit) does not work.

	      *	     No	 acceleration  (is  there  a program that
		     uses it anyway?).

	      *	     Sometimes does  not  restore  textfont  when
		     going   back   to	textmode  (or  maybe  the
		     palette).

       Matan Ziv-Av <zivav@cs.bgu.ac.il>

   ATI Mach32
       Please see svgalib.mach32(7).


   ATI Mach64
       NOTE!
       Because of the problems	with  Mach64  it's  autodetection
       (though	working)  is  disabled.	 Please	 place a `chipset
       Mach64' at the end of  /etc/vga/libvga.config  to  enforce
       detection  of  a	 Mach64 when you have read all the Mach64
       docs and still wan't to try it.

       Mach64 Driver for SVGALIB. March 17/96

       Pre-alpha driver... could we get any worse than that? :)

       USE AT OWN RISK... DO NOT USE IN CONJUNCTION WITH  X  WIN-
       DOWS...	 DOES  NOT  WORK PROPERLY... MAY DAMAGE SYSTEM...
       NEED HELP IN MAKING IT WORK.

       Hi. I've working on this on and off since August with min-
       imal  progress.	I could really use some help... I seem to
       be stumped with my problems.

       At the moment this driver is only supposed to work with my
       board  since I did not include any general ramdac program-
       ming or memory checking.

       ATI WINTURBO 2MB VRAM w/ 18818 clock and ATI 68860 RAMDAC.
       Essentially  if	the  first  Mach64 XServer worked or your
       board is old then it may be ok.

       I've used both the ATI Mach64 SDK and the  XFree86  server
       to  try	and  write  this.   What  I  get now is a corrupt
       screen... Its's offset at every 64k page and it has  black
       vertical	 stripes  running  down it.  No there is no smoke
       from the monitor.

       Its 640x480 with a 25Mhz dot clock.   Actually  its  clock
       select 8 - which is the default setting of reserved.

       I  use the default clock setting of 8.  This works ok on a
       system that was cold booted and did not	do  any	 graphics



Svgalib 1.3.0		   8 April 1998			       14





svgalib(7)	       Svgalib User Manual	       svgalib(7)


       activity.  If there was graphics activity such as X.  Then
       the display will look shrunken.	The only reason I used 8,
       was  that  at  the time it produced a decent picture.  You
       may want to uncomment the lines in  the	crtc  programming
       that  set  the  clock  to  0x00|0x10 ... this is 50Mhz and
       divide by 2.

       I checked and messed with the dac and crtc programming  to
       no avail.

       The  way	 I  want  to  write the driver is as follows: The
       mach64 has an accelerator a vga/extended	 vga  controller.
       In  order  to  use  any of the fancy acclerated features I
       have to use the accelerator.  So I totally  disregard  the
       vga/extended vga, and put it into accelerator mode.  I use
       the accelerators CRTC, DAC, and CLOCK registers	to  setup
       the  display  mode.   It seems to work... but something is
       wrong somewhere causeing the  screen  to	 become	 corrupt.
       Note:  I did set some vga registers but they don't seem to
       do anything.  The only crucial  one  is	the  128k  memory
       block  setting.	 This  allows access to memory mapped gui
       registers.

       There are three ways to do bank switching:

       1.     Use the extended vga registers for 64k  page  flip-
	      ping.  This is only used in standard vga.

       2.     Use   the	 dual  32k  pages.   This is available in
	      standard vga and accelerator modes.

       3.     Linear aperature.


       For the time being I'm gonna use	 #2  and  eventually  #3.
       For  #2 you use the MEM_VGA_* registers.	 OF course when I
       set page 0 nothing appears...  flip it  to  255	something
       happens... argh.

       Saving/setting  registers...  I	didn't pay much attention
       here yet since I only touch a few vga registers.	  Running
       the  X  server  and this driver at this time may be lethal
       since I turn off the linear aperature that  the	X  server
       uses...	and  I	never  turn it back on.	 It only sets the
       registers necessary for a non-corrupt textmode.

       So essentially I need help in figuring out why my  display
       is  corrupt  and	 enlightenment	on  why when I switch the
       banks it writes to the same part of the screen.

       Asad Hanif
       w81h@unb.ca
       (Til June/96)




Svgalib 1.3.0		   8 April 1998			       15





svgalib(7)	       Svgalib User Manual	       svgalib(7)


       Michael Weller: Development of that driver seems	 to  have
       ceased. If you are interested, take over.


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

       I decided it was best to quit working on	 more  modes  and
       try to get acceleration working.

       My  et6000  card	 is on a PCI bus, about which I know very
       little. The card will run on a vesa bus, but since I don't
       have  one  on my machine I couldn't develope vesa bus han-
       dling. I got information on the PCI bus	by  reading  pro-
       grams  which  used the PCI bus in XFree86. It apears there
       are 2 PCI bus types. I test for type 1 and 2. Mine is type
       1, and I do not know how to read type 2. I quit if the PCI
       bus is type 2 or 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.

       Please see svgalib.et6000(7).

       Don Secrest <secrest@uiuc.edu> June 9, 1998



   Oak Technologies OTI-037/67/77/87
       First  a	 few  comments of me (Michael Weller <eowmob@exp-
       math.uni-essen.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



Svgalib 1.3.0		   8 April 1998			       16





svgalib(7)	       Svgalib User Manual	       svgalib(7)


       OTI-087	card  and can thus no longer give optimal support
       to this driver. Thus you might be better of contacting  me
       or  Frodo for questions. If you are a knowledgable 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  fea-
       tures:


       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  incorporates  a  completely different set of extended
       registers, I found it necessary 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	 monitor 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 anyway,  so
       there it sits.




Svgalib 1.3.0		   8 April 1998			       17





svgalib(7)	       Svgalib User Manual	       svgalib(7)


       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	buffer	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. set-
       ting 8-bit color as 4, wrong dot clock frequencies, 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 virtual	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 desirable it is to have this changed; direct port
       access can hardly be done without. Root privileges can now
       be  given  up  right  after initialization. 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 permissions 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 run-
       ning 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,  caus-
       ing 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  sus-
       pended  while not in the current virtual console. Would it
       be a good idea to let them run in the background, virtual-
       izing 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



Svgalib 1.3.0		   8 April 1998			       18





svgalib(7)	       Svgalib User Manual	       svgalib(7)


       (although just using a separate real-time viewing  program
       is much more elegant).

       Anyone  wanting	to rewrite it all in a cleaner way (some-
       thing with loadable kernel modules shouldn't hurt  perfor-
       mance  with linear framebuffer/vgagl type applications) is
       encouraged.

       Also, if anyone feels really strongly about a low-resource
       and truecolor supporting graphical window environment with
       cut-and-paste, I believe it would be  surprisingly  little
       work  to	 come  up  with	 a simple but very useful client-
       server system with shmem,  the  most  useful  applications
       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 sun-
       site.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  svgalib-1.2.12.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 secu-
       rity risk if setuid-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.



Svgalib 1.3.0		   8 April 1998			       19





svgalib(7)	       Svgalib User Manual	       svgalib(7)


   Viewers    (in    /pub/Linux/apps/graphics/viewers	on   sun-
       site.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 helpful.


   Miscellaneous
       There's	an  alternative RAW-mode keyboard library by Rus-
       sell 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  pre-
       fix  "HARTMUT:"). A more up-to-date port by Daniel Jackson
       (djackson@icomp.intel.com) is on sunsite.unc.edu.

       The vgalib ghostscript device driver sources can be  found
       on sunsite.unc.edu, /pub/Linux/apps/graphics.  Ghostscript
       patches from  Slackware:	 ftp.cdrom.com,	 /pub/linux/misc.
       gnuplot patches are on sunsite.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



Svgalib 1.3.0		   8 April 1998			       20





svgalib(7)	       Svgalib User Manual	       svgalib(7)


       sunsite.unc.edu.	 These functions may go into a later ver-
       sion 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,  especially 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 Cir-
       rus. 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	(restore-
       textmode)  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 distribution 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
       /etc/vga/libvga.et6000


SEE ALSO
       svgalib.et4000(7),  svgalib.et6000(7),	svgalib.chips(7),
       svgalib.mach32(7),   vgagl(7),	libvga.config(5),  3d(6),



Svgalib 1.3.0		   8 April 1998			       21





svgalib(7)	       Svgalib User Manual	       svgalib(7)


       accel(6), bg_test(6), eventtest(6),  forktest(6),  fun(6),
       keytest(6), mousetest(6), joytest(6), mjoytest(6), scroll-
       test(6), speedtest(6), spin(6),	testaccel(6),  testgl(6),
       testlinear(6), vgatest(6), planukit(6), wrapdemo(6), conv-
       font(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>	who  cur-
       rently maintains svgalib.  The original documentation  and
       most    of   svgalib   was   done   by	Harm   Hanemaayer
       <H.Hanemaayer@inter.nl.net> though.










































Svgalib 1.3.0		   8 April 1998			       22


