EZ-VGA GRAPHICS LIBRARY FOR DJGPP V1.4 - 
FUNCTION DESCRIPTIONS:
-----------------------------------------
The EZ-VGA graphics library and components (c) Copyright Matthew Bentley 1996 - 1998.

Descriptions are listed under context, in order of relevance. There is also an alphabetical listing of all functions at the end of this document :
(N.B : All references to the letters x and y (Also x1, y1, etc) refer to the vga screens' horizontal co-ordinate 'x' and the screens' vertical co-ordinate 'y'.)

Initial functions :

* vgainit : 
        Syntax : "vgainit()"
        Description : Switches the computer into 320 horizontal pixels by 200 vertical pixels with 256 colours. You MUST use this before you use any of the graphics functions in this library, or else no graphics will appear on the screen.
        Example : "vgainit();"
* vgaexit :
        Syntax : "vgaexit()"
        Description : This -must- be used at the end of a VGA session to switch back to text mode and clean up the near pointers under DJGPP.
        Example : "vgaexit();"
* cls :
        Syntax : "cls(colour);"
        Description : Fills the video windows with any one colour - Ie 'colour'. The most common usage of this is to clear the screen - fill it with colour 0.
	Example : "cls(0);"
* setborders :
	Syntax : "setborders(x1, y1, x2, y2)"
        Description : Changes the video window borders - any graphics output to the screen outside these borders is ignored. The border is from 'x1, y1' (The top left corner of the window) to 'x2, y2' (The bottom right corner of the window).
	Example : "setborders(5, 5, 300, 100);"

Drawing functions :

* putpix :
	Syntax : "putpix(x, y, colour)"
	Description : Puts a pixel of colour 'colour' on the screen at co-ordinates x, y.
	        (Note for advanced programmers : For direct to video memory pixel setting, without clipping, use "video[y * 320 + x] = colour;".)
	Example : "putpix(13, 15, 245);"
* getpix :
	Syntax : "getpix(x, y)"
	Description : Returns the colour of a pixel on the screen at co-ordinates x, y.
	Example : "colour = getpix(13, 15);"
* line : 
	Syntax : "line(x1, y1, x2, y2, colour);"
	Description : This can be used to draw a line from 'x1, y1' to 'x2, y2' 			of colour 'colour'.
	Example : "line (0, 0, 150, 100, 14);"
* box : 
	Syntax : "box(x1, y1, x2, y2, colour, EMPTY or FILLED);"
        Description : Makes a box from x1,y1 to x2,y2 which can be either       EMPTY or FILLED with the desired colour. Note that you must use         capitals for the EMPTY or FILLED.
        Example : "box (10, 20, 35, 47, 15, EMPTY);"
* circle :
	Syntax : "circle(x_center, y_center, radius, colour);"
        Description : Draws a circle of radius 'radius' with it's center at 'x_center, y_center', of colour 'colour'.
	Example : "circle (100, 15, 50, 1);"
* ellipse :
	Syntax : "ellipse(x_center, y_center, h_radius, v_radius, colour);"
        Description : Draws an ellipse or circle at 'x_center, y_center', with a horizontal "half-width" of 'h_radius' and a vertical "half-height" of 'v_radius', with colour 'colour'.
	Example : To draw an ellipse with it's height half it's width :
                  "ellipse(15, 31, 40, 20, 1);"

Palette Functions :
 
* setpal:
	Syntax : "setpal(palette_number, red_value, green_value, blue_value);"
	Description : Sets a palette number 'palette' to a combination of the values
		        'red_value', 'green_value', and 'blue_value'. All three of these values must be in the range 0 - 63, 0 being least and 63 being the highest.
	Example : To set the colour 24 to bright purple : "setpal(24, 32, 0, 63);"
* setallpals:
	Syntax : "setallpals(palette_array);"
        Description : This function sets all the 256 colours in the VGA palette to values of red, green and blue stored in an array 'palette_array' of type 'unsigned char' and size of at least 770 bytes. The array is encoded thus :
		        red, green, blue, red, green, blue, red, etc. The values of each colour are from 0 to 63, 0 being highest, 63 being lowest.
	Example : "setallpals(pals);"

