
			  Wordup Graphics Toolkit 4.0

			       Library Reference

		     Copyright 1994 Barry and Chris Egerter


			    Revised: March 27, 1994



		   WordUp Graphics Toolkit: Library Reference        Page 2

			       Table Of Contents

WGT4.LIB								7
INSTALLKBD..............................................................8
LIB2BUF.................................................................9
MDEINIT.................................................................9
MINIT..................................................................10
MOFF...................................................................11
MON....................................................................11
MOUSESHAPE.............................................................12
MREAD..................................................................13
MSETBOUNDS.............................................................14
MSETSPEED..............................................................14
MSETTHRESHHOLD.........................................................15
MSETXY.................................................................15
NOCLICK................................................................16
SETLIB.................................................................17
SETPASSWORD............................................................17
UNINSTALLKBD...........................................................18
VGA256.................................................................18
VGADETECTED............................................................19
WBAR...................................................................19
WBEZIER................................................................20
WBUTT..................................................................21
WCIRCLE................................................................21
WCLIP..................................................................22
WCLS...................................................................22
WCOLROTATE.............................................................23
WCOPYSCREEN............................................................24
WDETECTCPU.............................................................25
WDRAW_SCANPOLY.........................................................26
WELLIPSE...............................................................27
WEMS_CLOSE.............................................................28
WEMS_COPY..............................................................28
WEMS_FREE..............................................................29
WEMS_GETDATA...........................................................29
WEMS_GETFRAME..........................................................30
WEMS_GETSPRITE.........................................................31
WEMS_INIT..............................................................31
WEMS_LOADSPRITES.......................................................32
WEMS_MAP...............................................................33
WEMS_OPEN..............................................................34
WEMS_PRESENT...........................................................34
WEMS_STOREBLOCK........................................................35
WEMS_STOREDATA.........................................................36
WEMS_RESET.............................................................36

		   WordUp Graphics Toolkit: Library Reference        Page 3

WFADE..................................................................37
WFADE_BETWEEN..........................................................38
WFADE_BETWEEN_ONCE.....................................................39
WFADE_IN...............................................................40
WFADE_IN_ONCE..........................................................41
WFADE_OUT..............................................................42
WFADE_OUT_ONCE.........................................................43
WFASTPUTPIXEL..........................................................44
WFILL_CIRCLE...........................................................44
WFILL_ELLIPSE..........................................................45
WFLASHCURSOR...........................................................45
WFLINE.................................................................46
WFLIPBLOCK.............................................................46
WFREE_SCANPOLY.........................................................47
WFREEBLOCK.............................................................48
WFREEFONT..............................................................49
WFREESPRITES...........................................................49
WGET_CAPSLOCK..........................................................50
WGET_LALT..............................................................50
WGET_LCTRL.............................................................51
WGET_LSHIFT............................................................51
WGET_NUMLOCK...........................................................52
WGET_RALT..............................................................52
WGET_RCTRL.............................................................53
WGET_RSHIFT............................................................53
WGET_SCRLOCK...........................................................54
WGETBLOCKHEIGHT........................................................54
WGETBLOCKWIDTH.........................................................55
WGETMODE...............................................................55
WGETPIXEL..............................................................56
WGETTEXTHEIGHT.........................................................56
WGETTEXTWIDTH..........................................................57
WGOURAUDPOLY...........................................................58
WGTPRINTF..............................................................59
WHLINE.................................................................60
WHOLLOWPOLY............................................................61
WLINE..................................................................62
WLOADBLOCK.............................................................63
WLOADBMP...............................................................64
WLOADCEL...............................................................64
WLOADFONT..............................................................65
WLOADPAK...............................................................65
WLOADPALETTE...........................................................66
WLOADPCX256............................................................67
WLOADSPRITES...........................................................68
WNEWBLOCK..............................................................69
WNORMSCREEN............................................................70
WOUTTEXTXY.............................................................70
WPAN...................................................................71

		   WordUp Graphics Toolkit: Library Reference        Page 4

WPUTBLOCK..............................................................71
WPUTPIXEL..............................................................72
WREADPALETTE...........................................................72
WRECTANGLE.............................................................73
WREGIONFILL............................................................73
WREMAP.................................................................74
WRESIZE................................................................75
WRETRACE...............................................................76
WSAVEBLOCK.............................................................76
WSAVEBMP...............................................................77
WSAVECEL...............................................................77
WSAVEPAK...............................................................78
WSAVEPALETTE...........................................................78
WSAVEPCX256............................................................79
WSCAN_CONVERTPOLY......................................................80
WSET_CAPSLOCK..........................................................81
WSET_NUMLOCK...........................................................81
WSET_SCRLOCK...........................................................82
WSETCOLOR..............................................................82
WSETCURSOR.............................................................83
WSETMODE...............................................................83
WSETPALETTE............................................................84
WSETRGB................................................................85
WSETSCREEN.............................................................86
WSKEW..................................................................86
WSLINE.................................................................87
WSOLIDPOLY.............................................................88
WSTRING................................................................89
WSTYLELINE.............................................................90
WTEXTBACKGROUND........................................................91
WTEXTCOLOR.............................................................91
WTEXTGRID..............................................................92
WTEXTTRANSPARENT.......................................................92
WTEXTUREDPOLY..........................................................93
WTIMER.................................................................94
WVERTRES...............................................................95
WWARP..................................................................96
WWIPE..................................................................97
WXORBOX................................................................98
WGTJOY.LIB							       99
WCALIBRATEJOYSTICK....................................................100
WCHECKJOYSTICK........................................................101
WINITJOYSTICK.........................................................101
WREADJOYSTICK.........................................................102

		   WordUp Graphics Toolkit: Library Reference        Page 5

WGT3D.LIB							      103
WINIT3D...............................................................104
WROTATEPOINTS.........................................................105
WSETROTATION..........................................................106
WFILE.LIB							      107
WFILESEL..............................................................108
WGTSB.LIB							      110
WADDR.................................................................111
WDEINITSB.............................................................111
WFINDFM...............................................................112
WFMRESET..............................................................112
WFMSETSTATUS..........................................................113
WFMSONGSPEED..........................................................113
WFMSTOPMUSIC..........................................................114
WFMVERSION............................................................114
WFREECMF..............................................................115
WFREEVOC..............................................................115
WINITSB...............................................................116
WLOADCMF..............................................................117
WLOADVOC..............................................................117
WPAUSEVOC.............................................................118
WPLAYCMF..............................................................118
WPLAYVOC..............................................................119
WRESUMEVOC............................................................119
WSBVERSION............................................................120
WSETSPEAKER...........................................................120
WSTOPVOC..............................................................121
WGTSCROL.LIB							      122
IS_IN_WINDOW..........................................................123
SOVERLAP..............................................................124
WCOPYSCROLL...........................................................125
WENDSCROLL............................................................125
WFREEMAP..............................................................126
WGETWORLDBLOCK........................................................126
WGETWORLDPIXEL........................................................127
WINITSCROLL...........................................................128
WLOADMAP..............................................................130
WPUTWORLDBLOCK........................................................131

		   WordUp Graphics Toolkit: Library Reference        Page 6

WSAVEMAP..............................................................132
WSCROLLWINDOW.........................................................133
WSHOWOBJECTS..........................................................134
WSHOWWINDOW...........................................................135
WGTMENU.LIB							      136
CHECKMENU.............................................................137
INITDROPDOWNS.........................................................138
REMOVEMENUBAR.........................................................138
SHOWMENUBAR...........................................................139
WSPR.LIB							      140
ANIMATE...............................................................141
ANIMOFF...............................................................142
ANIMON................................................................142
DEINITSPR.............................................................143
DRAWSPR...............................................................143
ERASESPR..............................................................144
INITSPR...............................................................144
MOVEX.................................................................145
MOVEXOFF..............................................................146
MOVEXON...............................................................146
MOVEY.................................................................147
MOVEYOFF..............................................................147
MOVEYON...............................................................148
OVERLAP...............................................................148
SPRITEOFF.............................................................149
SPRITEON..............................................................149
WGTFLIC.LIB							      150
OPENFLIC..............................................................151
NEXTFRAME.............................................................151
COPYFLIC..............................................................152
CLOSEFLIC.............................................................153
WGTVESA.LIB							      154
WVESA_DETECTED........................................................155
WVESA_BANK............................................................155
WVESA_GETMODEINFO.....................................................156
WVESA_INIT............................................................157
WVESA_SUPPORTED.......................................................158

		   WordUp Graphics Toolkit: Library Reference        Page 7



WGT4.LIB

This is the main WGT system library. It provides the user with everything from
VGA/CPU detection routines to texture-mapped polygons. Every project file 
which uses graphics must link this library file.



		   WordUp Graphics Toolkit: Library Reference        Page 8

installkbd 
------------------------------------------------------------------------------
Function:     	Installs a keyboard handler which permits multiple keypresses 
		at the same time.

Declaration:  	void installkbd (void)

Remarks:	Once installed, this keyboard handler will store the status of 
		all keypresses in an array of 128 integers. The array is called
		kbdon. Each element of the array is either a 0 or a 1. Each 
		key on the keyboard is assigned a scancode which is represented
		by the same element in the array. To determine if a key has 
		been pressed, simply check to see if the corresponding element 
		of kbdon is greater than 0.

		You must uninstall the keyboard handler before attempting any
		normal keyboard input routines or before leaving the program. 
		To determine the scancodes of the keys you want, refer to a DOS
		programmer's manual, or run the included SCANCODE.EXE file.

		A variable called keypressed is increased each time a key is 
		pressed. You may set this variable to 0 and then wait until it
		reaches 1 (or more) to determine if a key has been pressed.
		At this point you may check the kbdon array to determine which 
		keys have been pressed. Reset the variable to 0 again after 
		checking the array.

Parameters:	None.

Return Value: 	None.

See also:	uninstallkbd

Examples:	56, 57, 58


		   WordUp Graphics Toolkit: Library Reference        Page 9

lib2buf 
------------------------------------------------------------------------------
Function:	Allocates memory for a file, and loads it into memory.

Declaration:	void *lib2buf (char *filename)

Remarks:	This allows any type of file to be loaded into memory from 
		the WGT Data Library file. It gets the required memory first, 
              	and then returns a pointer to the data.  It can be used for 
              	many things, such as text, Sound Blaster VOC's, CMF files, 
              	calculated tables, and any other data.

		What is done with the data loaded is up to you.  If the data
            	is text, you will need to process it from the pointer into
              	a usable form.

Parameters:	filename - The name of the file inside the WGT Data Library 
                           file which will be loaded into memory.

Return Value:	A pointer to the data which was loaded.

See Also:   	setlib, setpassword

Examples:	31





mdeinit 
------------------------------------------------------------------------------
Function:	Removes the custom mouse handler.         

Declaration: 	void mdeinit (void)

Remarks:     	WGT installs a custom mouse handler when the mouse is  
             	initialized with minit.  This routine MUST be called before
             	your program ends when using the mouse routines.  If the 
             	custom mouse interrupt is not removed, moving the mouse when 
             	inside a rodent-free application will usually lock the 
             	computer.

Parameters:	None

Return Value:	None

See Also:  	minit

Examples:	12, 13, 14, 16, 18, 19, 20, 22, 23, 25, 30, 36, 37, 47

		   WordUp Graphics Toolkit: Library Reference        Page 10

minit
------------------------------------------------------------------------------
Function:	Initializes the mouse driver.

Declaration:	int minit (void)

Remarks:   	This command initializes the mouse driver.  It must be a
            	Microsoft compatible driver.   Other drivers may behave 
            	strangely using the standard mouse calls.  You must call this
            	first if you want to use the mouse.  Initially the mouse cursor
            	is not visible. Use mon to turn on the display of the cursor.
            	You should also note that all mouse routines work in graphics
            	and text mode.

            	Upon initialization, a custom mouse interrupt is installed.
            	Whenever an action occurs with the mouse, such as it being
            	moved, or a button being depressed, the interrupt is called.
              	Within the interrupt, the variables mx, my, and but are
              	updated to contain the information about the mouse.
              	mx and my are the coordinates on the screen.  mx is in the
              	range 0 to 320, and my ranges 0 to 200.  

             	If you are using the mouse routines in text mode, they will
             	still report values in the ranges mentioned above.  To change
             	the values into character values, you must divide the
             	coordinates by a number.  For example, if you are in 80 column
              	mode, the actual character column would be mx/4, since 320/4
              	gives you 80 possible values.  Also, make a copy of the
              	mx, my, variables and divide them instead.  This is because
              	mx and my may change at any time from the custom mouse
              	interrupt.

            	The but variable contains information for all of the buttons.
              	Each button is represented by a bit within this number.

             	Left button: bit 1 (value of 1)
              	Right button: bit 2 (value of 2)
              	Middle button bit 3 (value of 4)

              	Therefore to see if a certain button is depressed,

              	if (but & 1)  button=LEFT;
              	if (but & 2)  button=RIGHT;
              	if (but & 4)  button=MIDDLE;

              	You can create defines for each button to make reading easier.

Parameters: 	None

Return Value:	Number of buttons on the mouse if driver is found.
             	If the number is less than 1, no mouse driver is present.

See Also:    	mdeinit, moff, mon, mouseshape, mread, msetbounds, msetspeed,
             	msetthreshhold, noclick

Examples:	12-14, 16, 18-20, 22, 23, 25, 30, 36, 37, 39, 47

		   WordUp Graphics Toolkit: Library Reference        Page 11

moff 
------------------------------------------------------------------------------
Function: 	Turns off the display of the mouse cursor.

Declaration:	void moff (void)

Remarks:   	The mouse driver keeps a counter of the number of times
             	you've turned the mouse cursor off.  In order to make the 
              	cursor visible, you must call mon the same number of times.

              	This routine is usually called when you are drawing to the
              	visual screen, otherwise the mouse will disturb the drawing
              	operation.  

Parameters:  	None

Return Value:	None

See Also:  	minit, mon

Examples:	12, 14, 16, 25, 30, 47





mon 
------------------------------------------------------------------------------
Function:  	Turn on the display of the mouse cursor.

Declaration:	void mon (void)

Remarks:   	If the mouse is displayed while you are using some drawing
              	procedures, it will destroy the background of the screen if
              	you move it over the area being updated.  Turn it off during 
              	all drawing procedures with moff, and restore it when finished 
              	drawing with mon.

            	Note: If wgetpixel is used on an area where the mouse cursor
              	appears, it will return the color within the mouse cursor, not
              	what is on the screen behind it.

Parameters:   	None

Return Value: 	None

See Also:    	minit, moff

Examples:	12, 13, 30, 37, 40

		   WordUp Graphics Toolkit: Library Reference        Page 12

mouseshape
------------------------------------------------------------------------------
Function:    	Sets the bitmap shape and hotspot of the mouse cursor.

Declaration:  	void mouseshape (int colhot, int rowhot, void far *mousebitmap)

Remarks:      	This procedure sets the cursor hotspot as defined by the
              	variables colhot and rowhot. The hotspot is the place on the 
		mouse cursor where the actual coordinates will be returned. 
		Usually the hotspot is in the top left corner, but you are free 
		to modify this depending on your mouse cursor shape.  The 
		actual bitmap information is stored in an array of integers 
		called mousebitmap. It is defined as follows:

              	The first 16 words are used to set the cursor shape, while the
              	last 16 words set the mask.  To create this monochrome 
              	bitmap data, use the WGT Sprite Editor's mouse cursor tool.

Parameters:   	colhot - Hot Spot X position (-16 to 16).

              	rowhot - Hot Spot Y position (-16 to 16).

              	mousebitmap -  A pointer to the screen and cursor masks.

Return Value: 	None

Examples:	13

		   WordUp Graphics Toolkit: Library Reference        Page 13

mread
------------------------------------------------------------------------------
Function:     	Reads the current state of the buttons and coordinates from
              	the mouse driver.

Declaration:  	void mread (void)

Remarks:      	Three global variables are updated when you call this
              	procedure.  mx and my are the mouse coordinates, and
              	but is the button state.

              	WARNING:  This routine is now obsolete since minit installs
              	a custom mouse interrupt.  This is updated whenever a button
              	is pressed, or the mouse is moved.  The variables mx, my, and
              	but are therefore updated continuously.

              	All calls of this function should be deleted from your code,
              	since it is possible for the mouse driver to malfunction.
              	On fast computers, if the mouse driver is polled too quickly,
              	it can cause the movement of the mouse to become very slow.
              	Through the use of the custom interrupt, the mouse controls
              	when it is polled, and this problem does not occur.

              	Since the mouse variable are updated constantly, you should
              	make some temporary mouse variables which will not change
              	in the middle of a procedure.  This will ensure your program
              	behaves exactly as it did with older versions of WGT.
              	For example:

              	int px,py,pbut;

              	// mread();  /* The old code */
              	px = mx;     /* Store mouse state in variables */
              	py = my;     /* which will be used later */
              	pbut = but;

              	...  /* Continue program as usual */


Parameters:  	None

Return Value: 	None

See Also:     	minit

Examples:	None

		   WordUp Graphics Toolkit: Library Reference        Page 14

msetbounds
------------------------------------------------------------------------------
Function:    	Sets the movement boundaries of the mouse cursor.

Declaration:  	void msetbounds (int minx, int miny, int maxx, int maxy)

Remarks:      	The cursor's movement will be restricted to the specified
              	region after this routine is called.   This routine is
              	used to control the user's actions by limiting where they
              	can click on the screen.

Parameters:   	minx - The left X coordinate of the mouse boundary.

              	miny - The top Y coordinate of the mouse boundary.

              	maxx - The right X coordinate of the mouse boundary.

              	maxy - The bottom Y coordinate of the mouse boundary.

Return Value: 	None

Examples:	12, 13, 19, 20




msetspeed 
------------------------------------------------------------------------------
Function:     	Sets the speed of the mouse.

Declaration:  	void msetspeed (int x_speed, int y_speed)

Remarks:      	This routine sets the speed of the mouse in each direction. 
              	10 is about average for both values.  1 is fast, 40 is slower.
              	In other words, if you set the speed to be 40 for the x, and
              	1 for the y, you will have to move the mouse a greater
              	distance horizontally to move the cursor one pixel. On the
              	other hand, you can move the cursor very quickly up and down.

              	Mouse movement is measured in mickeys.  This routine sets 
              	how many mickeys are required to move the mouse one pixel
              	on the screen.  One mickey is about 1/200 of an inch.

Parameters:   	x_speed - Horizontal mickeys per pixel.

              	y_speed - Vertical mickeys per pixel.

Return Value: 	None

Examples:	13

		   WordUp Graphics Toolkit: Library Reference        Page 15

msetthreshhold 
------------------------------------------------------------------------------
Function:     	Sets the speed the mouse must reach before it doubles its
              	movements.

Declaration:  	void msetthreshhold (int speed)

Remarks:      	When the mouse is moved faster than this speed, all movements
              	are doubled.  This is used to control the sensitivity of
              	the mouse.

Parameters:   	speed - Threshhold speed in mickeys per second.

Return Value: 	None

See Also:     	msetspeed

Examples:	13




msetxy 
------------------------------------------------------------------------------
Function:     	Sets the screen location of the mouse cursor.

Declaration:  	void msetxy (int x, int y)

Remarks:      	You may set the location of the mouse cursor on the screen with
		this command. Use this whenever you want to force the user to 
		move to a certain region of the screen.

Parameters:   	x - Horizontal screen coordinate.

              	y - Vertical screen coordinate.

Return Value: 	None

Examples:	37

		   WordUp Graphics Toolkit: Library Reference        Page 16

noclick 
------------------------------------------------------------------------------
Function:     	Waits until all buttons are released.

Declaration:  	void noclick (void)

Remarks:      	This routine waits in a loop until the mouse driver reports
              	all the mouse buttons are released. It is useful if you want 
              	the user to click on a button, perform an action, and wait for 
              	another button click.  Without this command, the user could 
              	hold down the button and the program will think you pressed 
              	it a bunch of times.  Put this command in after you have found 
              	the user pressed a button.  For example:
          
              	if (but == 1)
              	 {
              	  ctr++;
              	  /* Keep track of how many times you press the left button) */
              	  noclick ();  /* Wait until user lets go */
              	 }

Parameters:   	None

Return Value: 	None

See Also:     	minit, moff, mon

Examples:	13, 19, 20, 36

		   WordUp Graphics Toolkit: Library Reference        Page 17

setlib
------------------------------------------------------------------------------
Function:     	Sets the WGT Library name.

Declaration:  	void setlib (char *libname)

Remarks:      	WGT has the ability to store all of your graphics or data files
              	into one large library file. Use the utility called wgtlib to 
              	manage your WGT Library files. These library files are not the
              	library files made by TLIB.  Set the name of the library file 
              	in the beginning of your program, and all WGT commands which 
              	load something will use the library instead of individual 
              	files. Pass NULL as libname to disable library files.

Parameters:   	libname - Filename of the WGT Data Library file.

Return Value: 	None

See Also:     	lib2buf, setpassword

Examples:	31




setpassword
------------------------------------------------------------------------------
Function:     	Sets the WGT Library password.

Declaration:  	void setpassword (char *newpassword)

Remarks:      	WGT library files can be protected by a password.  If you 
              	choose the incorrect password, files cannot be loaded in.
              	This prevents other WGT users from taking your graphics and
              	sound files. Use " " to indicate no password.

Parameters:   	newpassword - The password used to access the currently open
			      WGT Data Library file.

Return Value: 	None

See Also:     	lib2buf, setlib

Examples:	31

		   WordUp Graphics Toolkit: Library Reference        Page 18

uninstallkbd 
------------------------------------------------------------------------------
Function:	Removes the WGT custom keyboard handler.

Declaration:	void uninstallkbd (void)

Remarks:      	Any program which calls the installkbd command must at some
		point call this routine as well. If the program fails to remove
		the keyboard handler, strange things may happen once the 
		program ends.

Parameters:   	None.

Return Value: 	None.

See Also:     	installkbd

Examples:	56, 57, 58



vga256 
------------------------------------------------------------------------------
Function:     	Initializes the 256 color graphics mode.

Declaration:  	void vga256 (void)

