svgalib

package: svgalib

title: svgalib(7)

summary: a low level graphics library for linux

text:
# svgalib(7)

## NAME
svgalib - a low level graphics library for linux

## TABLE OF CONTENTS
0. Introduction

1. Installation

2. How to use svgalib

3. Description of svgalib functions

4. Overview of supported SVGA chipsets and modes

5. Detailed comments on certain device drivers

6. Goals

7. References (location of latest version, apps etc.)

8. Known bugs

## 0. INTRODUCTION
This is a low level graphics library for Linux, originally based on VGAlib 1.2 by Tommy Frandsen. VGAlib supported a number of standard VGA graphics modes, as well as Tseng ET4000 high resolution 256-color modes. As of now, support for many more chipsets has been added. See section 4 Overview of supported SVGA chipsets and modes

It supports transparent virtual console switching, that is, you can switch consoles to and from text and graphics mode consoles using alt-[function key]. Also, svgalib 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 /var/lib/svgalib, 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 recomended 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 it's own section 3 manual page. For a list of vgagl functions see vgagl(7).

### Initialization
vga_init(3)

- initialize svgalib library.

vga_disabledriverreport(3)

- makes svgalib not emit any startup messages.

vga_claimvideomemory(3)

- declare the amount of video memory used.

vga_safety_fork(3)

- start a parallel process to restore the console at a crash.

vga_setchipset(3)

- force chipset.

vga_setchipsetandfeatures(3)

- force chipset and optional parameters.

### Inquire hardware configuration
vga_getmousetype(3)

- returns the mouse type configured.

vga_getcurrentchipset(3)

- returns the current SVGA chipset.

vga_getmonitortype(3)

- returns the monitor type configured.

### Setting video modes
vga_setmode(3)

- sets a video mode.

vga_setdisplaystart(3)

- set the display start address.

vga_setlogicalwidth(3)

- set the logical scanline width.

vga_setlinearaddressing(3)

- switch to linear addressing mode.

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 freqencies, 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 knowledgable OTI-087 user and experience problems you are welcome to provide fixes. No user of a OTI-087 is currently known to me, so if you are able to fix problems with the driver please do so (and contact me) as noone else can.

Michael.

Now back to the original Oak information:

The original OTI driver, which supported the OTI-067/77 at 640x480x256, has been augmented with the following 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.


svgalib.chips

title: svgalib.chips(7)

text:
# svgalib.chips(7)

## NAME
svgalib.chips - Information for Chips and Technologies Users

## TABLE OF CONTENTS
Information for Chips and Technologies Users

David Bateman <dbateman@eng.uts.edu.au>

23nd May 1997

0. Introduction

1. "libvga.config" options

2. Unsupported Chips and Technologies chipsets

3. Known bugs

## 0. INTRODUCTION
This is the really only my first attempt to get a working fully featured driver for the Chips and Technologies chipset to work with svgalib(7). As such the only machine that I know it will work on is my own. If you use this software then at this point I'm still very interested in hearing from you by e-mail. Include full details of your chipset, amount of videoram and whether you have a VL-Bus or PCI bus machine.

This server was written using the svgalib(7) 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. In addition support for the 65525, 65535, 65546, 65548, 65550 and 65554 have been included. The 64200 and 64300 chips are unsupported, however these chips are very similar to the 6554x chips which are supported.

At this point this code is only confirmed to work correctly on a 65545 VL-Bus machine. However as much of the code was stolen from my experiences with writing code for XFree I hope not to have too many problems with other machines. However if you run this code on a 65545/48 PCI machine or a 65550/54 machine then I am particularly interested in hearing of any success or failure stories.

## 1. "libvga.config" OPTIONS
The first thing to note is that the option parser for svgalib(7) is not very robust. Hence if you make some typing mistakes, you can have some very strange effects. I've set out below the libvga.config(5) options that are of particular interest to Chips and Technologies users. Normally this configuration file can be found at /etc/vga/libvga.config.

HorizSync MIN MAX

Often LCD panels has very different specifications for the horizontal sync than CRT's do. Hence often you'll need this option, particularly if you are using the XFree like modelines described below. The two floating point numbers specified will set the minimum and maximum allowed horizontal sync in kHz.

VertRefresh MIN MAX

Similar to the above, but this sets the LCD or CRT's vertical refresh rate in Hz.

modeline 640x480 20.00 640 688 704 776 480 480 481 486

This option allows you to specify XFree like modelines to use in preference to the in built modelines. Often LCD panels will need very different pixel clocks and timings than CRT's. Hence this option allows you to specify these. Note that the LCD panel timings are related to the panel size and not the mode size. Therefore by default the BIOS setting already uploaded into the registers are used by default. See the "UseModeline" option below if you wish to override these.

chipset C&T 5 1024

These option allows the user to specify the chipset to use and the amount of installed memory in kBytes. Currently supported chipsets are

0 65520

1 65525

2 65530

3 65535

4 65540

5 65545

6 65546

7 65548

8 65550

9 65554

TextClockFreq 25.175

One major difference between this code and the previously available support for the Chips and Technologies chipsets is that it supports the use of programmable clocks. Because of the way that the Chips and Technologies chips program the VCO from the registers, there is no way to be sure to recover the previously programmed clock value. Hence the driver assumes that the console clock is 25.175MHz. This will be wrong for many machines. However I have supplied this option to use a different value that might be more suitable for your machine.

nolinear

This option disables the use of the linear framebuffer. This might be useful for machines that have broken linear framebuffers. In lar the linear framebuffer doesn't seem to work with the achines.

linear

Allow, but don't enforce the use of the linear framebuffer. As this is the default anyway, I don't see that this option is much use.

setuplinear 0xC0000000

For VL-Bus machines I expect that the linear framebuffer starting address will be setup correctly. However to get the starting address for PCI machines requires access to the MEMBASE register in the PCI address space. Code to do this doesn't currently exist with svgalib(7), and so I've taken the easy option of just testing a few known PCI starting addresses. For now these are just 0xFE000000, 0xFD000000, 0x41000000 and 0xC0000000. If you have a different starting address then the linear framebuffer will be unusable. You might like to report your starting address to me so that I can include it in the probing code, but till then this option can be used to set up the correct address. This option just forces the given address to be the only one probed. It doesn't force the linear framebuffer to be used.

LCDPanelSize 800 600

For some machines the LCD panel size is incorrectly probed from the registers. This option forces the LCD panel size to be as specified. If you have a black band down one side of your LCD display you might very well need this option. Also if you are using the option "fix_panel_size" in XFree then this option has a similar effect. This option can be used in conjunction with the option "UseModeline" to program all the panel timings using the modeline values. Two machines that are known to need this option are the HP Omnibook 5000CTS and the NEC Versa 4080 800x600 TFT machines.

UseModeline

The flat panel timings are related to the panel size and not the size of the mode specified. For this reason the default behaviour of the svgalib(7) is to use the panel timings already installed in the chip. The user can force the panel timings to be recalculated from the modeline with this option. However the panel size will still be probed. Two machines that are known to need this option are the HP Omnibook 5000CTS and the Prostar 8200. You are advised to check the README.chips that come with XFree for more details.

NoBitBlt

