CD Actual 14

home *** CD-ROM | disk | FTP | other *** search

/ CD Actual 14 / CDACTUAL.iso / cdactual / demobin / share / program / Basic / VGALIB10.ZIP / MANUAL.DOC < prev next >

Wrap

Text File | 1991-08-21 | 31.7 KB | 726 lines

BASIC GAME DESIGNERS' VGA LIBRARY INTRODUCTION This is a library of graphic functions, written in assembly language, that add a lot of speed and power to your QuickBASIC programs. WARNING! These functions will ONLY work in the VGA 256 color mode. At present, the VGALIB supports the 320 x 200 mode, 320 x 240, and the 320 x 400 mode. Soon, however, I plan to add support for SVGA modes...including 640x480 and 800x600. Almost all of the functions in my library have tested faster that their QuickBASIC equivalents and there are many functions in my library that aren't in BASIC. After all, BASIC doesn't support anything better than 320x200. VGALIB library of functions were written especially with game programming in mind. I have included a demo program that has samples of a couple different games... a 3-D adventure game, a scrolling game, etc. The documented source code to the demo is available upon registration, as well as a small tutorial and hints file on how to write PC games. SHAREWARE? The VGA QLB file is shareware. You may freely distribute it as long as it is not modified and that it is distributed with the following original, unmodified, unaltered files: VGA .QLB The VGA QuickLibrary 3D .EXE Demo of 3-D adventure game SCROLL .EXE Demo of Scrolling game DECLARE .BAS Declare statements for all the functions DEMO .BAS Demo of graphic primitives MANUAL .DOC This manual REGISTER.DOC Registration form Feel free to use the QuickLibrary as much as you like. It will allow you to use ALL of the functions in the run-time environment and allow you to "try before you buy." That way, you can decide whether or not it will help you and whether you should buy it. I encourage all of you who are seriously interested in PC game/graphics programming to register. Registered users will receive the latest version of the library (the .QLB file and the .LIB) and discounts on future revisions of the VGALIB, an updated manual, the source code and data files that make up the demo programs, other special programs not in the evaluation package, a small tutorial/hints file on programming PC games, a periodic game programmers newsletter, and my gratitude. I have a lot of things planned for this library. Just some of things I plan to do (if there is enough interest..ie. registered users) are as follows: 1) Add support for 256 color SVGA modes, 640 x 400, 640 x 480, and 800x600 modes. 2) Add support for using graphics primitives on the virtual screens. Being able to use LINE200, XLINE200, CIRCLE200, etc. on the virtual screens. 3) Add support for loading, saving and manipulating images in various formats, including GIF, PCX, MAC, and others. 4) Start a BBS dedicated to PC Game Programming with the current version of my library available for registers users, as well as forums about programming various types of games. There will be a technical support forum for my library where any questions you may have can be answered by myself. But none of this will happen unless you register it. I put a lot of money, research, and programming time into creating and testing this library. And my wife put up with me through all of this without asking for a divorce -- so please register it or she won't let me come out with version 2. GETTING STARTED The first thing you should do is create a directory for the QuickLibrary and the demo program. For example: MD \VGALIB Next, unzip the files into the directory and you're ready to go. To start the demo, type DEMO at the prompt: C:\VGALIB>DEMO This will start the demo of the libraries features and some of the game programming genres (ie. 3-D Adventure games, Scrolling action games, etc.). This also does a speed comparison between my graphic primitives and BASIC's functions. USING GRAPHICS FUNCTIONS IN THE QUICKBASIC ENVIRONMENT The VGA Library is written for QuickBASIC 4.x. Although I have only tested it with QuickBASIC 4.5, it should work with any version 4. The registered version will run with BASIC PDS 7.x as well. To use the VGA QuickLib (.QLB) in the QuickBASIC editor, you must start QB with the /L parameter followed by the path and name of the library. For example: C:\QB45>QB /LC:\VGALIB\VGALIB.QLB This will cause QB to load the VGA graphics library into memory and allow you to access all of it's functions in the run-time environment. DECLARING THE SUBROUTINES All of the VGALIB commands are defined as subroutines. You MUST declare any routines in be beginning of your program for them to work correctly. If you do not declare the subroutines in your program, weird results may occur, including system lockup, garbled screen results, etc. The basic program DECLARE.BAS, which is included, has the necessary declaration statements for you to access all of the functions. THE LIBRARY The following is a list of the commands, calling syntax, and a brief description of what each command does and any of my own comments. In the 320x200 mode, you should only use the routines that end with the suffix 200 (ie. PSET200, LINE200, etc.) . When in the 320x240 mode or the 320x400 mode, please use only routines that end with 240 (ie. PSET240, LINE240, PUT240, etc.) Since I only added 320x240 and 320x400 support recently, some of the routines are slow but that will soon be remedied as I get more accustomed to the setup of the VGA memory in these extended modes. SET320x200 Syntax: Call SET320x200 or SET320x200 Description: This routine uses the DOS Interrupt to set the screen into graphics mode. It sets up graphics mode 13H, which is the 320 x 200 mode in 256 colors. WARNING! If you use this command to switch to graphics mode, most of the QB graphics functions WILL NOT work because the QB SCREEN statement sets an internal QB variable that tells the QB environment which graphics mode it's in. This subroutine DOES NOT set that variable so as far as QB is concerned...you're still in text mode. CLS, LINE, PAINT, PSET, GET, PUT, and PRINT WILL NOT function when the SET320x200 is used. SET320x240 Syntax: Call SET320x240 or SET320x240 Description: This routine uses the DOS Interrupt to set the screen into graphics mode. It sets up graphics mode 13H, which is the 320 x 200 mode in 256 colors. Then, it changes a few things around to give you 240 scan lines instead of 200. I won't go into specifics here. WARNING! When you are in this mode, use only the commands that end in 240....(ie. PSET240, POINT240, LINE240, etc.) Using the other commands will cause bizarre results. As of this writing there is no support to PRINT text in either the 320x240 or the 320x400 modes... that will be added shortly. SET320x400 Syntax: Call SET320x400 or SET320x400 Description: This routine uses the DOS Interrupt to set the screen into graphics mode. It sets up graphics mode 13H, which is the 320 x 200 mode in 256 colors. Then, it changes a few things around to give you 400 scan lines instead of 200. Again, I won't go into specifics here. Register if you want more details. WARNING! When you are in this mode, use only the commands that end in 240....(ie. PSET240, POINT240, LINE240, etc.) Using the other commands will cause bizarre results. As of this writing there is no support to PRINT text in either the 320x240 or the 320x400 modes... that will be added shortly. The way the video memory is set up in the 320x240 and the 320x400 modes is identical so you can use the commands from the 240 mode in the 400 mode. SET80x25 Syntax: Call SET80x25 or SET80x25 Description: This routine uses the DOS Interrupt to set the screen into text mode. Normally, when QB terminates a program, it automatically exits to text mode. If you used the SET320x200 sub to set the graphics mode, then YOU must set text mode before the program terminates or you will drop the user to DOS in graphics mode. PSET200 Syntax: Call PSET200 (X%, Y%, Color%) or PSET200 X%, Y%, Color% Description: This routine will set individual pixels on the screen. It will set the pixel at column X% and row Y% to what ever color is specified by the Color% variable. (See DEMO.EXE or DEMO.BAS) Other notes: In the 320x240 mode & the 320x400 mode, you may use the PSET240 command, which has the identical syntax as the PSET200. POINT200 Syntax: A%=PSET200 (X%, Y%) or Description: This routine will return the value of individual pixels on the screen. POINT200 is almost identical to the BASIC Point function. Other notes: In the 320x240 mode & the 320x400 mode, you may use the POINT240 function, which has the identical syntax as the PSET200. LINE200 Syntax: CALL LINE200(X1%, Y1%, X2%, Y2%, Color%) or LINE200 X1%, Y1%, X2%, Y2%, Color% Description: Similar to QB's own LINE statement, the Line200 routine will draw a straight line between two points in the given color. It is faster than the QB LINE statement. (See DEMO.EXE or DEMO.BAS) Other notes: In the 320x240 mode & the 320x400 mode, you may use the LINE240 command, which has the identical syntax as the LINE200. XLINE200 Syntax: CALL XLINE200 (X1%, Y1%, X2%, Y2%, Color%) or XLINE200 X1%, Y1%, X2%, Y2%, Color% Description: This routine is identical to the LINE200 routine above except it XORs the line on top of the existing background. Consequently, if you XOR it back on, it will effectively erase itself, leaving the background unaffected. This technique is often referred to as "rubberbanding." (See DEMO.EXE or DEMO.BAS) Other notes: There is no XLINE command for the 320x240 mode & the 320x400 mode yet but it will be added shortly. BOX200 Syntax: CALL BOX200 (X1%, Y1%, X2%, Y2%, Color%) or BOX200 X1%, Y1%, X2%, Y2%, Color% Description: The BOX200 routine is very similar to the QB LINE command with the B option to create the outline of a box. It create the outline of a box at the given coordinates. (See DEMO.EXE or DEMO.BAS) Other notes: In the 320x240 mode & the 320x400 mode, you may use the Box240 command, which has the identical syntax as the Box200. BOXF200 Syntax: CALL BOXF200 (X1%, Y1%, X2%, Y2%, Color%) or BOXF200 X1%, Y1%, X2%, Y2%, Color% Description: The BOXF200 routine is very similar to the QB LINE command with the BF option to create the outline of a box. It create the a box filled with the given color at the specified coordinates. (See DEMO.EXE or DEMO.BAS) Other notes: In the 320x240 mode & the 320x400 mode, you may use the BoxF240 command, which has the identical syntax as the BoxF200. CIRCLE200 Syntax: CALL CIRCLE200 (X%, Y%, Radius%, Color%) or CIRLCE200 X%, Y%, Radius%, Color% Description: This routine creates a circle who center is X%, Y% and whose radius is determined by the Radius% variable. This creates only the circle outline, not a filled circle. (See DEMO.EXE or DEMO.BAS) Other notes: In the 320x240 mode & the 320x400 mode, you may use the Circle240 command, which has the identical syntax as the Circle200. GET200 Syntax: CALL GET200 (X1%, Y1%, X2%, Y2%, Array(Offset%)) or GET200 X1%, Y1%, X2%, Y2%, Array(Offset%) Description: Similar, but MUCH faster than BASIC's GET command, the GET200 routine will quickly copy an image from the screen to the an array. The array must be previously dimensioned and can be either STATIC or DYNAMIC. IMPORTANT! DO NOT USE A CONVENTIONAL STRING ARRAY. Doing so will cause unpredictable results. You may however, use fixed length string arrays which you have created, or numeric arrays. The size of the array is calculated as follows: XDistance% = ABS(X2% - X1%) + 1 YDistance% = ABS(Y2% - Y1%) + 1 NumOfBytes% = XDistance% *YDistance% +10 ArraySize% = NumOfBytes% \ ElementSize% ElementSize% depends on what type of array you are using. Type of Array ElementSize% Integer 2 Long Integer 4 Single Precision 4 Double Precision 8 TYPE array Size TYPE Other notes: In the 320x240 mode & the 320x400 mode, there is not yet a GET command. However, if you GET something using the GET200 command, you can use the PUT240 command to display it in the 320x240 & 32x400 modes. PUT200 Syntax: CALL PUT200 (X%, Y%, Array(Offset%), Operation%) or PUT256 X%, Y%, Array(Offset%), Operation% Description: Again, the PUT200 is a faster version of BASIC's PUT command. It will quickly display an image that was captured using the GET200 command. The Operation% variable is a logical operation. The logical operations supported are: 0 PSET The image in the array will overwrite anything on the screen. 1 XOR The image in the array will be XORed on to the screen. 2 AND The image in the array will be ANDed onto the screen. 3 OR The image in the array will be ORed onto the screen. Using the XOR logical operator, you can display an image on a complex background, and when you XOR it again it will disappear, restoring the original screen. This is useful for some animation but causes flickering. Other notes: In the 320x240 mode & the 320x400 mode, you may use the PUT240 command, which has the identical syntax as the PUT200, except that it does not yet support the logical operators...only the PSET option. The syntax is the same except that you do not include a logical operator. TPUT200 Syntax: CALL TPUT200 (X%, Y%, Array(Offset%)) or TPUT200 X%, Y%, Array(Offset%) Description: This is a special routine that I made myself. It the Transparent PUT200 routine. Like PUT200, the TPUT200 routine quickly copy an image captured with the GET200 command to the screen. However, the TPUT200 routine WILL NOT copy any pixel in the array that is color 255. This is similar to the movie/TV technique called "blue screening." Other notes: There is no TPUT command for the 320x240 and 320x400 modes yet. It should be done by time you register. RPUT200 Syntax: CALL RPUT200 (X%, Y%, Array(Offset%)) or RPUT200 X%, Y%, Array(Offset%) Description: This is a special routine that I made myself. It the Reverse PUT200 routine. Like PUT200, the RPUT200 routine quickly copy an image captured with the GET200 command to the screen. However, the RPUT200 routine reverses the image from left to right. Other notes: There is no RPUT command for the 320x240 and 320x400 modes yet. It should be finished by time you register. VIRTUAL SCREENS That's it for the commands you might be used to. The next series of the commands have to do with virtual screens. And what is a virtual screen you might ask? What you see on the monitor is called a active screen. The active screen is lives in the memory on your display adapter. A virtual screen is a copy of the active screen that lives in RAM. And because it is in RAM, we can do all sorts of neat things with it because we're not limited by the display adapter. For instance, we can create a virtual screen that is LARGER than the active screen and then display only a part of it on the active screen. This is a technique they often use in scrolling arcade games. Anyway, QB doesn't really allow you to work with virtual screens. You can do it. Or at least I did it. But it was SO slow it was not practical. Consequently, I came up with some assembler routines to do the dirty work for me with considerably speeded things up. Okay, that's it for the explanation. There is more in the manual you get with the registered version. Plus, the source code to SCROLL.EXE deals shows how to use virtual screens. CreateVirtualScreen Syntax: CALL CreateVirtualScreen (Array(Offset%)) or CreateVirtualScreen X1%, Y1%, X2%, Y2%, Array(Offset%) Description: This command creates a virtual screen with the array that you specify. Example: CreateVirtualScreen 0, 0, 639, 479, Array(0) That example creates a virtual screen that is 640 pixels wide by 480 pixels long. VGET Syntax: CALL VGET(Source(Off%)), X1%,Y1%,X2%, Y2%,Target(Off%) or VGET Source(Off%), X1%, Y1%, X2%, Y2%, Target(Off%) Description: This command is similar to the GET200 command, except that it captures a rectangular image off of a virtual screen. Example: VGET Source(0), 0, 0, 20, 20, Target(0) In the example, VGET would copy the image off the virtual screen that you created in Source() at coordinates 0,0 to 20,20 into an array called Target(). You could then PUT200 the image in Target() on the active screen, or use on of the other commands. WARNING! This subroutine assumes a lot. It assumes: 1) That there is a valid VIRTUAL SCREEN created in the Source(). 2) That the coordinates that you pass to it are valid. 3) That Target() is dimensioned properly. (See GET200) If any of these assumptions are not met, unpredictable results may occur. VPUT Syntax: CALL VPUT (Target(Offset%), X%, Y%, Image(Offset%)) or VPUT Target(Offset%), X%, Y%, Image(Offset%) Description: This is very similar to the PUT200 command, except that it PUTs images onto a virtual screen. At present, it only supports the PSET option...no XOR, OR, AND options yet. Again this routine assumes that the Target() array contains EITHER a Virtual Screen or another image that you've captured with the GET200 command. VTPUT Syntax: CALL VTPUT (Target(Offset%), X%, Y%,Image(Offset%)) or VTPUT Target(Offset%), X%, Y%, Image(Offset%) Description: This is very similar to the VPUT command, except that it PUTs images onto a virtual screen using the "blue screening" technique. (See TPUT200 for more) Again this routine assumes that the Target() array contains EITHER a Virtual Screen or another image that you've captured with the GET200 command. OTHER NEAT STUFF There are also some additional features that I've found useful for game programmers and graphics programmers alike. They are small routines that allow you to use different fonts, routines to save/restore the VGA palette, and instructions on how to SAVE/RESTORE 256 Color Screens. There will be more of these routines in future versions. I plan to add support for loading & saving PCX, GIF, and other formats. So look for future versions! SAVEPAL Syntax: CALL SAVEPAL (Target(Offset%)) SAVEPAL Target(Offset%) Description: This subroutine saves the entire VGA color palette (all 256 colors) into an array called Target(). The Target() array MUST have been previously dimensioned for at least 768 bytes. This is because the color palette contains three bytes (1 for green, blue, and red) for each color it saves. So you need 256 * 3 (or 768) number of bytes to store the whole palette. Once you have use the SAVEPAL command to save the palette values into an array, you may use the following technique to save it to disk: DEFINT A-Z ' Integer arrays are 2 bytes per element so we need ' 768 / 2 elements...or 384. DIM Target(0 to 384) ' Save the palette values into the array SAVEPAL Target(0) ' Save the array to disk DEF SEG=VARSEG(Target(0)) BSAVE "Test.PLT", VARPTR(Target(0)), 768 DEF SEG RESTOREPAL Syntax: CALL RESTOREPAL (Source(Offset%)) RESTOREPAL Source(Offset%) Description: This subroutine restores the entire VGA color palette (all 256 colors) from an array called Target(). The Source() array MUST have been previously dimensioned for at least 768 bytes and loaded with palette values. Below is a small program to restore a palette that was saved using the SAVEPAL routine, and then BSAVEd to disk. DEFINT A-Z ' Integer arrays are 2 bytes per element so we need ' 768 / 2 elements...or 384. DIM Source(0 to 384) ' Load the array from disk DEF SEG=VARSEG(Source(0)) BSAVE "Test.PLT", VARPTR(Source(0)) DEF SEG ' Quickly restore the vga values RESTOREPAL Source(0) Other notes: When used with the 320x240 or 320x400 modes, you should use the RestorePal command AFTER you use the SET320x400/SET320x240 commands because the SET320x400/SET320x240 commands destroy the palette. SETFONT200 Syntax: CALL SETFONT200 (FontArray(Offset%)) SETFONT200 FontArray(Offset%) Description: The SETFONT200 routine will enable a special graphics font which has been loaded into FontArray(). This uses a DOS interrupt to quickly change the VGA font table. The evaluation copy comes with two fonts -- a futuristic font and a old looking font. (To load a font, see DEMO4.EXE or DEMO4.EXE) If you register you will receive a special character editor that will allow you to create your own fonts. PRINT200 Syntax: CALL PRINT200 (X%, Y%, Text$, Colr%) PRINT200 1, 1, "Hello", 14 Description: The PRINT200 print a string to the screen when in the 320x200 mode at the coordinates specified by X%, Y%. The Colr% variable specifies the foreground and background colors (something you can't do with QB PRINT). Colr% = Background * 256 + Foreground OTHER UTILITY PROGRAMS There are a few utility programs that are included with the registered version that help you to use the some of the VGALIB functions better. They are: CHAREDIT.EXE - A small character editor for use with the SETFONT200 command. It allows you to create as many 8 x 8 character fonts as your heart desires. It saves fonts in BLOADable format to be used with the SETFONT200 command. SPREDIT.EXE - When you register your copy of VGALIB, you will receive my own sprite editor which will allow you sprites/icons which you can later animate with the functions in VGALIB. OTHER BENEFITS I admit it. Not ALL of my subroutines are faster than their BASIC counterparts. But those that aren't are very close. What I've tried to do is build a replacement library of graphics functions for BASIC that would allow you to totally avoid BASIC graphics library and cut down code size. How much code size? Well, if you don't use any of BASIC's graphics commands...including CLS, SCREEN, LINE, GET/PUT, PAINT, PRINT, etc...you can cut down the size of your compiled code by about 20K or so. I compiled two programs (identical except that one used BASIC's graphics commands and the other used VGALIB equivalents). The VGALIB program compiled to just over 10K (10,976), the BASIC program compiled to just over 30K (36,222). Not a bad savings. It leaves you more room for your own program code. Plus, VGALIB would make an EXCELLENT complement to Crescent's PDQ, since all of the functions and subs are made to work with integers. With PDQ & VGALIB, you could conceivably compile graphics programs that were smaller and faster than "C" or Pascal programs. Am I kidding? No way. So start programming those games you've always wanted to make. Register your copy of VGALIB today! AFTERWARD Ok, that's it for all the hype. This is the real me talking. I made VGALIB because I love to program games but I also love BASIC. And as you all know...BASIC has almost NO good graphics functions or the useful functions (GET/PUT) are slow and far from comprehensive. I looked for a good graphics library for BASIC but it seems all the good ones only supported "C" or Pascal...not BASIC. I saw a really nice sounding graphics library from Company A for $250. I called and asked them before I bought it and they said "Yeah...yeah...it'll do all those things you want...and more!" So, I ordered it. And it came. The disks were in an envelope that had a sticker on it that basically said "OPEN THIS AND YOU CAN'T RETURN IT." So here I am in a dilemma. I can't find out if it does what they say unless I open it...and if I open it, and it doesn't do what I want...I can't return it. Finally I decided to go ahead and open it. Needless to say...it didn't do half the things they said it would, the manual was cryptic and the phone support person (I called 6 times and always spoke to the same person) was rude at best. So there I was, in the same spot as before, except out $250. That is why I am releasing my library (the QLB file at least) into Shareware. So that you can try the graphics functions on your own system and see whether or not they are what you want. If not, fine...you've lost nothing. If so, all you have to do is register it and you're off and running. I do hope you register. But if not, at least send in your comments. Tell me if you see something you like...and PLEASE tell me if there's something you WOULD like. Send all comments, contributions, greeting cards, blank checks, etc. to: SCN Software Solutions 1043 Main Street, Floor 2 Emerald, PA 18080-1006 Remember to make all checks or money orders payable to John or Tammy Cressman. Thank you.