Provided by: libsvga1_1.4.3-31_amd64 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.