Remarks:      	This command will change the video mode into mode 0x13, which
              	is 320x200 with 256 colors.  This is the only mode WGT operates
              	in.  Mode 0x13 is the most popular mode for games because it
              	is very fast and easy to program.  vga256 must be called before
              	any other drawing commands.

              	Upon initialization, vga256 sets a pointer called abuf to the
              	visual screen of the VGA card.  abuf will contain a pointer
              	to the current graphics page throughout your program.

Parameters:   	None

Return Value: 	None

See Also:     	vgadetected, wgetmode, wsetmode

Examples:	1-29, 31-43, 46-49, 51-53

		   WordUp Graphics Toolkit: Library Reference        Page 19

vgadetected
------------------------------------------------------------------------------
Function:     	Determines if a VGA card is available.  

Declaration:  	char vgadetected (void)

Remarks:      	If a VGA card is found, this routine returns 1.
              	Otherwise, your program should stop immediately since
              	WGT's graphics commands will not function.

Parameters:   	None

Return Value: 	1 = VGA card found
              	0 = VGA card not found

See Also:     	vga256, wgetmode, wsetmode

Examples:	1-4, 6-24, 26-29, 31-37, 46-50





wbar 
------------------------------------------------------------------------------
Function:     	Draws a filled rectangle.

Declaration:  	void wbar (int x1, int y1, int x2, int y2)

Remarks:      	(x1,y1) defines the upper left corner of the bar, and
              	(x2,y2) defines the lower right. The rectangle will be clipped 
		to the clipping boundaries if needed.

Parameters:   	x1 - The left X coordinate of the bar.

              	y1 - The top Y coordinate of the bar.

              	x2 - The right X coordinate of the bar.

              	y2 - The bottom Y coordinate of the bar.

Return Value: 	None

See Also:     	wrectangle

Examples:	4, 11, 18, 27, 29, 42, 43

		   WordUp Graphics Toolkit: Library Reference        Page 20

wbezier
------------------------------------------------------------------------------
Function:     	Calculates the points of a bezier curve.

Declaration:  	void wbezier (tpolypoint *rawpts, int numraw,
                              tpolypoint *curvepts, int numcurve)

Remarks:      	wbezier takes a list of polygon points and creates a 
              	smooth curve between them.  It puts the points of the
              	curve into another vertex list that can be used with
              	WGT's polygon routines.


Parameters:   	rawpts   - an array of initial data points.

              	numraw   - contains the number of data points in the rawpts
                           array.

              	curvepts - the array which contains the points of the 
                           bezier curve.

              	numcurve - the number of points on the curve.  Greater values 
                           of numcurve will produce smoother bezier curves.  
                           numcurve must always be greater than numraw.

Return Value: 	None

Examples:	33

		   WordUp Graphics Toolkit: Library Reference        Page 21

wbutt 
------------------------------------------------------------------------------
Function:     	Draws a 3-dimensional button.

Declaration:  	void wbutt (int x1, int y1, int x2, int y2)

Remarks:      	wbutt draws a 3D button by using different colors for shading
              	around the sides.  It is useful for creating user interfaces
              	which often require a screen which is appealing to the eye.
              	This routine uses colors 253 to 255 for shading the button.
              	These colors must be of decreasing intensity for the button
              	to look correct.

Parameters:   	x1 - The left X coordinate of the button.

              	y1 - The top Y coordinate of the button.

              	x2 - The right X coordinate of the button.

              	y2 - The bottom Y coordinate of the button.

Return Value: 	None

See Also:     	wbar, wrectangle

Examples:	4, 13, 20




wcircle 
------------------------------------------------------------------------------
Function:     	Draws a circle with a given radius.

Declaration:  	void wcircle (int x, int y, int radius)

Remarks:      	wcircle draws a hollow circle using the given location and
              	radius.  

Parameters:   	x      - The X coordinate of the center of the circle.

              	y      - The Y coordinate of the center of the circle.

              	radius - The radius of the circle.  It must be greater 
                         than 0.

Return Value: 	None

See Also:    	wellipse, wfill_circle, wfill_ellipse

Examples:	4, 8

		   WordUp Graphics Toolkit: Library Reference        Page 22

wclip 
------------------------------------------------------------------------------
Function:     	Sets the current clipping area for all graphics pages.

Declaration:  	void wclip (int x1, int y1, int x2, int y2)

Remarks:      	(x1,y1) defines the upper left corner of the clipping area, and
              	(x2,y2) defines the lower right.   All of WGT's drawing
              	commands will draw within this boundary unless mentioned
              	otherwise.  Set the coordinates to (0,0,319,199) to 
              	'disable' clipping.

Parameters:   	x1 - The left X coordinate of the clipping region.

              	y1 - The top Y coordinate of the clipping region.

              	x2 - The right X coordinate of the clipping region.

              	y2 - The bottom Y coordinate of the clipping region.

Return Value: 	None

Examples:	4, 8, 11, 12, 17, 32




wcls
------------------------------------------------------------------------------
Function:     	Clears the currently selected graphics page with a specified
              	color number.

Declaration:  	void wcls (unsigned char col)

Remarks:      	This command fills the current drawing page with the color
              	given.  Clipping is not performed. 

Parameters:   	col - The color used to fill the screen.

Return Value: 	None

See Also:     	wnormscreen, wsetscreen

Examples:	2-4, 6-14

		   WordUp Graphics Toolkit: Library Reference        Page 23

wcolrotate 
------------------------------------------------------------------------------
Function:     	Cycles the colors within a specified group from a palette
              	variable.

Declaration:  	void wcolrotate (unsigned char start, unsigned char finish,
                                 int dir, color *palette)

Remarks:      	This routine takes the colors from start to finish and shifts
              	them one in the direction specified by dir. 
              	This effect can be used to simulate animation.

              	dir = 0, rotates up.
              	dir = 1, rotates down.

              	This function does NOT set the palette.  You must call 
              	wsetpalette in order to see the changes.  This allows you to
              	define multiple rotation areas at a time, by several calls
              	to wcolrotate.

Parameters:   	start   - First palette entry in rotation.

              	finish  - Last palette entry in rotation.

              	dir     - Direction of rotation.

              	palette - A pointer to the palette

Return Value: 	None

See Also:     	wsetpalette, wsetrgb

Examples:	5, 20, 27

		   WordUp Graphics Toolkit: Library Reference        Page 24

wcopyscreen
------------------------------------------------------------------------------
Function:     	Copies a section of one screen onto a different graphics page.

Declaration:  	void wcopyscreen (int x1, int y1, int x2, int y2, block source,
                                  int dx, int dy, block dest)

Remarks:      	This command copies a region of one graphics page to a new
              	location.  The source and destination pages may be the same
              	as long as the source and destination region do not overlap.
              	It is commonly used to copy from one page to another.

              	The area defined by (x1,y1,x2,y2) is copied from the screen
              	described by source, and is placed with the upper left corner
              	at (dx,dy) on the screen referred to by dest. For example,
              	to copy screen second(entirely) to the screen first, type
              	wcopyscreen(0,0,319,199,second,0,0,first). The visual page
              	can be accessed by replacing the destination or source with
              	NULL.

              	For example to copy firstscr to the visual page:
             	   wcopyscreen (0, 0, 319, 199, firstscr, 0, 0, NULL);
              	or the other way around:
             	   wcopyscreen (0, 0, 319, 199, NULL, 0, 0, firstscr);

              	You should also note that in the last example, firstscr must
              	already be allocated from another image function such as
              	wnewblock, or wloadblock.  It is not the same as
              	firstscr = wnewblock (0, 0, 319, 199) because wcopyscreen 
              	assumes there is already memory allocated for firstscr.

             	You can also copy a region of one screen to a different 
              	location on another. For example,
              	wcopyscreen(30,20,180,190,first,60,90,NULL);

              	Full clipping is performed, so you do not have to worry about
              	the coordinates being completely within the destination screen.

Parameters:   	x1     - The left X coordinate of the source region.

              	y1     - The top Y coordinate of the source region.

              	x2     - The right X coordinate of the source region.

              	y2     - The bottom Y coordinate of the source region.

              	source - A pointer to the source image.

              	dx     - The X coordinate in the destination region.

              	dy     - The Y coordinate in the destination region.

              	dest   - A pointer to the destination image.


Return Value: 	None

Examples:	16, 18-20, 23, 25, 29, 42

		   WordUp Graphics Toolkit: Library Reference        Page 25

wdetectcpu
------------------------------------------------------------------------------
Function:     	Determines the type of processor.  

Declaration:  	int wdetectcpu (void)

Remarks:      	This routine is useful for determining the processor type    
              	when WGT's 386 specific commands are used.  It returns      
              	either 0, 2,3,4 or 5 meaning pre-286, 286, 386, 486, or 
		Pentium.

Parameters:   	None

Return Value: 	The type of processor:
              	Value         CPU Type
              	  0            CPUOLD
              	  2            CPU286
              	  3            CPU386
              	  4            CPU486
              	  5            CPUPENTIUM

See Also:     	vgadetected

Examples:	45

		   WordUp Graphics Toolkit: Library Reference        Page 26

wdraw_scanpoly
------------------------------------------------------------------------------
Function:     	Draws a concave polygon which was previously scan converted
              	with the wscan_convertpoly routine.

Declaration:  	void wdraw_scanpoly (int x, int y, wscanpoly *newp, 
                                     void (*customline)(int x1, int x2, int y))

Remarks:      	The polygon must have been scan converted by the 
              	wscan_convertpoly routine before you call this routine.

              	X and Y are added to each vertex before drawing the polygon,
              	allowing you to move the shape to a different location.

              	customline is a pointer to a function which will draw a 
              	horizontal line.  If you set this to NULL, it will 
              	use the whline routine.  customline accepts three parameters,
              	the first two being the x coordinates of the line.  The third
              	is the y coordinate of the horizontal line.

              	You can write your own horizontal line routines that don't
              	fill the line with a solid color.  Some possibilities
              	include plasma, wall papering, or fill patterns.  

Parameters:   	x          - Horizontal offset added to each vertex.

              	y          - Vertical offset added to each vertex.

              	newp       - the rendered polygon structure containing 
                             the polygon to draw.

              	customline - A pointer to a function which draws a horizontal
                             line.

Return Value: 	None

See Also:     	wscan_convertpoly, wfree_scanpoly

Examples:	51

		   WordUp Graphics Toolkit: Library Reference        Page 27

wellipse
------------------------------------------------------------------------------
Function:     	Draws a hollow ellipse.

Declaration:  	void wellipse (int xc, int yc, int xr, int yr)

Remarks:      	Draws a hollow ellipse with center (xc,yc) using radius
		(xr,yr). Both xr and yr must be greater than 0. Set xr equal to 
		yr to draw a circle, or use the faster command wcircle.

Parameters:  	xc - Center of ellipse along horizontal axis.

              	yc - Center of ellipse along vertical axis.

              	xr - Horizontal radius in pixels.

              	yr - Vertical radius in pixels.

Return Value: 	None

See Also:     	wcircle, wfill_circle, wfill_ellipse

Examples:	4

		   WordUp Graphics Toolkit: Library Reference        Page 28

wems_close
------------------------------------------------------------------------------
Function:     	Closes down EMS, and releases any reserved EMS memory.

Declaration:  	void wems_close (void)

Remarks:      	Before you exit your program, you must call this routine
              	or the EMS memory you reserved with wems_open will not
              	be available until you reboot the computer.  EMS memory
              	is not like conventional memory which automatically gets
              	released when your program ends.  

Parameters:   	None

Return Value: 	None

See Also:     	wems_open, wems_present

Examples:	43, 52




wems_copy
------------------------------------------------------------------------------
Function:     	Copies a block into the page frame at the given offset.

Declaration:  	void wems_copy (block sb, unsigned offset, unsigned size)

Remarks:      	This is used to transfer regions of memory into the EMS
              	page frame.  Note that since blocks are defined as
              	unsigned char *, you can transfer any kind of allocated
              	data with this command.

              	Offset is the byte offset into the page frame and can
              	range from 0-65535.

Parameters:   	sb     - Pointer to the memory which will be copied to EMS.

              	offset - Destination offset into the page frame.

              	size   - Number of bytes to copy.

Return Value: 	None

Examples:	None

		   WordUp Graphics Toolkit: Library Reference        Page 29

wems_free
------------------------------------------------------------------------------
Function:     	Returns the number of unallocated EMS pages.

Declaration:  	long wems_free (void)

Remarks:      	This is used for finding out how much EMS memory your
              	program can use.  It returns the number of 16k pages that
              	are available.   For use with WGT, you must still allocate
              	them in 64k bundles, so you might have up to 48k of extra
              	EMS memory that you cannot use.

Parameters:   	None

Return Value: 	The number of unallocated 16k EMS pages.

Examples:	None




wems_getdata
------------------------------------------------------------------------------
Function:    	Maps data previously stored in EMS into the page frame, and 
             	returns a pointer to it.

Declaration:  	block wems_getdata (block mydata)

Remarks:      	This routine is used to restore data that you have put into
              	EMS memory with the wems_storedata routine.   It can be used
              	to bring any EMS data into the page frame.

Parameters:   	mydata - A pointer to the EMS block of memory.

Return Value: 	A pointer the data which has been mapped into the page frame.

See Also:     	wems_storedata

Examples:	43

		   WordUp Graphics Toolkit: Library Reference        Page 30

wems_getframe
------------------------------------------------------------------------------
Function:     	Maps four EMS pages into the page frame at once.

Declaration:  	void wems_getframe (int pagegroup)

Remarks:      	WGT uses EMS in 64k chunks in order to store full screen
              	pictures in EMS.  This command is used to map the given group
              	of four pages into the page frame all at once. This makes 
		virtual screens in EMS easier since we can write to the page 
		frame like any other virtual page in conventional memory.

              	The variable emscurpage is set equal to pagegroup.  This can 
              	be used to see if the current pages are already mapped in.

Parameters:   	pagegroup - First page in sequence (of 4) to copy into the
                            pageframe. Pages numbered pagegroup to pagegroup+3
                            will be used.

Return Value: 	None

See Also:     	wems_map

Examples:	None

		   WordUp Graphics Toolkit: Library Reference        Page 31

wems_getsprite
------------------------------------------------------------------------------
Function:     	Maps a sprite stored in EMS into the page frame, and returns
              	a pointer to it.

Declaration:  	block *wems_getsprite (int spr, block *sprites)

Remarks:      	This routine is used to restore a sprite that you have put into
              	EMS memory with the wems_storesprite routine.  sprites is the
              	name of the array you are holding your EMS pointers in.
              	It then uses spr as an index into that array, and maps that
              	pointer into the page frame.

              	Example:

              	   emsbl = wems_getsprite (2, mysprites);

              	This will get sprite number 2 of the mysprites array from EMS.

Parameters:   	spr     - Index of the sprite you wish to restore from EMS.

              	sprites - Array of sprites using EMS pointers.

Return Value: 	A pointer to the sprite which has been mapped into the page 
		frame.

See Also:     	wems_getdata, wems_getframe

Examples:	None




wems_init
------------------------------------------------------------------------------
Function:     	Initializes the EMS driver.

Declaration:  	int wems_init (void)

Remarks:      	This will initialize the EMS memory, and prepare it for
		use in your program.

Parameters:   	None

Return Value: 	0 = Failed, could not initialize
              	1 = Successful initialization

See Also:     	wems_open, wems_present

Examples:	43, 52

		   WordUp Graphics Toolkit: Library Reference        Page 32

wems_loadsprites
------------------------------------------------------------------------------
Function:     	Loads a sprite file into EMS memory.

Declaration:  	int wems_loadsprites (color *pal, char *filename, 
                                      block *sprites, int start, int end)

Remarks:      	WGT provides an easy way to load all of your sprites into
              	EMS memory at once.  The parameters of this routine are
              	the same as wloadsprites.  The difference is all the pointers
              	will be EMS pointers, instead of conventional pointers.
              	To use a sprite that is in EMS memory, you must first map
              	the sprite into the page frame using wems_getsprite. It will
              	return a conventional pointer which you can use with the
              	rest of WGT's commands.   You cannot have more than one
              	sprite mapped into the page frame at once, unless they are
              	stored in the same 64k page.   This means you must deal with
              	sprite images one at a time, since the next time you map in
              	a new image, the old one may be gone.
              
Parameters:   	pal      - Array of 256 colors used in sprites.

              	filename - Full pathname of sprite file to load.

              	sprites  - Array of EMS pointers to the sprites.

              	start    - Start index of the sprites to load.

              	end      - End index of the sprites to load.

Return Value: 	0 = error
              	1 = no error

See Also:     	wloadsprites

Examples:	43

		   WordUp Graphics Toolkit: Library Reference        Page 33

wems_map
------------------------------------------------------------------------------
Function:     	Maps an EMS page into the page frame.

Declaration:  	int wems_map (int phys, int logi)

Remarks:      	Normally, this routine is for internal use only.  However, 
              	if you decide to write your own EMS routines, you can use
              	this routine to map a EMS page into the page frame.

              	phys can be 0,1,2 or 3.  The page frame is made up of 4
              	16k pages which are mapped into conventional memory.
              	When you write data into the page frame, you are actually
              	writing the EMS memory that has been mapped into that space.

              	logi is the logical page, starting at 0, of the EMS memory
              	you reserved with wems_open.  It ranges from 0 to the number
              	of pages you reserved.

              	For example:

              	If you want to store a 64k picture in the first portion of
              	your reserved EMS memory, map in the four pages like this

              	wems_map(0,0);
              	wems_map(1,1);
              	wems_map(2,2);
              	wems_map(3,3);

              	and copy the full picture into the page frame. You can then
              	map other pages in and out and the picture will be kept in
              	EMS memory.  If you want to retrieve the picture, map the
              	first four pages in again, and copy from the page frame
              	to your destination (ie VGA ram, temporary buffer, etc).

Parameters:   	phys - Physical page number.

              	logi - Logical page number.

Return Value: 	0 = error
              	1 = success                       

See Also:     	wems_getdata, wems_getframe

Examples:	None

		   WordUp Graphics Toolkit: Library Reference        Page 34

wems_open
------------------------------------------------------------------------------
Function:     	Allocates a portion of EMS memory.

Declaration:  	int wems_open (int pages)

Remarks:      	Pages is the number of 16k EMS pages your program requires.
              	Since all of WGT's EMS routines must be able to operate
              	with a full screen of graphics, which requires 64k, pages
              	MUST be a multiple of 4.  This means that the amount of
              	memory you can allocate must be a multiple of 64k.

              	For example, to reserve 256k for your program,
              	  wems_open (16);   /* 16 * 16k gives you 256k */

Parameters:   	pages - Number of 16 kilobyte pages to allocate in EMS.

Return Value: 	0 = Error, could not reserve the memory requested
              	1 = Success, EMS memory reserved

See Also:     	wems_init, wems_present

Examples:	43, 52




wems_present
------------------------------------------------------------------------------
Function:     	Checks to see if EMS memory is available

Declaration:  	int wems_present (void)

Remarks:      	This routine determines if you can use EMS for storing data.
              	It returns 0 if EMS is not found, or 1 if EMS is present.
              	WGT can use EMS memory for loading sprites and storing
              	blocks of data.

Parameters:   	None

Return Value: 	0 = no EMS found
              	1 = EMS found

See Also:     	wems_init, wems_open

Examples:	43, 52

		   WordUp Graphics Toolkit: Library Reference        Page 35

wems_storeblock
------------------------------------------------------------------------------
Function:     	Changes a block stored in conventional memory to a block stored
              	in EMS memory.

Declaration:  	block wems_storeblock (block spr)

Remarks:      	This command is used to convert a previously allocated block
              	into one that is stored in EMS memory.  It will copy the block
              	spr into the next available place in EMS memory, free the
              	conventional memory previously used, and return an EMS pointer
              	to the block.

              	EMS pointers are specific to WGT's EMS system. Since pointers
              	are made of 4 bytes, we can use them to store information
              	about the position in EMS memory.  The segment word (first
              	half) is used to store the EMS page.  The offset word (second
              	half) is used to store the offset of the block within the
              	EMS page.  The page refers to a 64k block, or 4 EMS pages.
              	The offset can therefore be from 0-65535.  WGT never uses
              	an offset of 0, since your first EMS pointer would be 0000:0000
              	which is a NULL pointer.  All block routines consider NULL
              	pointers as empty, and this would cause some errors.

              	Here is an example EMS pointer:

              	     0001:1234
              	Page --^   ^---Offset

Parameters:   	spr - Pointer to image in conventional memory.

Return Value: 	An EMS pointer to the block.

See Also:     	wems_storedata

Examples:	43

		   WordUp Graphics Toolkit: Library Reference        Page 36

wems_storedata
------------------------------------------------------------------------------
Function:     	Changes a block of conventional ram data into EMS data.

Declaration:  	block wems_storedata (block mydata, unsigned size)

Remarks:      	While wems_storesprite is used to store image data,
              	wems_storedata can be used to store any kind of data in
              	EMS memory.  Do not be fooled by this function because it
              	returns a block.  Blocks are simply unsigned char *, so you
              	can store any pointer you want with it.  You must supply the 
              	size of the data contained in mydata.

Parameters:   	mydata - Pointer to data in conventional memory.

              	size   - Number of bytes to copy.

Return Value: 	An EMS pointer to the data.

See Also:     	wems_storeblock

Examples:	None




wems_reset
------------------------------------------------------------------------------
Function:     	Resets the WGT EMS driver to start loading files from the
              	beginning of EMS memory.

Declaration:  	void wems_reset (void)             

Remarks:      	This routine is used when you want to erase all of the data
              	currently stored in EMS and replace it with new data. 
              	It simply sets two variables:

              	emsoffset = 1;
              	emspage = 0;

              	These variable tell WGT where to put the next data into EMS.
              	You should set all EMS pointers to NULL after calling this
              	routine, because all the data in EMS will be overwritten.

Parameters:   	None

Return Value: 	None

See Also:     	wems_init

Examples:	43

		   WordUp Graphics Toolkit: Library Reference        Page 37

wfade
------------------------------------------------------------------------------
Function:   	Dissolves a screen of memory onto the active screen.

Declaration:  	void wfade (block sourcescreen, int *patt, int speed)