This option disables the use of H/W acceleration. As far as I know the only thing that currently uses the H/W acceleration is libvgagl, so this might not be a problem anyway. However if you see corruption of the graphics on the screen try this option and see if it goes away.

Use18BitBus

For 24bpp on TFT screens, the server assumes that a 24bit bus is being used. This can result in a reddish tint to 24bpp mode for machines that actually have a 18 bit bus. This option, selects an 18 bit TFT bus. Note that using this option with a 24 bit bus machine will similarly discolour the screen. For other depths this option has no effect.

Center ENABLE/DISABLE or Stretch ENABLE/DISABLE

The default behaviour of svgalib(7) is to leave the stretching and centring registers completely alone. However for some machines this might result in poorly placed modes, or modes that don't fill the whole screen. These two options can be used to centre and stretch the mode on the screen. Note that for instance a Center DISABLE might follow a Center ENABLE in the config file. Only the last option takes effect.

## 2. UNSUPPORTED CHIPS AND TECHNOLOGIES CHIPSETS
The 64200 and 64300 chips are unsupported. However by specifying the chipset in your libvga.config as either a

chipset C&T 3 2048

Use 65535 for a 64200 assuming 2M of video ram, or

chipset C&T 7 2048

Use 65548 for a 64300 assuming 2Mb of video ram

then svgalib can be made to give limited support to these chipsets. Note that the paged addressing mode of the 65548 chip and earlier can only address upto 1Mb of video ram. If the additional memory is needed then linear addressing must be used!! Note that support of the 64xxx chips has not been tested at all, and the above is just a suggestion that I believe will work.

## 3. KNOWN BUGS
One persistent and annoying bug is that the text mode stretching on LCD displays is not always restored correctly for 65550 and 65554 machines. This is to do with the manner in which the extended registers are restored and what is being done with the synchronous reset while the registers are restored. As I don't have a 65550 or 65554 machine of my own on which to test this code, I have been unable to fix this problem. In most circumstances an LCD-CRT switch will restore the LCD stretching to the desired state.

David.

## FILES
/etc/vga/libvga.config

## SEE ALSO
svgalib(7), libvga.config(5).

## AUTHOR
of the driver and this documentation is David Bateman <dbateman@eng.uts.edu.au>. However, it was slightly reformatted by Michael Weller <eowmob@exp-math.uni-essen.de>.


title: svgalib.et4000(7)

summary: Information for Tseng ET4000 users

text:
# svgalib.et4000(7)

## NAME
svgalib.et4000, libvga.et4000 - Information for Tseng ET4000 users

## TABLE OF CONTENTS
NOTE: The ET4000 register layout changed stepping from svgalib 0.98 to 0.99. See 8. Problems below first

1. Basics of ET4000 cards

2. How to configure svgalib(7)

3. Creating card dependent register values

4. Defining new modes

5. Redefining standard modes

6. Available examples

7. ET4000/W32 support

8. Problems

9. Using dynamic loading with other cards

## 1. BASICS OF ET4000 CARDS
Basicly all ET4000 cards are equal, some are even more equal ...

The Chipset is well documented (by Tseng Labs and eg. the vgadoc2.zip) and all graphics functions can be used the same way on different cards (including the ET4000/W32 based ones). There are three important points to be kept in mind:

a.)

amount of available, the organisation and timing of video memory

b.)

type and capabilities of the DAC

c.)

available oscillator frequencies

svgalib(7) will check the available video memory during startup. This should work on all DRAM cards. If there are any problems concerning VRAM equipped cards, please tell us about.

By now we found is no reliable way to detect the memory organisation/ timing and the DAC type/capabilities. Most modern card use a frequency synthizier and provide the following pixel frequencies (in MHz):

50.350 56.644 65.0 72.0 80.0 89.8 63.0 75.0

Checking older ET4000 cards we found a wide spread range of available frequencies. Since the video timing is based on the pixel frequency, the required register values are card dependent.

## 2. HOW TO CONFIGURE SVGALIB
svgalib(7) has a somewhat 'standard' registers set that may work with modern ET4000 cards. If svgalib(7) fails on your machine or you have a HiColor dac, you need to configure your svgalib(7).

The svgalib(7) may use hard linked or dynamical linked register values. If you use hard linked values, the binary will be smaller and start up faster but might fail on other machines.

Compiling the svgalib(7) with DYNAMIC defined (see Makefile.cfg) will set up dynamic register loading. Otherwise the value from svgalib/et4000.regs will be hard linked.

The dynamic configuration will be read from /etc/vga/libvga.et4000 which is an ASCII file (see Makefile.cfg for exact naming). If you have a working et4000.regs for your system just copy this file to /etc/vga/libvga.et4000 or link /etc/vga/libvga.et4000 to your svgalib/et4000.regs file.

The actual scanner/parser will handle the following entries:

\#define DAC_TYPE <integer>

Overwrite the DAC detection

\#define <MODE1> <MODE2>

Enable MODE1 using MODE2 registers, eg. 64K modes like 32K modes

\#define <MODE> DISABLE_MODE

do not use MODE (eg. from vgadrv)

char <MODE><strg>[..] = {<integer>, <integer>, ... };

register definition

with

<MODE> ::= 'g'<decimal>x<decimal>x<color><ignored>

<integer> ::= <decimal>|<hex>

<hex> ::= '0x'<hexdigit>{<hexdigit>}

<decimal> ::= ['+'|'-']<digit>{<digit>}

<hexdigit>::= <digit>|'a..f'|'A..F'

<digit> ::= '0..9'

<color> ::= '2'|'16'|'256'|'32k'|'32K'|'64k'|'64K'|'16M'

<strg> ::= <empty>|[(<alpha>|'_'){<digit>|<alpha>|'_'}]

<alpha> ::= 'a..z'|'A..Z'

C style comments will be skipped. See the et4000/ subdirectory of the svgalib distribution for examples.

## 3. CREATING CARD DEPENDENT REGISTER VALUES
You may create a et4000.regs on your own with the tseng3.exe program. This DOS program and its source is included in the svgalib distribution.

Just boot MS-DOS and start

tseng3 et4000.reg

The tseng3.exe will measure the video timing for each available mode. Check the et4000.regs file against your monitor documentation and disable all non conformant modes, eg.

\#define g1024x768x256_regs DISABLE_MODE

/*

static unsigned char g1024x768x256_regs[71] = {

...

};

*/

will disable the 1024x768x256 mode. You mustn't disable the 640x480x256 mode!

