gnu1987/vgalib

Hi!

This is version 1.1 of the VGA graphics library for linux. As the
previous versions it has the following features:
- Support for all standard VGA 16 and 256 color modes
- Support for non-standard 256 color modes (including mode X)
- Text mode restoration
- Handling of console I/O
- Flipping between graphics mode and text mode
- Restores text mode after CTRL-C interrupt
The present version adds the following:
- Tseng ET4000 SVGA 256 color modes
- Monochrome 640x480 mode
- Bug fixes and some minor improvements

VGAlib requires the 0.96b kernel (or newer) and must be compiled
with GCC 2.2.2 (or newer). To compile and install VGAlib just
type make. This will also build the following programs:
vgatest: a simple demonstration of the library and the various
video modes
dumpreg: dumps the current VGA registers to stdout, mainly used
for debugging and creating new video modes
runx : if you have problems with text mode restoration after
running X386, then try to use runx instead of startx
Remember that all programs using VGAlib must be run with setuid
root, otherwise you will get a "can't get I/O permissions" error.

VGAlib does it's best to restore the text mode, but it may fail
with some SVGA cards if you use a text mode with more than 80
columns. If you are having problems please try to use an 80
column text mode.

Below is a short description of the functions in the library.
Look at vgatest.c for examples on how to use these functions:
- vga_setmode() is used to select the graphics mode or to
restore the text mode.
- vga_hasmode() tests if a given video mode is supported
by the graphics card (use this function before using
any of the ET4000 SVGA modes)
- vga_clear() clears the graphics screen. This is also done
by vga_setmode().
- vga_getxdim(), vga_getydim() and vga_getcolors() return
the resolution and number of colors for the current mode.
- vga_getpalette() and vga_getpalvec() returns the contents
of one or more palette registers, respectively.
- vga_setpalette() and vga_setpalvec() allows you to modify
one or more palette registers, respectively.
- vga_setcolor() determines the color for future calls of
the drawing functions.
- vga_drawpixel() and vga_drawline() draws a pixel or a line
in the current color, respectively.
- vga_drawscanline() draws one single horisontal line of
pixels and has been optimized for the fastest possible
output.
- vga_screenoff() and vga_screenon() turns the screen refresh
off and on. On some VGA's the graphics operations will be
faster, if the screen is turned off during graphics output.
- vga_flip() switches between graphics and text mode without
destroying the screen contents. This makes it possible for
your application to use both text and graphics output.
- vga_gecth() waits for a character to be typed an returns
the ASCII value. If you press ESC (the exact key can be
changed with vga_setflipchar()), the text mode will be
temporarily restored until you press another key. This allows
you to switch to another virtual console and later return to
your graphics application.
- vga_setflipchar() changes the character that vga_getch()
uses for flipping between graphics and text mode.
- vga_dumpregs() dumps the current VGA register contents to
stdout
My main motivation for implementing the graphics/text flipping was
to make debugging easier. If your program reaches a breakpoint while
in graphics mode, you can switch to text mode with the gdb command

print vga_flip()

and later restore the graphics screen contents with the same command.
It is usefull to define the following alias in gdb:

define flip print vga_flip() end

There has been a lot of interest in the previous versions of VGAlib,
and I would like to thank everybody who has suggested improvements.

Tommy Frandsen (frandsen@diku.dk)