Remarks:      	The screen described by sourcescreen is dissolved onto the
              	active screen using the pattern specified by patt. 
              	Patt is an array of integers.  It can be defined by the
              	program called dissolve.exe, included with WGT. After saving a
              	pattern with this program, include the code generated into your
              	program, and pass it the array to this procedure.
              	The speed is the amount to delay after each pixel is copied.

Parameters:   	sourcescreen - Pointer to screen which will replace active
                               screen after fade. 

              	patt         - Array of integers used to define fade pattern.

              	speed        - Delay in milliseconds between pixel updates.

Return Value: 	None

Examples:	6, 17, 20, 49

		   WordUp Graphics Toolkit: Library Reference        Page 38

wfade_between 
------------------------------------------------------------------------------
Function:     	Gradually fades in a group of colors from one palette
              	to another palette using the specified speed.

Declaration:  	void wfade_between (unsigned char start, unsigned char finish,
                                    int speed, color *pal1, color *pal2)

Remarks:      	The colors from start to finish are faded from pal1 to pal2.
              	The speed may range from (0..32767), and is similar to using
              	the DELAY command between each change of the colors.

Parameters:   	start  - Start index of palette array for fade range.

              	finish - End index of palette array for fade range.
              
              	speed  - Delay in milliseconds between color updates.
              
              	pal1   - Starting palette.
              
              	pal2   - Palette which will result from fade.

Return Value: 	None

See Also:     	wfade_between_once, wfade_in, wfade_in_once, wfade_out, 
              	wfade_out_once

Examples:	49

		   WordUp Graphics Toolkit: Library Reference        Page 39

wfade_between_once
------------------------------------------------------------------------------
Function:     	Fades in a group of colors from one palette
              	to another, performing only 1/64th of the fade operation.

Declaration:  	void wfade_between_once (unsigned char start, 
                                         unsigned char finish, color *pal1, 
                                         color *pal2)

Remarks:      	The colors from start to finish are faded from pal1 to pal2.
              	This routine only performs one step of the fade to allow other
              	operations to be performed while the colors are fading.
              	It must be called at least 64 times to complete the fade 
              	between the palettes. The palette is not set by this routine, 
		so you must use wsetpalette to do so. After this is called 64 
		times, pal1 = pal2, so be sure to preserve pal1 in another 
		color buffer if you don't want to lose it.

Parameters:   	start  - Start index of palette array for fade range.

              	finish - End index of palette array for fade range.

              	pal1   - Starting palette.

              	pal2   - Palette which will result from fade.

Return Value: 	None

See Also:     	wfade_between, wfade_in, wfade_in_once, wfade_out, 
              	wfade_out_once

Examples:	49

		   WordUp Graphics Toolkit: Library Reference        Page 40

wfade_in  
------------------------------------------------------------------------------
Function:     	Gradually fades in a group of colors from black to a palette 
              	variable using a specified speed.

Declaration:  	void wfade_in (unsigned char start, unsigned char finish,
                               int speed, color *mypalette)

Remarks:      	The colors from start to finish are faded in starting from
              	black. The speed may range from (0..32767), and is similar to
              	using the DELAY command between each change of the colors.

Parameters:   	start     - Start index of palette array for fade range.

              	finish    - End index of palette array for fade range.

              	speed     - Delay in milliseconds between color updates.

              	mypalette - Colors will fade from black to the ones contained
                            in this array.

Return Value: 	None

See Also:     	wfade_between, wfade_between_once, wfade_in_once, wfade_out, 
              	wfade_out_once

Examples:	6, 20

		   WordUp Graphics Toolkit: Library Reference        Page 41

wfade_in_once
------------------------------------------------------------------------------
Function:     	Fades in a group of colors from black to a palette variable,
              	performing only 1/64th of the fade operation.

Declaration:  	void wfade_in_once (unsigned char start, unsigned char finish,
                                    color *mypalette, color *temppal)

Remarks:      	The colors from start to finish are faded from black to 
              	mypalette.  This routine only performs one step of the fade
              	to allow other operations to be performed while the colors are
              	fading.  It must be called at least 64 times to complete the
              	fade. You must pass temppal as a black palette.

Parameters:   	start     - Start index of palette array for fade range.

              	finish    - End index of palette array for fade range.

              	mypalette - Colors will fade from black to the ones contained
                            in this array.

Return Value: 	None

See Also:     	wfade_between, wfade_between_once, wfade_in, wfade_out, 
              	wfade_out_once

Examples:	6

		   WordUp Graphics Toolkit: Library Reference        Page 42

wfade_out 
------------------------------------------------------------------------------
Function:     	Gradually fades out a group of colors from a palette variable
              	(using a specified speed) to black.

Declaration:  	void wfade_out (unsigned char start, unsigned char finish,
                                int speed, color *palette)

Remarks:      	The colors from start to finish are faded out to black starting
              	from the palette given.  black. The speed may range from 
              	(0..32767), and is similar to using the DELAY command between 
              	each change of the colors.

Parameters:   	start   - Start index of palette array for fade range.

              	finish  - End index of palette array for fade range.

              	speed   - Delay in milliseconds between color updates.

              	palette - Palette will fade from these colors to black.

Return Value: 	None

See Also:     	wfade_between, wfade_between_once, wfade_in, wfade_in_once,
              	wfade_out_once              

Examples:	6

		   WordUp Graphics Toolkit: Library Reference        Page 43

wfade_out_once
------------------------------------------------------------------------------
Function:     	Fades out a group of colors from a palette variable to black,
              	performing only 1/64th of the fade operation.

Declaration:  	void wfade_out_once (unsigned char start, unsigned char finish,
                                     color *mypalette)

Remarks:      	The colors from start to finish are faded from mypalette to
              	black.  This routine only performs one step of the fade
              	to allow other operations to be performed while the colors are
              	fading.  It must be called at least 64 times to complete the
              	fade.

Parameters:   	start     - Start index of palette array for fade range.
              
              	finish    - End index of palette array for fade range.

              	mypalette - Colors will fade from this palette to black.

Return Value: 	None

See Also:     	wfade_between, wfade_between_once, wfade_in, wfade_in_once, 
              	wfade_out

Examples:	6

		   WordUp Graphics Toolkit: Library Reference        Page 44

wfastputpixel 
------------------------------------------------------------------------------
Function:     	Plots a pixel at the given screen coordinate without clipping.  

Declaration:  	void wfastputpixel (int x, int y)

Remarks:      	This routine operates the same as wputpixel only it ignores 
              	clipping.  This is the fastest pixel plotting method.

Parameters:   	x - Pixel coordinate along horizontal axis.

              	y - Pixel coordinate along vertical axis.

Return Value: 	None

See Also:     	wgetpixel, wputpixel

Examples:	2, 39, 51




wfill_circle 
------------------------------------------------------------------------------
Function:     	Draws a filled circle with a given radius.

Declaration:  	void wfill_circle (int x, int y, int radius)

Remarks:      	(x,y) is the center of the circle to be drawn. 
              	Radius is the size in pixels horizontally.  It must be
              	greater than 0.

Parameters:   	x      - Pixel coordinate along horizontal axis.

              	y      - Pixel coordinate along vertical axis.

              	radius - Radius of circle in pixel units.

Return Value: 	None

See Also:     	wcircle, wellipse, wfill_ellipse

Examples:	4, 10, 12, 18, 27, 43

		   WordUp Graphics Toolkit: Library Reference        Page 45

wfill_ellipse
------------------------------------------------------------------------------
Function:     	Draws a filled ellipse.

Declaration:  	void wfill_ellipse (int xc, int yc, int xr, int yr)

Remarks:      	Draws a filled ellipse with center (xc,yc) using radius 
		(xr,yr). Both xr and yr must be greater than 0.

Parameters:   	xc - Center of ellipse on horizontal axis.

              	yc - Center of ellipse on vertical axis.

              	xr - Radius of ellipse along horizontal axis (in pixels).

              	yr - Radius of ellipse along vertical axis (in pixels).

Return Value: 	None

See Also:     	wcircle, wfill_circle, wellipse

Examples:	4, 43




wflashcursor
------------------------------------------------------------------------------
Function:     	Flash the cursor using the values set by wsetcursor and
              	the global variable curspeed.

Declaration:  	void wflashcursor (void)

Remarks:      	This routine uses the cursor coordinates set by the global
              	variables xc and yc. Curspeed is another global variable which 
              	can be set to change the flashing speed.

              	wflashcursor will display the software emulated cursor,
              	delay according to curspeed, erase the cursor, delay again,
              	and then return.  It will erase the cursor and return 
              	immediately if a key is pressed. 

Parameters:   	None

Return Value: 	None

See Also:     	wstring

Examples:	14

		   WordUp Graphics Toolkit: Library Reference        Page 46

wfline 
------------------------------------------------------------------------------
Function:     	Draws a line between two points, without clipping.

Declaration:  	void wfline (int x1, int y1, int x2, int y2)

Remarks:      	This routine is similar to wline, except that no clipping
              	is performed on the line. This results in a slightly faster
		routine, although care must be taken to ensure that the
             	endpoints are within screen boundaries.

Parameters:   	x1 - Horizontal coordinate of first endpoint.

              	y1 - Vertical coordinate of first endpoint.

              	x2 - Horizontal coordinate of second endpoint.

              	y2 - Vertical coordinate of second endpoint.

Return Value: 	None

See Also:     	wline, wstyleline

Examples:	4, 16, 19, 20, 25




wflipblock
------------------------------------------------------------------------------
Function:     	Flips a block in one of two directions. The block is physically
              	changed in memory, not on the screen.

Declaration:  	void wflipblock (block blockname, int direction)

Remarks:      	This procedure will flip a previously stored image either
              	vertically or horizontally. The stored image is physically
              	changed, and therefore the results will not be seen until
              	the block is displayed with wputblock.

              	direction is defined as the following:

              	vertical   = 0
              	horizontal = 1

Parameters:   	blockname - Pointer to the image which we will flip.

              	direction - Indicates axis along which the flip is performed.

Return Value: 	None

See Also:     	wfreeblock, wnewblock, wputblock, wresizeblock

Examples:	10, 19

		   WordUp Graphics Toolkit: Library Reference        Page 47

wfree_scanpoly
------------------------------------------------------------------------------
Function:     	Frees memory used by a polygon buffer.

Declaration:  	void wfree_scanpoly (wscanpoly *freep)

Remarks:      	When you use wscan_convertpoly, the polygon is stored in a
              	buffer which must be deallocated before you use the buffer 
              	again.  This routine will free the memory used by one of these
              	scan converted polygons.

Parameters:   	freep - Buffer in which the polygon was stored, and will now
                        be deallocated.

Return Value: 	None

See Also:     	wdraw_scanpoly, wscan_convertpoly

Examples:	51

		   WordUp Graphics Toolkit: Library Reference        Page 48

wfreeblock
------------------------------------------------------------------------------
Function:     	Releases memory used to store an image.

Declaration:  	void wfreeblock (block blockname)

Remarks:      	When memory is allocated for a block, it is allocated 
              	dynamically using farmalloc.  Most commands that return a
              	block variable allocate this memory for you.  To release
              	this memory, use wfreeblock.   As with farmalloc, you cannot
              	use the same pointer twice in a row without freeing the
              	memory.

              	For example, the following code would produce memory errors:

              	pic = wloadblock ("myblock.blk");
              	pic = wloadblock ("myblock.blk");
              	...
              	wfreeblock (pic);

              	It should read:
              
              	pic = wloadblock ("myblock.blk");
              	wfreeblock (pic);
              	pic = wloadblock ("myblock.blk");
              	...
              	wfreeblock (pic);

Parameters:   	blockname - Pointer to image which is to be deallocated.

Return Value: 	None

See Also:     	wnewblock

Examples:	9-11, 15-21, 24, 32

		   WordUp Graphics Toolkit: Library Reference        Page 49

wfreefont 
------------------------------------------------------------------------------
Function:     	Frees memory previously allocated for a font.

Declaration:  	void wfreefont (wgtfont yourfont)

Remarks:      	When a bitmapped font is loaded with wloadfont, memory is
              	allocated dynamically.  This is similar in operation to
              	the block commands.  Use wfreefont to release the memory
              	for the font.

Parameters:   	yourfont - Pointer to font buffer which will be deallocated.

Return Value: 	None

See Also:     	wloadfont

Examples:	40, 41, 47




wfreesprites
------------------------------------------------------------------------------
Function:     	Frees memory from an array of blocks.

Declaration:  	void wfreesprites (block *spritearray, int start, int end)
     
Remarks:      	When a sprite file is loaded, several blocks are allocated
              	at once.  This routine will free all of the blocks in the
              	array from start to end. It should be noted that this routine
              	will deallocate the images, but will not set the pointers to
              	NULL. You must do this yourself if required.

              	  Example usage:
              	    block sprites[1001];
              	    ...
              	    wfreesprites (sprites, 0, 1000);

Parameters:   	spritearray - Array containing sprite pointers.

              	start       - Start index for sprite deallocation.
              
              	end         - End index for sprite deallocation.   

Return Value: 	None

See Also:     	wloadsprites

Examples:	19, 20, 22, 23, 25, 29, 31

		   WordUp Graphics Toolkit: Library Reference        Page 50

wget_capslock
------------------------------------------------------------------------------
Function:     	Returns the state of the Capslock key.

Declaration:  	int wget_capslock (void)

Remarks:      	This routine is used to report the state of the caps lock
              	key.  It cannot be used when the WGT keyboard interrupt is
              	installed.

Parameters:   	None

Return Value: 	0 = Capslock is off
              	1 = Capslock is on

See Also:     	wset_capslock

Examples:	44




wget_lalt
------------------------------------------------------------------------------
Function:     	Returns the state of the left Alt key.

Declaration:  	int wget_lalt (void)

Remarks:      	This routine is used to report the state of the left Alt
              	key.  It cannot be used when the WGT keyboard interrupt is
              	installed.

Parameters:   	None

Return Value: 	0 = Left Alt is released
              	1 = Left Alt is depressed

See Also:     	wget_ralt

Examples:	44

		   WordUp Graphics Toolkit: Library Reference        Page 51

wget_lctrl
------------------------------------------------------------------------------
Function:     	Returns the state of the Left Control key.

Declaration:  	int wget_lctrl (void)

Remarks:      	This routine is used to report the state of the left control
              	key.  It cannot be used when the WGT keyboard interrupt is
              	installed.

Parameters:   	None

Return Value: 	0 = Left Control is released
              	1 = Left Control is depressed

See Also:     	wget_rctrl

Examples:	44




wget_lshift
------------------------------------------------------------------------------
Function:     	Returns the state of the Left Shift key.

Declaration:  	int wget_lshift (void)

Remarks:      	This routine is used to report the state of the left shift
              	key.  It cannot be used when the WGT keyboard interrupt is
              	installed.

Parameters:   	None

Return Value:	0 = Left Shift is released
              	1 = Left Shift is depressed

See Also:     	wget_rshift

Examples:	44

		   WordUp Graphics Toolkit: Library Reference        Page 52

wget_numlock
------------------------------------------------------------------------------
Function:     	Returns the state of the Numlock key.

Declaration:  	int wget_numlock (void)

Remarks:      	This routine is used to report the state of the numlock
              	key.  It cannot be used when the WGT keyboard interrupt is
              	installed.

Parameters:   	None

Return Value: 	0 = Numlock is off
              	1 = Numlock is on

See Also:     	wset_numlock

Examples:	44




wget_ralt
------------------------------------------------------------------------------
Function:     	Returns the state of the Right Alt key.

Declaration:  	int wget_ralt(void)

Remarks:      	This routine is used to report the state of the right Alt
              	key.  It cannot be used when the WGT keyboard interrupt is
              	installed.

Parameters:   	None

Return Value: 	0 = Right Alt is released
              	1 = Right Alt is depressed

See Also:     	wget_lalt

Examples:	44

		   WordUp Graphics Toolkit: Library Reference        Page 53

wget_rctrl
------------------------------------------------------------------------------
Function:     	Returns the state of the Right Control key.

Declaration:  	int wget_rctrl (void)

Remarks:      	This routine is used to report the state of the right control
              	key.  It cannot be used when the WGT keyboard interrupt is
              	installed.

Parameters:   	None

Return Value: 	0 = Right Control is released
              	1 = Right Control is depressed

See Also:     	wget_lctrl

Examples:	44




wget_rshift
------------------------------------------------------------------------------
Function:     	Returns the state of the Right Shift key.

Declaration:  	int wget_rshift (void)

Remarks:      	This routine is used to report the state of the right shift
              	key.  It cannot be used when the WGT keyboard interrupt is
              	installed.

Parameters:   	None

Return Value: 	0 = Right Shift is released
              	1 = Right Shift is depressed

See Also:     	wget_lshift

Examples:	44

		   WordUp Graphics Toolkit: Library Reference        Page 54

wget_scrlock
------------------------------------------------------------------------------
Function:     	Returns the state of the Scroll Lock key.

Declaration:  	int wget_scrlock (void)

Remarks:      	This routine is used to report the state of the scroll lock
              	key.  It cannot be used when the WGT keyboard interrupt is
              	installed.

Parameters:   	None

Return Value: 	0 = Scroll Lock is off
              	1 = Scroll Lock is on

See Also:     	wset_scrlock

Examples:	44




wgetblockheight
------------------------------------------------------------------------------
Function:     	Returns height of a previously stored block.

Declaration:  	int wgetblockheight (block blockname)

Remarks:      	This routine returns the height of the block in pixels.
              	The height can range from 1 to 200.  If the block has
              	not been allocated, the result is undefined.

Parameters:   	blockname - Pointer to image which will be measured.

Return Value: 	Height of the block, in pixels.

See Also:     	wgetblockwidth, wnewblock

Examples:	11

		   WordUp Graphics Toolkit: Library Reference        Page 55

wgetblockwidth
------------------------------------------------------------------------------
Function:     	Returns width of a previously stored block.

Declaration:  	int wgetblockwidth (block blockname)

Remarks:      	This function returns the width of the block in pixels.
              	The width can range from 1 to 320.  If the block has
              	not been allocated, the result is undefined.

Parameters:   	blockname - Pointer to image which will be measured.

Return Value: 	Width of the block, in pixels.

See Also:     	wgetblockheight, wnewblock

Examples:	11, 29




wgetmode
------------------------------------------------------------------------------
Function:     	Returns the current video mode number.

Declaration:  	int wgetmode (void)

Remarks:      	This is used to store the current video state before changing
              	into graphics mode.  You can use wsetmode to restore the
              	mode before ending your program.

Parameters:   	None

Return Value: 	The mode number of the current video mode.

See Also:     	vga256, vgadetected, wsetmode

Examples:	1-24, 26-29, 31-38, 40, 42, 43, 46-49, 51-53

		   WordUp Graphics Toolkit: Library Reference        Page 56

wgetpixel 
------------------------------------------------------------------------------
Function:     	Gets the pixel value at the given screen coordinate. 

Declaration:  	unsigned char wgetpixel (int x, int y)

Remarks:      	This reads the color of a pixel from the current page and
              	returns the color value at the coordinate given.

Parameters:   	x - Horizontal coordinate of pixel to check.

              	y - Vertical coordinate of pixel to check.

Return Value: 	Color value of the pixel, between 0 and 255.

See Also:     	wfastputpixel, wputpixel

Examples:	2, 38




wgettextheight
------------------------------------------------------------------------------
Function:     	Returns the maximum height of the string.

Declaration:  	int wgettextheight (char *printit, wgtfont prfont)

Remarks:      	This function is used for justification of strings.
              	If prfont is NULL, it always returns 8, which is the height of
              	the default font.  If prfont is a pointer to a bitmapped font,
              	the height of the tallest character in the string is returned.

Parameters:   	printit - The string to measure.

              	prfont  - Pointer to the font used in measurement.

Return Value: 	The height in pixels of the tallest letter in the string.

See Also:     	wgettextwidth

Examples:	41

		   WordUp Graphics Toolkit: Library Reference        Page 57

wgettextwidth 
------------------------------------------------------------------------------
Function:     	Returns the width of the string.

Declaration:  	int wgettextwidth(char *printit, wgtfont prfont)

Remarks:      	This function is used for justification of strings.
              	If prfont is NULL, the width is 8 for each character. 
              	If prfont is a pointer to a bitmapped font, the width of each
              	character may vary.  

Parameters:   	printit - The string to be measured.

              	prfont  - Pointer to the font used in measurement.

Return Value: 	The total width in pixels of the string.

See Also:     	wgettextheight

Examples:	41

		   WordUp Graphics Toolkit: Library Reference        Page 58

wgouraudpoly
------------------------------------------------------------------------------
Function:     	Draws a Gouraud shaded convex polygon.

Declaration:  	void wgouraudpoly (tpolypoint *vertexlist, int numvertex, 
                                   int x, int y)

Remarks:      	The wgouraudpoly routine draws a Gouraud shaded polygon by 
              	shading the polygon between the colors at each vertex.
              	Each vertex is has the offset (x,y) added to it before the
              	polygon is drawn.   vertexlist is an array of vertices, which
              	contains numvertex vertices.

              	The tpolypoint structure is defined as:

              	typedef struct
              	 {
              	  int x, y;   /* Coordinate on the screen */
              	  int sx, sy; /* Coordinate on the texture */
              	 } tpolypoint;

            	wgouraudpoly uses the sx variable to store the color of the
              	vertex.  This means each vertex has a color value (0-255).
              	For Gouraud shading, the polygon uses color numbers between
              	the ones stored at the vertices.  For example, if one vertex
              	is color 5, and another is color 30, the polygon will use 
              	colors 5-30.   Therefore in order to make a shaded polygon,
              	those color values must be smoothly blended from one to the
              	other.  You can use the blend function in the WGT Sprite 
              	Editor to create a blended range of colors.

Parameters:  	vertexlist - Array of vertices defining the polygon.

             	numvertex  - Total number of vertices in the array.

              	x          - Horizontal offset added to each vertex.

              	y          - Vertical offset added to each vertex.

Return Value: 	None

See Also:     	whollowpoly, wsolidpoly, wtexturedpoly

Examples:	42, 54, 55

		   WordUp Graphics Toolkit: Library Reference        Page 59