Your et4000.regs must define the following symbols (register values or #define ... DISABLE_MODE) for hard linking:

g320x200x32K_regs, g640x400x256_regs, g640x480x256_regs, g640x480x32K_regs, g640x480x16M_regs, g800x600x16_regs, g800x600x256_regs, g800x600x32K_regs, g1024x768x16_regs, g1024x768x256_regs, and g1280x1024x16_regs.

and all 64K modes handled like 32K modes by the driver:

\#define g320x200x64K_regs g320x200x32K_regs

\#define g640x480x64K_regs g640x480x32K_regs

\#define g800x600x64K_regs g800x600x32K_regs

You may omit every unusable mode in /usr/lib/libvga.et4000.

## 4. DEFINING NEW MODES
All standard svgalib(7) modes may be selected by the mode constants defined in #include<vga.h> (eg. G320x200x16). You may define new modes on your own. Just use dynamic register loading and add the register definition of the new mode. Your program may determine the related modenumber by checking the vga_getmodeinfo(1..vga_lastmodenumber()).

Most ET4000 cards provide 640x350 and 640x400 graphics modes. The tseng3.exe generates the related register sets. You may also use dumpreg(1) from an X window to grab you favourite X graphics mode. The X mode normaly isn't usable directly. See cardex.w32 for an example and et4000.c for a brief description of et4000 registers (both files are included in the svgalib distribution).

## 5. REDEFINING STANDARD MODES
Using dynamic register loading you may redefine any standard VGA mode except of TEXT and 640x480x16. Just add the ET4000 specific register set to /etc/vga/et4000.regs.

## 6. AVAILABLE EXAMPLES
In the et4000/ subdir of teh svgalib distribution you'll find some sample register sets:

cardex.w32

Cardex ET4000/W32 card, Music TrueColor DAC

speedstar+

SpeedSTAR PLUS card, Normal DAC

orchid.pdII

Orchid Prodesigner II

## 7. ET4000/W32 SUPPORT
The actual driver seems to be ET4000/W32 compatible. Tell us about any problems (and solutions). If you've got any information about the ET4000/W32 blitter, we would be pleased to receive it.

## 8. PROBLEMS
As mentioned before, the DAC detection isn't very reliable. vgatest(6) should print equal screens in 256 color and HiColor/TrueColor modes. You may have to edit your libvga.et4000 register file by hand to setup the correct DAC.

The tseng3.exe may fail due to incompatible mode numbering. You might use a VESA driver (eg. tlivesa.com from VPIC 6.0) or edit and recompile the tseng3.exe.

Newer ET4000 chipsets (eg. W32 and W32i) allow up to 32 clock frequencies. Two additional register values were added just before the old extened register value. The new registers are CRTC/30h and CRTC/31h. The old register set had 71 values, the new growed to 73. You may update your old register set by hand:

-

run the dumpreg program, remember the first two values from last data line.

-

edit your libvga:

for each mode change the number of register values from 71 to 73

add the values from dumreg output at front of last data line

-

run .BR vgatest (6) to check the new register set

## 9. USING DYNAMIC LOADING WITH OTHER CARDS
The dynamical register loading may be used in other drivers. Since hard linked register values work fine for Cirrus and Trident cards, we didn't include this feature.

## FILES
/etc/vga/libvga.config

/etc/vga/libvga.et4000

## SEE ALSO
svgalib(7), libvga.config(5).

## AUTHOR
This documentation for the ET4000 registers was provided by Hartmut Schirmer. However, it was slightly reformatted by Michael Weller <eowmob@exp-math.uni-essen.de>.


svgalib.faq

title: svgalib.faq(7)

text:
# svgalib.faq(7)

## NAME
svgalib.faq - frequently asked questions about svgalib

## INTRODUCTION
I (Matan Ziv-Av), added/changed some of the answers in this file, so some answers are mine, and some are Michael's.

List of (recently) frequently asked questions about svgalib. Esp. about it's status and future. Please note that as of now all answers are just written by me, Michael Weller <eowmob@exp-math.uni-essen.de>. I'd like this to change. So email your suggestion (best of all: question and the answer).

Also, most questions deal with the status and future and my ideas about it. Necessarily they contain my own private opinions on this. People may disagree and I'm sure I don't have the best ideas about it or may even be completely wrong. I don't want to force anyone to agree with me.

Also, I was asked about MY opinions, so I'm just presenting them here.

## CONTENTS
Q 1)

I want to write some svgalib application. Where is the documentation?

Q 2)

My board is not supported. What now?

Q 3)

I get: You must be the owner of the current console to use svgalib.

Not running in a graphics capable console, and unable to find one.

However, though logged in not directly from the linux console, I am the owner of the console.

Q 4)

Is svgalib dead?

Q 5)

There are so many Xfree drivers, why not just use them.

Q 6)

Why not just use the VGA BIOS?.

Q 7)

What about GGI?

Q 8)

Why not just use X11?

Q 9)

Now, again, what about the future of svgalib?

Q 10)

Ok, just for completeness, what are your plans about svgalib anyway?

Q 11)

Nice plan. But will it become true?

## THE QUESTIONS

### Q 1)
I want to write some svgalib application. Where is the documentation?

### A a)
Well, did you really look at everything? The 0-README file in the top level directory contains all function prototypes and explanations on how to call them.

Yes, the documentation is short and/or confusing. Sorry, English is not my native tongue. Many people complain and want to write some better documentation. You are welcome to do so! However, up to now, either people found the documentation sufficient once they looked at the correct files or they just gave up. At least, I never heard from these people again.

Also, svgalib comes with source. If in doubt: read it.

Finally: Linux distributions include svgalib, but not the source and README's (or hide them so good noone finds them). Well, no problem, get full svgalib source, demos, readme's from svgalib-*.tar.gz on any Linux FTP server in your vicinity. Even if you don't dare to install or compile it, it contains the readme's.

Oh yes, there are some simple demos in the demos/ subdir. They should get you started.

When someone writes man(1) manual pages, a distribution might just install them. Please do not complain, write them, mail them to me.

### A b)
Finally, I, Michael Weller wrote the manpages. Looking at svgalib(7) should get you started. Additions and corrections are still welcome, of course.

### Q 2)
My board is not supported. What now?

### A)
Simple:

a)

Contact the maintainers (see other README's) and check out if someone is working on a driver.

b)

If so, contact them if you like and announce you'd be willing to test things or even help coding.

c)