Picture Functions :

* getpic :
	Syntax : "getpic(x1, y1, x2, y2, unsigned char array);"
        Description : Gets a block of the vga screen from 'x1, y1' to 'x2, y2' into an array of type 'unsigned char'. This array can be saved as a graphics file (as described later on) or put back on the screen using 'putpic' or 'putsprite'. Note : The array must be large enough to hold the image - to find how large the array needs to be, use this formula :
			array size = (picture width * picture height) + 3

                      Or to put it another way :
			array size  = (Y2 - Y1 + 1) * (X2 - X1 + 1) + 3

        (Note to more advanced programmers - the first 3 bytes are to tell the putpic and other functions how large the picture is, vertically and horizontally.)
        Example : "getpic(10, 32, 40, 45, graphicarray);"
* putpic :
	Syntax : "putpic(x, y, graphics_array);"
        Description : Puts a block of screen gotten with 'getpic', back onto the screen at co-ordinates 'x, y', using the array 'getpic' used.
	Example : "putpic(150, 10, graphicsarray);"
* putsprite:
	Syntax : "putsprite(x, y, graphics_array, ignored_colour);"
	Description : Does what 'putpic' does, but also ignores a particular colour in 
		        the graphics image, specified by 'ignored_colour' - this means that you can get a picture off the screen, and overlay it over a background picture, as long as you know the colour in the image that you want to be transparent - this is usually colour 0.
	Example : "putsprite(100, 50, graphicarray, 0);"

File functions :

Note : All of these file functions will only work with arrays of type 'unsigned char'.

IMPORTANT NOTE : In C++, instead of using one slash '\' to separate directories, two are used. For instance, "c:\prog\game.pcx" becomes "c:\\prog\\game.pcx". This is to do with telling the C++ compiler that the '\' is not actually a switch, but a character.


* loadraw:
	Syntax : "loadraw("filename", array);"
        Description : Loads a file of raw binary data (Up to 65535 bytes long) into an array. The size of the file is automatically detected.
		        (Note : As with all the following file functions, the extension of the filename (E.g. '.raw', '.pcx', etc) does not affect how it has to be loaded.) To load the  file onto the screen, replace the array name with 'video'.
	Example : To load data into an array :
                        "loadraw("c:\\utilitys\\data.raw", dataarray);"
		     To load the file onto the screen :
			"loadraw("c:\\graphics\\picture.raw", video);"
* loadbld:
	Syntax : "loadbld("bldfile", array);"
        Description : Those who have used quickbasic will probably be familiar with the .bld file. This function loads a file of .bld format into an array or onto the screen. To load the .bld file onto the screen, replace the array name with 'video'.
			(Quickbasic Note : For those wanting to load .PLT files, use the loadbld function to load these files into an array of at least 770 bytes, then use the 'setallpals' function to set the palette from this array.)
	Example : To load the bld into an array :
                        "loadbld("c:\\graphics\\picture.bld", graphicarray);"
		     To load the bld onto the screen :
			"loadbld("c:\\graphics\\picture.bld", video);"
* loadpcx:
	Syntax : "loadpcx("pcxfile", array_name, palette array)
        Description : Loads a compressed 320x200 256 colour .PCX file into an array or onto the screen. If the .pcx file is larger than 320 pixels by 200 pixels, this function 'squashes' the picture down to 320 pixels by 200 pixels. 
		        This function also loads the picture's palette from the file into an 'unsigned char' array of at least 770 bytes - the palette can then be set using the function 'setallpals' and the palette array 'palette array'. 
		        To load the image to the screen, put 'VIDEO' in the 'arrayname' option. 
		        To load the image into an array, which can later be put onto the screen using 'putpic', put the name of the array you wish to use in the 'array_name' option. 
		        As with the 'getpic' function, the array needs to be large enough to hold the picture - see 'getpic' for the formula for the array size. 
		        (Note : The PCX is a compressed graphics file, which means that it uses less disk space - this can be very useful for programs which use a lot of graphics.)
	Example : To load a .pcx file to the screen :
 		        "loadpcx ("c:\\graphics\\picture.pcx", screen, video, pals) ;"
                  To load a .pcx file into an array :
                        "loadpcx("c:\\graphics\\picture.pcx", array, graphicarray, pals);"