wgtprintf 
------------------------------------------------------------------------------
Function:    	Prints text using the standard printf format.

Declaration:  	void wgtprintf (int xloc, int yloc, wgtfont prfont,
                               char *fmt, ... )

Remarks:      	Allows the user to print to the screen using the same
              	format as the printf command from Turbo C.
              	The text is printed at the screen coordinates xloc,yloc,
              	and uses the font prfont. The format is the same as
              	the printf command, so you can easily print numbers
              	within strings very easily.

              	Example:
              	wgtprintf (30, 40, bigfont, "Hello %s! You are %i years old.",
                           name, years);

              	If prfont is NULL, it uses the default 8x8 font.

              	Note: Special characters such as newline, bell, or carriage
              	return are NOT interpreted.  wgtprint will display the
              	character used by these codes.

Parameters:   	xloc   - Horizontal location for string display.

              	yloc   - Vertical location for string display.
              
              	prfont - Pointer to font which will be used.
              
              	fmt    - String for formatted output (see printf).

              	...    - Variables used for formatted string output.

Return Value: 	None

See Also:     	wouttextxy

Examples:	12, 20, 26, 35, 41, 43, 49, 51

		   WordUp Graphics Toolkit: Library Reference        Page 60

whline 
------------------------------------------------------------------------------
Function:    	Draws a horizontal line between two points.

Declaration: 	void whline (int x1, int x2, int y)

Remarks:     	This routine will draw horizontal lines faster than the
              	normal wline routine. Be careful when passing parameters
              	because the two x coordinates are passed before the single
              	y coordinate (different format than wline).

Parameters:   	x1 - Horizontal coordinate of first endpoint.

              	x2 - Horizontal coordinate of second endpoint.

              	y  - Vertical coordinate for the whole line.

Return Value: 	None

See Also:     	wfline, wline, wstyleline

Examples:	46

		   WordUp Graphics Toolkit: Library Reference        Page 61

whollowpoly
------------------------------------------------------------------------------
Function:	Draws a hollow polygon.

Declaration:	void whollowpoly (tpolypoint *vertexlist, int numvertex, 
                                 int x, int y, int closemode)

Remarks:	The whollowpoly routine draws a hollow polygon using
		the current color.  Each vertex is has the offset (x,y) added
		to it before the polygon is drawn.   vertexlist is an array
		of vertices, which contains numvertex vertices. closemode tells
		whether the polygon is open or closed. If closemode is 1, the 
		first and last points are connected.

              	The tpolypoint structure is defined as:

              	typedef struct
              	 {
              	  int x, y;   /* Coordinate on the screen */
              	  int sx, sy; /* Coordinate on the texture */
              	 } tpolypoint;

              	whollowpoly does not use the sx,sy variables.  While this is
              	wasteful of memory, it allows you to switch between polygon
              	rendering methods without altering your vertex data variables.

Parameters:  	vertexlist - Array of vertices defining the polygon.

              	numvertex  - Total number of vertices in the array.

              	x          - Horizontal offset added to each vertex.

              	y          - Vertical offset added to each vertex.

              	closemode  - Indicates if the polygon is open or closed.

Return Value:	None

See Also:    	wgouraudpoly, wsolidpoly, wtexturedpoly

Examples:	42, 54, 55

		   WordUp Graphics Toolkit: Library Reference        Page 62

wline 
------------------------------------------------------------------------------
Function:    	Draws a line between two points.

Declaration:  	void wline (int x1, int y1, int x2, int y2)

Remarks:      	(x1,y1) defines the first endpoint of the line. (x2,y2) defines
		the second endpoint of the line. The line is clipped if needed.

Parameters:   	x1 - Horizontal coordinate of first endpoint.

              	y1 - Vertical coordinate of first endpoint.

              	x2 - Horizontal coordinate of second endpoint.

              	y2 - Vertical coordinate of second endpoint.

Return Value: 	None

See Also:     	wfline, wstyleline

Examples:	1, 4, 5, 6, 9, 10, 12, 14, 15, 17, 18, 23, 28, 29, 33, 36

		   WordUp Graphics Toolkit: Library Reference        Page 63

wloadblock
------------------------------------------------------------------------------
Function:     	Loads a block file from disk into memory.

Declaration:  	block wloadblock (char *filename)

Remarks:      	wloadblock automatically allocates the appropriate amount
              	of memory, by calling farmalloc, and loads the data into the 
              	space allocated.  It then returns a pointer to this memory so
              	you may perform other actions on the block.   You do should NOT
              	call wnewblock before you load the block.  wnewblock is used
              	for reading a block off the current video page only.

              	Block files are the simplest of graphics file formats.
              	A block has the following format:

              	width : integer
              	height: integer
              	data  : width*height bytes (no compression)

              	No palette data is stored in a block.  You must load palettes
              	separately with wloadpalette if you use block files.

Parameters:   	filename - Full pathname of image to be loaded.

Return Value: 	A pointer to the block loaded. If the block could not be
              	found on disk, it returns NULL.

See Also:     	wsaveblock

Examples:	11, 21, 24, 32, 35, 47, 48, 49, 53

		   WordUp Graphics Toolkit: Library Reference        Page 64

wloadbmp
------------------------------------------------------------------------------
Function:     	Loads a BMP image and converts it into block format.

Declaration:  	block wloadbmp (char *fname, color *pal)

Remarks:      	Given a filename, this function loads the BMP image and
              	converts it to block format (image may be mono, 2/4/8 or
              	24-bit color). Images which are larger than 64k may be
              	loaded, but custom display routines must be written.

Parameters:   	fname - Full pathname of image to be loaded.

              	pal   - Color array for image palette.

Return Value: 	Pointer to the loaded BMP, in block format. If the BMP could
              	not be found on disk, it returns NULL.

See Also:     	wsavebmp

Examples:	35




wloadcel
------------------------------------------------------------------------------
Function:     	Loads a CEL file (AutoDesk Animator format) from disk into 
              	memory.

Declaration: 	block wloadcel (char *filename, color *palette)

Remarks:      	CEL files are created with AutoDesk Animator.  The newer 
              	version, Animator Pro, is not compatible with WGT's CEL format.
              	You should use the POCO program oldcel included with
              	Animator Pro to save the old format supported by WGT.

              	wloadcel automatically allocates the appropriate amount
              	of memory by calling farmalloc, and loads the data into the 
              	space allocated.  It then returns a pointer to this memory so
              	you may perform other actions on the block.   You should NOT 
              	call wnewblock before you load the block.

Parameters:   	filename - Full pathname of image to be loaded.

              	palette  - Color array for image palette.

Return Value: 	Pointer to the loaded cel, in block format. If the CEL could
              	not be found on disk, it returns NULL.

See Also:     	wsavecel

Examples:	35, 42

		   WordUp Graphics Toolkit: Library Reference        Page 65

wloadfont
------------------------------------------------------------------------------
Function:     	Loads a bitmapped font from disk and returns a pointer to it.

Declaration:  	wgtfont wloadfont (char *fontfile)

Remarks:      	Fonts can be used with wouttextxy, wgtprintf, or wstring.
              	Custom fonts are created with the WGT Sprite Editor.

              	Example:
              	myfont = wloadfont ("tiny.wfn");

              	Bitmapped fonts require memory to be allocated when loading
              	them, so you should use wfreefont to release this memory when
              	you are finished using the font.

Parameters:   	fontfile - Full pathname of font to load.

Return Value: 	Pointer to font in memory.

See Also:     	wfreefont, wouttextxy, wstring

Examples:	26, 40, 41, 47




wloadpak
------------------------------------------------------------------------------
Function:     	Loads a compressed PAK file from disk into memory.

Declaration:  	block wloadpak (char *filename)

Remarks:      	wloadpak automatically allocates the appropriate amount
              	of memory by calling farmalloc, and loads the data into the 
              	space allocated.  It then returns a pointer to this memory so
              	you may perform other actions on the block.  You do should NOT
              	call wnewblock before you load the block.

              	PAK files are a custom format, only used within WGT
              	applications.  It uses a run-length encoding compression
              	scheme, and compresses a bit better than the PCX format.
              	No palette information is saved.

Parameters:   	filename - Full pathname for image to be loaded.

Return Value: 	Pointer to the loaded PAK file, in block format. If the PAK
              	could not be found on disk, it returns NULL.

See Also:     	wsavepak

Examples:	35

		   WordUp Graphics Toolkit: Library Reference        Page 66

wloadpalette
------------------------------------------------------------------------------
Function:     	Loads a palette file from disk into a palette variable.

Declaration:  	void wloadpalette (char *filename, color *palette)

Remarks:      	Palette files created by WGT or popular graphics programs may
              	be loaded into the variable specified by palette. Changes are 
              	not made to the currently displayed palette. A good example of
              	compatibility would be the AutoDesk Animator. It's .COL files
              	are of this type.  Many commercial games use these files as
              	well.  Each file must be exactly 768 bytes, or it is an 
              	incorrect format.

              	The format of a palette file is:

              	  unsigned char red1
              	  unsigned char green1
              	  unsigned char blue1
              	  unsigned char red2
              	  unsigned char green2
              	  unsigned char blue2
              	  ...
              	  unsigned char red256
              	  unsigned char green256
              	  unsigned char blue256

              	These values are repeated for each of the 256 palette
              	registers, giving you a 768 byte file (3*256).

Parameters:   	filename - Full pathname for palette file to be loaded.

              	palette  - Array in which to load the palette.

Return Value: 	None

See Also:     	wsavepalette, wsetpalette, wsetrgb

Examples:	11, 21, 24, 32, 35, 39, 48, 49, 53

		   WordUp Graphics Toolkit: Library Reference        Page 67

wloadpcx256
------------------------------------------------------------------------------
Function:     	Loads a PCX file from disk into memory.

Declaration:  	block wloadpcx256 (char *filename, color *palette)

Remarks:      	wloadpcx256 automatically allocates the appropriate amount
              	of memory by calling farmalloc, and loads the data into the
              	space allocated.  It then returns a pointer to this memory so
              	you may perform other actions on the block.   You do should NOT
              	call wnewblock before you load the block.

              	PCX files are created from many drawing programs.  It uses
              	a run-length encoding compression scheme and unlike the
              	PAK format, includes palette information.

              	PCX files MUST be 256 color bitmaps.  Pictures with 16 colors
              	or less are not supported.

Parameters:   	filename - Full pathname for PCX image to be loaded.
              
              	palette  - Array in which the PCX's palette will be stored.

Return Value: 	Pointer to the loaded PCX, in block format. If the PCX could
              	not be found on disk, it returns NULL.

See Also:     	wsavepcx256

Examples:	35

		   WordUp Graphics Toolkit: Library Reference        Page 68

wloadsprites
------------------------------------------------------------------------------
Function:     	Loads in a sprite file.

Declaration:  	int wloadsprites (color *palette, char *filename,                       
	                  	  block *spritearray, int start, int end)

Remarks:      	wloadsprites will load a sprite file created with the 
              	WGT Sprite Editor.  palette is the variable to store the
              	palette of the sprites into.  The command only loads
              	sprites with numbers start to end.  spritearray is
              	an array of blocks to load the sprites into.  Your array
              	must be large enough to hold the number of sprites between
              	start and end.

              	Example usage:
              	   block mysprites[800];
              	   ...
              	   ok = wloadsprites (palette, "game.spr", mysprites, 0, 500);

              	Furthermore, you can "chain" sprite files together by
              	giving an offset of the block array. For example to load
              	another file at the end of the previous file,

              	  ok = wloadsprites (palette, "stuff.spr", &mysprites[501], 
                                     0, 200);

Parameters:  	palette     - Array of colors used in sprites.

              	filename    - Full pathname of sprite file to load from.

              	spritearray - Array of pointers to the sprites loaded.

              	start       - Start index of sprites to load.

              	end         - End index of sprites to load.

Return Value: 	-1 = unsuccessful
              	 0 = successful

See Also:    	wfreesprites 

Examples:	19, 20, 22, 23, 25, 29, 31

		   WordUp Graphics Toolkit: Library Reference        Page 69

wnewblock 
------------------------------------------------------------------------------
Function:     	Captures a section of the screen into a block.

Declaration:  	block wnewblock (int x1, int y1, int x2, int y2)

Remarks:      	Dynamic memory is used to automatically calculate the size of
              	the data, and to store it in the standard block format.
              	See wloadblock for a description of this format.
              
              	The size of the block is calculated, and then farmalloc is
              	allocated to reserve enough memory for the block.  The section
              	of the current page is copied into this memory, and a pointer
              	is returned to the new block.
              	(x1,y1) defines the upper left corner of the region, and
              	(x2,y2) defines the lower right corner.
              
              	example:
              	block mypicture;
              	void main (void)
              	{
              	 ...
              	 mypicture = wnewblock (50, 50, 60, 60);
              	 ...
              	}

Parameters:   	x1 - Horizontal coordinate of left edge.

              	y1 - Vertical coordinate of upper edge.

              	x2 - Horizontal coordinate of right edge.

              	y2 - Vertical coordinate of lower edge.

Return Value: 	A pointer the to block.  If there is not enough memory to
              	create the block, it returns NULL.

See Also:     	wflipblock, wfreeblock, wgetblockheight, wgetblockwidth,
              	wloadblock, wputblock, wsaveblock 

Examples:	9, 10, 15-20, 24, 27, 33, 42, 43, 47, 51

		   WordUp Graphics Toolkit: Library Reference        Page 70

wnormscreen 
------------------------------------------------------------------------------
Function:     	Sets the active page back to the original visual page.

Declaration:  	void wnormscreen (void)

Remarks:      	This is used to return all drawing operations to the normal
              	(visual) screen.

Parameters:   	None

Return Value: 	None

See Also:     	wfreeblock, wnewblock, wsetscreen

Examples:	11, 15, 16, 17, 18, 20, 24, 33, 43




wouttextxy
------------------------------------------------------------------------------
Function:     	Outputs a string of text.

Declaration:  	void wouttextxy (int x, int y, wgtfont prfont, char *string)

Remarks:      	The coordinate system may be 40*25 or 320*200 depending on 
              	the state of the text grid system.  See the wtextgrid procedure
              	for more information. It uses prfont for displaying bitmapped
              	fonts which were loaded with wloadfont.

              	In place of the wgtfont, use NULL to display text with
              	the default 8x8 font.

Parameters:   	x      - Horizontal coordinate for string display. 

              	y      - Vertical coordinate for string display.

              	prfont - Pointer to font which will be used.

              	string - String to display.

See Also:     	wgtprintf, wloadfont, wstring, wtextgrid

Return Value: 	None

Examples:	4, 7, 13, 14, 15, 20, 24, 48

		   WordUp Graphics Toolkit: Library Reference        Page 71

wpan 
------------------------------------------------------------------------------
Function:     	Changes the offset of the visual screen.

Declaration:  	void wpan (unsigned int offset)

Remarks:      	This can be used for special effects to make the screen shake. 
              	Each row contains 320 pixels across. Therefore the screen will
              	shift up one if the offset is 320.  Offsets with multiples of
              	320 will shift the screen up or down, and other offsets will 
              	move left or right.  For a shaking effect, use small offsets 
              	(0-5).

Parameters:   	offset - Offset in pixel units used to shift screen display.

Return Value: 	None

Examples:	28




wputblock 
------------------------------------------------------------------------------
Function:     	Displays a block onto the current graphics page.

Declaration:  	void wputblock (int x, int y, block blockname, int mode)

Remarks:      	This routine is used in a variety of situations for displaying
              	bitmapped imaged onto the screen.   It can be used to show
              	single sprites, or full screen pictures which have been loaded
              	with the set of image commands.  X and y are the coordinates 
              	on the screen to show the bitmap blockname, and mode can be
              	either:

              	0 = Normal
              	1 = XRay

              	The XRay mode uses the 0 color as a "see-through" color.  Any
              	occurrence of this color is not drawn on the screen. This is
              	useful for drawing sprites which overlay a background screen.

Parameters:   	x         - Horizontal coordinate for image display.

              	y         - Vertical coordinate for image display.

              	blockname - Pointer to image which will be displayed.

              	mode      - Technique used to display image.

Return Value: 	None

See Also:     	wloadblock, wloadbmp, wloadcel, wloadpak, wloadpcx256, 
              	wnewblock

Examples:	9, 10, 11, 15, 18-21, 29, 31, 33, 35, 43, 47-49

		   WordUp Graphics Toolkit: Library Reference        Page 72

wputpixel 
------------------------------------------------------------------------------
Function:     	Plots a pixel at the given screen coordinate.

Declaration:  	void wputpixel (int x, int y)

Remarks:      	Draws a point in the current drawing color (set by wsetcolor)
              	at the coordinate (x,y) of the current graphics page.

Parameters:   	x - Horizontal coordinate of pixel to set.

              	y - Vertical coordinate of pixel to set.
          
Return Value: 	None

See Also:     	wfastputpixel, wgetpixel

Examples:	2, 8, 38




wreadpalette 
------------------------------------------------------------------------------
Function:     	Reads the current palette into a palette variable.

Declaration: 	void wreadpalette (unsigned char start, unsigned char finish, 
                                   color *palette)

Remarks:      	Reads the palette registers between start and finish and stores
              	them into the palette variable.  This is used to capture the
              	palette being used at the time.

Parameters:   	start   - Start index of palette array to set.

              	finish  - End index of palette array to set.

              	palette - Array of colors to be altered.

Return Value: 	None

See Also:     	wloadpalette, wsavepalette, wsetcolor, wsetpalette, wsetrgb  

Examples:	4, 27, 40, 47-49

		   WordUp Graphics Toolkit: Library Reference        Page 73

wrectangle 
------------------------------------------------------------------------------
Function:     	Draws a rectangle using the current color and graphics page.

Declaration:  	void wrectangle (int x1, int y1, int x2, int y2)

Remarks:	(x1,y1) defines the upper left corner of the rectangle, and
              	(x2,y2) defines the lower right.

Parameters:	x1 - Horizontal coordinate of left edge.

		y1 - Vertical coordinate of upper edge.

		x2 - Horizontal coordinate of right edge.

		y2 - Vertical coordinate of lower edge.

Return Value: 	None

See Also:     	wbar

Examples:	4, 43




wregionfill 
------------------------------------------------------------------------------
Function:     	Fills an area of the screen bounded by any color. 
              

Declaration:  	void wregionfill (int x, int y)

Remarks:      	Fills an enclosed area starting at (x,y), which is bounded by
              	pixels of any color other than the one at the original point.
              	Full clipping is performed.

Parameters:   	x - Horizontal coordinate of starting pixel.

              	y - Vertical coordinate of starting pixel.

Return Value: 	None

Examples:	8

		   WordUp Graphics Toolkit: Library Reference        Page 74

wremap 
------------------------------------------------------------------------------
Function:     	Remaps the colors of a block or the visual screen to a new
		palette.

Declaration:  	void wremap (color *pal1, block remapblock, color *pal2)

Remarks:      	pal1 is the palette belonging to the block remapblock.  pal2
              	contains the new palette the block will use after remapping.
              	This changes every pixel in the block from the normal palette,
              	to the closest color in the new palette pal2.
		If remapblock is NULL, the visual screen is used.

Parameters:   	pal1       - Array of colors normally used for image.

              	remapblock - Image to be remapped.

              	pal2       - Palette to remap block with.

Return Value: 	None

See Also:     	wloadblock, wloadpalette

Examples:	48

		   WordUp Graphics Toolkit: Library Reference        Page 75

wresize
------------------------------------------------------------------------------
Function:    	Draws a previously stored image on the screen to fit within a
		given boundary.

Declaration: 	void wresize (int x1, int y1, int x2, int y2, block blockname,
                              int mode)

Remarks:      	This routine will stretch a bitmapped image to a different size
              	than it was originally stored in.  The bitmap is displayed
              	on the current graphics page.  If the new size is larger than
              	the original, the image becomes blockier.  If the new size is
              	smaller, some of the pixels within the image are removed.
              	Resizing is generally used in special effects sequences, not
              	within a game animation loop.  It is too slow to draw several
              	resized bitmaps on the screen at once, so you should resize
              	each image beforehand and store each one as a block.
              	mode is similar to the mode in wputblock.  

              	mode = 0 : Normal
              	mode = 1 : X-ray (color 0 is not copied)

Parameters:   	x1        - Horizontal coordinate of left edge.

              	y1        - Vertical coordinate of upper edge.

              	x2        - Horizontal coordinate of right edge.

              	y2        - Vertical coordinate of lower edge.

              	blockname - Pointer to image which will be resized.

              	mode      - Technique used when resizing (xray or normal)

Return Value: 	None

See Also:	wvertres

Examples:	11, 19

		   WordUp Graphics Toolkit: Library Reference        Page 76

wretrace 
------------------------------------------------------------------------------
Function:     	Waits for the vertical retrace.

Declaration:  	void wretrace (void)

Remarks:      	Use the wretrace command when you get flickering graphics.
              	This command waits for the vertical retrace on your monitor, 
              	so you can write to the screen while it is not refreshing the
              	screen.

              	It will not work perfectly unless you are writing small
              	amounts to the screen, but it is worth a try if you get
              	flickering screens. This routine is also used for timing 
		(obtaining constant speeds on different CPUs).

Parameters:   	None

Return Value: 	None

Examples:	5, 20, 22, 23, 24, 25, 29, 37, 39, 51




wsaveblock
------------------------------------------------------------------------------
Function:     	Saves a block to a disk file in raw format.

Declaration:  	int wsaveblock (char *filename, block blockname)

Remarks:      	A file is created which holds the data stored at the pointer
              	given by blockname. This allows your programs to store images
              	that can be loaded at a later time.

Parameters:   	filename  - Full pathname for image to save.

              	blockname - Pointer to image itself.

Return Value: 	0 if successful, 
              	1 if it could not save the file

See Also:     	wfreeblock, wloadblock, wnewblock

Examples:	35

		   WordUp Graphics Toolkit: Library Reference        Page 77

wsavebmp
------------------------------------------------------------------------------
Function:     	Saves a block image to disk in BMP format.

Declaration:  	void wsavebmp (char *fname, block saveptr, color *pal)

Remarks:      	Given a filename and a pointer to a block, this function 
              	saves the image in BMP format (8-bit color). 