If not, write a driver. Get as many docs on your card as you can, then read and understand the internals of svgalib (again read the README's carefully!).

Please understand that this is a free project. I will not go and buy a similar card and write a driver for you. I already wrote support for the hardware I have! I just do this as a hobby. Because I don't get paid for this I can not just buy card & docu and spend much much time supporting whatever graphics card on earth exists.

Also read below on the future of svgalib.

If you don't feel able to write a driver for whatever reason, please do not complain if other people don't do it for you (because you are not better than they are).

### Q 3)
I get:

You must be the owner of the current console to use svgalib.

Not running in a graphics capable console, and unable to find one.

However, though logged in not directly from the linux console, I am the owner of the console.

### A)
Alas, some programs use their suid root privilege and become a full root owned process. svgalib thinks they are run by root which does not own the current console. Defining ROOT_VC_SHORTCUT in Makefile.cfg and recompiling will allow svgalib to allocate a new VC. However, it will allow any person which is able to exec that program to start in on a new console. Even if not logged in from the console at all. Thus, for security, you need to explicitly enable that root feature.

### Q 4)
Is svgalib dead?

### A)
This question comes up frequently esp. in recent times.

The answer is, of course, no.

### Q 5)
There are so many Xfree drivers, why not just use them.

### A)
Well, actually much of the code in there is actually already used by svgalib. Xfree coders worked on svgalib and vice versa. But honestly, do not expect that a driver from Xfree can just be used for svgalib. The internal structures of Xfree and svgalib (and GGI) are just too different. As a source of knowledge and for one or the other subroutine, the Xfree sources are invaluable however.

### Q 6)
Why not just use the VGA BIOS?.

### A)
Actually, we do. There is now, thanks to Josh Vanderhoof, a VESA driver. The VESA driver does not work on all cards, even though it should. It does not even work on all cards where vbetest works. If vbetest does not work it means the bios writers assumed it would always run in DOS, and used tricks (for delay, etc.) that can't work under Linux. If vbetest works, but the VESA driver does not, I (Matan Ziv-Av) believe it is due to the following reason: The driver use VESA function 4 (save/restore video state). This function can't be used in a singletasking environment (DOS) and as such, some bios writers failed to implement it properly, and all the tests (which are run under DOS) failed to discover this.

The VESA driver does work with many cards though.

### Q 7)
What about GGI?

### A)
Yes, GGI. Another long story. At first: Yes, I like the idea of an in kernel graphics driver. I like it very much. And, yes, this is a bit weird because I am the svgalib maintainer and a working GGI will make svgalib obsolete. Again, I already said above: I did not invent svgalib nor do I promote it as the solution (now compare this to GGI). It just does what it does and works for me and some other people.

I liked this idea so much, I even started coding a frame buffer device once. After a short time, other people came out with the GGI idea. Right from their beginning they claimed to be the only source of wisdom. I tried to join our efforts, but failed. In general we have the same goals (read the GGI project pages for that).

Anyhow, at that time a flame war started. I don't really know why. I don't see I did anything else than offering my opinions, work and experience. But that should be judged by others.

Well, after some time I stopped bothering them. I was satisfied to learn later though that they actually came up with some conclusions I proposed first but weeks or months later. But let us leave the past alone.

When intending to contribute to svgalib, you should think about what you really want. I don't see that GGI is becoming available soon. GGI people told me the opposite again and again, ok, I still don't see it. Still out of a sudden, everything might be GGI infested, so you might consider contributing to GGI instead.

With svgalib you might be able to use your fruits earlier. And anyone (with supported hardware) can just use it right away without reinstalling kernel/X11 what else (maybe being unable to use something he did before).

### Q 8)
Why not just use X11?

Yes, this is what many people say. This is the common Unix way to do it. X does it.

But X has some drawbacks:

i)

It uses many resources. Admittedly this is becoming of lesser importance now, where you can run a sensible X11 Linux system on 8MB (16 MB for heaven like performance) which is the absolute minimum to get a simple text editor running under M$ windows. Still, an advantage of Linux is the ability to use old hardware for mission critical background jobs on the net (servers/routers/firewalls) on low price or otherwise even unusable hardware.

ii)

X has a nice API with draw commands for any kind of 'command oriented' screen output. I mean with that: Select a color, draw a line, polygon, etc. This imposes a bunch of overhead. If you just want access to the screen memory, it slows things down as hell. If you want just to use above's draw commands, it is ok!

iii)

One can now circumvent the API restrictions by getting direct screen access using a special Xfree extension. Basically Xfree just setups the screen and gives you shared memory access to the screen memory. IMHO, this is not much different from the shared memory X11 extension by MIT (which is probably why it was added so easily). Still it needs quite some overhead, at least when the card does not allow for a linear frame buffer. However, you cannot change screen modes and rez as easily. This is IMHO THE drawback of X. For a picture viewer, you want 256 color high/true color modes on a per picture basis (also, insert any other application you like: movie viewers, a special game, a drawing program). Also, you want a small picture use a low rez s.t. it does not appear as a thumbnail, maybe use a high rez mode for a huge picture which you don't want to use on a permanent basis because it flickers like hell (and you don't want to use a panning virtual desktop too, I hated them at best).

This latter restriction can of course be circumvented by enlarging the picture. But this will need much time for a picture viewer already and certainly too much for smooth video or game animations.

iv)

Finally, the problem how X11 itself accesses the screen is not solved. Security is usually no concern because X11 does it, is a trusted executable and a firewall between applications and the hardware. Alas, there might be security holes, also the stability and performance issues (IRQ driven accelerator queue, CPU support for VGA memory paging) still exist, though one can expect an Xserver to be a generally well coded application.

### Q 9)
Now, again, what about the future of svgalib?

For console graphics, svgalib is still the only solution for most people, and as such it should go on for a while. Compared to the other console graphics options (kgi and kernel fb device), writing svgalib driver is the simplest (at least, this is my experience), and so it makes sense to believe that svgalib will work on all cards where there is someone interested enough in that support.

### Q 10)
Ok, just for completeness, what are your plans about svgalib anyway?

First, make svgalib cooperate nicely with kernel fb device. Then (and it should be very similiar) make svgalib work on a secondary vga card.

A rewrite of the code for memory handling and virtual console handling is necessary for the previous goals, but is also necessary in itself, and so will be done also.

I do intend to maintain complete binary compatibility, so that older programs will go on working.

As internal changes are made, the drivers have to be changed as well. For some of the older drivers (ali, ark, ati, et3000, et4000, gvga, oak), I no longer get any reports, so I don't know if they still work. Some features are also lost, for example, linear frame buffer on non-PCI cards. This should not be a very big problem, as users with such cards can go on using 1.3.1, as most changes are not applicable for older machines.

## SEE ALSO
svgalib(7), libvga.config(5).

## AUTHOR
This file was written by Michael Weller <eowmob@exp-math.uni-essen.de>, And later changed by Matan Ziv-Av.


title: svgalib.mach32(7)

text:
# svgalib.mach32(7)

## NAME
svgalib.mach32 - Information on the Mach32 chipset driver

## TABLE OF CONTENTS
0. Introduction

1. Specifying pixel clocks

2. Copyrights

3. The mach32info utility

4. Third party cards

5. Logical linewidth

6. Noisy video signals

7. The configuration EEPROM

8. EEPROM woes

9. The Mach32Eeprom command

10. Setup of the memory aperture (linear framebuffer)

11. Accelerator support and other weird features

12. Ramdacs

13. Meaning of the detection message from svgalib

14. Conclusions

## 0. INTRODUCTION
The driver should allow you to use any of the graph-modes your Mach32 card supports. Note that there is no support for <8bpp modes and that I won't ever implement that because I don't see any reason for doing so. All standard VGA-modes are supported, of course (by using the standard VGA driver routines).

If you configured your Mach32 for a memory aperture and it is at least as big as the memory of your card (that is, not a 1MB memory aperture for a 2MB card) support for linear frame buffer access of svgalib is given.

Auto detection of the Mach32 seems not to work on all cards. That's really strange since I got the code from the X people. It should be OK regardless of my docs. Well, I fixed that (hopefully). Actually the bug was found by Daniel Lee Jackson (djackson@ichips.intel.com). (Thanks again.. It was so silly... I would have never found it) If you still have problems just put a chipset Mach32 in your config file.

## 1. SPECIFYING PIXEL CLOCKS
WARNING! The Mach32 driver needs to know correct clock frequencies for graceful DAC configuration. Wrong clocks may damage your card! However, this version contains code for automatic clock detection. Since clock detection is time critical, please do it on a completely idle system. Then put the printed out clocks line in your libvga.config(5) file.

The driver tries to do this for you. After that, you can restart whatever svgalib program you used and you are set. If you already put a clocks line in your config by hand, comment it out to have the driver check your clocks.

