




                   Detailed Description Of All Functions

                                   of the

                            SVGA Drawing Library

                                     by

                              Piotr Ulaszewski


                                December 2000

                            (with C/C++ support)





*******************************************************************************
	This document explains the use of SVGA graphics procedures.
	You can use this code or part of it in any way you find useful.
	The author (Piotr Ulaszewski) does not take any responsability for
	special, incidental or any other quind of dameges arising out of or
	resulting from the use, misuse or modification of the code.
	Futhermore the author does not take any quind of responsability
	for any text written in this manual.txt file and does not even
	guarantee that anything explained here is really true !!!!!
*******************************************************************************


INTRODUCTION:

	This file contains detailed documentation on any function of the
 SVGA drawing library.  This library uses VESA to comunicate with the graphic
 card, which means that you must have a VESA compliant graphic adapter
 in order to use it.  Many functions described here are quite old, some even
 three or four years old.  But the page flipping mechanism is quite new.
 Earlier, when I used VESA 1.2 with standard drawing mechanism, I found out
 that making animated frame sequences using a virtual buffer the old way
 (that means: allocating the virtual buffer in system memory, writing to it,
 then transfering it to video memory by 'rep movsd', then again clearing
 the virtual buffer in system memory with 'rep stosd' and repeating the whole
 thing again) was too slooooooooow!!!  That's why I decided to use a virtual
 buffer in video memory (only with VESA 2.0 and Linear Frame Buffering) and
 simply flip pages in order to show the virtual screen.  This is called double
 buffering and is much faster then the standard technique.  My flip mechanism
 will work on any quind of computer (including Pentium III and Athlon K7),
 provided that they all have a VESA 2.0 compliant graphics card with Linear
 Frame Buffering.  This is accomplished by waiting for vertical refresh, and
 in fact slowing down those systems a lot.
	Note that I did develop these procedures some time ago for my own use,
 and that now I'm simply making them available to others, still interested in
 programing under the good old DOS.
	Also note, that everything that is to be drawn (triangles, lines, e.t.c.
 will in fact be drawn on the virtual screen which is located in video
 memory and will only became visible after calling FLIP to show the virtual
 screen (no data is actually moved, simply the pointers of visible page and
 the virtual screen are exchanged.


1. IRQ Handler for the keyboard (file INT.ASM):

	This is a simple keyboard handler for protected mode.

	void key_init (); - to initialize the internal keyboard handler

	void key_deinit (); - to deinitialize the internal keyboard handler

	void exit_program (); - to instantly exit form the program

	byte *key_table - pointer to key info buffer.
			  example:
			  while (!*(key_table+scan_Space)) {
			  ... your code
			  }
			  this will execute a sequence of code until
			  space is pressed.

;******************************************************************************



2. XLine - Draws a horizontal line on the virtual screen and takes care
	     of dword alignment in video memory (file DRAW.ASM):
	     (any color modes).

	void XLine (int x1, int x2, int y, dword c);

	x1 - x1 coordinate of xline
	x2 - x2 coordinate of xline
	y  - y coordinate of xline
	c  - color of line



3. FTriangle - Draws a flat shaded triangle on the virtual screen and takes
               care of dword alignment in video memory (file DRAW.ASM):
               (any color modes).

	void FTriangle (int x1, int y1, int x2, iny y2, int x3, int y3, dword c);

	x1 - x1 coordinate of filled triangle
	y1 - y1 coordinate of filled triangle
	x2 - x2 coordinate of filled triangle
	y2 - y2 coordinate of filled triangle
	x3 - x3 coordinate of filled triangle
	y3 - y3 coordinate of filled triangle
	c  - color of filled triangle



4. PutText - Draws text on the virtual screen in ASCIIZ format.
	       That means the string must be ZERO terminated.
	       A colorized text means a multicolor text (file DRAW.ASM):
	       (any color modes).

	void *PutText (int x0, int y0, dword c, byte colorize, char *text);

	x0 - x0 coordinate of text start
	y0 - y0 coordinate of text start
	c  - color of the text
	colorize - 1=colorize   0=normal
	text - pointer to the displayed text


	Out: - position at virtual screen after the text was written


5. ScrollText - Draws text on the virtual screen, in a way that it is
		    scrolled vertically (from top down upwards).
		    For every frame the text moves one pixel up if you
		    decrement the y0 coordinate before calling the function.
		    Consequently the y0 coordinate must start above your
		    curren VBE_YResolution (let's say VBE_YResolution+10),
		    and you must repeatedly call that function in your loop.
		    Every line of the scrolled text must be ZERO terminated,
		    and the last line must be followed by 0, then 0ffh.
		    The text is automatically centered on the screen.
		    You should call CheckScrollTextLength before calling this
		    function only to scroll the same text multiple times.  
		    You can achieve this by checking if the text was already
		    scrolled in your loop.  If yes then reset y0 to the magic
		    value of VBE_YResolution+10.
		    (file DRAW.ASM):
		    (any color modes).

	void ScrollText (int y0, dword c, byte colorize, char *text);

	y0 - y coordinate of the text
	c  - color of the text
	colorize - 1=colorize   0=normal
	text - pointer to the displayed text



6. WriteWordSVGA - Write word as a decimal number in SVGA graphics mode.
                   Short explanation for 15bits SVGA modes:
                   The first 5 bits are the 32 shades of red.
                   The second 5 bits are the 32 shades of gren.
                   The third 5 bits are the 32 shades of blu.
                   Therefore 32x32x32=32768 colors=15bits per pixel.
                   For 16bits modes the green has 64 shades.
                   As you may already know a white color is made
                   out of the maximum intensity of red,green and blu,
                   so it would be 65535 in 16bit modes and
                   32767 in 15bit modes.  But you may use 65535
                   (0xffff) for both modes, since the last bit
                   is ignored in 15bit modes.
                   You may use the CreateColor function instead
                   of all the tricky calculations.
                   (file DRAW.ASM):
                   (any color modes).

	void *WriteWordSVGA (word number, dword color, void *position);

	number - number to write from 0 to 65535
	color  - color of that number
	position - position at virtual screen

	Out: new position at virtual screen



7. WriteCharSVGA - write char as a decimal number in SVGA graphics mode.
		        (file DRAW.ASM):
		        (any color modes).

	void *WriteCharSVGA (char sign, dword color, void *position);

	sign - an ascii char
	color - color of that char
	position - position at virtual screen

	Out: new position at virtaul screen



8. Line - Draws any quind of line on the virtual screen.  You must remember
	    to always check if the line coordinates do not exceed the virtual
	    screen boundary, otherwise you will get a page fault or a general
	    protection fault if paging is disabled.
	    (any color modes).

	void Line (int x1, int y1, int x2, int y2, dword c);

	x1 - x1 coordinate of line
	y1 - y1 coordinate of line
	x2 - x2 coordinate of line
	y2 - y2 coordinate of line
	c  - color of line



9. Circle - Darws a circle on the virtual sscreen.  You may draw a circle
	      which is only partially visible on the screen, because full
	      clipping is implemented.
	      (any color modes).

	void Circle (int x0, int y0, int r, dword c);

	x0 - x coordinate of circle (center)
	y0 - y coordinate of circle (center)
	r  - ray of circle
	c  - color of circle



10. PutPixel - Puts a pixel on the virtual screen.  Watch out where you put
               the pixel, it must be within the virtual screen boundary.
               (any color modes).

	void PutPixel (int x0, int y0, dword c);

	x0 - x cooedinate of pixel
	y0 - y coordinate of pixel
	c  - color of pixel



11. GetPixel - Gets a pixel from the virtual screen.  Watch out from where
	         you get the pixel, it must be withing the virtual screen
	         boundary.
	         (any color modes).

	byte GetPixel (int x0, int y0);

	x0 - x coordinate of pixel
	y0 - y coordinate of pixel

	Out: color of the pixel



12. CheckScrollTextLength - Checks the length of the text to be scrolled.
			          I looks at 0,0xff at the end of the text.

	int CheckScrollTextLength (char *text);

	text - pointer to the text which is to be scrolled

	Out: Length of the text



13. CreateColor - Creates a color (only in highcolor or truecolor modes) from
                  three values:
                  The intensity of red   (0-255)
                  The intensity of green (0-255)
                  The intensity of blue  (0-255)

	dword CreateColor (byte r, byte g, byte b);

	r - intensity of red   (0-255)
	g - intensity of green (0-255)
	b - intensity of blu   (0-255)

	Out: the created color in your current Bits Per Pixel mode.



;******************************************************************************



14. PcxUnpack - Loads and decompresses an 8bit PCX image of any size.
	          (file FFORMATS.ASM):

	int PcxUnpack (char *filename, void *destination);

	filename - PCX compressed file name.
	destination - pointer to the destination address
		        (where the PCX image is to be decompressed).
		        This area must be allocated by the user.

	Out: NULL in case of error.
	     NONZERO in case of success



15. ActivePcxPal - Activates the PCX palette stored at end of buffer.
		       Note: to activate the palette you must first change
			 the video mode to graphics mode of your choice.
			 Use only in 256 color modes!!!
		       (file FFORMATS.ASM):

	void ActivePcxPal (void *image);

	image - Linear address of uncompressed PCX



;******************************************************************************



16. CheckVESA - Checks if VESA BIOS EXTENSION is present and sets
		    primary VBE variables.
		    Always call this function first.
		    Note: errors 1 and 4 should never occur.
		    (file VESA.ASM):

	int CheckVESA(void);
	
	Out:  = 0 VESA was found
		= 1 DOS memory allocation failed
		= 2 Not used
		= 3 VESA not supported
		= 4 DOS memory deallocation failed



17. InitVESAMode - Verifies if requested mode is available and initializes it.
		       Note: errors 1 and 4 should never occur.
		       (file VESA.ASM):

	int InitVESAMode (word width, word height, word bpp);

	width - Width of requested VESA mode
	height - Height of requested VESA mode
	bpp - Bits Per Pixel of requested VESA mode (8/15/16/24/32 - any)

	Out:  = 0 Initialization was successfull
		= 1 DOS memory allocation failed
		= 2 Not used
		= 3 Not used
		= 4 DOS memory deallocation failed
		= 5 Requested video mode not found
		= 6 Wrong VESA mode was requested
		= 7 Can't map memory (function 0800h of DPMI interface)
		= 8 Bank switching is not really available
		= 9 Bad Window A attributes (must be read/write)
		= A Virtual screen allocation in system memory failed



18. SetVBEMode - Set the previously initialized SVGA graphics mode.
		     Before calling this function you should first call
		     CheckVESA, then InitVESAMOde.
		     (file VESA.ASM):

	void SetVBEMode(void);



19. CloseVBEMode - This function simply unmaps the memory mapped for
		       Liner Frame Buffering if VESA 2.0 modes were used.
		       (file VESA.ASM):

	void CloseVBEMode(void);



20. PutVESAScreen - Transfers a picture from virtual screen in system memory
		        to the VESA screen in video memory (for VESA 1.2).
		        This function may also be used with VESA 2.0 or above,
		        simply to show an image that was decoded in system memory.
		        (file VESA.ASM):

	void PutVESAScreen (void *buffer);

	buffer - pointer to the buffer which is to be shown on the screen



21. GetROMFont - Get the system font pointer using VSA BIOS call and asve it
		     in [ROM_Font] location declared as external.
		     (file VESA.ASM):

	void GetROMFont (void);



22. WaitRetrace - additional wait for vertical retrace procedure, which
		      is not used any more.
		      It will slow down the system to your curent refresh rate,
		      regardless of the speed and power of your computer.
		      You should not use this function because the flip procedure
		      already has internal checking for vertical retrace.
		      (file VESA.ASM):

	void WaitRetrace (void);



23. Flip - Performs multi buffering in video memory (like under DirectX),
	     provided that the user has VESA 2.0 or higher with Linear Frame
	     Buffering instelled. Under VESA 1.2 it performs a simulated flip.
	     Support for Real Mode and Protected mode VESA interface is
	     included (you don't need PMODE interface in order to do page
	     flipping but you must have a Linear Frame Buffer).
	     Also note that PMODE interface is much faster than the standard
	     real mode method.  Please see the README.TXT file for more
	     details on multi buffering.
	     (file VESA.ASM):

	void Flip (void);

	Out: (pages are flipped and the current back buffer bacomes
	     visible on the screen).



24. IncreaseResolution - Increases the current VESA graphics mode, but
			       the Bits Per Pixel field stays the same.
			       The modes are switched in a way that was defined
			       after color_modes (from 320x200 to 800x600),
			       but you may define other mode that suit your needs.
			       (file VESA.ASM):

	void IncreaseResolution (void);



25. DecreaseResolution - Decreases the current VESA graphics mode, but
			       the Bits Per Pixel field stays the same.
			       The modes are switched in a way that was defined
			       after color_modes (from 800x600 to 320x200),
			       but you may define other mode that suit your needs.
			       (file VESA.ASM):

	void DecreaseResolution (void);



;******************************************************************************
 >> ADDITIONAL DPMI FUNCTIONS (INTERFACE TO C/C++ PROGRAMS)
;******************************************************************************



26. DPMI_DOSmalloc - Allocate low mwmory (0 to 1MB) via DPMI.

	int DPMI_DOSmalloc (long size, short segment, short selector);

	size - requested size in bytes
	segment - variable that will hold the segment of allocated block
	selector - variable that will hold the selector of allocated block

	Out: NULL in case of error
	     TRUE in case of success



27. DPMI_DOSfree - Free previously allocated low memory.

	void DPMI_DOSfree (short selector);

	selector - selector of the freed block



28. DPMI_GetRMVector - Get the real mode vector of an interrupt.

	void DPMI_GetRMVector (int intnum, short segment, short offset);

	intnum - number of the interrupt (0-255)
	segment - variable that will hold the segment of the real mode vector
	offset - variable that will hold the offset of the real mode vector



29. DPMI_SetRMVector - Set the real mode vector of an interrupt.

	void DPMI_SetRMVector (int intnum, short segment, short offset);

	intnum - number of the interrupt (0-255)
	segment - segemnt of real mode vector
	offset - offset of real mode vector



30. DPMI_GetPMVector - Get the protected mode vector of an interrupt.

	void DPMI_GetPMVector (int intnum, short selector, long offset);

	intnum - number of the interrupt (0-255)
	selector - variable that will hold the selector of the PM vector
	offset - variable that will hold the offset of the PM vector



31. DPMI_SetPMVector - Set the protected mode vector of an interrupt.

	void DPMI_SetPMVector (int intnum, short selector, long offset);

	intnum - number of the interrupt (0-255)
	selector - selector of protected mode vector
	offset - offset of protected mode vector
 


32. DPMI_malloc - Allocate extended memory via DPMI.

	void *DPMI_malloc (long size, long handle);

	size - requested size in bytes
	handle - variable that will hold the handle of the allocated block

	Out: pointer to the allocated block in case of success
	     NULL in case of error


33. DPMI_free - Free previously allocated extended memory.

	void DPMI_free (long handle);

	handle - handle of the freed block



;******************************************************************************
 >> ADDITIONAL CONSOLE FUNCTIONS FOR WIN32 COMPILERS (WITH NO DOS SUPPORT)
;******************************************************************************

	There is no need to use these functions, unless you only have a Win32
 based C/C++ compiler like me (BCC5.5).
	If you have a DOS based compiler for 32bit DPMI (WATCOM C++,BCC4.5...)
 try to delete the header file "extra.h" and insert your standard include
 files (note: some modifications must be made). However the code should work
 fine with all 32bit C/C++ DPMI based compilers with no modifications if you
 only use my headers and my mini run time library.
	To compile with the free Borland C++ compiler version 5.5, you must
 include all the header files (like in the example). You must then include
 a starting point (let's say in 'extra.asm' which will call _main, defined
 as external. If you link the files with tlink32 (not ilink32) you must then 
 execute stubit (from the WDOSX package) on the final executable in order
 to create a DOS extended program.
 
 You may also use another linker (like WLINK - Wactom linker) to produce
 the final executable.  It is much easier with this one.
 	You can of course use another compiler or linker, but the target exe
 must be a 32bit dos extended application.

 The example program is using LADSoft C (with only my headers) to compile
 the C program, and WLINK to link all the object files.


34. print - Standard print function.
	      the ascii staring must be terminated by '$'.

	void print (char *text);

	text - pointer to the displayed text



35. SetVGAMode - Set the VGA mode (0-13) via interrupt 10h.

	void SetVGAMode (int mode);

	mode - nr of requested mode.



36. int386 - standard interrupt function (like in any RTL)

	void int386 (int intnr, union REGS *inregs, union REGS *outregs);

	intnr - number of the executed interrupt
	inregs - pointer to array of registers (on enter)
	outregs - pointer to arraty of registers (on exit)



37. outport or outpw - output a word to a hardware port.

	void outport (short port, short value);

	port - hardware port (0-65535)
	value - word value to be sent



38. outportb or outp - output a byte to a hardware port.

	void outportb (short port, byte value);

	port - hardware port (0-65535)
	value - byte value to be sent



39. inport or inpw - input a word from a hardware port.

	int inport (short port);

	port - hardware port (0-65535)

	Out: received word value



40. inportb or inp - input a byte from a hardware port.

	int inportb (short port)

	port - hardware port (0-65535)

	Out: received byte value



41. delay - request delay in miliseconds.

	void delay (int miliseconds);

	miliseconds - value of the dealy in miliseconds



42. fsize - check file size.

	long fsize (char *filename);

	filename - pointer to file name

	Out: file size



43. loadfile - load a file in memory from any file position.

	int loadfile (char *filename, void *fileposition, void *destination,
	long size);

	filename - pointer to file name
	fileposition - pointer to position in the file (0=begining)
	destination - pointer to the destination area (allocated by user)
	size - size in bytes to read

	Out: NULL in case of error
	     TRUE in case of success