Parameters:   	fname   - Full pathname of image to save.

              	saveptr - Pointer to actual image.

              	pal     - Palette to save with image.

Return Value: 	None

See Also:     	wloadbmp

Examples:	35




wsavecel
------------------------------------------------------------------------------
Function:     	Saves a CEL file (AutoDesk Animator format) to disk.

Declaration:  	int wsavecel (char *filename, block saveblock, color *palette)
              
Remarks:      	A file is created which holds the data stored at the pointer
              	given by blockname. This allows your programs to store images
              	that can be loaded at a later time.

Parameters:   	filename  - Full pathname of image to save.

              	saveblock - Pointer to actual image in memory.

              	palette   - Palette to save with image.

Return Value: 	0 if succesful,
              	1 if it could not save the file

See Also:     	wloadcel

Examples:	35

		   WordUp Graphics Toolkit: Library Reference        Page 78

wsavepak
------------------------------------------------------------------------------
Function:     	Saves a block to disk in compressed format.

Declaration:  	int wsavepak (char *filename,block blockname)

Remarks:      	This is similar to wsaveblock except that the image is
              	in a file which is compressed. The compression used
              	is "similar" to PCX format (sometimes better). The more
              	simplistic the image, the smaller the file. The image
              	still requires the same amount of memory when loading it in,
              	but takes up less disk space.

Parameters:   	filename  - Full pathname of image to save.

              	blockname - Pointer to actual image in memory.

Return Value: 	0 if succesful,
              	1 if it could not save the file

See Also:     	wloadblock, wloadpak 

Examples:	35




wsavepalette 
------------------------------------------------------------------------------
Function:     	Save a palette variable's contents to a file.

Declaration:  	void wsavepalette (char *filename, color *palette)

Remarks:      	Creates a 768 byte palette file to disk from a variable
              	specified by palette. This is useful for storing different
              	palettes for games and their various screens.

Parameters:   	filename - Full pathname of palette file to save.

              	palette  - Actual palette to save.

Return Value: 	None

See Also:     	wloadpalette, wsetpalette, wsetrgb

Examples:	35

		   WordUp Graphics Toolkit: Library Reference        Page 79

wsavepcx256
------------------------------------------------------------------------------
Function:     	Saves a block to disk in the PCX compressed format.

Declaration:  	void wsavepcx256 (char *filename, block blockname, color *pal)

Remarks:      	This is similar to wsaveblock except that the image is
              	in a file which is compressed. The compression used
              	is the PCX format. The more simplistic the image, the smaller 
              	the file. The image still requires the same amount of memory 
              	when loading it in, but takes up less disk space.

Parameters:   	filename  - Full pathname of PCX file to save.

              	blockname - Pointer to image in memory.

              	pal       - Palette to save with image.

Return Value: 	None

See Also:     	wloadblock, wloadpak, wloadpcx256 

Examples:	35

		   WordUp Graphics Toolkit: Library Reference        Page 80

wscan_convertpoly
------------------------------------------------------------------------------
Function:     	Scan converts a concave polygon into a rendered polygon
              	buffer.

Declaration:  	void wrenderpoly (tpolypoint *vertexlist, int numvertex, 
                                  wscanpoly *newp)

Remarks:      	Concave polygons allow multiple horizontal line segments on
              	each row of the polygon.   This means you can have any
              	number of vertices in any position and the polygon will
              	still be drawn correctly.  

              	Rendered polygons are only stored in an allocated buffer.
              	They are not drawn until wdraw_scanpoly is called.  The 
              	benefit of storing the polygon in a buffer is you can
              	draw the polygon in a different location on the screen
              	without doing the mathematical calculations again.

              	wscanpoly is a structure to hold the polygon buffer.
              	It is defined as:            

              	typedef struct 
              	   {
              	    char *pointbuffer[200]; 
              	      /* Holds a buffer of x coordinates for each 
              	         row of the polygon. */

              	    unsigned numpoints[200];  
              	      /* Holds the size of the point buffer in bytes. */   
              	   } wscanpoly;

Parameters:   	vertexlist - Array of vertices that define the concave polygon. 

              	numvertex  - Total number of vertices in the array.

              	newp       - Array of vertices defining the rendered polygon.

Return Value: 	None

See Also:     	wdraw_scanpoly, wfree_scanpoly

Examples:	51

		   WordUp Graphics Toolkit: Library Reference        Page 81

wset_capslock
------------------------------------------------------------------------------
Function:     	Sets the state of the capslock key.

Declaration:  	void wset_capslock (int state)

Remarks:      	This routine will set the state of the capslock key and change
              	the keyboard LEDS appropriately.

Parameters:   	state - Indicates on/off status of key.
		     	0=off     1=on

Return Value: 	None

See Also:     	wget_capslock, wset_numlock, wset_scrlock 

Examples:	44




wset_numlock
------------------------------------------------------------------------------
Function:     	Sets the state of the numlock key.

Declaration:  	void wset_numlock (int state)

Remarks:      	This will set the state of the numlock key and change the
              	keyboard LEDS appropriately.

Parameters:   	state - Indicates on/off status of key.
		     	0=off	   1=on

Return Value: 	None

See Also:     	wget_numlock, wset_capslock, wset_scrlock 

Examples:	44

		   WordUp Graphics Toolkit: Library Reference        Page 82

wset_scrlock
------------------------------------------------------------------------------
Function:     	Sets the state of the scrlock key.

Declaration:  	void wset_scrlock (int state)

Remarks:      	This will set the state of the scroll lock key and change the
              	keyboard LEDS appropriately. 

Parameters:   	state - Indicates on/off status of key.
		     	0=off	   1=on

Return Value: 	None

See Also:     	wget_scrlock, wset_capslock, wset_numlock

Examples:	44




wsetcolor 
------------------------------------------------------------------------------
Function:     	Sets the current drawing color.

Declaration:  	void wsetcolor (unsigned char col)

Remarks:      	Col may be in the range 0 to 255. All drawing procedures
              	used after setting this will use the color you choose.

Parameters:   	col - Color index to use for graphics primitives.

Return Value: 	None

See Also:     	wloadpalette, wsavepalette, wsetpalette, wsetrgb

Examples:	1, 2, 4, 5, 6, 8, 9, 10-12, 14-20

		   WordUp Graphics Toolkit: Library Reference        Page 83

wsetcursor
------------------------------------------------------------------------------
Function:     	Sets the shape of the software emulated text cursor.

Declaration:  	void wsetcursor (int y, int y2)

Remarks:      	Y and Y2 coordinates are the coordinates for the upper and
              	lower lines for a cursor 8 pixels wide. The X coordinates are
              	fixed to 8 pixels wide. The cursor is not the hardware text
              	cursor, but rather a software simulation which flashes during
              	text input. A solid box would be (0,7).

Parameters:   	y  - Upper coordinate of cursor.

              	y2 - Lower coordinate of cursor.

See Also:     	wflashcursor, wstring 

Return Value: 	None

Examples:	14




wsetmode
------------------------------------------------------------------------------
Function:     	Sets the video mode.

Declaration:  	void wsetmode (int newmode)

Remarks:      	This is mainly used to restore the video mode.
              	The most common mode to restore is 0x03, which is
              	80x25 Text mode.

Parameters:   	newmode - Video mode to switch into.

Return Value: 	None

See Also:     	vga256, vgadetected, wgetmode

Examples:	1-29, 31-42, 46-49, 51-53

		   WordUp Graphics Toolkit: Library Reference        Page 84

wsetpalette
------------------------------------------------------------------------------
Function:     	Sets a group of colors from a specified palette variable.

Declaration:  	void wsetpalette (unsigned char start, unsigned char finish,
                                  color *palette)

Remarks:      	Colors from start to finish are set using the values stored
              	in the palette variable. The variable type color is
              	specific to WGT and may not be used elsewhere. It is
              	defined as follows:

               	typedef struct {
               	  unsigned char r, g, b;
               	} color;

              	To define a palette, you must make an array of colors like
              	this:

              	color palette[256];

Parameters:   	start   - Start index of palette array to set.

              	finish  - End index of palette array to set.

              	palette - Array of colors to use.

Return Value: 	None

See Also:     	wloadpalette, wreadpalette, wsavepalette, wsetcolor, wsetrgb

Examples:	4-7, 11, 13, 19-25, 27, 31, 32, 35

		   WordUp Graphics Toolkit: Library Reference        Page 85

wsetrgb 
------------------------------------------------------------------------------
Function:     	Sets a color's red, green, and blue values.

Declaration:  	void wsetrgb (unsigned char color, unsigned char red,
                              unsigned char green, unsigned char blue, 
                              color *palette)

Remarks:      	Color can range from 0 to 255.
              	The Red, Green, and Blue values are in the range 0 to 63
              	giving a total of 262144 color combinations possible.
              	(64*64*64)
                        
              	The colors do NOT change until you call the wsetpalette
              	command.  This way you can set a number of colors
              	and change them all simultaneously.

Parameters:   	color   - Index within color array to set.

              	red     - Red level to use (0-63).
              
              	green   - Green level to use (0-63).

              	blue    - Blue level to use (0-63).

              	palette - Array of colors to set.

Return Value: 	None

See Also:     	wloadpalette, wsavepalette, wsetcolor, wsetpalette

Examples:	4-7, 13, 20, 38, 40, 42, 47, 51

		   WordUp Graphics Toolkit: Library Reference        Page 86

wsetscreen 
------------------------------------------------------------------------------
Function:     	Makes all drawing procedures use a different video page.

Declaration:  	void wsetscreen (block screenname)

Remarks:      	Sets the active drawing page to screenname.  All of WGT's
              	graphics routines will write to this page instead of the
              	visual page.  This is used to create pictures in memory to
              	be displayed later using wputblock or wcopyscreen.

              	The screen must be first initialized by using wnewblock
              	with coords 0,0 to 319,199.

              	If screenname is NULL, the active page is set to the visual
              	page. (equivalent to wnormscreen)

Parameters:   	screenname - Pointer to screen which becomes the active screen.

Return Value: 	None

See Also:     	wfreeblock, wnewblock

Examples:	11, 15-20, 22, 23, 25, 33, 42




wskew 
------------------------------------------------------------------------------
Function:     	Skews a block sideways.

Declaration:  	void wskew (int x, int y, block skewblock, int degrees)

Remarks:      	Shows the bitmap skewblock on the current page at (x,y)
              	using a skew value of degrees.  Each row of the bitmap is
              	pushed either left or right of the previous.  If degrees
              	is negative, it will be skewed in the opposite direction.

Parameters:   	x         - Horizontal display coordinate.
              
              	y         - Vertical display coordinate.

              	skewblock - Pointer to image to be displayed.

              	degrees   - Number of degrees to skew image (not rotate).

Return Value: 	None

Examples:	27

		   WordUp Graphics Toolkit: Library Reference        Page 87

wsline
------------------------------------------------------------------------------
Function:     	Stores the points of a line into an array instead of plotting
              	them on the screen.

Declaration:  	wsline (int x1, int y1, int x2, int y2, int *ptarray)

Remarks:      	Simply stores the y coordinate values in the appropriate
              	place in the array for every x coordinate on a line.
              	ptarray is an array of 320 integers.
              	See wwarp for more info.

Parameters:   	x1      - Horizontal coordinate of first endpoint.

              	y1      - Vertical coordinate of first endpoint.

              	x2      - Horizontal coordinate of second endpoint.

              	y2      - Vertical coordinate of second endpoint.

              	ptarray - Buffer used to store points in the line.

Return Value: 	None

See Also:     	wwarp

Examples:	32

		   WordUp Graphics Toolkit: Library Reference        Page 88

wsolidpoly
------------------------------------------------------------------------------
Function:     	Draws a filled convex polygon.

Declaration:  	void wsolidpoly (tpolypoint *vertexlist, int numvertex,
                                 int x, int y, void (*customline)(int x1, int 	
				 x2, int y))

Remarks:      	The wsolidpoly routine draws a filled convex polygon using
              	the current color.  Each vertex is has the offset (x,y) added
              	to it before the polygon is drawn.   vertexlist is an array
              	of vertices, which contains numvertex vertices.
              	customline is the name of the horizontal line routine to
              	call for each line in the polygon.  If NULL is given, it
              	will use whline.  You can create your own line routines
              	to make other unique effects such as fill patterns using
              	the wstyleline command, image copying using memcpy, or
              	shadebob techniques.

              	The tpolypoint structure is defined as:

              	typedef struct
              	 {
              	  int x,y;  /* Coordinate on the screen */
              	  int sx,sy; /* Coordinate on the texture */
              	 } tpolypoint;

              	wsolidpoly does not use the sx,sy variables.  While this is
              	wasteful of memory, it allows you to switch between polygon
              	rendering methods without altering your vertex data variables.

		customline is a function which accepts three parameters.  The 
		first two are the x coordinates of a horizontal line, and the
		third is the y coordinate.  

Parameters:   	vertexlist - Array of vertices defining the polygon.

              	numvertex  - Total number of vertices in the array.

             	x          - Horizontal offset to add to each vertex.

              	y          - Vertical offset to add to each vertex.

              	customline - Address of custom horizontal line routine.

Return Value: 	none

See Also:	whollowpoly

Examples:	42, 51, 54, 55

		   WordUp Graphics Toolkit: Library Reference        Page 89

wstring 
------------------------------------------------------------------------------
Function:     	Reads in a string of text from the keyboard and displays
              	both the text and a simulated cursor on the graphics page.

Declaration:  	void wstring (int x, int y, char *instring, char *legal,
                              int num)
               
Remarks:      	This procedure uses the flashing cursor while you input the
              	string. Any characters you wish to be able to type in must
              	be included in LEGAL.  For example, if you want a yes or
              	no answer only, make LEGAL="YNyn". num is the maximum number
             	of letters in the string. x and y are the coordinates of the
              	initial cursor position.

              	INSTRING must be a pointer to char:
              	    char *filename;
              	Along with legal:
              	    char *legal_chars = " ABCDEFGHIJKLMNOPQRSTUVWXYZ
              	      abcdefghijklmnopqrstuvwxyz1234567890_.";
          
              	Then, you must allocate memory for the string, like this:
              	    filename = (char *) malloc (13);
              	Add 1 to the length for the null terminator.

              	Call the string procedure:
              	    wstring (10, 22, filename, legal_chars, 12);

              	After you're done with the string, free the memory by
              	    free (filenameout);

              	INSERT,DELETE,HOME,END and the arrow keys are functional,
              	and backspace is destructive.

              	If you press insert, the cursor shape changes and toggles
              	between insert and overwrite modes.

Parameters:   	x        - Horizontal coordinate for text input.

              	y        - Vertical coordinate for text input.

              	instring - Character string input buffer.

              	legal    - String of legal input characters.

              	num      - Maximum number of characters to input.

Return Value: 	None

See Also:     	wflashcursor, wgtprintf, wouttextxy

Examples:	14

		   WordUp Graphics Toolkit: Library Reference        Page 90

wstyleline 
------------------------------------------------------------------------------
Function:     	Draws a line from between two points with a line pattern.

Declaration:  	void wstyleline (int x, int y, int x2, int y2,
                                 unsigned int pattern)

Remarks:      	(x1,y1) defines the first endpoint of the line.
              	(x2,y2) defines the second endpoint of the line.
              	pattern is a number between 0 and 65535 which defines the
              	line pattern.  The pattern can be thought of as an array
              	of 16 bits, each telling if a pixel is on (1) or off (0).

              	For example, a dashed line would have half of the pixels
              	turned on, and half of them turned off.  This would
              	be represented as 1111111100000000 in binary.

              	Of course you cannot use binary numbers within your C program,
              	so you must first convert them to hexadecimal.  To convert 
              	this number, split the digits into groups of four.  Below
              	is a table of the binary group on the left, and the 
              	hexadecimal equivalent on the right.

                            0000  0            1000  8
                            0001  1            1001  9
                            0010  2            1010  A
                            0011  3            1011  B
                            0100  4            1100  C
                            0101  5            1101  D
                            0110  6            1110  E
                            0111  7            1111  F

              	Some examples of this conversion are:

              	Binary:      1111 1111 0000 0000
              	Hexadecimal:  F    F    0    0   = 0xFF00

              	Binary:      1000 1000 1001 1001
              	Hexadecimal:  8    8    9    9   = 0x8899

              	This conversion process is also important when creating
              	user defined mouse cursors with the mouseshape routine.

Parameters:   	x       - Horizontal coordinate of first endpoint.

              	y       - Vertical coordinate of first endpoint.

              	x2      - Horizontal coordinate of second endpoint.

              	y2      - Vertical coordinate of second endpoint.

              	pattern - Bitpattern of the line.
              
Return Value: 	None

See Also:     	wfline, wline

Examples:	4

		   WordUp Graphics Toolkit: Library Reference        Page 91

wtextbackground 
------------------------------------------------------------------------------
Function:     	Sets the background text color.

Declaration:  	void wtextbackground (unsigned char col)

Remarks:      	Col is in the range 0 to 255.  The background color behind 
		text may be turned off by calling wtexttransparent.

Parameters:   	col - Color index to use for text background.

Return Value: 	None

See Also:     	wouttextxy, wstring, wtextcolor, wtextcursor, wtextgrid,
		wtexttransparent
              	

Examples:	7, 14, 20, 26




wtextcolor 
------------------------------------------------------------------------------
Function:     	Selects the foreground character color.

Declaration:  	void wtextcolor (unsigned char col)

Remarks:      	Col is in the range 0 to 255.  The foreground color of text 
              	(the actual letters) may be turned off by calling
              	wtexttransparent.

Parameters:   	col - Color index to use for text output.

Return Value: 	None

See Also:     	wouttextxy, wstring, wtextbackground, wtextcursor, wtextgrid, 
		wtexttransparent, 
              	
Examples:	4, 7, 12-15, 20, 24, 26, 35, 41, 43, 48, 49, 51, 53

		   WordUp Graphics Toolkit: Library Reference        Page 92

wtextgrid 
------------------------------------------------------------------------------
Function:     	Switches the text coordinate system from 320*200 to 40*25.

Declaration:  	void wtextgrid (int state)

Remarks:      	Text may be output in regular graphics coordinates (320*200) or
              	a text mode system of 40*25. If STATE is set to 1, all input
              	and output values for WGT text functions are expected to be
              	in the 40*25 range. Characters will be 'snapped' to the grid as
              	if it were a text mode. 0 will use the regular graphics system
              	coordinates.

Parameters:   	state - Indicates text gridlock on/off status.

Return Value: 	None

See Also:     	wouttextxy, wstring

Examples:	7




wtexttransparent 
------------------------------------------------------------------------------
Function:     	Sets text output to supress the display of the foreground or
              	background.

Declaration:  	void wtexttransparent (int mode)

Remarks:      	This will turn off the display of either the foreground or the
              	background, or set it to show both.

              	The values possible are:
              	TEXTFG  (0): Foreground turned on
              	TEXTBG  (1): Background turned on
              	TEXTFGBG(2): Both turned on

Parameters:   	mode - Indicates visibility status of text fore/background.

Return Value: 	None

See Also:   	wtextbackground, wtextcolor

Examples:	7, 12, 13, 14, 20, 26, 48, 49, 51, 53

		   WordUp Graphics Toolkit: Library Reference        Page 93

wtexturedpoly
------------------------------------------------------------------------------
Function:     	Draws a texture mapped convex polygon.

Declaration:  	void wtexturedpoly (tpolypoint *vertexlist, int numvertex,
                                    int x, int y, block tex, int mode)

Remarks:      	The wtexturedpoly routine draws a texture mapped convex polygon
              	using the texture bitmap tex. Each vertex is has the offset
              	(x,y) added to it before the polygon is drawn.   vertexlist is
              	an array of vertices, which contains numvertex vertices.

              	Mode can either be NORMAL (0), or XRAY (1) , which allows for 
		see-through textures. The tpolypoint structure is defined as:

              	typedef struct
              	 {
              	  int x,y;  /* Coordinate on the screen */
              	  int sx,sy; /* Coordinate on the texture */
              	 } tpolypoint;

              	(sx,sy) contains the offset within the texture bitmap
              	of the vertex.  Since a bitmap is rectangular, the resulting
              	polygon should have 4 vertices in order for the texture
             	to be drawn correctly.   Warping of the texture image occurs
              	when one side of the polygon is greatly differing in length
              	of the other.

Parameters:   	vertexlist - Array of vertices which define the polygon.

              	numvertex  - Total number of vertices in array.

              	x          - Horizontal offset added to each vertex.

              	y          - Vertical offset added to each vertex.

              	tex        - Pointer to block used as a texture.

              	mode       - Indicates copy mode (xray or normal).

Return Value: 	None

See Also:     	wgouraudpoly, whollowpoly, wsolidpoly

Examples:	42

		   WordUp Graphics Toolkit: Library Reference        Page 94

wtimer
------------------------------------------------------------------------------
Function:     	Returns the difference between two times in hundredths of 
              	seconds.

Declaration:  	long wtimer (struct time t, struct time t2)

Remarks:      	Use gettime to store the timing variables first, and call this
              	routine to see how long it took to execute a command or 
              	procedure.  For measuring the frame rate of an animation,
              	count the number of times the screen is updated, and store
              	the time it took. To find the number of frames per second, 
              	divide the number of updates by the time.  To find the average 
              	time it took for each frame, perform the reverse.

              	This routine can be used to control the timing of animation
              	on different computer systems.  Fast computers will need to 
              	be slowed down to stay at the prefered speed.

              	/* Beginning of procedure */
              	gettime (&time1)
              	...
              	/* End of procedure */
              	gettime (&time2)
              	while (wtimer (time1,time2) < 5)
              	   gettime (&time2);

              	This will make the animation run at 20 frames per second
              	(100 microseconds / 5).  If the computer is not fast enough
              	to get 20 fps, it will run as fast as possible.

Parameters:   	t  - Start time.

              	t2 - End time.

Return Value: 	Hundredths of seconds between the two times.

Examples:	46

		   WordUp Graphics Toolkit: Library Reference        Page 95

wvertres
------------------------------------------------------------------------------
Function:     	Draws a previously stored image on the screen to fit within a
              	given boundary but only stretches it vertically.