Since clock probing is time critical, values differ from time to time, you may try it multiple times and see which values seem to be most exact. You can also compare them with the standard clock chips for Mach32 cards in libvga.config(5)).

The clock probing relies on the 7th clock being 44.9MHz as this is what Xfree does. If this is not true (and it is not always), probing is hosed. See libvga.config(5) for a list of the clocks used by common svgalib cards.

## 2. COPYRIGHTS
Some tiny routines are copied from Xfree86. The clock detection code is almost just copied. So I repeat the copyright statements for these parts here:

Copyright 1992 by Orest Zborowski <obz@Kodak.com>

Copyright 1993 by David Wexelblat <dwex@goblin.org>

Permission to use, copy, modify, distribute, and sell this software and its documentation for any purpose is hereby granted without fee, provided that the above copyright notice appear in all copies and that both that copyright notice and this permission notice appear in supporting documentation, and that the names of Orest Zborowski and David Wexelblat not be used in advertising or publicity pertaining to distribution of the software without specific, written prior permission. Orest Zborowski and David Wexelblat make no representations about the suitability of this software for any purpose. It is provided "as is" without express or implied warranty.

Orest Zborowski and David Wexelblat disclaim all warranties with regard to this software, including all implied warranties of merchantability and fitness, in no event shall Orest Zborowski or David Wexelblat be liable for any special, indirect or consequential damages or any damages whatsoever resulting from loss of use, data or profits, whether in an action of contract, negligence or other tortious action, arising out of or in connection with the use or performance of this software.

Copyright 1990,91 by Thomas Roell, Dinkelscherben, Germany.

Copyright 1993 by Kevin E. Martin, Chapel Hill, North Carolina.

Permission to use, copy, modify, distribute, and sell this software and its documentation for any purpose is hereby granted without fee, provided that the above copyright notice appear in all copies and that both that copyright notice and this permission notice appear in supporting documentation, and that the name of Thomas Roell not be used in advertising or publicity pertaining to distribution of the software without specific, written prior permission. Thomas Roell makes no representations about the suitability of this software for any purpose. It is provided "as is" without express or implied warranty.

Thomas Roell, Kevin E. Martin, and Rickard E. Faith disclaim all warranties with regard to this software, including all implied warranties of merchantability and fitness, in no event shall the authors be liable for any special, indirect or consequential damages or any damages whatsoever resulting from loss of use, data or profits, whether in an action of contract, negligence or other tortious action, arising out of or in connection with the use or performance of this software.

Author: Thomas Roell, roell@informatik.tu-muenchen.de

Rewritten for the 8514/A by Kevin E. Martin (martin@cs.unc.edu)

Modified for the Mach-8 by Rickard E. Faith (faith@cs.unc.edu)

Rewritten for the Mach32 by Kevin E. Martin (martin@cs.unc.edu)

And here is my own copyright:

This driver is free software; you can redistribute it and/or modify it without any restrictions. This library is distributed in the hope that it will be useful, but without any warranty.

Copyright 1994 by Michael Weller

Email addresses as of this writing:

eowmob@exp-math.uni-essen.de mat42b@spi.power.uni-essen.de

Michael Weller disclaims all warranties with regard to this software, including all implied warranties of merchantability and fitness, in no event shall Michael Weller be liable for any special, indirect or consequential damages or any damages whatsoever resulting from loss of use, data or profits, whether in an action of contract, negligence or other tortious action, arising out of or in connection with the use or performance of this software.

## 3. THE MACH32INFO UTILITY
The mach32info(6) utility or demo reads out all configuration registers and the configuration EEPROM of your Mach32 card. If there is a problem with the particular card you have, compile and run the utility in the mach32/ directory of the svgalib distribution and send it's stdout to me This might also be useful if you need a lot of options (e.g. clocks on new models?) to get it to work so that this can be done automatically in future versions.

## 4. THIRD PARTY CARDS
I got a few reports about AST systems with onboard Mach32. They do feature an incompatible EEPROM setup, but I think I got around that. Nevertheless the Mach32 chipset driver doesn't work out of the box on any AST system I heard of.

Since original ATI Mach32 demos and tools don't work as well, I've to claim that the Mach32 on these AST systems does not conform to ATI's Mach32 docs. Fortunately, Vernon C. Hoxie <vern@zebra.alphacdc.com> found a work around after years (really!) of investigating. AST Mach32 seems to work now. The work around was also submitted to Xfree and will be incorporated to allow running it on the AST hardware too in recent versions. Please read on the misc_ctl command below.

Dell users should have a look at the vendor, ramdac, and svgaclocks commands below (if they have problems with the default settings).

### Commands to support third party cards
I had to learn that those cards seem to use not only non standard clocks for the Mach32, but also for the included SVGA. However, since people often like to use proprietary, non standard VGA (read 80x25) textmodes, the Mach32 driver has to set the included SVGA to a VGA compatible clock frequency. Otherwise svgalib has problems using plain VGA modes. This screws VGA modes up if these clocks have different values on third party Mach32 cards.

svgaclocks n

with n a number between 0 and 31 to select the svga clocks to be used in vga modes. The bits of n refer to specific ATI register bits to complicated to explain here. Even if I would, I can't tell which clocks they would select on your third party card (which is the actual problem) svgaclocks 9 is the default setting and correct for original ATI cards.

Often svgaclocks 0 (Dell cards) works.

svgaclocks keep

is special in that the driver will not touch any SVGA timings. This requires the Mach32 SVGA part to be in a VGA compatible mode when the svgalib application is started, that is, you must use 80x25 (maybe 80x50) console textmodes.

As I mentioned already, Vernon C. Hoxie <vern@zebra.alphacdc.com> really seems to have located the reason for the Mach32 AST problems. Any access to MISC_CTL locks up the card & system. Fortunately MISC_CTL is only used for some DAC fine tuning (actually the setting you can fine tune with the blank command) which is only of barely noticable effect to the screen.

The following configuration commands exist to support AST cards:

misc_ctl keep-off

Do not dare to touch MISC_CTL.

misc_ctl use

Use it for fine tuning of the Ramdac setup (default).

Finally, for your convenience there exist:

vendor ati

vendor dell

vendor ast

These are macros that expand to settings for svgaclocks, ramdac, misc_ctl, and mach32eeprom that are usually correct for ATI, Dell, AST cards. Be aware that they really work like macros. That is, they override any setting of svgaclocks, ramdac, misc_ctl, and mach32eeprom made before them and individual aspects will be changed by a following svgaclocks, ramdac, misc_ctl, and mach32eeprom command. Note that the mach32eeprom ignore required for some Dell cards requires you to include explicit timings for Mach32 modes other than 640x480x256. The mach32/mach32.std-modes file in the svgalib distribution contains recommendations for modes from ATI.

I heard about a bug in some ATI chipsets returning wrong memory amounts configs. (But cannot confirm that)

You can enforce correct chipset identification from the configuration file:

chipset Mach32 chiptype memory

where chiptype is the sum of at exactly one value from each of the following two groups

128

use no memory aperture.

160

use a 1MB memory aperture.

192

use a 4MB memory aperture.

0

choose size for the memory aperture automatically.

and

16

Ramdac is of type 0 (ATI68830)

17

Ramdac is of type 1 (IMS-G173, SC11486)

18

