svgalib v1.12 0. Introduction 1. Installation 2. Overview of supported SVGA chipsets and modes 3. Description of svgalib functions additional to VGAlib v1.2 4. How to use svgalib 5. Structure of chipset driver modules 6. Changes (see file CHANGES) 7. Known bugs 8. Goals 9. References (location of latest version, apps etc.) 0. Introduction This is a low level graphics library for Linux, 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. I added support for my Cirrus 542x based card, including 15/16/24 bit color modes, and merged in the Trident code from Toomas Losin's tvgalib. It also provides ET4000 hicolor/truecolor DAC support. There's also an alpha ATI mach32 driver by Michael Weller. 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 and SIGILL, and ensuring that a program is running in the currently visible virtual console before setting a graphics mode. When the library is first used by a program at run-time, 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 and graph_mem (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). There's a README in the gl/ directory. One obvious application of the library is a picture viewer. Several are available, along with animation viewers. See the references at the end of this document. I have added a simple VGA textmode font restoration utility (restorefont) which may help if you suffer from XFree86 textmode font corruption. It can also be used to change the textmode font. It's in the utils/ directory, along with a README and some other textmode utilities: restoretextmode (which saves/restores textmode registers), restorepalette, and the script textmode. If you run the savetextmode script to save textmode information to /tmp, you'll be able to restore textmode by running the textmode script. If you have an ET4000 card, you should read the README in the et4000/ directory. You will probably want to replace the ET4000 registers. Directories: demos/ Demo and test programs. utils/ Textmode/font utilities. src/ Main library source. src/mouse/ Source for mouse interface. src/keyboard/ Source for keyboard interface. gl/ External framebuffer graphics library sources, and docs. support/ DOS-based utility for dumping VGA registers. et4000/ Notes, utilities and sample registers for ET4000. mach32/ Notes and a utility for the ATI mach32 driver. jump/ Configuration files for building DLL shared library. sharedlib/ Shared library image and stubs. I welcome any questions, comments, suggestions, bug-reports, etc. There's also a Linux-Activists mailing list (see the current Linux FAQ for instructions). Much of the source code is detrimental to your health, don't look at it. Only if you are adequately prepared. Do write amazing multi-player networked 3D lightsource-shaded real-time VGA virtual reality simulations. Harm Hanemaayer hhanemaa@cs.ruu.nl 1. Installation Running 'make install' as root should take care of proper installation. Shared library stubs and images are included in the distribution. Edit the Makefile to change installation paths and to select the parts that should be installed, and edit libvga.config to set the monitor and mouse type. If things go wrong, make sure that you have properly installed a recent libc (i.e. deleted /usr/lib/libgcc.(s)a), and that ld.so is up to date. If you have an ET4000 card, read the et4000/README and copy the appropriate register file to et4000.regs. Remember to set the DAC type. The default behaviour is the following: Shared libraries are installed in /lib and /usr/local/lib, header files in /usr/local/include (any old header files in /usr/include are removed). In the Slackware distribution the linkable libraries are in /usr/lib, and the utilities in /usr/bin; these are now removed by make install. Until now just doing make install with Slackware may have produced duplicate binaries, but fortunately the newer version in usr/local/* would have taken precedence in use. The et4000 registers (et4000.regs) are installed as /usr/local/lib/libvga.et4000, but only if this file does not exit yet. The same goes for the configuration file, libvga.config. Textmode utilities are installed in /usr/local/bin. These are restorefont, runx, restorepalette, dumpreg, restoretextmode, textmode, savetextmode, and fix132x43. If you change the Makefile to install the static libraries, static libraries are compiled, and installed in /usr/local/include. Note that you do not need to do this; the shared library is enough. If you now run 'make', the demo programs are created in the demos/ directory. You can remove previously installed files (not the et4000 registers and config file) with 'make uninstall'. Note that if you change and recompile the (static) library and install it (you can use 'make installstaticlib installheaders' for this), programs may still get linked to the (old) shared library version. Try temporarily removing the stubs in /usr/local/lib, or specifying libvga.a on the commandline instead of -lvga. 2. Overview of supported SVGA chipsets and modes Supported chipsets: VGA and compatibles 320x200x256, and the series of 16-color and non-standard planar 256 color modes supported by VGAlib, as well as 720x348x2. Cirrus Logic GD542x 640x480x256, 800x600x256, 1024x768x256, 640x480x32K, 640x480x64K, 800x600x32K, 800x600x64K, 1024x768x32K, 1024x768x64K, 640x480x16M, 320x200x32K, 320x200x64K, 320x200x16M. The last mode has a logical scanline width of 960 bytes, but the VESA BIOS uses 1024. Also, 800x600x16M at 50 Hz; and 800x600x16, 1024x768x16, 1280x1024x16. Some bitblt functions are supported. The way the second Mb of memory is enabled on 2Mb cards is suspect (dependent on DRAM configuration); please report any problems with 2Mb cards. Tseng ET4000/ET4000W32(i/p) Derived from VGAlib; not the same register values. ET4000 register values are not compatible; see et4000/README. 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 in et4000.regs or the dynamic registers file). ET4000/W32 based cards usually have an AT&T or Sierra 15025/6 DAC. 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 (/usr/local/lib/libvga.et4000 is parsed at runtime if DYNAMIC is defined in config.h). 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. I finally got to test an (old) ET4000 board myself, and the auto-detection didn't appear to work. Trident TVGA 8900C/9000 (and possibly also 8800CS/8900A/B) Derived from tvgalib by Toomas Losin. 640x480x256, 800x600x256, 1024x768x256 (I and NI) Might be useful to add 16-color modes (for those equipped with a 512K TVGA9000). Oak Technologies OTI-037/67/77 May work if somebody provides the register dumps (especially the extended registers) using XFree86 v2.0 (see Changes) (worked for 640x480x256). 640x480x256 for now. ATI Mach32 The alpha driver by Michael Weller supports all BIOS-defined modes. However, non-Type 2 DAC's are untested. Check out README.mach32 (and README.config). Do send feedback. S3 The minimal S3 driver source present is a quick hack, and does not work. It can be enabled by explicitly setting the chipset to S3 in the configuration file, and defining SVGALIB_TRY_S3 in the environment. Several people have expressed interest and their willingness to get something done. In principle dynamically loaded registers based on register dumps together with handling some types of DAC/clock chips should be sufficient. Join the Linux-Activists SVGALIB channel if you're interested. 3. Additional VGAlib functions For vgagl, see gl/README. The mouse and keyboard interfaces are "documented" in their headerfiles. There is no automatic mouse pointer support; handle it around mouse_(waitfor)update(). vga_init() Initialize library; detects chipset and gives up supervisor rights. Recommended first line of any program that uses svgalib; vga_setchipset can be used before it to avoid detection. vga_modeinfo *vga_getmodeinfo( int mode ) Returns pointer to mode information structure for a mode. width Width of mode in pixels. height Height of mode. bytesperpixel Bytes per pixel (framebuffer-wise). This is 1, 2 or 3, and 0 for planar VGA modes. linewidth Logical scanline width in bytes. colors 2, 16, 256, 32768, 65536 or 16M maxlogicalwidth Maximum logical scanline width (bytes). startaddressrange Mask of changeable bits of start address (in pixels). maxpixels Maximum number of pixels that will fit in a logical screen (depends on video memory). haveblit Indicates whether bitblit functions are available. Bit 0: Bitblit Bit 1: Fillblit Bit 2: Imageblit flags Miscellaneous flags. Bit 0: Setreadpage/setwritepage available. Bit 1: Mode is interlaced. Bit 2: Mode is mode-X like (planar 256 colors). Bit 3: Dynamically loaded mode. Bit 4: Can set to linear addressing. Bit 5: Linear addressing enabled. Bit 6: The following fields in this information structure are set: chiptype the chiptype that was detected/set. memory memory available on the card in KB linewidth_unit use only a multiple of this value for set_logicalwidth or set_displaystart to ensure graceful alignment of lines onto the vga memory in this mode. linear_aperture ptr to a mmaped secondary linear framebuffer (NULL if unavailable) aperture_size size of framebuffer in KB. 0 if unavailable. set_aperture_page a function taking an int as parameter to select a page in the framebuffer if aperture_size= memory and setting bits 4 and 6 in flags will automatically enable linear addressing support. setmode( int mode, int previous_mode ) Sets all registers for a mode; returns nonzero if mode not available. __vga_setregs can be called to set the VGA registers. unlock() Unlocks chipset-specific registers. lock() Lock (protect) chipset-specific registers. Currently not called. test() Identify chipset; initialize (check memory and type) and return nonzero if detected. setpage( int page ) Set 64K page number to be mapped at 0xa0000. init( int force, int par1, ... ) Initialize memory and type; called by test. If force is 1, the chiptype or the amount of memory can be forced (this is pretty useless). The following functions are not required; they provide for things like page flipping and hardware scrolling virtual desktops. setdisplaystart( int addresss ) Sets the display start address in video memory in pixels. setlogicalwidth( int width ) Sets the logical scanline length in bytes. Usually a multiple of 8. The function getchipset() in vga.c must call the test routine for the chipset. The chipsetfunctionslist must be have a pointer to the chipsetfunctions table for the chipset (which is the only global symbol in a chipset driver). Also, vga.h contains a magic number for each chipset. Also driver_names[] in vga.c has to contain a name for each driver at the correct position. 6. Changes See the file CHANGES. 7. Bugs 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 program 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. 8. 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 priviledges 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 safety_fork 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 seperate 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. 9. References The latest version of svgalib can be found on sunsite.unc.edu and mirrors as svgalibXXX.tgz in the directory /pub/Linux/libs. 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. If you want to recompile the shared library, you will need the DLL 'tools' package (found on tsx-11.mit.edu, GCC dir). Viewers (in /pub/Linux/apps/graphics/viewers on sunsite): spic Picture viewer; JPG/PPM/GIF; truecolor; scrolling. zgv Similar, 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): 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. wt Free state-of-the-art Doom-like engine. 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. 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. The vgalib ghostscript device driver sources can be found on sunsite, /pub/Linux/apps/graphics. Ghostscript patches from Slackware: ftp.cdrom.com, /pub/linux/misc. gnuplot patches are on sunsite. 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. These functions may go into a later version of svgalib.