Declaration:  	void wvertres (int x1, int y1, int y2, block blockname)

Remarks:      	This is an extremely fast shrink/expand routine for blocks.
              	It is similar to wresize but doesn't change the width of
              	the block. Use this at all times if you are only
              	resizing the height, since it is much faster.

Parameters:   	x1        - Horizontal coordinate of image.

              	y1        - Upper Y coordinate of image.

              	y2        - Lower Y coordinate of image.

              	blockname - Pointer to image which will be resized.

Return Value: 	None

See Also:     	wresize

Examples:	21

		   WordUp Graphics Toolkit: Library Reference        Page 96

wwarp
------------------------------------------------------------------------------
Function:     	Displays a block on the screen, using different heights
		for each column displayed.

Declaration:  	void wwarp (int x1, int x2, int *top, int *bot, 
			    block blockname)

Remarks:      	Instead of drawing the block straight across in a
              	rectangular manner, this function resizes the block
              	vertically for every column displayed. You can have
              	each column stretched by different amounts allowing
              	for some very interesting effects.
              	X1 and X2 are the two x coordinates the block
              	will be resized between. Top and bot are 320 integer
              	arrays which hold the y values for every x coordinate.
              	Blockname is the block to warp.

              	Use wsline to set up the top and bot arrays if you
              	are using straight lines.

              	Example: 
              	  wsline (0, 199, 319, 0, &top);   // sets up line for top
              	  wsline (0, 199, 319, 199, &bot); // sets up bottom line
              	  // Imagine drawing these two lines on the screen...

             	  wwarp (0, 319, &top, &bot, warp_block);

              	Top should have all points above the corresponding point in 
              	bot.  The block is resized between these points on the screen. 
              
              	You do not need to use wsline to make straight lines for
              	warping.  Other possibilities include zig-zags, sine waves,
              	etc.

Parameters:   	x1        - Horizontal coordinate of left edge.

              	x2        - Horizontal coordinate of right edge.

              	top       - Array of y coordinates for upper edge.

              	bot       - Array of y coordinates for lower edge.

              	blockname - Pointer to image which will be resized.

Return Value: 	None

See Also:     	wsline

Examples:	32

		   WordUp Graphics Toolkit: Library Reference        Page 97

wwipe
------------------------------------------------------------------------------
Function:     	Draws a line but uses colors from another virtual screen.

Declaration:  	void wwipe (int x1, int y1, int x2, int y2, block screen)

Remarks:      	This special effect allows you to draw a line on the screen,
              	but instead of using one color, each pixel drawn is the
              	color of the pixel at the same location on the block
              	screen. You can created impressive wipes and make your
              	programs look very professional.  You will want to make
              	one or more 'for' statements that copy the whole screen over
              	since this only does it one line at a time.  The lines don't 
		have to be horizontal or vertical, so you can create complex
		patterns with the lines.

Parameters:   	x1     - Horizontal coordinate of first endpoint.

              	y1     - Vertical coordinate of first endpoint.

              	x2     - Horizontal coordinate of second endpoint.

              	y2     - Vertical coordinate of second endpoint.

              	screen - Screen to use as the wipe source.

Return Value: 	None

Examples:	24

		   WordUp Graphics Toolkit: Library Reference        Page 98

wxorbox 
------------------------------------------------------------------------------
Function:     	Draws a filled rectangle using exclusive-or mode.

Declaration:  	void wxorbox (int x, int y, int x2, int y2, 
                              unsigned char col)

Remarks:      	This routine performs an XOR on the pixels within the box
              	and the with color given.  It is useful for drawing outlines 
              	or showing button presses. If you draw a box on the same
              	place twice in a row using the same color, the box will
              	erase itself due to the results of the XOR mode.         

Parameters:   	x      - Horizontal coordinate of first endpoint.

              	y      - Vertical coordinate of first endpoint.

              	x2     - Horizontal coordinate of second endpoint.

              	y2     - Vertical coordinate of second endpoint.

              	col    - Color index used to draw the xor box.

Return Value: 	None

Examples:	36

		   WordUp Graphics Toolkit: Library Reference        Page 99


WGTJOY.LIB

Most games will need some method of detecting and reading from the joystick 
port(s) of the computer. These routines provide full access to 1 or 2 joysticks
which are connected to the system. Routines for detection, calibration, and 
reading the button and positional values are all found in this library.



		   WordUp Graphics Toolkit: Library Reference        Page 100

wcalibratejoystick
------------------------------------------------------------------------------
Function:     	Finds out the coordinate range of the joystick.

Declaration:  	int wcalibratejoystick (joystick *joy)

Remarks:      	Before using the joystick, it is best to calibrate it. 
              	Calibration simply finds out the range of values the joystick
              	can return, and this is done by moving the stick to the
              	extreme direction in each axis.

              	This routine can be used in two ways:
              	1. Tell the user to move the joystick to the upper left and
              	   press a fire button. Call wcalibratejoystick. 
              	   Tell the user to move the joystick to the lower right and
              	   press a fire button. Call wcalibratejoystick again. 

              	2. Tell the user to swirl the joystick a few times.  This
              	   method only requires one wcalibratejoystick call.

              	If you want to calibrate the joystick in a setup program, 
              	you can save all the calibrated values in a configuration
              	file, and load them back in for your main program. This way
              	the user only has to calibrate the joystick once.

              	Here is the data structure you must save:
              	typedef struct {
              	    int x, y;
              	    int cenx, ceny;
              	    int xrange, yrange;
              	    int port, buttons;
              	    int scale;
              	    } joystick;

		Once the range of the joystick has been determined, you have
		to use it in your program to control the sensitivity of the
		joystick.  xrange and yrange are positive numbers that tell
		the absolute distance the joystick will return.  For example,
		if xrange was 50, the joystick would return a value from -50
		to 50.  You will want to acknowledge the joystick movement
		when the value is greater than a certain percentage of the
		range.  Eg. If the value is greater than 2/3 the xrange,
		the user is pushing right.  If the value is less than 2/3 the
		negative xrange, the user is pushing left.

Parameters:   	joy - Pointer to the joystick information data structure.

Return Value:	1 if the joystick was calibrated
		0 if the joystick was not calibrated

See Also:     	wcheckjoystick, winitjoystick, wreadjoystick

Examples:	50

		   WordUp Graphics Toolkit: Library Reference        Page 101

wcheckjoystick
------------------------------------------------------------------------------
Function:     	Determines which joysticks are connected.

Declaration:  	int wcheckjoystick (void)

Remarks:      	This routine checks for the presence of each joystick. 
              	It returns an integer with 2 bits set. If bit 1 is set,
              	joystick 1 has been found. If bit 2 is set, joystick
              	2 has been found.

Parameters:   	None

Return Value: 	0 = no joysticks found
              	1 = joystick 1 found
              	2 = joystick 2 found
              	3 = both joysticks found

See Also:     	wcalibratejoystick, winitjoystick, wreadjoystick

Examples:	50




winitjoystick
------------------------------------------------------------------------------
Function:     	Initializes a joystick.

Declaration:  	void winitjoystick (joystick *joy, int joynum)

Remarks:      	Initializes joystick number joynum using the joystick structure
              	joy.  This assumes the joystick is centered when you call the
              	routine.  joynum can be either 0 (for joystick 1)
		or 1 (for joystick 2).

              	You should calibrate the joystick after this routine.

Parameters:   	joy    - Pointer to the joystick information structure.

              	joynum - Indicates joystick number to initialize.

Return Value:	None

See Also:     	wcalibratejoystick, wcheckjoystick, wreadjoystick

Examples:	50

		   WordUp Graphics Toolkit: Library Reference        Page 102

wreadjoystick
------------------------------------------------------------------------------
Function:     	Reads the information from a joystick.

Declaration:  	int wreadjoystick (joystick *joy)

Remarks:      	This routine reads the coordinates of the stick and button
              	state and stores them in the joystick structure.

              	joy.x is the x coordinate
              	joy.y is the y coordinate
              	joy.buttons is the button status.

		The buttons flag uses bits to determine which buttons are
		pressed, similar to the mouse button routines.

Parameters:   	joy - Pointer to the joystick information structure.

Return Value:	1 if successful
		0 if not successful

See Also:     	wcalibratejoystick, wcheckjoystick, winitjoystick

Examples:	50

		   WordUp Graphics Toolkit: Library Reference        Page 103


WGT3D.LIB

Lacking in the previous releases of WGT was a 3D interface. WGT 4.0 features a 
simple, but effective library of routines for rotating a set of points in all 
3 dimensions. When used in combination with the polygon routines in the main 
library, this system can produce excellent wireframe and solid polygon-based
animations.

Routines in this library were written in assembly language to optimize speed.


		   WordUp Graphics Toolkit: Library Reference        Page 104

winit3d
------------------------------------------------------------------------------
Function:     	Initializes the WGT 3D system.

Declaration:  	void winit3d (void)

Remarks:      	This command must be called in your program once, before the
              	wrotatepoints command is used.  It creates a sine and cosine 
              	lookup table that is used for 3D rotations.
              	WGT's 3D rotation library is meant for simple applications
              	only.  The main limitation is that you cannot change the
              	camera's location within the 3D coordinate system. You can
              	move 3D objects around by changing their center point however.

Parameters:   	None

Return Value: 	None

See Also:     	wrotatepoints, wsetrotation

Examples:	48, 54, 55

		   WordUp Graphics Toolkit: Library Reference        Page 105

wrotatepoints
------------------------------------------------------------------------------
Function:     	Rotates a set of three dimensional points.

Declaration:  	void wrotatepoints (point3d *pt, point3d *finp, int maxpt)

Remarks:      	The wrotatepoints command will take the array of 3D points
              	called pt, with maxpt points, and rotate them around their
              	axis.  It stores the rotated points in the finp point array.
              	The rotation amounts are set with the command wsetrotation.

              	The point3d structure is defined as:

              	typedef struct
              	    {
              	     int x, y, z;
              	     int sx, sy;
              	    } point3d;

              	sx, and sy are used for storing colors and texture bitmap
              	offsets when using wtexturedpoly and wgouraudpoly.  

              	In addition, the following variables are used in WGT's 3D
              	system:

              	long sx, sy, sz; /* Scale Factors */
              	int move_x, move_y, move_z;
              	   /* Translational Offsets - Added to each point after 
              	      rotation */
              	int origin_x, origin_y, origin_z; 
              	   /* Point of origin.  All points will be rotated around this
              	      point */

Parameters:   	pt    - Pointer to array of original point3d structure.

              	finp  - Pointer to array of rotated points.

              	maxpt - Number of points in the original buffer.

Return Value: 	None

See Also:     	winit3d, wsetrotation

Examples:	48, 54, 55

		   WordUp Graphics Toolkit: Library Reference        Page 106

wsetrotation
------------------------------------------------------------------------------
Function:     	Sets the rotational amount in each axis that all points
              	will be rotated by.

Declaration:  	void wsetrotation (int rx, int ry, int rz)

Remarks:      	The wrotatepoints routine rotates all the points given to it
              	by the amount set with this command.  rx, ry and rz can range
              	between 0 and 360.  

              	For example, to rotate the points by 30 degrees in the x axis:
              	wsetrotation (30,0,0);
              	wrotatepoints (&stpoint, &finpoint, 4);

Parameters:   	rx - Degrees to rotate in the x-axis.

              	ry - Degrees to rotate in the y-axis.

              	rz - Degrees to rotate in the z-axis.

Return Value: 	None

See Also:     	winit3d, wrotatepoints

Examples:	48, 54, 55

		   WordUp Graphics Toolkit: Library Reference        Page 107


WFILE.LIB

A graphical file selector is the easiest way to select files from large 
directory lists. This library contains a single routine which creates this 
selector. The file selector is capable of being moved to a different position 
on the screen by the user, and it provides full access to all available floppy 
disks and hard drives on the system. File listings are sorted alphabetically, 
with the drives and subdirectories at the top of each list.

Programs are required to load the font file "LITTLE.WFN" in order to properly 
display this selector. Larger fonts will not work properly with the display. 
Refer to the example programs to see how this works.


		   WordUp Graphics Toolkit: Library Reference        Page 108

wfilesel
------------------------------------------------------------------------------
Function:     	Activates the WGT file selector routine.

Declaration:  	char *wfilesel (char *mask, char *title, int x, int y, 
                                block background)

Remarks:      	This routine displays a graphical file selector, and allows
              	the user to scroll up and down through the file listing, 
		change drives and directories, and pick a file, by using
		the mouse.  This is the same file selector used in the 
		Sprite Editor and Map Maker.

              	mask contains a file extension mask, such as "*" or
              	"spr".  It will automatically add a "*." to the file mask.
              	It controls what kind of files will be listed in 
              	the file selector when first activated.  The user can change
              	this from within the selector if needed.

              	title contains the text which is displayed at the top of the
              	selector.  This is used to inform what file operation will
              	be performed on the chosen file.
              
              	(x,y) is the coordinate where the selector will be drawn.
              	It must fit completely on the screen.  The user can move the
              	file selector around, if you give a background screen, by
              	clicking and holding on the title bar of the selector.

              	background is a 320x200 full screen block which will be used
              	to restore the background when moving the file selector.
              	If background is NULL, the selector will be fixed at the
              	(x,y) coordinates you pass, and it will not erase itself.

              	The file selector returns a pointer to a string containing
              	the name of the file selected.  If no file was chosen,
              	it returns NULL.
                            
              	Example usage:

              	char *filename;
              	...
              	filename = wfilesel("spr", "Load a sprite file", 10, 10, 
              	                     back);
              	printf ("filename was: %s", filename);
              	free (filename);  /* Free the filename once we're finished 
                                     with it */

		   WordUp Graphics Toolkit: Library Reference        Page 109



Parameters:   	mask       - File extension to list as default.
              
              	title      - Title for file selector.

              	x          - Horizontal coordinate of selector on screen.

              	y          - Vertical coordinate of selector on screen.

              	background - Pointer to buffer for background preservation.
              
Return Value: 	Pointer to the string which contains the filename.

Examples:	47

		   WordUp Graphics Toolkit: Library Reference        Page 110


WGTSB.LIB

One of the most popular soundcards around, the SoundBlaster (by Creative Labs) 
has prompted a large number of game manufacturers to create support for this 
product. WGT contains a library of routines to play both FM and digital sounds
on this brand of cards (and compatibles).

The formats used by this card are CMF for the FM music and VOC for the digital 
sound files. Routines for loading and playing these files are provided within
this library. There are a number of different possible configurations for the 
card itself, so routines are also provided to switch the base port address and 
irq values. Routines are not guaranteed to work on any settings other than 
the default port 220h and IRQ 7.


		   WordUp Graphics Toolkit: Library Reference        Page 111

waddr
------------------------------------------------------------------------------
Function:     	Changes the I/O address used by the SoundBlaster routines.

Declaration:  	void waddr (int base)

Remarks:      	The port address of the SoundBlaster card is usually
              	0x220, but it can be changed by moving a jumper on the
              	card.
              
Parameters:   	base - Address of port which SoundBlaster is installed at.

Return Value: 	None

Examples:	None




wdeinitsb
------------------------------------------------------------------------------
Function:     	Deinitializes the SoundBlaster driver.

Declaration:  	void wdeinitsb (void)

Remarks:      	This routine will turn off the SoundBlaster driver properly.
              	You must call this before your program exits.  

Parameters:   	None

Return Value: 	None

See Also:     	winitsb

Examples:	34

		   WordUp Graphics Toolkit: Library Reference        Page 112

wfindfm
------------------------------------------------------------------------------
Function:     	Sees if the SoundBlaster CMF driver has been 
              	loaded (SBFMDRV.COM).

Declaration:  	int wfindfm (void)

Remarks:      	This command will searches the interrupts to find out if
              	SBFMDRV.COM has been loaded, and initializes the status 
              	variable fmstat to reflect the current CMF playing status.
              	wfindfm returns -1 if the driver was not found, or 0
              	if it was found.

              	If the driver was found, a variable called fmint contains
              	the interrupt number the SoundBlaster FM driver is using.

Parameters:   	None

Return Value: 	0  = driver is installed
              	-1 = driver is not installed

See Also:     	wfindfm

Examples:	34


wfmreset
------------------------------------------------------------------------------
Function:     	Resets the SoundBlaster FM driver.

Declaration:  	void wfmreset (void)

Remarks:      	This command must be called before any FM output is
              	initiated by the program.

Parameters:   	None

Return Value: 	None

See Also:     	wfindfm

Examples:	34

		   WordUp Graphics Toolkit: Library Reference        Page 113

wfmsetstatus
------------------------------------------------------------------------------
Function:     	Assigns the status variable of FM routines.

Declaration:  	void wfmsetstatus (unsigned ofs, unsigned seg)

Remarks:      	A variable called fmstat is automatically set by wfindfm,
              	but you may want to change it to your own variable.

              	fmstat can be one of the following values:

		0     - not playing (Your song has finished)
		255   - Song is playing
		1-254 - Song marker found

              	eg:
              	  unsigned char mystat;
              	fmsetstatus (FP_OFF (&mystat), FP_SEG (&mystat));

Parameters:   	ofs - Offset value of pointer to status variable.

              	seg - Segment value of pointer to status variable.

Return Value: 	None

See Also:     	wfindfm

Examples:	None


wfmsongspeed
------------------------------------------------------------------------------
Function:     	Changes the tempo of the current CMF file playing.

Declaration:  	void wfmsongspeed (unsigned songspeed)

Remarks:      	The average value of the tempo is around 20000 for most
              	songs.  The smaller the tempo, the faster the song is
              	played.   Do NOT play songs too quickly or the driver
              	may malfunction.  This may also cause VOC's to freeze,
              	or disable them entirely.  Keep the tempo above 2000
              	to ensure your program's stability.

Parameters:   	songspeed - Tempo used to play FM song.

See Also:     	wplaycmf, wfmstopmusic

Examples:	34

		   WordUp Graphics Toolkit: Library Reference        Page 114

wfmstopmusic
------------------------------------------------------------------------------
Function:     	Stops the song which is currently playing.

Declaration:  	void wfmstopmusic (void)

Remarks:      	This command will stop the current CMF song that was started
              	using the wplaycmf command.  Once the song is stopped, it
              	can only be restarted from the beginning.

Parameters:   	None

Return Value: 	None

See Also:     	wplaycmf

Examples:	34




wfmversion
------------------------------------------------------------------------------
Function:     	Returns the FM driver version number.

Declaration:  	unsigned wfmversion (void)

Remarks:      	None

Parameters:   	None

Return Value: 	Version number of the SoundBlaster FM driver.

See Also:     	wfindfm

Examples:	34

		   WordUp Graphics Toolkit: Library Reference        Page 115

wfreecmf
------------------------------------------------------------------------------
Function:     	Frees memory allocated by a CMF file.

Declaration:  	void wfreecmf (wgtsong cmfname)

Remarks:      	Each CMF file you load is stored in conventional memory  
              	and must be deallocated before your program ends.  This will 
              	release the memory used by the CMF file.

Parameters:   	cmfname - Pointer to song data in memory which will be
                         deallocated.

Return Value: 	None

See Also:     	wfindfm, wfmreset, wfmsetstatus, wfmsongspeed, wfmstopmusic, 
		wfmversion, wloadcmf, wplaycmf

Examples:	34


wfreevoc
------------------------------------------------------------------------------
Function:     	Frees memory allocated by a VOC file.

Declaration:  	void wfreevoc (wgtvoice vocname)

Remarks:      	Each VOC file you load is stored in the conventional memory  
              	and must be deallocated before your program ends.  This will 
              	release the memory used by the VOC file.

Parameters:   	vocname - Pointer to voice data in memory which will be
                          deallocated.

Return Value: 	None

See Also:     	wloadvoc, wpausevoc, wplayvoc, wresumevoc, wstopvoc

Examples:	34

		   WordUp Graphics Toolkit: Library Reference        Page 116

winitsb
------------------------------------------------------------------------------
Function:     	Attempts to initialize the SoundBlaster for digitized sound
              	playback.

Declaration:  	int winitsb (int irq)

Remarks:      	Before the Soundblaster can be initialized, you must first
              	know which IRQ and address the card is using.  

              	The ct-voice.drv file must be in the current directory, or
              	within the current WGT Data Library file.

              	A variable called sbstat will tell the state of digital
              	playback after the soundcard has been initialized successfully.

Parameters:   	irq - IRQ the SoundBlaster is installed at.

Return Value: 	-1 if CT-VOICE could not be loaded from the current directory
	    	-2 if SB could not reset correctly
             	 0 if successful

See Also:     	wfmreset

Examples:	34

		   WordUp Graphics Toolkit: Library Reference        Page 117

wloadcmf
------------------------------------------------------------------------------
Function:     	Allocates memory and loads a CMF file.

Declaration:  	wgtsong wloadcmf (char *loadfile)

Remarks:      	You can load multiple CMF files similar to the method of
              	loading multiple VOC files. Memory is automatically allocated 
              	for you.  To free the memory used by a CMF file, use farfree.

              	eg:
              	  wgtsong mysong;
              	  ...
              	  mysong = wloadcmf ("intro.cmf");
              	  ...
              	  farfree (mysong);

Parameters:   	loadfile - Full pathname of CMF file to load.

Return Value: 	A pointer to the CMF file loaded.

See Also:     	wfmstopmusic, wplaycmf

Examples:	34



wloadvoc
------------------------------------------------------------------------------
Function:     	Loads VOC file into conventional memory.

Declaration:  	wgtvoice wloadvoc (char *name)

Remarks:      	You can store multiple VOC files in memory at once, by making
              	different wgtvoice variables, and loading different VOC files
              	into them.  This command will load in a VOC file and return  
              	a pointer to the file in memory.  

                eg:
		wgtvoice hello, world;          /* Declare pointers */
		hello = wloadvoc ("hello.voc"); /* Load first VOC   */
		world = wloadvoc ("world.voc"); /* Load another VOC */

Parameters:   	name - Full pathname of voice file to load.

Return Value: 	None

See Also:     	wfreevoc, wpausevoc, wplayvoc, wresumevoc, wstopvoc

Examples:	34

		   WordUp Graphics Toolkit: Library Reference        Page 118

wpausevoc
------------------------------------------------------------------------------
Function:     	Pauses playback of a VOC file.