Ramdac is of type 2 (ATI68875, TLC34075)

19

Ramdac is of type 3 (INMOS176, INMOS178)

20

Ramdac is of type 4 (Bt481, Bt482)

21

Ramdac is of type 5 (ATI68860)

0

Ramdac type is queried from Mach32 chip.

memory is the amount of videomemory in KB.

Note that the type of the ramdac can be set more conveniently with the ramdac command.

## 5. LOGICAL LINEWIDTH
At least my VRAM card seems to be very peculiar about logical linewidths. From my experience a multiple of 64 pels is needed. Your mileage may vary. Use the config file options to adjust it and tell me if your card needs a different value. Include the name and model number of the card and what the correct numbers should be. This is so that I can correct the auto configuration of the driver.

If some svgalib application has problems, note that you can force the logical linewidth to the default value from the configfile. Probably this will lead to glitches in some 800x600 resolutions. You can inhibit these resolutions from the configfile as well. Apropos glitches, I found no guidelines as to what clockrates to use due to memory restrictions. I adjusted the driver, such that I get a stable pic in all resolutions. However sometimes the screen is disturbed by heavy video memory accesses. If you don't like that, reduce the clocks used with the maxclock16 or maxclock24 command, resp. This may of course lead to none of the predefined modes being used. Then you can try to define your own mode via the define command.

## 6. NOISY VIDEO SIGNALS
If you get some flicker or heavy noise on your screen, some fine tuning may be needed. My docs didn't give me hints as to what each card can stand. Especially DRAM cards may give problems (I've VRAM). In that case, use the fine tuning config commands and send me your results along with the output of mach32info(6). Then I can include them in my next release.

### Fine-tuning configuration commands
First you should think about the maxclock* configuration commands to reduce pixel clocks used for each color depth.

Especially important for DRAM cards is the video FIFO depth used to queue memory values for writing to the screen. Here is a command to set this value for the 8bpp modes:

vfifo8 number

where number is in range 0 - 15. The default is now 6. Since vfifo is of some impact to the speed of the card, tell me the lowest setting that satisfies your card.

For 16/24/32 modes, there are non-zero values preset from internal tables and the EEPROM, however you can enforce minimal vfifo values with:

vfifo16 number

vfifo24 number

vfifo32 number

blank number

where number is 4 * pixel_delay + blank_adjust where pixel_delay and blank_adjust are in range 0 .. 3. pixel_delay delays pixels before they are sent to the DAC and blank_adjust adjusts the blank pulse for type 2 DAC's. blank should be set correctly for each DAC type automatically. So use it only as a last resort.

latch number

where number is the sum of zero or more of the following numbers:

128

VRAM serial delay latch enable, DRAM latch bits 63 - 0 enable.

4096

Latch video memory data.

8192

Memory data delay latch enable for data bits 63 - 0.

16384

Memory full clock pulse enable.

Default is to switch all settings on (they are on on my card by default anyway).

Note that these commands may vanish again once they are no longer needed for debugging purposes.

There is no 320x200 mode in the EEPROM of the Mach32 at all, however I defined one in the default configuration file for you. This is the best thing I could get up on my card/screen. Note that it will probably have big borders on your screen, and black lines in between the pixel lines. This is because of the lack of low clocks < 16MHz on the Mach32 and the lack of a line doubling mode as VGA has. The Mach32 is not intended for such low resolutions. If you find a better mode or have an idea, please let me know. You can also just remove my timings from the default configuration file.

## 7. THE CONFIGURATION EEPROM
Ah yes, about the EEPROM, I figured out how to read out the Mach32 EEPROM. I did it by disassembling the BIOS routine mentioned in the docs. I then redid it in C. The driver will use everything it finds there.

Use the Mach32 install tools (they should have reached you together with your Mach32 VGA card) to setup your card/monitor combo correctly. The monitors setting from the config file (or default of 35kHz or something) will be obeyed by the driver nevertheless (for safety!).

As you probably know already, accessing the EEPROM causes some screen flickering. If this annoys you (or even worse your monitor) have a look at the mach32eeprom command described below. This allows you to put the data from the EEPROM into a file and which can be read whenever it is required.

Don't even think about changing the contents of the file. (There is an easily faked checksum in it.). Anyway the driver ensures (hopefully) that no damage can be caused.

Also, if some mode is not well aligned on your screen or you don't like it's sync frequency, consider using the Mach32 install utility (setup for custom monitor) and set one up interactively. If there is no valid faster (higher VSYNC) standard mode given in the EEPROM the driver will use that mode. You will find that this is fun compared with calculating video timings for /etc/XF86Config or /etc/vga/libvga.config.

However the install utility does restrict the maximum pixel depth for custom modes sometimes unneeded hard and the driver obeys that. (Hmm.. actually it should be smart enough to decide itself which pixel depth it can use in that mode.) Since the standard modes are usually only slightly shifted to one side a file with the configuration commands representing the standard modes is given in mach32/mach32.std-modes in the svgalib distribution. You can use these as a starting point.

But here are some real problems:

## 8. EEPROM WOES
I got 2 reports of people having problems with incorrect EEPROM checksums. Both had motherboards with onboard Mach32 VGA's from AST. I guessed a checksum algorithm from those reports and put this in the code in addition to the standard ATI style. Still I got a report of someone whose EEPROM was completely empty. If you have problems with checksums send me the output of mach32info(6) and I'll see what I can do.

By default svgalib writes a complaining message and ignores the contents. You can have svgalib ignore the checksum and contents with the configuration command

mach32eeprom ignore

Then you can decide to use the partial info that is still in it. Use

mach32eeprom ignore usetimings

to use the videomodes that are defined in the EEPROM (if no better modes are known by the driver). This is usually safe, because the driver knows which modes are safe for your hardware (if clocks, monitor and ramdac are configured correctly). You can also allow the driver to use the configuration for the linear frame buffer in the EEPROM:

mach32eeprom ignore useaperture

or

mach32eeprom ignore usetimings useaperture

However I discourage this because the driver will just enable what the EEPROM says about the aperture. Use mach32info(6) to check the address it will choose is safe. It might be better to use setuplinear to set up a 4MB aperture at a free address range.

## 9. THE MACH32EEPROM COMMAND
The mach32eeprom allows to work around these problems. Here is the complete description for this configuration command.

mach32eeprom filename

The filename has to begin with a "/". Unfortunately reading the EEPROM causes annoying screen flickering and is slow. To avoid this, specify a filename from which to read the contents of the EEPROM.

If the file cannot be read, the EEPROM is read out and the file is created. There is a very simple checksum put into this file. Although it can easily be fooled, don't change the file except you know very, very well what you are doing.

Also, as long as the file exists, changes in the Mach32's EEPROM are ignored. Delete the file to recreate an updated version on next use of svgalib. You should ensure that the permissions of the file don't allow normal users to change it. (This may happen if umask has a bad value when svgalib creates the file).

Example:

mach32eeprom /etc/vga/mach32.eeprom

Due to problems with some boards this command got heavily expanded:

mach32eeprom subcommand1 [subcommand2...]

At least one subcommand is needed. Valid subcommands are:

ignore

Don't complain about checksum and don't use any EEPROM contents.

useaperture

Use the configuration for the memoryaperture given in the EEPROM.

