Apart from a few readme's, this directory contains all man pages for svgalib.

I case you want to see one prior to installing svgalib, you can use

man -M. manpage

to see the page if you man binary supports it. If not, and if you have
nroff or groff the tman script in this directy can be used as:

tman manpage

tman will have problems with the compressed files. However, the error
message will indicate at which manual page you should look instead.

Finally,

make ascii
make lpr
make dvi
make ps

will produce documentation files in these format for nice printouts in
this directory. 'ascii' is an Ascii file to be viewed on a terminal.
'lpr' is an ascii file too, but will contain <Backspace> characters
to emulate bold and underlined on a line printer.

make clean

will remove these files again.

The file ../0-README is actually an ascii printout of svgalib.7

Hi!
I wrote a set of SVGAlibish joystick routines while I played with porting
DOSDoom to SVGAlib.
It is compatible with both the older joystick driver for Linux 1.x and 2.0
and the newer joystick driver that is in recent 2.1.x kernels.
Some of the code is ripped from the userland tools joystick-0.6.7 and
joystick-2.0.6 none of wich has any special license attaced to them.

The files are:
joydev.h:      my userland version of the kernel joystick.h
vgajoystick.h: library include file analog to vgakeyboard.h and vgamouse.h
joystick.c:    the library routines.
joytest.c:     a simple test program/example

I dunno how useful these will be, but I could at least use them in doom. (Not
that joystick control in doom adds anything, I just implemented it for
completeness.)

BUGS:
Only one joystick device at any time (but the new 2.1.x driver will let you
map 4 axis and 4 buttons to one logical device).

The routines:

int joystick_init(const char *joydev, int verbose, FILE *file);
This one inits the joystick routines and opens the device. Returna the
filedescriptor of the joystick device if successfull or -1 if not.
Outputs some messages to stdout id verbose is != 0. If file != NULL it will
try to recalibrate the joystick and output the recalibration instructions to
the struct file pointed to by file.
E.g.