Declaration:  	void wpausevoc (void)

Remarks:      	If you want to include a pause key in your program, you can 
              	temporarily pause the digital playback with this command.
              	The sound is still considered to be playing and you must 
              	use either wresumevoc or wstopvoc after this command.

Parameters:   	None

Return Value: 	None

See Also:     	wfreevoc, wloadvoc, wplayvoc, wresumevoc, wstopvoc

Examples:	34


wplaycmf
------------------------------------------------------------------------------
Function:     	Plays a previously loaded CMF file.  

Declaration:  	void wplaycmf (wgtsong song)

Remarks:      	This command is used to play background music.  VOC files may
              	be played simultaneously with CMF songs, so you may have FM
              	and digital sound.

              	While a song is playing, fmstat or the status variable set
              	with wfmsetstatus is 255.

Parameters:   	song - Pointer to CMF song in memory.

Return Value: 	None

See Also:     	wfmstopmusic, wloadcmf

Examples:	34

		   WordUp Graphics Toolkit: Library Reference        Page 119

wplayvoc
------------------------------------------------------------------------------
Function:     	Plays a previously loaded VOC file.

Declaration:  	void wplayvoc (wgtvoice buffer)

Remarks:      	You can store multiple VOC files in memory at once, by making
              	different wgtvoice variables, and loading different VOC files
              	into them.  Sbstat is set to 255 while playing, and resets to
              	0 when the VOC is finished.

	 	If a VOC is already playing, nothing will happen when you
              	call this routine.  Use wstopvoc to stop current sounds, and
              	then wplayvoc to start a new one.

Parameters:   	buffer - Pointer to voice data in memory.

Return Value: 	None

See Also: 	wfreevoc, wloadvoc, wpausevoc, wresumevoc, wstopvoc

Examples:	34


wresumevoc
------------------------------------------------------------------------------
Function:     	Resumes playback of a paused VOC file.

Declaration:  	void wresumevoc (void)

Remarks:      	If the VOC playback was previously paused with the
              	wpausevoc command, you can use this one to resume playing the
              	sound.  The sound will continue from the last point played.

Parameters:   	None

Return Value: 	None

See Also:     	wfreevoc, wloadvoc, wpausevoc, wplayvoc, wstopvoc

Examples:	34

		   WordUp Graphics Toolkit: Library Reference        Page 120

wsbversion
------------------------------------------------------------------------------
Function:     	Returns the version number of the SoundBlaster driver.

Declaration:  	int wsbversion (void)

Remarks:      	None

Parameters:   	None

Return Value: 	Version number of your SoundBlaster digitized voice driver.

See Also:     	winitsb

Examples:	34




wsetspeaker
------------------------------------------------------------------------------
Function:     	Turns the SoundBlaster speaker on or off.

Declaration:  	void wsetspeaker (int onoff)

Remarks:      	This routine will turn on or off the SoundBlaster speaker. 
              	0 is off, and 1 is on.

Parameters:   	onoff - Indicates if speaker is to be turned on or off.

Return Value: 	None

See Also:     	winitsb

Examples:	34

		   WordUp Graphics Toolkit: Library Reference        Page 121

wstopvoc
------------------------------------------------------------------------------
Function:     	Stops playback of a VOC file if one is currently playing. 

Declaration:  	void wstopvoc(void)

Remarks:      	Before you can play another VOC, you must first stop the one
              	that is currently playing (if there is one).  This command
              	will stop the voice that is currently playing and allow you
              	to assign a new VOC file to play.

Parameters:   	None

Return Value: 	None

See Also:     	wfreevoc, wloadvoc, wpausevoc, wplayvoc, wresumevoc

Examples:	34

		   WordUp Graphics Toolkit: Library Reference        Page 122



WGTSCROL.LIB

The most popular games in the past few years have all followed the same trend. 
Graphics are created using a set of repeated "tiles" to simulate a background. 
The tiles are placed on a map which is larger than the visual screen and this 
map is scrolled to show the various regions requested. 

In the WGT system, the background tiles are created with the WGT Sprite Editor 
and may be any size up to 64*64 pixels. The tiles do not need to be square, 
although map design is simpler with square tiles. The WGT Map Maker is then 
used to create the map itself. On each map, up to 2000 sprites ("objects") may 
be placed in their starting positions. Each tile may be assigned a number 
indicating some property or value that the program may interpret. Maps may be 
up to 320*200 tiles in size. This results in a maximum pixel resolution of 
20480*12800; a size much larger than any available video mode supports at the 
current time (thus the scrolling).

Maps may be superimposed on each other to produce an effect known as 
"parallax". Each map may be scrolled independently of the other maps which are
loaded. Up to 4 maps may be loaded into memory at any given time.

Routines contained in this library require a 386 or better processor. Systems
which do not meet this specification should not attempt to execute the code 
contained here.


		   WordUp Graphics Toolkit: Library Reference        Page 123

is_in_window
------------------------------------------------------------------------------
Function:     	Determines if the coordinate given is inside the scrolling
              	window.

Declaration:  	int is_in_window (int currentwindow, int x, int y, int range)

Remarks:      	This command will see if the coordinate (x,y) is within the
              	scrolling window currentwindow.  It is commonly used for   
              	playing sound effects triggered by a certain action.  Since
              	it would be annoying for sound to play because of an action
              	happening somewhere else on the map, is_in_window comes in
              	handy for this.  range is a distance (in pixels, always >0)
              	to extend the window's dimensions.  A range of 0 would return 
              	1 if the coordinate was exactly within the window.  A value
              	of 50 would increase the area to check by 50 pixels on each
              	side.  This is used in case the point is close to the window
              	and the window may scroll over it in the next few frames.

Parameters:   	currentwindow - Scrolling window containing the map.

              	x             - World X coordinate to check.

              	y             - World Y coordinate to check.

              	range         - Number of pixels of to expand the test window 
                               by.

Return Value: 	0 if the coordinate is outside the window (plus the range)
                1 if the coordinate is inside the window (plus the range)

Examples:	None

		   WordUp Graphics Toolkit: Library Reference        Page 124

soverlap
------------------------------------------------------------------------------
Function:     	Detects collisions between two scrollsprites.

Declaration:  	int soverlap (int s1, scrollsprite *wobjects1, block *sprites1,
                              int s2, scrollsprite *wobjects2, block *sprites2)

Remarks:      	This command checks for collisions between two scrollsprites.
              	It uses a quick rectangular region check which sees if the
              	bounding rectangles of the sprites overlap.  This means the
              	collision is not pixel accurate, but in most computer games,
              	exact collisions are not required.  If a collision is found,
              	it will return 1, otherwise it returns 0.

              	If one of the scrollsprites is turned off 
              	(ie. scrollsprite[i].on == 0) then no collision is found.

              	soverlap is usually used in a loop where ranges of sprites are
              	checked for collisions between each other.

              	If your sprite images are stored in EMS, soverlap will attempt
              	to retrieve them from EMS memory as long as the wemsobjects
              	flag is set to 1.

Parameters:   	s1        - Scrollsprite number of sprite 1

              	wobjects1 - Pointer to the array of scrollsprites for sprite 1

              	sprites1  - Pointer to the images used for sprite 1

              	s2        - Scrollsprite number of sprite 2

              	wobjects2 - Pointer to the array of scrollsprites for sprite 2

              	sprites2  - Pointer to the images used for sprite 2

Return Value: 	0 if the sprites are not overlapping
              	1 if the sprite are overlapping

See Also:     	wshowobjects

Examples:	58

		   WordUp Graphics Toolkit: Library Reference        Page 125

wcopyscroll
------------------------------------------------------------------------------
Function:     	Copies the scrolling window onto the visual graphics page.

Declaration:  	void wcopyscroll (int currentwindow, int x1, int y1)

Remarks:      	wcopyscroll will display the scrolling window onto the visual
              	screen.  The top left corner of the window will be placed
              	at (x1,y1).  The scrolling window image must have been 
              	constructed by calling wscrollwindow and wshowobjects if 
              	needed.  

Parameters:   	currentwindow - Scrolling window to copy to the visual screen.
                                (Must be a NORMAL window)

              	x1            - Left X coordinate of window on visual screen.

              	y1            - Top Y coordinate of window on visual screen.

See Also:     	wloadmap

Examples:	56, 57, 58




wendscroll
------------------------------------------------------------------------------
Function:     	Releases memory used for a scrolling window.

Declaration:  	void wendscroll (int currentwindow)

Remarks:      	wendscroll deallocates the memory used to store a scrolling
              	window's buffers.  It must be called to shut down the scrolling
              	system.   

Parameters:   	currentwindow - Scrolling window to close.

See Also:     	wresetmap

Examples:	56, 57, 58

		   WordUp Graphics Toolkit: Library Reference        Page 126

wfreemap
------------------------------------------------------------------------------
Function:     	Releases memory used to store a map file.

Declaration:  	void wfreemap (wgtmap mymap)

Remarks:      	When loading a new map file, you must first free the memory
              	used by the previous map before you use the same pointer.  

Parameters:   	mymap - Pointer to the map in memory.

Return Value: 	None

See Also:     	wloadmap

Examples:	56, 57, 58




wgetworldblock
------------------------------------------------------------------------------
Function:     	Returns the tile number at the given location in a map.

Declaration:  	int wgetworldblock (int currentwindow, int posx, int posy)

Remarks:      	wgetworldblock is used for detecting collisions between sprites
              	and different parts of the map.  posy and posy are world   
              	coordinates, so you may pass it the coordinates of a 
              	scrollsprite and add a pixel offset if needed.

              	It is essential for determining when the scrollsprites should
              	react with their surrounding map.

Parameters:   	currentwindow - Scrolling window of containing the map.

              	posx          - X coordinate of tile. (in world coordinates)

              	posy          - Y coordinate of tile. (in world coordinates)

Return Value:	Tile number at the location given.

See Also:     	wgetworldpixel, wputworldblock

Examples:	58

		   WordUp Graphics Toolkit: Library Reference        Page 127

wgetworldpixel
------------------------------------------------------------------------------
Function:     	Returns the color of a pixel within a map.

Declaration:  	unsigned char wgetworldpixel (int currentwindow, int x, int y)

Remarks:      	wgetworldpixel will return the color of the pixel at (x,y)
              	within the map.  x and y are world coordinates.  This command
              	can be used for pixel-precise collision detection if you
              	"color code" your tiles.

Parameters:   	currentwindow - Scrolling window containing the map.

              	x             - World X coordinate of pixel.

              	y             - World Y coordinate of pixel.

Return Value:	Color of the pixel at the location given.

See Also:     	wgetworldblock

Examples:	None

		   WordUp Graphics Toolkit: Library Reference        Page 128

winitscroll
-----------------------------------------------------------------------------
Function:     	Initializes one of the four scrolling windows.

Declaration:  	void winitscroll (int currentwindow, int mode, int link, 
                                  int wwidth, int wheight, block *tileref)

Remarks:      	The WGT scrolling library has the ability to control four
              	scrolling windows at a time.  This command will initialize
              	one of these windows.

              	currentwindow is the window to initialize from 0 to 3.

              	mode is either NORMAL (0) or PARALLAX (1).  NORMAL windows are 
              	used as a base window meaning other PARALLAX windows may be
              	shown overtop it.  PARALLAX windows are like the xray mode in
              	wputblock where color 0 is considered to be see-through.  

              	link is used for PARALLAX windows only.  To use a PARALLAX 
              	window, you must also have a NORMAL window which is shown 
              	underneath.  link is the scrolling window number of this 
              	NORMAL window.  Also note that you may have more than one 
              	NORMAL scrolling window.
              
              	wwidth is the width (in tiles) of the scrolling window. 
              	wheight is the height (in tiles) of the scrolling window.
              	Both of these variables must be at least 2.  The maximum
              	value for these variables depends on the size of the tiles
              	being used.  In general, the window size in pixels must be
              	less than or equal to 320x200.
              
              	When using a PARALLAX window, you must make sure the NORMAL
              	window and the PARALLAX window have the same window dimensions
              	in pixels.  If you are using different sizes of tiles for
              	each window, it may be impossible to achieve this.   To
              	calculate the window dimensions in pixel, multiply the
              	size of the tiles by the size of the window.

              	Example of a correct scrolling window setup:
              	 NORMAL window: tile size is 16x16,  window size is 20x12 tiles
              	  window width in pixels = 320  
              	  window height in pixels = 192  
              	 PARALLAX window: tile size is 40x32, window size is 8x6 tiles
              	  window width in pixels = 320  
              	  window height in pixels = 192  

		Furthermore, the resulting window width must be a multiple
		of 4, due to the 386 optimized assembly routines used.

              	tileref is a pointer to the block array containing the tiles.
              	winitscroll looks at the first tile in this array which isn't
		NULL to obtain the dimensions of the tiles.

		   WordUp Graphics Toolkit: Library Reference        Page 129

Parameters:   	currentwindow - Scrolling window to initialize (0-3).

              	mode          - Window mode : NORMAL or PARALLAX.

              	link          - Number of related NORMAL window, only used if
                                the mode is PARALLAX.

              	wwidth        - Width of window (in tiles).

              	wheight       - Height of window (in tiles).

              	tileref       - Pointer to the array of tile images.

Return Value: 	None

See Also:     	wloadmap, wscrollwindow, wshowwindow

Examples:	56, 57, 58

		   WordUp Graphics Toolkit: Library Reference        Page 130

wloadmap
-----------------------------------------------------------------------------
Function:     	Loads a tiled map into a scrolling window.

Declaration:  	wgtmap wloadmap (int currentwindow, char *mapfile, 
                                 int *tiletypes, scrollsprite *wobjects)

Remarks:      	Maps that are created with the WGT Map Maker can be loaded 
              	into memory with this command.  currentwindow can be a number
              	from 0 to 3, which defines which scrolling window to load the
              	map into.  Each scrolling window may have different maps and
              	use different tiles.  mapfile is the name of the WGT map
              	file (.WMP extension) to load.  tiletypes is a pointer to an
              	array of 256 integers which contains a number for each
              	tile.  These numbers can be used to group tiles into certain
              	categories, such as solid or hollow.   wobjects is a 
              	scrollsprite structure to load the positions and sprite numbers
              	of the objects in the map.  wobjects must be large enough to
              	hold all the objects.  For example if the last object number 
              	used in a map is 678, you must define wobjects as:
              	scrollsprite wobjects[679];


              	Global Variables Set:

              	mapwidth[currentwindow] contains the width of the map in tiles.
              	mapheight[currentwindow] contains the height of the map in 
		tiles.

Parameters:   	currentwindow - Scrolling window to load the map into (0-3).

              	mapfile       - Filename of the map to load.

              	tiletypes     - Pointer to an array of 256 integers used for
                                storing tiletypes.

              	wobject       - Pointer to an array of scrollsprites.  

Return Value: 	A pointer to the WGT map in conventional memory.
              	NULL is returned map could not loaded due to not enough
              	memory, or the file could not be found.

See Also:     	wfreemap

Examples:	56, 57, 58

		   WordUp Graphics Toolkit: Library Reference        Page 131

wputworldblock
------------------------------------------------------------------------------
Function:     	Changes the tile number at the given location on a map.

Declaration:  	void wputworldblock (int currentwindow, int posx, int posy, 
                                     int tilenum)

Remarks:      	wputworldblock is used for modifying the map while displaying
              	it in a window.  posx and posy are the map coordinates of the
              	tile, and tilenum is the new tile number.  It should be used
              	sparingly with animating tiles, since wputworldblock is slow
              	due to the nature of the scrolling system.  For better results,
              	try placing a scrollsprite in front of the tile you want 
              	animated, and draw those scrollsprites first.

Parameters:   	currentwindow - Scrolling window of containing the map.

              	posx          - X coordinate of tile.

              	posy          - Y coordinate of tile.

              	tilenum       - New tile number

Return Value: 	None

See Also:     	wgetworldblock

Examples:	58

		   WordUp Graphics Toolkit: Library Reference        Page 132

wsavemap
------------------------------------------------------------------------------
Function:     	Saves a WGT map stored in memory into a file.

Declaration:  	void wsavemap (int currentwindow, char *filename,
                               wgtmap savemap, int *tiletypes, 
                               scrollsprite *wobjects, int numobj)

Remarks:      	This command will save the current map in the given scrolling
              	window, along with all of the scrollsprite positions and   
              	tiletypes.  currentwindow is the scrolling window containing
              	the map to save.  filename is the map file to create.
              	savemap is the wgtmap pointer which points to the map data.
              	tiletypes is an array of 256 integers for the tile types.
              	wobjects is an array of scrollsprites holding the information
              	about the sprites in the map.  numobj contains the size of
              	the wobjects array.

Parameters:   	currentwindow - Scrolling window containing the map to save.

              	filename      - Filename of the map file to save.

              	savemap       - Pointer to the map in memory. 

              	tiletypes     - Pointer to the array of tile types. 
                                (256 integers)

              	wobjects      - Pointer to the array of scrollsprites.

              	numobj        - Size of the wobjects array.  

Return Value: 	None

See Also:     	wfreemap, wloadmap

Examples:	56

		   WordUp Graphics Toolkit: Library Reference        Page 133

wscrollwindow
------------------------------------------------------------------------------
Function:     	Scrolls a window by a distance vertically and horizontally.

Declaration:  	void wscrollwindow (int currentwindow, int wspeedx, 
                                    int wspeedy)

Remarks:      	wscrollwindow scrolls the given window by a number of pixels
              	in any direction.  It must be called continuously to update
              	the scrolling window, even if the scrolling distances are 0.

              	wspeedx is the number of pixels to move in the x direction.  
              	A negative value for wspeedx will scroll to the left. 

              	wspeedy is the number of pixels to move in the y direction.  
              	A negative value for wspeedy will scroll upwards.

              	When using parallax scrolling with many layers, the NORMAL
              	layer must be the first window to be scrolled/drawn. Each 
		parallax layer will be added to the image from back to front 
		when you use wscrollwindow to draw it.  Since each layer is 
              	constructed separately, it easy to change the order of the
              	parallax layers, and draw sprites between layers.

Parameters:   	currentwindow - Scrolling window of the map to scroll.

              	wspeedx       - Number of pixels to scroll in X direction.

              	wspeedy       - Number of pixels to scroll in Y direction.

Return Value: 	None

See Also:     	wshowwindow

Examples:	56, 57, 58

		   WordUp Graphics Toolkit: Library Reference        Page 134

wshowobjects
------------------------------------------------------------------------------
Function:     	Displays a range of scrollsprites on the scrolling window.

Declaration:  	void wshowobjects (int currentwindow, int start, int end, 
                                   block *sprites, scrollsprite *wobjects)

Remarks:      	wshowobjects provides an easy way to display your 
              	scrollsprites over the scrolling background.  start and end
              	refer to the starting and ending indexes of the scrollsprite
              	array wobjects.  All sprites within this range will be drawn
              	from the lowest index to the highest.  Lower indexes will 
              	are therefore drawn behind higher indexes.  You can also change
              	the order the sprites are drawn by splitting your sprites into
              	ranges, and draw them with a number of calls to wshowobjects.
              	Sprites may be placed behind a PARALLAX layer by showing them
              	before the layer is drawn with the wscrollwindow command.

Parameters:   	currentwindow - Scrolling window containing the map.

              	start         - Number of first scrollsprite to show.

              	end           - Number of last scrollsprite to show.

              	sprites       - Pointer to the array of images for sprites.

              	wobjects      - Pointer to the array of scrollsprites.

Return Value: 	None

See Also:     	wscrollwindow

Examples:	56, 58

		   WordUp Graphics Toolkit: Library Reference        Page 135

wshowwindow
------------------------------------------------------------------------------
Function:     	Sets the location of the world within a scrolling window.

Declaration:  	void wshowwindow (int currentwindow, int posx, int posy)

Remarks:      	wshowwindow is used to set where the window will be 
              	located within the map.  It is called once before wscrollwindow
              	to set the initial viewing coordinates, and may be used while
              	scrolling to instantly change the viewing coordinates.
              	posy and posy are the coordinates, in tile measurements, of
              	the new viewing coordinates.  You must start your viewing
              	coordinates on a tile boundary.

Parameters:   	currentwindow - Scrolling window to set viewpoint.

              	posx          - Initial X coordinate in map. (in map coords)

              	posy          - Initial Y coordinate in map. (in map coords)

Return Value: 	None

See Also:     	winitscroll

Examples:	56, 57, 58

		   WordUp Graphics Toolkit: Library Reference        Page 136

WGTMENU.LIB

User interfaces can be so confusing at times, and so helpful in others. This 
library provides a set of routines for providing dropdown menus (such as used 
in a windowing system). 

For examples of this library in action, take a look at the Map Maker 4.0 which 
is included with this release of WGT. The program uses the dropdown menu 
system as the core decision maker of the program logic flow. 


		   WordUp Graphics Toolkit: Library Reference        Page 137

checkmenu
------------------------------------------------------------------------------
Function:     	Polls the mouse until the users clicks a button, and returns
              	which menu choice was selected.

Declaration:  	int checkmenu (void)

Remarks:      	checkmenu loops until the user selects a choice from the menu 
              	bar or clicks the mouse button outside of the menu bar.
              	If a selection is made, it returns the number of the menu 
              	choice.  

              	The return value is a combination of the menu bar title and
              	the option within that bar.  For each menu bar, multiply by
              	10, and add the choice within the menu.

              	For example, if you selected the menu below, it would return 
              	the number 11.
              	dropdown[1].choice[1]=" Save ";

              	Mathematically:
              	result = menu*10 + choice
              	       = 1*10    + 1
              	       = 11

              	If the mouse is clicked outside the menu, it returns -1.

Parameters:   	None

Return Value: 	The number of the menu choice selected, or -1 if the mouse
              	was clicked elsewhere.

See Also:	initdropdowns, removemenubar, showmenubar

Examples:	40

		   WordUp Graphics Toolkit: Library Reference        Page 138

initdropdowns
------------------------------------------------------------------------------
Function:     	Initializes the drop down menu system.

Declaration:  	void initdropdowns (void)

Remarks:      	You must call this after you have defined the menu bar and
              	drop down menus.  If you change the text in the menus, 
              	such as toggling choices, you may need to call this again to 
              	get the correct sizes for the drop down menus.