usetimings

Use videomodes found in the EEPROM of the board.

nofile

Forget about any filename that maybe was already configured. Don't read a file, don't create one.

file filename

Newstyle form to specify the filename; On contrary to the mach32eeprom filename form it can be mixed with any other mach32eeprom subcommand.

updatefile

Don't read the file, always read the EEPROM (except when ignore is given) and create an uptodate image of the EEPROM.

keepfile

Disable all previous updatefile commands.

compatible

Fall back to default behavior: If checksum on the EEPROM data is not ok, use nothing of the configuration data. If it is ok, configure everything as specified in the EEPROM.

The subcommands are intended to be used together and are performed in the order specified. For example: mach32eeprom ignore useaperture usetimings

will ignore the checksum of your EEPROM, but use its contents. Order is vital! So:

mach32eeprom useaperture usetimings ignore

won't use any configuration from your EEPROM. Be careful with the useaperture subcommand. Please see the EEPROM WOES section. Note that any non understood subcommand will terminate the mach32eeprom command silently! Use only one subcommand per mach32eeprom command to avoid this.

The mach32eeprom command is usually not allowed in the environment variable SVGALIB_CONFIG.

## 10. SETUP OF THE MEMORY APERTURE (LINEAR FRAMEBUFFER)
Due to poor design, Xfree86 insists on setting up the aperture itself. It doesn't reset the original settings at a VC switch once it runs. You should not start X for the first time after a boot as long as an svgalib application is running. This will result in pre X values being restored at a VC switch by svgalib. If you use svgalib and XF86_Mach32 together, run X first or at least do not start it while any svgalib appl. is still running. After X was started once you can use svgalib and X in all combinations w/o any problems. Xfree uses whatever address is given in the MEM_CFG Mach32 register for a 4MB aperture, even if the aperture is not already enabled and the value in this register is pointless garbage. This is IMHO a dangerous bug as some systems may work only with a 1MB aperture.

However, usage of a correct EEPROM circumvents any such problems. If you cannot use that, use mach32info (6) to find the address in MEM_CFG. Then, if it is a senseable setting for your system, enable a 4MB aperture at that address with setuplinear. Ensure that no other card or memory uses the address range you choose.

## 11. ACCELERATOR SUPPORT AND OTHER WEIRD FEATURES
This version now has support for all accelerator functions of svgalib. However they were intended for use with the cirrus chips. It may happen that at runtime they find they cannot emulate the function actually requested. Then you should disable the corresponding blit function (at least for that application) with the blit config command.

Data transfer between the host and the Mach32 is normally via I/O. This proved to be pretty slow. If a big enough aperture is available, a simple memory copy is used instead. This is usually much faster. You can change which method is used with the blit command. This I/O option affects only vga_imageblt(3). The other functions are incredible fast.

For type 2 DACS, there is support for 8 bit per color (instead of the normal 6) in the RGB triple in the color lookup table of the 256 color modes. This can be enabled by an application, if it supports it. The testaccel(6) demo uses it if supported by your hardware. You can use vga_ext_set(3) to use it from your programs.

## 12. RAMDACS
Mach32 Ramdacs are specified by a type in range 1 .. 5. This type can be queried from the Mach32 and then specifies how to set up the ramdac. A list of actual hardware chips used for each type exists, but is not of much use. The Mach32 will return a type and the ramdac will be completely hardware compatible to one of the given type.

Type 1 and 4 Dacs need different clock frequencies for high colormodes. For 32K/64K colormodes the frequencies have to be doubled and for 16M colors (type 4 only) they have to be tripled. I followed the ATI scheme and did this internally. However this means that for 32K/64K you can use only clocks for which the doubled frequencies can be generated as well.

This is no hard restriction as the 16 clocks of the Mach32 can be divided by 2. Thus if you setup some mode yourself try to use one of the divided clocks in your timings and I can use the undivided clocks internally.

It is a real restriction for 16M colors. ATI themself only supports 25MHz (640x480) here by use of a 75MHz clock. Depending on your clock chip other values may be usable as well. Even the doubled/tripled clocks have to be less than the magic 80 MHz. However the driver does all this itself. It may just happen that some of the predefined or one of your handmade mode-timings can't be used because the clock that is used cannot be doubled/tripled. Even though there is already some tolerance in the driver you may fix that by slighty changing the clock values that you set with the clocks command. But note that this will as well affect the ability of the driver to calculate video timings and thus it ability to check the monitor and DAC safety restrictions.

In addition (in complete contrast to my original ATI docs) RAMDAC 4 does not support RGB with blue byte first but only with red first. This required special handling and me adding a bunch of functions to all modules of svgalib and vgagl. The added functions are of lower performance than the usual functions. However most data has to be completely mangled, so I doubt that it can be done much faster. Sorry.

Of course, I might have forgotten to port some parts or even confused things. About bugs in the gl and drawing libs, please ask Harm. But then, I'm able to emulate a BGR ramdac on my card, so I should even be able to reproduce your problems.

Recently I hear often about type 6 ramdacs in non ATI Mach32 cards. There exists no info about these dacs, thus I cannot support them. The driver assumes unknown DACs can stand up to 80MHz in 256 color clut modes and does not touch the ramdac (that is, assumes it is in the 256 color mode already)

To get rid of the warning message you can use the

ramdac n

configuration command. It allows to explicitly set the type of the dac to n (in range 0 to 5). Ramdac 3 is the most dumbest ramdac possible, s.t. you can use it without any fear for your hardware.

ramdac dumb

is equivalent to ramdac 3.

ramdac auto

switches back to the default autodetection.

## 13. MEANING OF THE DETECTION MESSAGE FROM SVGALIB
Some programs (which do not switch it off) will show a

Using Mach32 version (sizeM at adrM (how), memK mem, DAC dactype)

line. This will show up in testlinear(6) etc but will probably scroll away when you use vgatest(6). In this line:

version

is the version of the driver (as of my counting, not the svgalib version).

size

is the size of the memory aperture. It can be 1 or 4 (1 will lead to not using the linear aperture if your card has more than 1MB memory, however applications can still use the 1MB aperture and page the video memory through it in 1MB steps). size can also be no if no aperture is setup at all.

adr

is the base address of the aperture in MB.

how

is autodetect if the aperture was setup this way already when the program started. It is setup when the the setting was enforced with a setuplinear configuration command. It is EEPROM when no aperture was detected, but parameters to set it up were found in the EEPROM.

mem

is the amount of memory the card reported to have.

dactype

is the type of the DAC that was detected. If a special ramdac type was set with the ramdac command a (set) will be displayed after dactype.

If mem, dactype and/or the chipset were enforced with chipset from the configuration file or vga_setchipsetandfeatures(3) a forced will be appended to the line.

## 14. CONCLUSIONS
A final word: I have an ATI ULTRA PRO/2MB/EISA with a Type 2 DAC. My monitor is an EIZO F550i-M. Everything I tried works on it like a charm. However, I couldn't try it with other machines myself and esp. other DAC's. Fortunately the Type 2 DAC is the worst to code. So I will probably have gotten the other DAC's right. But please be warned!

I did my very best to code the driver to support the other DAC's by just reading the docs. But i can't give any definitive guarantee for it to work or even not damaging your hardware. So please be careful!