if (-1 == joystick_init("/dev/js0, 1, stdout))
{
    printf("Joystick init failed\n");
    exit(1);
}

void joystick_close(void);
Shuts down the joystick.

int joystick_update(void);
Reads the joystick and calls the joystick handler if anything events are
availible. Should be called every now and then.


void joystick_sethandler(__joystick_handler jh);
Install a user supplied joystick handler.

A user supplied joystick handler would look like this.
void joystick_handler(int event, int number, char value);
int event - event type:
  JOY_EVENTAXIS         an axis has moved
  JOY_EVENTBUTTONDOWN   a button has been pushed
  JOY_EVENTBUTTONUP     a button has been released
int number - the axis or button number for this event 0=x axis or button 1, etc.
char value - value for axis events (-128 .. 0 .. 127)

void joystick_setdefaulthandler(void);
Restore the default joystick handler.

char joystick_getnumaxes(void);
char joystick_getnumbuttons(void);
Retrun the number of axes/buttons on the joystick.

char joystick_getaxis(int a);
char joystick_getbutton(int b);
Querys the jostick state from the default joystick handler if it is used.

The following macros calls joystick_getaxis() or joystick_getbutton().
joystick_getb1() - Gets button 1
joystick_getb2() - Gets button 2
joystick_getb3() - Gets button 3
joystick_getb4() - Gets button 4

joystick_getx()  - Returns the X axis
joystick_gety()  - Returns the Y axis
joystick_getz()  - Returns the Z axis

That all folks,

Daniel Engstr�m
daniel.engstrom@riksnett.no

Background mode is not working with kernels in the 2.3 series (due to the
removing of the possiblity to mmap /proc/self/mem).
If you wish to use svgalib with kernel 2.3.27 or later, edit Makefile.cfg,
and comment out the BACKGROUND = y line.

** Svgalib keyboard scancode remapping: the Readme **

** Introduction

After a poll on Slashdot.org about keyboard layouts, I decided to switch from
QWERTY to the Dvorak simplified keyboard. (Such is the power of Slashdot!) It
was easy to switch the keymaps used by the console and X and even LILO, but
svgalib programs that used raw keyboard weren't affected since they interpret
the keyboard scancodes into characters themselves - often assuming a standard
US keyboard with QWERTY layout.

In order for my machine to present a ``unified front'' with a single consistent
keyboard layout, I added to svgalib the ability to remap scancodes. This is
done in keyboard_getevents(), before the event handler is called, so it will
work whether or not a program provides its own handler. Programs that do not
use raw keyboard are not affected, so by setting both the console and svgalib
itself to use the same keymap a consistent keyboard layout is available to all
svgalib programs.


** Background

When you press or release a key on your keyboard, it sends a byte of data to
your computer. The top bit indicates whether the key was pressed or released,
and the lower seven bits hold the scancode, a number that uniquely identifies
the key. A program on the computer interprets these scancodes as representing
characters (`A', `%', etc) or actions to be taken (`Page Up', `Back Space') or
modifiers that alter the interpretation of other keys (`Shift', `Alt', etc).
Most programs do not perform this interpretation themselves, but leave it up
to some other piece of software: the system BIOS, or the operating system,
or the graphical user interface system.

On Linux this is normally done by the kernel or by the X server for X clients,
but this doesn't meet the needs of some programs (especially games) which
care more about whether a key is up or down than what it means and treat the
modifiers the same way as other keys. These programs open the keyboard in `raw'
mode and deal directly with scancodes.

The problem comes because these programs often do need to interpret the keys
into characters, or it is important for a certain key to be identifiable to
the user as being associated with a certain key. For instance, a game player
might need to type a description of a saved game or be directed to press a
certain key to activate a game feature. Interpretation of keyboard scancodes
can be difficult since there are many different keyboard layouts which do not
have the same associations between scancodes, modifiers, characters, and
commands. So the author of the program must choose between writing a complex
and customizable conversion routine that can handle any layout the user might
have, and a simple routine that is hard-coded to use a single layout. In the
latter case, users of other keyboard layouts will encounter numerous
discrepancies between what he or she tries to type and what the program
interprets.


** How it works

Svgalib's scancode conversion is meant to at least partially fill this gap by
converting the scancodes that the keyboard produces to equivalent, or nearly
equivalent, scancodes for the keyboard layout that the program expects. The
program then (hopefully) interprets the new scancode into the intended
character.

As an example, let us consider a US keyboard with Dvorak layout and the game
Quake, which expects a US keyboard with QWERTY layout. Both layouts have the
same scancodes for each physical key, but different characters are produced.
For intance, the first row of letters produces the scancodes 16 through 27, but
on QWERTY this produces the charaters qwertyuiop[] while Dvorak produces
',.pyfgcrl/=. Thus when the Dvorak letter `p' is pressed, the scancode 19
is interpreted by Quake as the letter `r', which occupies scancode 19 on the
QWERTY layout.

The solution lies in the fact that svgalib acts as an intermediary between the
keyboard and the program and has the opportunity to present a different
scancode to the program than the keyboard produced. In this case we tell Quake
that the scancode was not 19 but rather 25, which is the letter `p' in the
QWERTY layout, so when Quake interprets the scancode the correct character is
produced.


** The keymap files

In order to know what scancodes to convert to what other scancodes, a keymap
file is read which lists scancodes produced by the keyboard and their
equivalents in the layout expected by the program.

A program called svgakeymap is provided to generate these maps from the
keytable files in /usr/lib/kbd/keytables; you must have perl for it to work.
Creating a keymap file with svgakeymap is easy; to make a map to convert
scancodes from a US Dvorak keyboard to a US QWERTY keyboard as for our example
above:

  svgakeymap dvorak us > dvorak-us.keymap

The path and .map and .gz suffixes are automatically added if necessary. If
your keytables are stored elsewhere, specify a complete path. If only one
keytable is specified, a keymap is generated that performs no conversions but
contains the correct key names so you can specify scancodes used by fake
keyboard and mouse events by name instead of by number. If none are specified,
this is done for the standard US QWERTY layout.

dvorak-us.keymap and default.keymap (the US QWERTY layout) are provided with
the svgalib distribution and can serve as an example if you wish to make your
own keymap files manually or create an improved generator.


** Configuration

You can specify a keymap to use for all svgalib programs (keeping in mind that
only those that use raw keyboard are affected) by putting a line like this into
libvga.config or ~/.svgalibrc:

  kbd_keymap /etc/vga/dvorak-us.keymap

You must specify a complete path to the keymap file. If no keymap is specified,
no conversion is performed.

You can also override the global keymap by setting the environment variable
SVGALIB_KEYMAP to point to the appropriate keymap file. This can be useful if
some programs support alternate keymaps directly but not others, or if
different users use their own keyboard layouts based on preference.


** Security issues

It can be dangerous to let users arbitrarily reassign keyboard scancodes; for
instance all keys could be routed to an unused scancode, making the console
unusable. To prevent this, put the option kbd_only_root_keymaps into
libvga.config; only keymaps owned by root will be accepted, so the available
keymaps can be limited to safe ones.


** Bugs and limitations

There are no known bugs, but there probably are some. If you find any please
let me know at brion@pobox.com.

Limitations however we definitely have. The scancode conversion performed is
very simple, and can only achieve 100% success when the keyboard layouts being
converted between differ _only_ in arrangement of keys while producing the same
characters from each key. Example: the de facto standard Dvorak keyboard has
the left and right brackets (`[' and `]') on separate keys, with the curly
braces (`{' and `}') produced by those keys when shifted. The standard QWERTY
keyboard produces those characters the same way, the only difference is that
the keys are a row higher on Dvorak; switching the scancodes around results in
proper character interpretation. However the official ANSI standard Dvorak
layout has tho two brackets on _the same key_, one regular and one shifted.
The curly braces similarly have their own key. These cannot be properly mapped
by scancode to the QWERTY keyboard since they produce different characters
in conjunction with modifiers, and the wrong character is produced by the
program.

This could be worked around by interpreting the modifiers in svgalib and
simulating the proper modifier/character keypress/release sequences, but it
would be very complex and would do nothing to help the situation where
characters on the physical keyboard layout do not exist on the target layout
(quite likely when dealing with national or language-specific keyboards);
they cannot be converted into any key sequence since they do not exist.

Ultimately it might be better to set up a ``medium-rare'' keyboard mode where
keys are interpreted into characters but ``raw''-style non-interpreted key
press and release events are available.


** Further information

There isn't really any further information right now unless you want to Use The
Source... More to come in the future. If it does you'll find it at:

  Brion Vibber's Svgalib Stuff - http://pobox.com/~brion/linux/svgalib.html


-- brion vibber (brion@pobox.com)
   3 July 1998

This is a modified version of Josh Vanderhoof's lrmi-0.5 package
The original is available at http://www.planet.net/pjoshv/



vbetest - show available modes, and test a mode

mode3 - set mode using vesa bios. It can usually restore text mode after
        svgalib leaves a non-working text-mode.

vga_reset - call real mode c000:0003, which should be the video card's
	initialization routine. Should work in some cases when mode3 fails to
	restore text mode.

Patching svgalib

Contents

0. Introduction
1. Indenting
2. Structure of the chipset drivers

0. Introduction

	Here is some info on writing patches and/or adding support for
	further chipsets. The info on the chipset drivers is outdated, but
	better than nothing and get you started.

	As a side note, other than a.out, ELF does not allow to have some
	symbols global to svgalib which are not accessible to user
	programs.

	Because of that, if possible all the symbols and functions in your
	program should be static. Those which can not be static should
	have a name like: "__svgalib_*" to mark them as internals s.t.
	people using them get what they deserve. Please do only add a new
	function to the user interface if it is really unavoidable. Better
	add some new parameters to an existing function.

	Adding a new function would definitly result in loosing a.out
	compatibility thus removing the chance to use new cards and such
	with old a.out binaries where the source is not available (doom
	comes to mind).

	A new function should be really important to outweigh this draw
	back.

1. Indenting

	Due to some request (and I heard it b4) all the sources were now
	automatically indentified.

	There were some requests for indent -gnu but it looks painful. I
	opted for -kr (there were requests for it as well) as it is not
	only nicer but also what is done in the linux-kernel and this is
	certainly a program only usable for linux.

	I dunno if emacs is confused by -kr, but to be honest this is a
	big all-in-one egg-giving-wool-milk-sow (as we say in german), and
	you won't tell me that this several megs beast is unable to edit
	this and I can't use -kr due to some restrictions of emacs. That
	would be really ridiculous. If it is the case just make emacs
	better.

	The OneModeEntry macro is eaten by indent (I would say it is an
	indent bug, I might send a bug report to them), please ensure (if
	at all possible) that your code can be passed through indent (use
	the INDENT-OFF comments as shown in some sources for
	OneModeEntry).

	You can use `make indent-gnu' (if you have a recent enough (I use
	1.9.1) indent) to switch to your favorite style. But please ensure
	your patches fit into this now declared as "official style"
	sources. (Use `make indent' to reformat).

	Do not use it too often though as most indent's tend to add empty
	lines at certain places in the source.

2. Structure of the chipset drivers

	The chipset specific registers saving function (saveregs) is only
	used directly to save the textmode registers at initialization.

	The chipset specific registers restoring function (setregs) is only
	used directly to return to textmode, and when setting a VGA mode
	after an SVGA mode.

	The registers for each mode are stored like the ET4000 modes in
	VGAlib 1.2, i.e. the extended registers at the end. The following
	functions must be provided in a driver:

	saveregs( unsigned char regs[] )
		Saves the chipset-specific registers in regs, starting at
		array index EXT (after the VGA registers).

	setregs( unsigned char regs[] )
		Sets the chipset-specific registers stored in regs from
		index EXT.

	modeavailable( int mode )
		Returns nonzero if mode is available (should check video
		memory).

	getmodeinfo( vga_modeinfo *modeinfo )
		Fills in chipset specific field of mode information
		structure: maxlogicalwidth, startaddressrange (mask of
		significant bits), and maxpixels (video memory divided by
		the number of bytes per pixel). haveblit indicates whether
		bitblt functions are available.
		Note: providing extended info and an aperture with size
		>= memory and setting bits 4 and 6 in flags will
		automatically enable linear addressing support.


	setmode( int mode, int previous_mode )
		Sets all registers for a mode; returns nonzero if mode not
		available. __vga_setregs can be called to set the VGA
		registers.

	unlock()
		Unlocks chipset-specific registers.

	lock()
		Lock (protect) chipset-specific registers. Currently not
		called.

	test()
		Identify chipset; initialize (check memory and type) and
		return nonzero if detected.

	setpage( int page )
		Set 64K page number to be mapped at 0xa0000.

	init( int force, int par1, ... )
		Initialize memory and type; called by test. If force is 1,
		the chiptype or the amount of memory can be forced (this
		is pretty useless).

	The following functions provide for things like page flipping
	and hardware scrolling virtual desktops.

	setdisplaystart( int address )
		Sets the display start address in video memory in pixels.

	setlogicalwidth( int width )
		Sets the logical scanline length in bytes. Usually a
		multiple of 8.

	The function getchipset() in vga.c must call the test routine for
	the chipset. The chipsetfunctionslist must be have a pointer
	to the chipsetfunctions table for the chipset (which is the only
	global symbol in a chipset driver). Also, vga.h contains a magic
	number for each chipset. Also driver_names[] in vga.c has to
	contain a name for each driver at the correct position.

Notes for the VESA driver:

The driver's autodetection is disabled by default, so in order to use it,
the line
chipset VESA
must be added to the config file (usually /etc/vga/libvga.config).

The error:
Int 0x10 is not in rom (xxxx:xxxx)
is usually caused by running linux using loadlin, after loading a dos tsr
that changes the int 10 vector, or after windows 95, that does the same
thing. The solution, is either to use lilo, or run loadlin after a clean
dos boot.


There is a new config file option that affects the vesa driver:
VesaText
If this option is used, the driver sets 80x25 text mode (using vesa bios)
before setting any standard vga mode.

This option was added in order to enable standard vga modes with the vesa
driver on Matrox Millenium, but now it has the following effect:
(read in a fixed width font)

chipset              with VesaText          without VesaText

CL-GD5446              works                leaves a messy font when
                                            returning to text mode

Riva 128             does not restore           works
                     previous used text
                     font, but reverts to
                     ROM font.

Matrox
Millenium             works                 does not set standard vga
                                            modes properly.

A list of cards known to work with the VESA driver is:
     * Riva128 (both on a STBV128 and a Viper330)
     * RivaTNT
     * Matrox Millenium 2
     * Matrox Mystique
     * Matrox Productiva G100
     * Matrox Millenium G200
     * Neomagic Magicgraph 128XD (in a Dell Inspiron laptop)
     * S3 375 Virge/DX ( A "Trident Video Excel 3D Accelerator" )
     * S3 Trio3D
     * Cirrus Logic GD5446
     * Rendition V1000 - Only modes up to 800x600 seem to work
     * ATI Expression+ PC2TV 2MB (RageII chipset) - tested only modes up
       to 800x600 resolution
     * ATI Xpert 2000
     * i740 (Diamond Stealth G460)
     * Voodoo Banshee
     * Alliance Technology AT24

Please note that some of this cards have also failed to work in some
cases, so it is _very_ configuration dependent.

For Matrox cards, the advice is to upgrade to the latest bios from Matrox.