Parameters:   	None

Return Value: 	None

See Also:	checkmenu, removemenubar, showmenubar

Examples:	40




removemenubar
------------------------------------------------------------------------------
Function:     	Turns off the menu bar at the top of the screen.

Declaration:  	void removemenubar(void)

Remarks:	This command restores the screen underneath the menu bar
		and shuts down the menu system.

Parameters:   	None

Return Value: 	None

See Also:	checkmenu, initdropdowns, showmenubar

Examples:	40

		   WordUp Graphics Toolkit: Library Reference        Page 139

showmenubar
------------------------------------------------------------------------------
Function:     	Displays the menu bar at the top of the screen.

Declaration:  	void showmenubar (void)

Remarks:	This will activate the menu you have defined, and 
		display the menu bar at the top of the screen.

Parameters:   	None

Return Value: 	None

See Also:	checkmenu, initdropdowns, removemenubar

Examples:	40

		   WordUp Graphics Toolkit: Library Reference        Page 140

WSPR.LIB

Some of the simplest and most entertaining games are created with the use of 
animated characters over a non-changing background. This library of routines 
provides you with the ability to animate images created with the WGT Sprite 
Editor. The full range of motion, animation and object collision is provided 
through these routines.

This library is NOT compatible with the WGTSCROL.LIB file. This library can 
not be used to produce animations over a tiled background created with our 
other utilities. Limitations to the number of "sprites" onscreen and the 
specialization of the routines themselves has prompted us to provide full 
source code for this library. Feel free to alter the code and recompile the 
library file to meet your own personal needs. DO NOT redistribute the library 
file once it has been altered. We are not responsible for the use of this code 
once it has been altered in any way.


		   WordUp Graphics Toolkit: Library Reference        Page 141

animate
------------------------------------------------------------------------------
Function:     	Sets the animation sequence for a sprite.

Declaration:  	void animate (int spritenum, char *animation_sequence)

Remarks:      	animate sets up animation for a sprite.  Spritenum is the 
              	sprite number to animate.  The animation_sequence string 
              	takes the following form:

 	      
		"(arrnumber,delay)(arrnumber2,delay2)...(arrnumberN,delayN)R"

              	Between each set of brackets is the information required to 
              	animate the sprite.  The first number is the sprite array 
              	number, and the second is how long that sprite number is 
              	displayed. You then make another set and use different sprite 
              	numbers and delays.  If you place a CAPITAL R at the end of 
              	the string, the animation will repeat itself when it gets to 
              	the end.  If you leave the R out, the animation will occur 
              	once, and stop.  You can have up to 40 sets in the animation 
		sequence.

              	For example: 
              	  To animate sprite number one between two sprites, and 
              	  repeat:

              	       Animate(1,"(1,0)(2,1)R");
              	               ^   ^    ^   ^
              	               |   |    |   | R repeats the sequence
              	               |   |    |
		               |   |    Second sprite shown is number 2, with 
                               |   |    1 delay
                               |   |
              	Sprite to animate   First sprite shown is number 1, with no 
                                    delay

              	After calling this procedure, you must turn the animation 
              	on with animon.

Parameters:   	spritenum          - Sprite number to animate.

              	animation_sequence - Pointer to the animation control string.

Return Value: 	None

See Also:	animon, animoff

Examples:	22, 23, 25

		   WordUp Graphics Toolkit: Library Reference        Page 142

animoff
------------------------------------------------------------------------------
Function: 	Freezes animation for the sprite.

Declaration: 	void animoff (int spritenum)

Remarks:	animoff will temporarily turn off the animation sequence for
		the given sprite.  Animation will resume from the point it
		stopped when animon is called.

Parameters:   	spritenum - Sprite numver to freeze animation.

Return Value: 	None

See Also:	animate, animon 

Examples:	25




animon
------------------------------------------------------------------------------
Function:     	Turns animation on for a sprite.  

Declaration:  	void animon (int spritenum)

Remarks:      	Animation sequence are set with the animate command.  To 
              	activate the sequence, the sprite must be turned on.
              	Each time drawspr is called, the animation will advance by
              	one frame, or delay unit.

Parameters:   	spritenum - Sprite number to turn on animation.

Return Value: 	None

See Also:	animate, animoff

Examples:	22, 23, 25

		   WordUp Graphics Toolkit: Library Reference        Page 143

deinitspr
------------------------------------------------------------------------------
Function:	Deinitializes the sprite system.

Declaration:	void deinitspr (void)

Remarks:	Before quitting your program, or calling initspr again, you 
		must first shut down the sprite system with deinitspr.  This 
		will free the memory used by the sprites on the screen.

Parameters:   	None

Return Value: 	None

See Also:	initspr

Examples:	22, 23, 25




drawspr
------------------------------------------------------------------------------
Function:	Draws the sprites and updates movement and animation counters.

Declaration:	void drawspr (void)

Remarks:	drawspr will first update the animation and movement of all the 
		sprites, and then draw them in the correct location on the 
		screen.

Parameters:   	None

Return Value: 	None

See Also:	erasespr

Examples:	22, 23, 25

		   WordUp Graphics Toolkit: Library Reference        Page 144

erasespr
------------------------------------------------------------------------------
Function:     Erases the sprites from the screen.

Declaration:  void erasespr (void)

Remarks:	erasespr will remove the sprites from the virtual screen 
		spritescreen, in preparation for drawing them in a new 
		location.  They will not disappear from the visual screen.
		To remove a sprite from the visual screen requires you to call 
		erasespr, turn the sprite off using spriteoff, and call drawspr
		which updates the screen.

Parameters:   	None

Return Value: 	None

See Also:	drawspr

Examples:	22, 23, 25




initspr
------------------------------------------------------------------------------
Function:     	Initializes the sprite library.

Declaration:  	void initspr (void)

Remarks:      	initspr sets up some internal variables, and makes a virtual 
              	screen called 'spritescreen'.

              	It assumes you have loaded sprites into an array called 
              	'sprites'.  You must call the array "sprites" for these 
              	routines to work.

              	You must call initspr after you load in the sprites using 
              	wloadsprites.  If you need to call this more than once in a
              	program, you must use the deinitspr command first.

Parameters:   	None

Return Value: 	None

See Also:	deinitspr

Examples:	22, 23, 25

		   WordUp Graphics Toolkit: Library Reference        Page 145

movex
------------------------------------------------------------------------------
Function:     	Sets the horizontal movement of a sprite.

Declaration: 	void movex (int spritenum,char *movement_sequence)

Remarks:	movex works similar to animate only there are 3 numbers in each 
		set. You can have up to 15 sets in the movement sequence.

		movex(3,"(1,50,1)(-1,50,0)R");

		The first number in the set is added to the current x 
		coordinate of the sprite.  Therefore if the sprite is at 100,50 
		on the screen, and you make the number a 5, the sprite will 
		move to 105,50.  This number can be anything, so you can have 
		the sprite move right (positive numbers), left (negative 
		numbers) or nowhere (zero).

		The second number in the set is the number of times to move the
		sprite before going on to the next set.  It must always be 
		greater then 0.

		The third number in the set is the delay for each time the 
		sprite moves.  Try using 0 at first and increase it to slow the 
		sprites down.

		If the set was (1,50,1), then the sprite would move to the 
		right one pixel, 50 times, with a delay of 1 for each move.  
		Then the next set would be activated. If you have a CAPITAL R 
		at the end of the string, the movement will repeat.

		For example, to make sprite 2 move back and forth on the screen
		continuously:
	
		movex(2,"(1,200,0)(-1,200,0)R");

		To make a sprite move from the left side to the right, and jump
		back to the left again:

		movex(2,"(1,319,0)(-319,1,0)R");
			    ^
			    | This moves the sprite 319 pixels to the left!

Parameters:   	spritenum         - Sprite number to set movement.

		movement_sequence - Movement sequence string.

Return Value: 	None

See Also:	movexoff, movexon

Examples:	22, 25

		   WordUp Graphics Toolkit: Library Reference        Page 146

movexoff
------------------------------------------------------------------------------
Function: 	Turns horizontal movement for a sprite off.

Declaration: 	void movexoff (int spritenum)

Remarks:	This will temporarily turn off the horizontal movement of a 
		sprite.  It can be turned back on with movexon.

Parameters:   	spritenum - Sprite number to deactivate movement.

Return Value: 	None

See Also:	movex, movexon

Examples:	25




movexon
------------------------------------------------------------------------------
Function: 	Turns horizontal movement for a sprite on.

Declaration: 	void movexon (int spritenum)

Remarks:	This will turn the horizontal movement for a sprite on.  The 
		movement sequence must have been defined previously with movex.

Parameters:  	spritenum - Sprite number to activate movement.

Return Value:	None

See Also:	movex, movexoff

Examples:	22, 25

		   WordUp Graphics Toolkit: Library Reference        Page 147

movey
------------------------------------------------------------------------------
Function: 	Sets up vertical movement for a sprite.

Declaration: 	void movey (int spritenum,char *movement_sequence)

Remarks:	This command works the same way as movex, only it sets the
		vertical movement of the sprite.  See movex for the 
		movement_sequence format.

Parameters:   	spritenum 	  - Sprite number to set movement.

		movement_sequence - Movement sequence string.

Return Value: 	None

See Also:	moveyoff, moveyon

Examples:	25




moveyoff
------------------------------------------------------------------------------
Function: 	Turns vertical movement for a sprite off.

Declaration: 	void moveyoff (int spritenum)

Remarks:	This will temporarily turn off the vertical movement of a 
		sprite.  It can be turned back on with moveyon.

Parameters:   	spritenum - Sprite number to deactivate movement.

Return Value: 	None

See Also:	movey, moveyon

Examples:	25

		   WordUp Graphics Toolkit: Library Reference        Page 148

moveyon
------------------------------------------------------------------------------
Function: 	Turns vertical movement for a sprite on.

Declaration: 	void moveyon (int spritenum)

Remarks:	This will turn the vertical movement for a sprite on.  The 
		movement sequence must have been defined previously with movey.

Parameters:  	spritenum - Sprite number to activate movement.

Return Value: 	None

See Also:	movey, moveyoff

Examples:	25




overlap
------------------------------------------------------------------------------
Function: 	Tests if two sprites overlap each other on the screen.

Declaration: 	int overlap (int spritenum_1,int spritenum_2)

Remarks:	overlap checks the bounding rectangles of the two sprites and
		returns a 1 if they are overlapping.  This is used for 
		collision detection between the sprites.

Parameters:   	spritenum_1 - Sprite number of first sprite.

		spritenum_2 - Sprite number of second sprite.

Return Value: 	1 if sprites overlap, 0 if they do not.

Examples:	5, 20

		   WordUp Graphics Toolkit: Library Reference        Page 149

spriteoff
------------------------------------------------------------------------------
Function:     	Turns off a sprite.

Declaration:  	void spriteoff (int spritenum)

Remarks:      	This command frees the memory used by a sprite, and removes it
              	from the screen during the next call to drawspr.

Parameters:   	spritenum - Sprite number to turn off.

Return Value: 	None

See Also:	spriteon

Examples:	22, 23, 25




spriteon
------------------------------------------------------------------------------
Function:     	Turns a sprite on at the given location.       

Declaration:  	void spriteon (int spritenum, int xcoord, int ycoord,
                               int arrnumber)

Remarks:      	spriteon turns a sprite on at the coordinates, using the 
              	arrnumber block from the sprites array.  Arrnumber is the same 
              	as the sprite numbers in the WGT Sprite Editor.  Spritenum can 
              	range from 1 to 40.  This means you can have 40 sprites on the 
              	screen at once.  Each call to spriteon must be followed later 
		in the program by a spriteoff.  Do not call spriteon using the 
		same spritenum twice in a row or the computer will lose 
              	conventional memory.  You must turn the sprite off and back on 
              	again.

Parameters:   	spritenum - Sprite number to turn on (1-40).

              	xcoord    - X coordinate of sprite.

              	ycoord    - Y coordinate of sprite.

              	arrnumber - Sprite image number.

Return Value: 	None

See Also:	spriteoff

Examples:	22, 23, 25

		   WordUp Graphics Toolkit: Library Reference        Page 150


WGTFLIC.LIB

Previous releases of WGT have provided routines for the playback of FLI files. 
Version 4.0 of WGT has increased support by implementing support for both FLI 
and FLC format animation files. These files are created using commercial 
software programs or a shareware program called Dave's Targa Animation.

The functions have different names than their previous versions, and now 
include the ability to return error codes to the user. The header information 
loaded from the animation file is stored in a global structure available to 
the user. Animations may now be played from either disk or EMS memory, 
providing a lot of power from only a few routines. Refer to the example file 
(mentioned in each command description) for full source code to play the files.


		   WordUp Graphics Toolkit: Library Reference        Page 151

openflic
------------------------------------------------------------------------------
Function:     	Opens an FLI or FLC animation file to be played.

Declaration:  	int openflic(char *filename)

Remarks:	This routine will open an animation file which has been created
		using the commercial file format by Autodesk. These animation
		files may be played from either disk or EMS memory. Disk 
		accesses are slow, so it is advisable to use EMS if possible.

		The function will return an error value if the file could not 
		be found, or if it is not the proper resolution. Refer to the
		WGTFLIC include file for the define statements which indicate
		the error.

Parameters:	filename - The full pathname of the animation to load.

Return Value:	Number indicating error during file open (if any).

See also:	closeflic, nextframe

Examples:	52




nextframe
------------------------------------------------------------------------------
Function:	Advances an open animation file to the next frame.

Declaration:	int nextframe (void)

Remarks:	Once an animation file has been opened with openflic, this
		command is used to update the animation to the next frame. An
		internal counter keeps track of the last frame played, and the
		function will return FLIC_DONE (see include file) when it 
		reaches the final frame. If this value is ignored, subsequent 
		calls to nextframe will loop around and start the animation 
		again.

Parameters:	None

Return Value:	Integer indicating error status or completion status of 
		animation. See include file for defines.

See Also:	closeflic, copyflic, openflic

Examples:	52

		   WordUp Graphics Toolkit: Library Reference        Page 152

copyflic
------------------------------------------------------------------------------
Function:	Copies the animation buffer to the visual screen.

Declaration:	void copyflic (void)

Remarks:	If you are using a secondary screen buffer to perform 
		animations, this command will copy from the virtual screen to 
		the visual screen. The virtual screen must have been created by 
		calling wnewblock, and you must set the flicscreen variable to 
		point to the buffer.

		For example (small FLI/FLC player using virtual screen):

		block buffer;
		buffer = wnewblock (0, 0, 319, 199);	/*Allocate our buffer*/
		flicscreen = buffer;				/*Assign it*/
		flic_mode = FLIC_DISK;			/*Play from disk*/
		result = openflic ("myflic.flc");	/*Open the file*/
		if (result == FLIC_OK)			/*If successful*/
		{
	  	  while (nextframe () == FLIC_OK)	/*and not done flic*/
	  	  {
	    	    copyflic ();			/*Copy to screen*/
	    	    delay (flichdr.speed);		/*Proper speed*/
	  	  }
	  	  closeflic ();				/*Close file*/
		}
		wfreeblock (buffer);			/*Free buffer*/

Parameters:	None

Return Value:	None

See Also:	closeflic, nextframe, openflic

Examples:	None

		   WordUp Graphics Toolkit: Library Reference        Page 153

closeflic
------------------------------------------------------------------------------
Function:	Closes a previously opened animation file.

Declaration:	void closeflic (void)

Remarks:	If an animation file has been opened successfully with the
		openflic command, this routine will close the file.

Parameters:	None

Return Value:	None

See Also:	openflic

Examples:	52

		   WordUp Graphics Toolkit: Library Reference        Page 154


WGTVESA.LIB


WGT now supports SVGA video modes through the use of a VESA video 
driver. There are currently a limited number of supported 
graphics routines for these modes, however they will be expanded 
over time to include the full set of WGT primitives. Block sizes 
are still limited to 320*200, as well as the virtual screen 
buffers. X and Y coordinates will depend on the video mode being 
used. The following commands are supported in SVGA modes:

void wvesa_clip (int x, int y, int x2, int y2);
void wvesa_cls (int color);
void wvesa_putpixel (int x, int y);
int  wvesa_getpixel (int x, int y);
void wvesa_line (int x, int y, int x2, int y2);
void wvesa_hline (int x, int x2, int y);
void wvesa_bar (int x, int y, int x2, int y2);
void wvesa_rectangle (int x, int y, int x2, int y2);
void wvesa_copyscreen (int sx, int sy, int sx2, int sy2, block src,
                       int dx, int dy, int method);
void wvesa_putblock (int dx, int dy, block src, int method);
void wvesa_outtextxy (int x, int y, wgtfont fnt , char *printit);


NOTE:  The wvesa_copyscreen contains an additional parameter
       compared to the normal wcopyscreen command. This parameter
       allows solid or xray copy modes.


		   WordUp Graphics Toolkit: Library Reference        Page 155

wvesa_detected
------------------------------------------------------------------------------
Function:	Returns 1 if a VESA (SVGA) driver is detected.

Declaration:	int wvesa_detected (void)

Remarks:	To enable a Super VGA video mode, WGT requires the presence of
		a VESA video driver. These drivers are available with the 
		software included with most SVGA cards, and may be obtained 
		from a local BBS if needed. Do not attempt to use any of the 
		remaining commands in this library if the function returns a 0.

Parameters:	None

Return Value:	0 - VESA driver not found.
		1 - Driver was found.

Examples:	53




wvesa_bank
------------------------------------------------------------------------------
Function:	Switches to a different bank on a SVGA card.

Declaration:	int wvesa_bank (int bank)

Remarks:	Generally this command will not be needed. It is included for
		those who wish to write their own video routines for VESA. You
		must call this command whenever you want to write to video ram
		outside the current bank number. The size (in bytes) of the 
		banks are stored in the VESAmode.banksize global variable. To 
		initialize this structure, you must first call 
		wvesa_getmodeinfo. See the WGTVESA include file for further 
		details on the global structures available to the programmer.

Parameters:	bank - Integer indicating bank number to switch to. This number
		       will vary in range depending on the video card and the
		       video mode selected.

Return Value:	0 - Successful call.
		1 - Error during call.

See Also:	wvesa_detected, wvesa_getmodeinfo, wvesa_init

Examples:	None

		   WordUp Graphics Toolkit: Library Reference        Page 156

wvesa_getmodeinfo
------------------------------------------------------------------------------
Function:	Stores video mode information in the VESAmode global structure.

Declaration:	int wvesa_getmodeinfo (int mode)

Remarks:	After detecting a VESA driver, the user may wish to determine
		which modes are supported by the video card. This information 
		may be obtained by calling wvesa_supported. If the function 
		returns a 1, you may then call wvesa_getmodeinfo with the same 
		mode value to get mode specific information. The information is
		stored in the VESAmode global variable after a successful 
		call. See the WGTVESA include file for a detailed description 
		of the structure and its contents.

Parameters:	mode - Video mode to obtain information on.

		As defined in WGTVESA.H:
		#define V640x400	0x100 /* Mode 256 is 640x400x256 */
		#define V640x480	0x101 /* Mode 257 is 640x480x256 */
		#define V800x600	0x103 /* Mode 259 is 800x600x256 */
		#define V1024x768	0x105 /* Mode 261 is 1024x768x256 */
		#define V1280x1024	0x107 /* Mode 263 is 1280x1024x256 */

Return Value:	0 - Call was successful.
		1 - Error during call.

See Also:	wvesa_detected, wvesa_init, wvesa_supported

Examples:	53

		   WordUp Graphics Toolkit: Library Reference        Page 157

wvesa_init
------------------------------------------------------------------------------
Function:	Initializes a SVGA video mode using a VESA driver.

Declaration:	int wvesa_init (int mode)

Remarks:	Instead of calling vga256 to initialize graphics mode, this 
		routine is used to start a SVGA video mode. The value passed as 
		the video mode may be determined by calling wvesa_supported or 
		pre-determined by the programmer. If the video mode is not 
		supported by the video card or the driver, this function will 
		return an error value and the video mode will not be 
		initialized. This function must be called before any graphics 
		operations are performed in SVGA modes.

		The VESAmode global structure will contain information about 
		the video mode after a successful call to wvesa_init.

Parameters:	mode - SVGA video mode to initialize.

		As defined in WGTVESA.H:
		#define V640x400	0x100 /* Mode 256 is 640x400x256 */
		#define V640x480	0x101 /* Mode 257 is 640x480x256 */
		#define V800x600	0x103 /* Mode 259 is 800x600x256 */
		#define V1024x768	0x105 /* Mode 261 is 1024x768x256 */
		#define V1280x1024	0x107 /* Mode 263 is 1280x1024x256 */

Return Value:	0 - Call was successful.
		1 - Error during call, video mode not supported.

See Also:	wvesa_detected, wvesa_getmodeinfo, wvesa_supported

Examples:	53

		   WordUp Graphics Toolkit: Library Reference        Page 158

wvesa_supported
------------------------------------------------------------------------------
Function:	Returns status of VESA and video card support for a given SVGA
		video mode.

Declaration:	int wvesa_supported (int mode)

Remarks:	Given a SVGA video mode number, this routine will return the
		status of VESA support for the mode. Different video cards will 
		support different video modes, so you must make sure that the 
		mode is supported before intializing graphics mode and 
		executing the rest of the program.

		Once support has been verified, the video mode may be 
		initialized, or a call to wvesa_getmodeinfo can be made to 
		determine information about the mode.

Parameters:	mode - SVGA video mode number.

		As defined in WGTVESA.H:
		#define V640x400	0x100 /* Mode 256 is 640x400x256 */
		#define V640x480	0x101 /* Mode 257 is 640x480x256 */
		#define V800x600	0x103 /* Mode 259 is 800x600x256 */
		#define V1024x768	0x105 /* Mode 261 is 1024x768x256 */
		#define V1280x1024	0x107 /* Mode 263 is 1280x1024x256 */

Return Value:	0 - Mode is NOT supported.
		1 - The given video mode is supported on this card.

See Also:	wvesa_detected, wvesa_getmodeinfo, wvesa_init

Examples:	53