Note that you will have to set the environment variable SVGALIB_MACH32 to ILLTRYIT if your DAC is not type 0, 2, 3 or 4. This will of course change if no one with a DAC equal to 1 or 5 has serious problems. If you have a different DAC, making patches to support your card will be much more helpful instead of just complaining. If you have a different DAC that works well tell me as well such that I can remove the need for SVGALIB_MACH32 in the next release. Still, even now, after years, I got no reports of a Mach32 card with a type 1 or 5 ramdac. Go figure.

Thank you for your audience and wishes you will enjoy this driver,

Michael.

## FILES
/etc/vga/libvga.config

/etc/vga/mach32.eeprom

## SEE ALSO
svgalib(7), libvga.config(5), mach32info(6).

## AUTHOR
The Mach32 driver and this documentation was written by Michael Weller <eowmob@exp-math.uni-essen.de>.


threedkit

title: threedkit(7)

summary: a set of functions for 3D support.

text:
# threedkit(7)

## NAME
threedkit - a set of functions for 3D support.

## DESCRIPTION
The 3dkit consists mainly of the following triangle functions gl_striangle(3), gl_swtriangle(3), gl_triangle(3), gl_trigetcolorlookup(3), gl_trisetcolorlookup(3), gl_trisetdrawpoint(3), gl_wtriangle(3).

Beware, these functions are not a direct part of the svgalib library. Instead their source is part of svgalib and can be found in the threeDkit/ subdirectory of the original svgalib distribution. However, it is not installed in the system by default, s.t. it is unclear where you can find it if your svgalib was installed by some linux distribution.

In case of any such problem, simply get an svgalib distribution from the net. You even don't need to install it. Just make in the threeDkit/ subdirectory. As of this writing, svgalib-1.2.12.tar.gz is the latest version and can be retrieved by ftp from sunsite.unc.edu at /pub/Linux/libs/graphics and tsx-11.mit.edu at /pub/linux/sources/libs which will most probably be mirrored by a site close to you.

The functions are defined in the tri.o and triangl.o files (or their resp. sources) which you must link to your program.

## EXPLANATION ON 3DKIT.C
This is main engine for 3D rendering.

Program flow:

1.

The function called from outside of 3dkit.c is TD_drawsolid. This first calculates the rotation matrix from the camera rotation angles (see below for more details). It then allocates memory for the temporary array for holding temporary coords in subsequently called functions. It also sorts the surfaces from furthest to closest; according to the distance of the centre grid-point of each surface from the camera. It also establishes whether ROTATE_OBJECT option is on and zero's the camera position if so --- this is for displaying the object at the screen centre like in a 3D CAD package, as apposed to virtual reality where the object can be anywhere and the actual camera position can move.

In the case of ROTATE_OBJECT being on, although the camera position is zero, some distance has to be placed between the camera and the object (or else it would appear to be infinitely large on the screen). This is done using the variable s_cam which is initialized to distance which is set by the calling application. It then loops through each surface (ordering them in the way they were just sorted --- i.e. according to sortarray indexing) and calls one of five graphic routines to write the 3D surface to the hardware.

2.

Assume that TD_drawsolid then calls TD_drawmesh. Here, each surface grid point is first TD_translate'd into a 2D screen point and stored in the temp array. There are obviously w(idth)*h(eight) points in the grid. Following, each line from the 2D temp array is drawn on the screen. To draw the surface, the corner wishbone (two lines) from each grid square is drawn while advancing across and the down. After completing the scan, the furthest two edges of the surface must then be filled in, vis.:

_ _ _ _ _ _

|_|_|_|_|_|_

|_|_|_|_|_|_

|_|_|_|_|_|_

|_|_|_|_|_|_

|_|_|_|_|_|_

| | | | | |

To understand the object rotation, a knowledge of matrix multiplication is required. I once derived a camera rotation before I learned matrix computation. It amounted to the same thing, but was unnecessarily complicated to optimise.

3.

TD_translate called from TD_drawmesh (and others) converts from the 3D grid point coordinate to the 2D screen coordinate using: (a) the three camera position coordinates, (or the single camera distance value, s_cam, if ROTATE_OBJECT is set), and (b) the three camera rotation angles. However, the three camera rotation angles have already been converted into a rotation matrix when TD_calc_rotation_matrix was called by TD_draw_solid. To convert from a 3D coordinate to a 2D screen coordinate, the camera position (or more correctly, the position of the object from the camera) must first be added to each of the 3D grid coordinates. If the user has chosen to use 32 bit values for the discription of the surface, then these must be right shifted to the same size as the 16 bit case.

x, y and z now hold the 3D position of the object relative to the camera centre (or in these terms, the centre of the video screen RIGHT ON the screen). The vector [x y z] must now be multiplied by the rotation matrix. The xt value must also have the camera distance, s_cam, added to it in case the ROTATE_CAMERA is set (in which case x_cam, y_cam and z_cam (the camera position) will be zero and instead s_cam will have a value to provide the necessary object-camera distance). A test is also made as to whether this value is zero or negative. In the case, the point is too close to the camera, or behind the camera, and must not be drawn.

After the multiplication, the resulting vector [xt yt zt] has been rotated to be aligned with screen. The vector is now adjusted for perspective by dividing the yt and zt values (horizontal and vertical respectively) by the xt value (into the screen). Division is done by muldiv64 because the intermediate product is larger than 32 bits. xscale and yscale are factors that scale the image to size. posx and posy is just the centre of the screen, or more precisely:

The exact position of the pinhole camera viewing the object.

4.

TD_calc_rotation_matrix calculates the nine entries of the 3 by 3 matrix used in TD_translate. In order that only integer arithmetic is performed, these values are stored and used as integers. Since this matrix's entries are always between -1 and +1, they have to be integer left shifted to give them accuracy. TD_MULCONSTANT scales them to sufficient bits of accuracy before they are converted to integers. This also means that results (of multiplications with them) have to be scaled down by the same amount. This scaling is inherent in the final multiplication and division (muldiv64) done in the TD_translate function, so an extra division is not consumed.

The rotation matrix effectively rotates the vector by the Eulerian angles alpha, beta and gamma. These angles represent successive rotations about each of the 3D axes. You can test which angles do what by looking at the calling application. Their precise definitions are not all that important since you can get the keyboard to do the right thing with a little trial and error.

Intrisics of drawing non-transparent surfaces...

to be continued ?!

## SEE ALSO
vgagl(7), svgalib(7), gl_striangle(3), gl_swtriangle(3), gl_triangle(3), gl_trigetcolorlookup(3), gl_trisetcolorlookup(3), gl_trisetdrawpoint(3), gl_wtriangle(3), plane(6), wrapdemo(6).

## AUTHOR
This manual page was edited by Michael Weller <eowmob@exp-math.uni-essen.de>. The demos, the initial documentation and the whole threedkit stuff was done by Paul Sheer <psheer@icon.co.za>.

Paper mail:

Paul Sheer

P O BOX 890507

Lyndhurst

Johannesburg 2106

South Africa

Donations (by check or postal order) will be appreciated and will encourage further development of this software. However this is strictly on a voluntary basis where this software falls under the GNU LIBRARY GENERAL PUBLIC LICENSE.