Provided by: libsvga1_1.4.3-31_i386 bug

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
       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  manage  console
       switching  internally  in  svgalib.   You  can  not  use  them  in your
       programs. 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)).
       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 console 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 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
       Makefile.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
       (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  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
       (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  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 significant 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  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
       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 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
       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 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
       unsupported, 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
       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 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/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.

       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-
       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  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
       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  register  is
       handled;  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
       option 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
       BACKGROUND enabled, and vga_runinbackground works.

       I decided it was best to quit working on more  modes  and  try  to  get
       acceleration 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
       handling.  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
       DOUBLESCAN
       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-
       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
       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
       questions. 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
       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.

       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.   setting   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 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
       loadable  kernel  modules  shouldn't  hurt  performance   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 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
       svgalib-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
       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.

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

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

SEE ALSO

       svgalib.et4000(7),   svgalib.chips(7),   svgalib.mach32(7),   vgagl(7),
       libvga.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),   testlinear(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.