* saveraw :
	Syntax : "saveraw("filename", array, size);"
        Description : Saves an 'array' of size 'size' as a file of raw binary data. This function overwrites any file of the same name as 'filename', if one exists. The array size can be up to 65535 bytes. To save a  screen, change the 'array' option to 'video' and the 'size' to 64000.
	Example : To save a raw file from an array :
                        "saveraw("c:\\utils\\data.raw", dataarray, 50);"
                  To save a raw file from the screen :
			"saveraw("c:\\graphics\\data.raw", video, 64000);"
* savebld :
	Syntax : "savebld("filename", array, size);"
        Description : Like the 'saveraw' function, this function saves an array 'array' of size 'size' as a file, but it saves it in quickbasic .BLD format. To save a  screen, change the 'array' option to 'video' and the 'size' to 64000.
	Example : To save a bld file from an array :
                        "savebld("c:\\graphics\\data.bld", dataarray, 50);"
                  To save a bld file from the screen :
			"savebld("c:\\graphics\\data.bld", video, 64000);"
* savepcx :
	Syntax : "savepcx("filename", arrayname, palette_array);"
	Description : Saves a screen or picture stored in an array (using 'getpic')
        		to a file 'filename' of compressed PCX format. This also saves the colour palette, and a palette array of 'unsigned char' type at least 770 bytes long is required. 
		        To save an image from the screen, put 'VIDEO' in the 'arrayname' option.
		        To save an image from an array gotten with 'getpic', put the name of your graphics array in the 'arrayname' option.
	Example : To save a PCX file from an array :
                        "savepcx("c:\\graphics\\picture.pcx", array, picturearray, pals);"
                  To save a PCX file from the screen :
			"savepcx("c:\\graphics\\picture.pcx", screen, video, pals);"

Mouse functions :

* mouseinit:
	Syntax : "mousecheck = mouseinit();"
        Description : Checks to see that a mouse driver exists, and if it is, resets all the parameters for the mouse (Ie. Mouse location, etc). If  no mouse is present, 'mousecheck' will equal 0. If a mouse is present, 'mousecheck' will equal 1.
	Example : "check = mouseinit();"
* mousecursor:
	Syntax : "mousecursor (on or off);"
	Description : Shows or hides the mouse cursor.
	Example : To turn the mouse cursor on :
			"mousecursor(on);"
		       To turn the mouse cursor off :
			"mouse cursor(off);"
* getmousepos :
	Syntax : "getmousepos(x, y);"
        Description : Returns the mouse's pixel-position on the screen. 'x' is the horizontal position (0 to 319), 'y' is the vertical position (0 to 199). Both must be variables of type 'int'.
	Example : "int xmouse, ymouse;
		        getmousepos(xmouse, ymouse);"
* setmousepos :
	Syntax : "setmousepos(x, y);"
	Description : Sets what position the mouse cursor is at on the screen.
	Example : "setmousepos(15, 100);"
* mousebuttons :
	Syntax : "buttonpress = mousebuttons();"
        Description : Returns the status of the mouse buttons. If no button has been pressed, 0 is returned. If the left one is pressed, 1 is returned. If the right one is pressed, 2 is returned. If both are pressed, 3 is returned.
	Example : "buttons = mousebuttons();"
* setmouselimits :
	Syntax : "setmouselimits (x1, y1, x2, y2);"
        Description : Changes the physical borders for the mouse so that it can only move from 'x1, y1' to 'x2, y2'.
	Example : "setmouselimits (10, 20, 150, 199);"

Alphabetical listing :

box
circle
cls
ellipse
getmousepos
getpic
getpix
line
loadbld
loadpcx
loadraw
mousebuttons
mousecursor
mouseinit
putpic
putsprite
putpix
savebld
savepcx
saveraw
setallpals
setborders
setpal
vgaexit
vgainit