
	Ŀ
	     DOCUMENTATION OF THE VESA LIBRARY 1.4 FOR PACIFIC C    
								     
		  (C) 1999, Detlef Reimers, dreimers@aol.com	     
	


	INTRO:

        Vesalib is a compact and easy to use graphics library for all
        the bank switched VESA modes that use 256 colors. These modes
	are supported by almost any VGA graphic adapters. The library
	supports resolutions from 640x400 up to 1280x1024 pixels.

        The library provides all basic drawing commands and also a
        graphical replacement of the printf() function. The library
        uses the small memory model to make small and fast code, but
	I could change this to large, if someone needed it.

	This document gives you detailled information how to compile,
	install and use this VESA library for Pacific-C. It also
	includes many hints and also ideas for further improvements.



			    CONTENTS:
			    

		     1.  ............ The Installation
		     2.  ............ The Compilation
		     2.1.  ............ with pacc.exe
		     2.2.  ............ with ppd.exe
		     3.  ............ The Test
		     4.  ............ The Library
		     5.  ............ The Use
		     6.  ............ The Source
		     7.  ............ The Future
		     8.  ............ The Author


     1. THE INSTALLATION:
     
	First of all, please make a copy of the zip archive and put it
	in a secure place. Sometimes you may need the original files.

	As you read this, you have already extracted the package. These
	files should be placed in a subdirectory inside your Pacific C
	directory. You should use the following directory structure:

				Ŀ
				  PACIFIC  
				
	       Ŀ
	   Ŀ	Ŀ	 Ŀ    Ŀ
	     BIN  	  INCLUDE  	   LIB        VESALIB  
                       
		   Ĵ
	       Ŀ    Ŀ	  Ŀ    Ŀ
	         DOC        PRG  	    SRC        TEST	
	           	      

        It's important that the vesalib directory is at the same level
	as the lib directory. Open the vesalib directory and copy the
	included header file "vesa.h" to the main "lib" directory of
	the Pacific C compiler package.

	Since version 1.2 I have made major changes to this VESA package.
	The VESALIB directory now has four subdirectories. All
	specific files are placed into the appropriate folders. There
	is one central batch file, which allows you to compile and test
	the library and do other specific tasks related to the library.

	All earier C functions (version 1.1 and 1.2) have been converted
	to assembler and optimized for speed. Now there are even more
	demo programs that show you many different uses of the library.

	Version 1.4 corrected a really nasty bug, that I found in the
	starting code. The palette function was also corrected and is
	much faster now. The text function has vanished, because now
	print can do it all in one function. There is one more parameter,
	that has to be passed to print (c2). If this parameter is 0, it's
	the normal print, otherwise the character is shadowed with
	color c2. Totally new are the moveto, lineto, curveto/bezier and
	bmode functions. Please, read the command summary to get detailed
	information. At least there are two support functions waitkey
	and bye. They have been added, because you don't have to link
	other big libraries only to get keyboard response or the ability
	to quit the program.

	I use the demo files as instructional programs in my own cs-
	classes. The source code is well structured and only elementary
	C functions are used. So there shouldn't arise any greater
	problems, if you also intend to use them for educational purpose.


     2. THE COMPILATION:
     
	You can compile the library from the source file "vesalib.as"
	either with the command line compiler "pacc.exe" or with the
	integrated development environment "ppd.exe".

	If you don't have the command version of the compiler you
	can download it from many places on the web or via fpt. You
	will find it at:

		ftp://ftp.htsoft.com

	or at the HighSoft WEB-site:

		http://www.htsoft.com

	Now you should start the central batch file "run.bat" from
	this directory. It makes the building of the library a snap.

     a) Compilation with pacc.exe:
	--------------------------
	To compile the library with "pacc.exe", you only have to
	choose the option "c" from inside the batch file.

	After pressing this key the library will be created instantly
	and it will also be placed to the correct lib directory,
	from which you have easy access to the library.

     b) Compilation with ppd.exe:
	-------------------------
	If you want to compile the library with the ide "ppd.exe",
	you have to choose the option "p" from inside the batch file.
	ppd will start and load the assembler source "vesalib.as"
	and also the preconfigured project file "vesalib.prj".

	Now you should open the menu item "output file name" in the
	main menu "Make". If the name and the directory you'll find
	are correct, you can easily compile the files to produce the
	library by activating the menu item "Make" under the same
	menu.

	Congratulations! Now you have compiled your own library file,
	it is called "86--dsv.lib". Why do I use this strange name?
	Mainly it has to do with the somewhat strange naming convention
	of Pacific C. The names of all runtime libs start with
	"RT86--D", all other C libraries names start with "86--D".

	The characters, directly following after this, specify the
	memory model used by this specific library. "S" stands for
	small memory model and "L" for the large one. If the last
	character is an "F", this is a floating point library.

	I used the above name, because now you can compile your
	graphic programs very easily with the following sequence:

		pacc foo.c -lv

	The compiler reads it the following way: Look inside the
	system library directory for this file, because it does not
	contain any directory specification and it is also not a full
	name like "vesa.lib" or something similar.

	Now we come to the most important part. During compilation
	all system library names are stripped down to their specific
	parts, so in this case, the "v" from the compiler commamnd
	is read like this by the compiler:

	Look inside the system library directory for the files
	"86--DS.." or "86--DL..". Because I used the small memory
	model, my name uses the acronym "DS". If you change the
	library name to something like "vesa.lib", you would have to
	compile your graphic programs with the following command:

		pacc foo.c -l<directory name>\vesa.lib

	This is actually much more complicated then the first command
	line. That's, why I used this strange library name.


     3. THE TEST:
     
	First of all you should run the test files, that accompany the
	library files. You can easily start the whole test range from
	within the batch file "run.bat" by choosing the option "a",
	which stands for "all".

	Now all the test programs will be compiled one after the other,
	and after a successful compilation they will be started.
	At the end the program will instantly be deleted from the
	test directory to avoid unneccessary file cluttering.

	If everything was ok, you can be happy, because the library
	works and you successfully passed the whole test range. Now
	you could start to do the real work: programming on your own.
	But please, wait a little while and first read on. There may
	be some specialities, you really need to know before you
	start rolling your own programs.

	The demo files are not only for demonstation purposes, but
	they also serve as living example files, from which you might
	want to cut special pieces for use in your own programs.
	To make life a little bit easier, I also put a tiny batch
	file inside the test directory.
	You can compile the demo files and also your own programs
	with the help of this batch file. Choose the "test" directory
	and start compiling with the command:

		c foo.c

	Your program will be created and started from this batch file.
	After the program finished, it will be deleted together with
	all the other files normally produced during compilation.

	If your monitor has problems with some of the VESA modes, you
	should read on, because managing this situation will also be
	discussed in depth later in this document.


     4. THE USE:
     
	The normal use of this library is very easy, because it is
	self contained. If you make your own graphics programs, the
	only mandantory line in your source file will be:

		#include <vesa.h>

	The header file has all library information the compiler
	needs for compilation. The above line is only true if you
	placed the header file into the "lib" directory of Pacific C.
	If you don't want it to be there, you should use the line:

		#include "vesa.h"

	All graphic functions are prototyped, so there should be no
	warning messages during compilation. The basic types are also
	declared in this file, especially the "byt" type. This one is
	needed for the palette function setcol(). Here the pointer
	structure of the font is declared and also several variables

	I just implemented bezier curves as native library functions,
	Please notice that the bezier routines used in assembler
	code, are my own copyright. You will not find those routines
	in any other libraries, because they use a highly optimised
	algorithm, which by itself depends on some very sophisticated
	math routines. If you want to change them, you are free to
	do so, but please mention  my authorship in your code, if
	others will use it. If you are also interested in the
	mathematical background for this algorithm, you can send me
	an email. I will send you a paper, which explains this routine
	and also gives valuable background information about bezier
	splines in general. (I also like to code in PostScript
	directly and you will find some nice demo programs related to
	this subject. In the near future I also want to translate a MAC
	program, which I programmed some years ago. It will fit any
	curves to bezier splines and produces pure PostScript output
	ready to print on a LaserWriter or to be importetd in other
	high quality output applications.


     5. THE LIBRARY:
     
	Now we come to the library itself. I will explain its contents
	in short. VESALIB is intended as a basic library with easy to
	use in mind, but you can extend it to your own needs.
	I have consulted my theoretical books about graphics
	programming to get this code work and I learned a lot about
	graphics programming in general and also about the compiler
	specific assembly language implementation of the functions.

	The VESA library works for all VESA modes with 256 colors.
	You need a VGA monitor that supports the VESA 1.2 standards.

	You also need a 386 processor at least, because I use some
	386-specific code in the library. All functions will also
	work with VESA 2.0 and 3.0.

	The test programs only use mode 101h, 103h and 105h. Your
	monitor should have no problems with these resolutions.

	  Ŀ
	   Mode 100h:     640*400 pixel, 256 colors,	4 banks 
	   Mode 101h:     640*480 pixel, 256 colors,	5 banks 
	   Mode 103h:     800*600 pixel, 256 colors,	8 banks 
	   Mode 105h:    1024*768 pixel, 256 colors, 12 banks 
	   Mode 124h:    1152*864 pixel, 256 colors, 16 banks 
	   Mode 107h:   1280*1024 pixel, 256 colors, 20 banks 
	  

	All resolutions work in bank switching mode. This means that
	every time your pixel address gets larger then 64k, the video
	bank will be switched to the next one. If you want to use the
	new VESA 2.0/3.0 video modes with linear frame buffers, you
	have to use a pure 32 bit compiler, because these function
	won't work in the real processor mode, but only in 32 bit
	protected mode. (Of course, this is what DJGPP is for!)

	All modern VGA monitors should normally support these banked
	modes, but there is one thing I want to mention:

	I assume that your VGA card has a granularity of 64k.

	The granularity is the amount of bytes to switch between the
	video banks. I'm aware of the fact that there are some very
	special cards around, which use smaller granularities down
	to 4k.

	If you have one of these cards, you should change the
	granularity value. I used in the sourcecode "vesalib.as".
	I have marked the position with "!!!" at the end of the
	assembler file. So you can read the comments, take your
	calculator and change the values to your needs.

	Here is an example of mode 101h:

	If your video card has a granularity of lets say 16k,
	recalculate the number of banks for this mode with the
	formula:

		bank numbers = hor * ver / granularity

	For mode 101h this means: n = 640 * 480 / 16384 = 18.75,
	which means, you have to choose n = 19. Then go to the end
	of the file and change all the banknumber values this way.

	But first you should assemble and link the file "vesainfo.as".
	You can also do this with the help of the batch file "run.bat".
	Simply choose the option "v" and the file "vesainfo.as" will
	be compiled and started.

	You should see a screen like this one (on my DELL computer).

	MODE 	HOR x  VER  LINE  GRAN  BITS  BANK  PLAN   COL
       
	100h 	640 x  400   640   64k     8     1     1     4
	101h 	640 x  480   640   64k     8     1     1     4
	103h 	800 x  600   800   64k     8     1     1     4
	105h  1024 x  768  1024   64k     8     1     1     4
	109h 	132 x	25   264   32k     4     1     4     0
	10Ah 	132 x	43   264   32k     4     1     4     0
	110h 	640 x  480  1280   64k    15     1     1     6
	111h 	640 x  480  1280   64k    16     1     1     6
	113h 	800 x  600  1600   64k    15     1     1     6
	114h 	800 x  600  1600   64k    16     1     1     6
	124h  1152 x  864  1152   64k     8     1     1     4
	12Dh 	512 x  384   512   64k     8     1     1     4
				     
	The critical information is  	here. If your value is less
	then 64k, you should make the above changes in "vesalib.as".

	If a special mode does not work with your monitor, simply
	disable the appropriate mode line at the end of "vesalib.as"
	in the list of the supported modes by placing a colon at the
	beginning of the critical line.

	After this, compile the library again and run one of the test
	files in your specific video mode.

	For your special mode the program should give you the message:

		"Mode xxxxh is not avaliable."

	After this the program directly stops, so no hardware part of
	your computer will be affected by bad programming. It's just
	hardcoded into the library to quit the program, if a special
	video mode is not supported by the hardware.

	Now lets come to the real thing, the graphic functions. This
	new library version 1.4 consists of a single assembler file.
	The C source isn't needed any more, because I changed all
	souces to assembly language and hand optimized the code. This
	fastened most of the functions remarkably.

	These are the graphic primitives included in the library:

	Ŀ
	     Function	     	   Arguments			   
	͵
             void bye            ()                              
	     int  key	     	   ()				   
	     int  waitkey   	   ()				   
	ĳĳ
	     void gmode     	   (m)				   
	     void tmode     	   ()				   
	     void pmode     	   (m)				   
	     void clip      	   (x1, y1, x2, y2)		   
	     void noclip    	   ()				   
	ĳĳ
             void clear          (c)                             
	     void plot      	   (x, y, c)			   
	     void line      	   (x1, y1, x2, y2, c)		   
	     void bezier    	   (n, c)			   
             void moveto         (x, y)                          
	     void curveto   	   (n, c)			   
             void lineto         (x, y, c)                       
	     void hline     	   (y, x1, x2, c)		   
	     void vline     	   (x, y1, y2, c)		   
	     void rect      	   (x1, y1, x2, y2, c)		   
	     void frect     	   (x1, y1, x2, y2, c)		   
	     void circle    	   (xc, yc, r, c)		   
	     void fcircle   	   (xc, yc, r, c)		   
	     void ellipse   	   (x, y, rx, ry, c)		   
	ĳĳ
             void print          (x, y, c1, c2, *str, ...)       
	ĳĳ
             void setcol         (c, r, g, b)                    
	     void setpal    	   (*p) 			   
	ĳĳ
             void retrace        ()                              
	

	The arguments I used, have the following meanings:

	Ŀ
	 m	     graphics mode or pixel write mode 	   
	 x, y	     coordinates of a point			   
	 xc, yc     center of a circle or an ellipse		   
	 x1, y1     left, top 				   
	 x2, y2     right, bottom				   
	 r	     radius of a circle			   
	 rx, ry     first and second radius of an ellipse	   
	 c	     color value				   
	 r, g, b    red, green and blue values (rgb) of a color  
	 p	     the color palette 			   
	 str	     a text string				   
	

	The "f" in the names frect() and fcircle() stands for "filled".

	I use very short names to make life easier. If you prefer
	more elaborate ones, change them any way you like it. But
	don't forget to change them in all files (also in vesa.h).

	Here is the detailled explanation of all graphic primitives:


    Ŀ
     void gmode(int m) 					     
    
      FUNCTION: 	Starts a specific graphics mode m. It will
			show an error message on the screen, if the
			mode is not supported and quits the program.

      EXAMPLE:		gmode(257)		  // aktivate mode
			{
			  ...(your code)	  // start coding
			}
			tmode();		  // back to text


    Ŀ
     void tmode(void)						     
    
      FUNCTION: 	Activates the normal text mode.

      EXAMPLE:		See last example. Use this at the end of
			your graphic programs to return to text mode.


    Ŀ
     void tmode(int m) 					     
    
      FUNCTION: 	Sets the pixel wirte mode.
			There are four mode available. These are:
			  mode 0:  copy mode
			  mode 1:  and	mode
			  mode 2:  or	mode
			  mode 3:  xor	mode
			The most useful modes are mode 0 (normally
			used) and mode 4 for special animation effects.
			You can see an example in graph.c, where the
			animated point and tangent line is plotted in
			xor mode.

      EXAMPLE:		pmode(3)
			hline(20, 100, 100, yellow);	// xor
			hline(20, 100, 100, yellow);	// now its erased
			pmode(0)


    Ŀ
     void clip(int x1, int y1, int x2, int y2) 		     
    
      FUNCTION: 	Sets up a general clipping rectangle for all
			graphic functions. Only the clear command
			allways acts on the whole screen area. The
			clipping is directly implemented into the main
			drawing commands to make it as fast as possible.
			Because clipping is activated in general for
			all functions, I will not mention it explicitly
			in the following function desciptions.

      EXAMPLE:		clip(100, 100, 500, 300);


    Ŀ
     void noclip(void) 					     
    
      FUNCTION: 	Deactivates clipping (the clipping rectangle
			is reset to the whole screen area, but the
			checking code inside the drawing commands are
			also skipped. This makes the noclip variety
			faster than it's clipping counterpart.

      EXAMPLE:		noclip();


    Ŀ
     void clear(int c) 					     
    
      FUNCTION: 	Clears the screen with a specific color c.

      EXAMPLE:		clear(black);


    Ŀ
     void plot(int x, int y, int c)				     
    
      FUNCTION: 	Sets the point at (x,y) to the color value c.

      EXAMPLE:		plot(25, 100, red);


    Ŀ
     void moveto(int x1, int y1)				     
    
      FUNCTION: 	Sets the current point to (x,y). This function
			is used in conjunction with lineto and curveto.

      EXAMPLE:		moveto(350, 100);
			lineto(450, 300);


    Ŀ
     void lineto(int x, int y, int c)				     
    
      FUNCTION: 	Draws a line from the current point to (x,y).
			This function will come in handy, if you have
			to draw lots of consecutive lines, because
			after the actual drawing it set the last point
			of the line to the new current point.

      EXAMPLE:		moveto(100, 300);
			lineto(450, 350);
			lineto(120, 250);


    Ŀ
     void curveto(int n, int c)				     
    
      FUNCTION: 	Draws a bezier curve from the current point
			to the last of a three point array with color.
			This works quite the same as the lineto
			pendant. In contrary to the bezier function
			it only needs three points, because it always
			uses the current point as starting point. The
			array of points, used by this function, is also
			the globally defined bez[][] array. n is the
			number of line segment in terms of 2^n.
			(Look at the bezier function for more)

      EXAMPLE:		for (i = 1; i < 4; i++)
			  for (k = 0; k < 2; k++)
			    bez[i][k] = 100 + i;
			moveto(100, 300);
			curveto(6, lred);
			curveto(6, lred);


    Ŀ
     void hline(int y, int x1, int x2, int c)			     
    
      FUNCTION: 	Draws a horizontal line from (x1,y) to (x2,y)
			with color c. You may use x2 values smaller
			than x1, the function will correct it. I will
			refer to this special feature as correction.

      EXAMPLE:		for (i = 0; i < 480; i++)
			  hline(i, 0, 639, lcyan);


    Ŀ
     void vline(int x, int y1, int y2, int c)			     
    
      FUNCTION: 	Draws a vertical line from (x,y1) to (x,y2)
			with color c. (with correction)

      EXAMPLE:		for (i = 0; i < 640; i++)
			  vline(i, 0, 479, grey);


    Ŀ
     void line(int x1, int y1, int x2, int y2, int c)		     
    
      FUNCTION: 	Draws a line with an arbitrary slope from
			(x1,y1) to (x2,y2) with color c. An
			optimized Bresenham algorithm is used for
			the line drawing. (with correction)

      EXAMPLE:		line(0, 0, 639, 479);


    Ŀ
     void rect(int x1, int y1, int x2, int y2, int c)		     
    
      FUNCTION: 	Draws a rectangle from left/top (x1,y1) to
			right/bottom (x2,y2) with color c. Only the
			outline will be drawn. (with correction)

      EXAMPLE:		rect(10, 20, 100, 80, yellow);


    Ŀ
     void frect(int x1, int y1, int x2, int y2, int c) 	     
    
      FUNCTION: 	Draws a rectangle from left/top (x1,y1) to
			right/bottom (x2,y2) filled with color c.
			(with correction)

      EXAMPLE:		frect(10, 20, 100, 80, lgreen);


    Ŀ
     void circle(int xm, int ym, int r, int c) 		     
    
      FUNCTION: 	Draws a circular outline with center (xm,ym)
			and radius r with color c. The algorithm used
			is very efficent, because it completely avoids
			multiplications. (zero radius will be set to 1)

      EXAMPLE:		circle(20, 100, 30, lwhite);


    Ŀ
     void fcircle(int xm, int ym, int r, int c)		     
    
      FUNCTION: 	Draws a circle with center (xm,ym) and radius
			r and fill it with color r. (with correction)

      EXAMPLE:		fcircle(30, 100, 40, lblue);


    Ŀ
     void ellipse(int xm, int ym, int rx, int ry, int c)	     
    
      FUNCTION: 	Draws an elliptical outline with center (xm,ym)
			1. radius xr and 2. radius yr with color c.
			( with correction)

      EXAMPLE:		ellipse(300,300, 100, 30, red);


    Ŀ
     void bezier(int n, int c) 				     
    
      FUNCTION: 	The bezier function internally always uses
			the coordinate array bez[0][0]...bez[3][1].
			It draws a smooth bezier curve through the
			given control points p[0] and p[3]. You can
			pass the color to this function as well as
			the number of line segments for drawing in
			terms of 2^n, n is the number of segments.

      EXAMPLE:		for (i = 0; i < 4; i++)
			  for (k = 0; k < 2; k++)
			    bez[i][k] = 300 + 50 * i * k;
			moveto(100, 300);
			bezier(7, lred);	// max n = 7
			bezier(7, lred);


    Ŀ
     void setcol(int c, byt r, byt g, byt b)			     
    
      FUNCTION: 	Sets a specific color to a new r-g-b value.

      EXAMPLE:		setcol(blue, 0, 23, 35);


    Ŀ
     void setpal(byt *p, int c1, int c2)			     
    
      FUNCTION: 	Set up a color palette from color c1 to c2.
			You can use this in conjunction with an own
			definition of a color palette for special
			color effects and the like.

      EXAMPLE:		byt pal[256][3];

			for(i = 0; i < 256 ; i++)
			{
			  pal[i][0] = i % 4;
			  pal[i][1] = i + i;
			  pal[i][2] = i * i;
			}

			setpal(*pal, 0 ,256);


    Ŀ
     void bye(void)						     
    
      FUNCTION: 	Quits the program (after changing back to
			textmode) and goes back to the OS. You don't
			need an external library for this function.

      EXAMPLE:		bye();


    Ŀ
     int key(void)						     
    
      FUNCTION: 	Checks, if the user pressed a key. If the
			key was <ESC>, the program quits immediately
			(after going to textmode). If it was another
			key, it returns 1, otherwise 0 it returns 0.
			This way no conio.h is needed.

      EXAMPLE:		{
			  ... (your code)
			}
			waitkey();		// waits for keypress


    Ŀ
     int waitkey(void) 					     
    
      FUNCTION: 	Waits, until the user presssed a key. If the
			key was <ESC>, the program quits immediately
			(after going to textmode). If it was another
			key, the ASCII code is returned (also for the
			grey keys, the F-keys or the cursor keys).
			This way no conio.h is needed.

      EXAMPLE:		{
			  ... (your code)
			}
			waitkey();		// waits for keypress


    Ŀ
     void print(int x, int y, int c1, int c2, char *str, ...)	     
    
      FUNCTION: 	Print a string on the screen with variable
			arguments at position (x,y) with color c1 and
			with shadow color c2 (no shadow, if c2 = 0).
			This function works like printf(), but in graph
			mode. Floating point numbers are not supported.

      EXAMPLE:		print(10, 10, red, 0, "%d + %d = %d", a, b, c);
			print(10, 10, red, 16, "Hello, world!");
			// the last one prints a string with shadow


    Ŀ
     void retrace(void)					     
    
      FUNCTION: 	Wait for the monitors vertical retrace.

			The retrace() function stands for vertical
			retrace. This is the time, the electron beam
			of the monitor needs to come back to the top
			left point of the screen, when it passed the
			the bottom right edge. This time can be used
			to draw into video memory without interfering
			with the actual contents. This makes smooth
			animations possible and reduces flickering
			substantially.

      EXAMPLE:		rect (10, 20, 100, 200, blue);
			frect(10, 20, 100, 200, lred);
			retrace();
			frect(10, 20, 100, 200, black);

	The animation demos show you how to use the retrace function.

	It's a good idea to use it before any access to the DAC
	registers (when you call a palette function). I used it in
	the animation test files. Try to disable the retrace() line
	and look how it changes the animation. There is a slight
	delay in the movement at periodic intervals. This is due to
	the bank switching, which takes place just at that moment. I've
	already replaced the normal VESA bank switching call 4f02h with
	the much faster far pointer call equivalent, but for real
	smooth moves you should use special software. I have included
	two special files in this packet: "VBE20.exe" and "SPEEDUP.exe".
	The first one will install a VBE 2.0 compatible video driver
	for S3 cards and the other will fasten the display remarkebly
	for S3 video cards. The batch file run.bat lets you install
	these TSR's with the single keystroke [v]. If you run the
	animation demos, you will notice the difference.

	In the header file there are also some special names for the
	basic colors. I always used short names in lower case:

		   Ŀ
		    Color values:		   
		   Ĵ
		    black	0   grey	8  
		    blue	1   lblue	9  
		    green	2   lgreen    10  
		    cyan	3   lcyan     11  
		    red	4   lred      12  
		    magenta	5   lmagenta  13  
		    brown	6   yellow    14  
		    white	7   lwhite    15  
		   

	The character "l" in front of a name is an acronym for "light".

	The following global variables are also important. You can use
	them in any program with this library. The globals are:

	  Ŀ
	    Type       Variable    Meaning			   
	  ͵
	    int        hor	     maximum horizontal pixels    
	    int        ver	     maximum vertical pixels	   
	    int        xcur	     current x-coordinate	   
	    int        ycur	     current y-coordinate	   
	    int        xmin	     clipping rect left	   
	    int        ymin	     clipping rect top 	   
	    int        xmax	     clipping rect right	   
	    int        ymax	     clipping rect bottom	   
	    int        mode	     the graphic mode		   
	    int        clp	     clipping variable (0 if not) 
	    char far   *font	     far pointer to the BIOS font 
	    int        bez[4][2]   the bezier point array	   
	  

     6. THE SOURCE:
     
	If you look at the assembler file "vesalib.as", you will see
	that I used a very short way to access the VESA functions. I
	only used the VESA information block to get the address of the
	bank switching routine, all other information is ignored.

	I could have done more, but I use this library in school classes
	and I know, which hardware equipment we have. So I decided to
	make things very easy and hardcoded the normal banked VESA modes
	and their resolutions into the code itself instead of searching
	for the values inside the appropriate VESA structures.

	I tested this library on 10 different computer systems and I
	found no problems. The only differences are the supported video
	modes, which is due to the different capabilities of the cards.

	The library will first look, if the graphics mode you passed is
	avaliable. In case it isn't, it will give you a message and stop
	the program. This makes it very easy to write your graphics
	program. The main skeleton of every program is simply this:

		gmode(mode);
		{
		  ....		// your code
		}
		waitkey();	// wait for keypress - optional
		tmode();

	The gmode function scans the modes listed in the assembler
	source code and askes the VESA driver, if it is supported.
	If not, nothing strange will happen, your program only quits
	with the appropriate screen message about that mode.

	Please notice that this behaviour is new. Earlier versions
	used another graphics mode initialization. But I realized,
	that there is really no need to make things more complicated.

	At the end of the code you go back to text mode. You can
	leave this out, but that's not good programming style, because
	it might leave you with a cluttered screen, which will not look
	very professional to the user of your programs (although I
	have seen a lot of programs using this bad practice).

	The program will show up your graphics until you decide to
	stop by pressing a key. The waitkey() function is provided
	for conveniance, because you don't need to link externel
	libraries for this functionality.

	In my test programs you will often find the sequence:

		setcol(blue, 0, 23, 35);

	I use it, because I don't like the DOS blue. For me it's much
	to intense, while editing with q.exe. So I made my own blue.
	You can leave it out, if you don't like it.

	There is a small batch file "c.bat" in the test directory. This
	lets you easily compile your own programs with the command:

		c foo.c

	at the DOS prompt. Your source "foo.c" file will be compiled and
	the library will be linked automatically. After this the program
	will be started and then deleted. Please notice, that all programs
	have to be compiled in the small memory model (option -Bs).
	If you compile it with the large model, strange things may
	happen, not harmful, but just not the way you wanted it.
	The mandelbrot program is the only one, which uses hardware
	floating point routines. Therefore I had to include the option
	"-lf" in the batch file "c.bat".

        Please notice, that all demo files only need one header file
        "vesa.h", no other external header files are neccessary to
        compile these demos. I designed the library with easy use in
	mind, so many programs will run without the need of additionally
        linking other system libraries.


     7. THE FUTURE:
     
	I want to extend the library with new functions, but I also
        encourage you to do this, because it's fun to do and we all
        can learn from each other. Things, I would like to do are:

	    - Special polygon and filling routines.

	    - Special plotting functions for easy graphing
	      of math functions.

	    - More palette manipulation.

	    - Mouse functions (I'm working on this). I plan to
	      build up a mouse event handler as a separate library,
	      because often these functions are not needed, so they
	      would only use unnecessary disk space.

	    - Buffer functions for copy and paste rectangular
	      areas from/to the screen to make screen animation
	      with sprites possible.

	    - Support for more fonts (also user fonts). I have
	      some ideas, but I have to try this first.

	    - Loading and saving of pictures (pcx, bmp and gif).
	      I think, I will use and adopt public sources for this.


     8. THE AUTHOR:
     
	I'm a German teacher. My subjects are mathematics, physics
	and computer science. I developed VESALIB especially for
	classroom teaching and for use in a gamers group, but I soon
	realized that others might as well participate in the
	functionality, this library provides.

	So I give it away as free software, because I strongly
	believe that freeware is the right answer to a still growing
	monopolistic software market. The great success of LINUX is
	a great example of superb software that's freely available.
	If this library doesn't fit your needs, simply throw it into
	the basket, but if you like to use it, I would be happy to
	get some feedback from you, telling me which parts could be
	improved or changed. I will always try to implement better
	features and more functions into this library.

	I use EUPHORIA from Rapid Deployment Systems for introductory
	programming projects. It's very easy to use and also powerful.

	For more elaborate projects I use Pacific C from HighSoft.
	Fore me this compiler is easy to handle and very clean in its
	functions. It also conforms very well to the ANSI-C standard,
	which is essential for classroom use. Assembly language has
	always been my special interest. I have been programming in
	machine language an a Macintosh for about ten years and I
	recently changed to the PC community. It's quite a big change
	to this new kind of processor, but after all it wasn't that
	hard to learn how to program 86xxx assembly language.

	I would like to thank the people from Highsoft for this really
	great C compiler. Thank you, I'm very pleased about this good
	compiler and I'm happy being allowed to use it freely.

	But I also have to complain a little bit. I use to code much
	in assembly language (as mentioned above) and the way the
	Pacific C compiler interacts with the assembler is not very
	easy to understand. In the manuals the difference between
	prototyped assembler functions and those, which are not
	prototyped is explained. But the people from HighSoft didn't
	tell us what the compiler adds to the assembler code.

	So you have to look it up by yourself and try. This is very
	hard for beginners. I would suggest, to provide a new
	compilation switch to the compiler:

		-n	No assembler manipulations behind my back!

	Perhaps this may help programmers to learn how to combine
	assembler code with C code. I translated the same library for
	the Symantec C compiler in about 3 hours, but managing this
	for Pacific C took me half a day! Now I know, what the compiler
	does, but it was hard to find out, anyway.

	But this is not the most important thing to be mentioned about
	the compiler package. This is, what makes it fun to use for me:

	I like the clean library of this compiler and the way, one is
	warned during compilation. The error messages are always very
	clear (after some time of learning, of course!). My students
	don't have any greater problems to learn how to manage their
	projects with the wonderful help from the IDE. This fine piece
	of code makes coding in C much easier, especially for beginners.

	Now, the important things are said and I want to come to the end.

	If you like this library, please let me know! Send me a little
	letter via email to "dreimers@aol.com". I would really be happy,
	if more prpogrammes use this library, and I also would like to
	get some productive criticism from users.

	Perhaps it could also be possible to get more life into the
	Pacific C community. At this time I can say, that more than 25
	people already received the VESA library from me via email.
	I hope they are satisfied with its functionality.

	I'm afraid my english is rather bad. I hope, you had no
	greater difficulties, understanding what I wanted to say.
	Believe me, I really tried my best!

	Thanks for your interest and happy programming with VESALIB!


	------------------------
	Detlef Reimers
	25474 Bnningstedt
	Hohenloher Ring 4
	(Germany)
	Tel: +49-040-6326364
	email: dreimers@aol.com

	24. Juni 1999
	------------------------

