The official documentation For VirtuaSoft Dash library release v1.50+0.28 by 1998-2000 VirtuaSoft DISCLAIMER VirtuaSoft is not responsible for any damages, permanent or temporary, that are caused to your computer by Dash. I have checked and rechecked Dash to make sure it is free of serious bugs, but there is always a possibility that some exist. If you find any bugs in Dash, please e-mail a detailed description of what happened, when it happened, and what error message (if any) was displayed on the screen to: gump@gnt.net, and I will promptly correct them. COLOR CODE red = code yellow = link green = topic heading blue = heading purple = returns KNOWN BUGS VSTexture: The image can't go too far out of the screen. VSTri: Holes will appear in the polygon at certain angles. VSWall: The y-coords can't be negative. MAKEDASH MakeDash allows you to mix-and-match your own Dash subs, functions, and libraries. Its easy interface has you choose the modules to put in your version of Dash, including QB.LIB and other libraries by moving the cursor over the desired selection. After you are done, it will automatically make the QLB, LIB, and BI files for you! (Note: It only works for QB4.5.) There are demos to Dash on my web site that may help you get started in the production of your programs. Feel free to use any of the code in these as a reference. Do NOT directly copy the code and use it as your own. If you decide to use this library in your games, etc., remember to mention that you used VirtuaSoft's Dash library by Danny Gump in your credits. Also, give my e-mail address and web site URL in the credits, and when you finish the program, please send me a copy so I can see how my library has been put to use. CONTACT E-mail: gump@gnt.net Web site: http://www.gnt.net/~gump Since the production of Dash was a very difficult job, and it has taken many months of work, I will be accepting donations as compensation for the hard work. The donations are not required, but if you use Dash in a program you sell, it would only be fair that I recieve some royalties for helping you make your program. The donations can be any amount you deem appropriate. Please send all donations to: Danny Gump P.O. Box 1092 Niceville, FL 32588-1092 GENERAL INFO COMMAND LINE QuickBASIC must be loaded with the Dash library using the following command line: QB /L DASH. HEADER FILE To get the library to work, you must include this at the beginning of your program, after the sub and function declarations and before the variable declarations: '$INCLUDE: 'Dash.bi' BUFFERS Throughout this document, you will come across the term "buffer." This simply refers to the screen where the graphics are being placed. With Dash, you can use arrays to make invisible screens where you can draw your graphics before transferring them to the screen. (This eliminates flickery graphics.) A buffer can also refer to the normal screen. To use an array as a buffer, you must use this as your address: VARSEG(buffer(0)), VARPTR(buffer(0)). The screen is &HA000, 0. SPRITES A sprite is any 2D image that can be placed on the screen and moved around independently from the background. Many of Dash's subs give a programmer the ability to use sprites in their programs. QuickBASIC's equivalent of the sprite is drawing an array to the screen using PUT. TEXTURE-MAPPING Texture-mapping subs are available in Dash for making skewed sprite images. A texture (sprite) is placed on a polygon and can be reshaped with the polygon. SEGMENTS AND OFFSETS Segments and offsets tell the locations in memory of anything you access. When you see some values of memory like this FFFFh:FFFFh, the value before the colon is the segment, and the value after the colon is the offset. (For more info on the specifics of segments and offsets, refer to VirtuaSoft's newsletter.) For Dash, the first segment and offset group is the source, and the second is the destination - with the exception of the XMS functions. For example, VSSprite's source is the sprite, and the destination is the buffer. You can find the values of the segment and offset using the following code: segment1% = VARSEG(array(0)) offset% = VARPTR(array(0)) QB's LIBRARY Dash also includes QB.LIB, so CALL INTERRUPT and CALL ABSOLUTE can be used. This allows the use of QMIDI, BWSB, or any other library that needs QB.QLB to run. THE SUBS PALETTE Rules for palette subs: 1. Do not use the extension ".PAL" for the files. No extension is needed. 2. For RGB values: 0=least intense; 63=most intense. 3. Palette files are BSAVEd 768-character strings. 4. For fades: 0=none, 63=full. Values <2 do not pause when fading. FADE BLACK/WHITE These fade the screen to black or white. A value must be given to tell how much the fade is. VSFadeBlack shades% VSFadeWhite shades% FADE TO PALETTE/COLOR These fade from the current palette to another palette or a color defined by its RGB values. VSFadeToPalette file$, shades% VSFadeToColor red%, green%, blue%, shades% NEGATIVE This negatives the current palette. VSNegative LOAD/SAVE PALETTE These load a 256-color palette and save the current palette to a file. If the file name is given as "" for VSPalette , it will load a black palette. VSPalette PalFile$ VSSavePalette PalFile$ ROTATE PALETTE These cycle the palette either forward of backward between two given colors. VSRotatePalF FirstColor%, SecondColor% VSRotatePalB FirstColor%, SecondColor% GRAYSCALE This grays the palette. VSGrayScale MEMORY ADDRESSING DEFINE SEGMENT Sets the default segment for VSPoke and VSPeek. The default value is A000h. VSDefSeg segment% WRITE MEMORY These write 16- or 32-bits to a defined place in memory. The segment is defined by VSDefSeg. VSPoke16 offset%, value% VSPoke32 offset%, value& READ MEMORY These read 16- or 32-bits from a defined place in memory. The segment is defined by VSDefSeg. variable% = VSPeek16%(offset%) variable& = VSPeek32&(offset%) TRANSFER MEMORY This transfers a chunk of memory between two locations of RAM. It can be used to copy arrays, etc. The sub truncates to the nearest 4 bytes for speed. VSBlit segment1%, offset1%, segment2%, offset2%, bytes% EXTENDED MEMORY Rules for XM subs: 1. VSDetectXMS MUST be run before any other XM subs. 2. When closing the program, remember to deallocate all handles. 3. Unlike the standard memory subs, these have destination THEN source. 4. A 32-bit flat memory model is used for XMS addressing (offset& instead of seg%:offset%). 5. For conv. mem. (handle=0), the seg%:offset% syntax is done like this: seg%*65536&+offset%. DETECT This sub tells if XMS exists on the computer. (Warning: This sub MUST be run before any other XMS subs!) variable% = VSDetectXMS% 1=XMS present, 0=no XMS ALLOCATE This sub allocates memory and assigns it to a handle for use. variable% = VSAllocateXMS% (BYVAL NumKB%) >0=handle#, 0=failure DEALLOCATE This sub frees the memory that was allocated. variable% = VSDeallocateXMS% (BYVAL handle%) 1=success, 0=failure RESIZE This sub resizes an XM handle. variable% = VSResizeXMS% (BYVAL Handle%, BYVAL NunKB%) 1=success, 0=failure MOVE This sub transfers a memory chunk one of the folowing ways: Conv mem->XM XM->Conv mem Conv mem->Conv mem XM->XM If you're addressing low memory, you give the segment and the offset, and the handle is 0; for XM, you give the handle and the 32-bit offset from the start of the handle. test% = VSMoveXMS% (BYVAL DestAddress&, BYVAL DestHandle%, BYVAL SrcAddress&, BYVAL SrcHandle%, BYVAL NumBytes&) 1=success, 0=failure CHECK FREE This sub tells how much free XM (in KB) there is. variable% = VSFreeXMS% # of XM KB free CHECK TOTAL This sub tells how much XM (in KB) there is. variable% = VSTotalXMS% # of total KB of XM SCREEN SET SCREENS This sets screen 13h (graphics mode) or screen 3 (text mode). VSGraphics VSText SCREEN FILL This fills a buffer with a color. This can be used to either fill the entire screen (segment%=&HA000, offset%=0) or a 64Kb buffer (segment%=VARSEG(buffer(0)), offset=VARPTR(buffer(0))) defined as an array in QB. Filling with the color 0 is the equivalent of QuickBASIC's CLS. VSFill segment%, offset%, color% SCROLL SCREEN These scrolls the screen a defined # of pixels upward, downward, left, or right. (Note: the subs will not fill in what has been scrolled away.) VSScrollU segment%, offset%, y% VSScrollD segment%, offset%, y% VSScrollL segment%, offset%, x% VSScrollR segment%, offset%, x% PCOPY This transfers a 64Kb image between two 64Kb chunks of RAM. This can be used to transfer an image from a buffer to the screen or vice versa. If the flag is set to 0, the copy is solid. The value of 1 will make a transparent copy (ignores color 0). VSPCopy segment1%, offset1%, segment2%, offset2%, flag% DELAY This delays the program in 1/60s increments and puts the graphics in sync with the monitor's vertical retrace. VSDelay delay% PIXEL PLOTTING PSET This places a pixel on the screen. It's the same as QB's PSET except it can draw a pixel to a buffer. VSPset segment%, offset%, x%, y%, color% POINT This gets a pixel's color. It's the same as QB's POINT except it can read a pixel from a buffer. variable%=VSPoint%(segment%, offset%, x%, y%) color# SPRITE Rules for sprites: 1. The sprite coords are for the top-left unless otherwise noted. 2. segment1% and offset1% are for the source. 3. segment2% and offset2% are for the screen. 4. The sprite format is the same as QB's GET/PUT format. TRANSPARENT/TRANSLUCENT This draws a sprite to a buffer, ignoring color 0. The flag value tells if the polygon is translucent (1) or not (0). VSSprite segment1%, offset1%, x%, y%, segment2%, offset2%, flag% SOLID This draws a sprite to a buffer. VSPut segment1%, offset1%, x%, y%, segment2%, offset2% This draws a translucent sprite to a buffer, ignoring color 0. (Note: The translucency will only work with a gradient palette of 32 shades per color.) VSSpriteT segment1%, offset1%, x%, y%, segment2%, offset2% SCALED (TRANSPARENT) This draws a scaled sprite to a buffer, ignoring color 0. The X and Y can be scaled independently with the default value of 64. The scaled-size can range from 0 to 255 (0x size to 4x size). The coordinates are centered in the sprite. VSSpriteS segment1%, offset1%, x%, y%, scaleX%, scaleY%, segment2%, offset2% ROTATED (TRANSPARENT) This draws a sprite to a buffer, ignoring color 0. The sprite can be rotated at any degree angle. The coords are centered in the sprite. (It's recommended that VSCosine and VSSine be used for the angles.) VSSpriteR segment1%, offset1%, x%, y%, 256cos%, 256sin%, segment2%, offset2% SINGLE COLORED (TRANSPARENT) This draws a sprite to a buffer, ignoring color 0, as a given color. VSSpriteC segment1%, offset1%, x%, y%, col%, segment2%, offset2% GET A SPRITE This saves an image to a sprite array. It works basically the same way as QB's GET except that it can also get from SCREEN buffers and off the screen (fills with 0s). VSGet segment1%, offset1%, x1%, y1%, x2%, y2%, segment2%, offset2% TEXTURE-MAPPING Rules for texturing: 1. Coords on poly go clockwise from the top-left. 2. segment1% and offset1% are for the source (the image). 3. segment2% and offset2% are for the screen (the buffer). TRANSPARENT/TRANSLUCENT This draws a sprite to a buffer as a skewed 4-sided polygon. The flag value tells if the polygon is translucent (1) or not (0) VSTexture segment1%, offset1%, x1%, y1%, x2%, y2%, x3%, y3%, x4%, y4%, segment2%, offset2%, flag% POLYGON FILL This draws a color into a buffer as a skewed 4-sided polygon. The coordinates start at the top-left of the sprite and work clockwise. VSFillPoly segment%, offset%, x1%, y1%, x2%, y2%, x3%, y3%, x4%, y4%, color% WALL This draws sprite to a buffer as a skewed 4-sided polygon with vertical sided (Doom style). VSWall segment%, offset%, x1%, y1%, y2%, x2%, y3%, y4%, segment2%, offset2% TRIANGLE This textures a transparent triangle. The coordinates go clockwise from the vertex of the triangle. The pixel vector tells how it will read the pixels: 0=reads from top-left to bottom-right, 1=reads from bottom-right to top-left. (Any other values will be treated as 0.) VSTri segment%, offset%, x1%, y1%, x2%, y2%, x3%, y3%, segment2%, offset2%, pixelVector% SPRITE COLLISION GIVEN COLOR This checks for a collision between a sprite and a given color on the screen. (Note: You use this sub like you are placing a sprite, but this sub does not actually draw it.) variable%=VSCollide2%(segment1%, offset1%, x%, y%, col%, segment2%, offset2%) 1=collision, 0=no collision NON-0 COLOR This checks for a collision between a sprite and a non-0 color on the screen. (Note: You use this sub like you are placing a sprite, but this sub does not actually draw it.) variable%=VSCollide%(segment1%, offset1%, x%, y%, segment2%, offset2%) color# in collision TEXT GRADIENT This prints a message on the screen at given pixel coordinates without destroying the background. You can also add an 8-color horizontal gradient to the text. This gradient is set by defining 2 colors: a top color and a bottom color. VSFont segment%, offset%, x%, y%, text$, TopColor%, BottomColor% SHADOW GRADIENT This prints a message on the screen similar to the way VSFont does but also places an additional layer of text behind the foreground one. A separate 8-color horizontal gradient can be set for the background text. VSShadowFont segment%, offset%, x%, y%, text$, TopColor1%, BottomColor1%, TopColor2%, BottomColor2% LINE LINES This draws a horizontal line on the screen or to a buffer. VSXLine segment%, offset%, x1%, x2%, y%, color% This draws a vertical line on the screen or to a buffer. VSYLine segment%, offset%, x%, y1%, y2%, color% This draws a line like QB's LINE statement. VSLine segment%, offset%, x%, y1%, x2%, y2%, color% BOX This draws a filled box on the screen or to a buffer. VSBox segment%, offset%, x1%, y1%, x2%, y2%, color% FILE Rules for file subs: 1. A fixed-length string must contain the file name (len>=#chars+1). 2. The graphics subs don't clip, so be careful where you load data. LOAD DATA This grabs a given number of bytes from a file and places the data in a section of memory. variable% = VSLoad%(FileNameSegment%, FileNameOffset%, segment%, offset%, nBytes&) 1=bad file name, 0=no error PUT FROM FILE This draws a solid sprite directly to a buffer from a file, saving the memory that would have otherwise been used for the sprite's array. variable% = VSLoadPut%(FileNameSegment%, FileNameOffset%, x%, y%, segment%, offset%) 1=bad file name, 0=no error DIRECTORY LISTING This lists all the files in a directory that match a given input string (wildcards are accepted). Two subs must be called to get this to work. VSFileMatchInit finds the first match in the directory, and VSFileMatch finds all the following matches. This array has to be defined in QB to store the name of the file returned on each match: TYPE dta Res AS STRING * 21 Attr AS STRING * 1 Filetime AS INTEGER Filedata AS INTEGER Filesize AS LONG Filename AS STRING * 13 Res2 AS STRING * 85 END TYPE DIM MatchedName AS dta variable% = VSFileMatchInit%(DTASegment%, DTAOffset%, FileNameSegment%, FileNameOffset%) variable% = VSFileMatch% 1=bad file name, 0=no error MISC MENU BORDER This draws a border that can be used for a menu. segment% and offset% follow the rules described in "Fill". x1% and y1% are the coordinates for the top-left of the menu. x2% and y2% are the coordinates for the bottom-right of the menu. col1% it the light-color; col2% is the medium-color; and col3% is the shadow-color. VSBorder segment%, offset%, x1%, y1%, x2%, y2%, color1%, color2%, color3% PARALLAX STARS This draws a set of 101 pixels on the screen. It was originally intended to be a sub to draw a layer of stars for the parallax background of Space-a-roo 2, but it can be used for other purposes as well. For this sub to work, a two dimensional INTEGER array (100, 1) must be declared. This will be the array from which the star coordinates are read. (0-100, 0) is the X; (0-100, 1) is the Y. VSParaStar segment1%, offset1%, x%, y%, color%, segment2%, offset2% CLEAR KB BUFFER This clears the keyboard buffer. VSClearKB MATH POLYGON VISIBILITY This uses the vector cross-product to test if a polygon is facing toward the screen. If the polygon is facing the screen, a 1 is returned, meaning the polygon is visible. If a 0 is returned, it means the polygon is facing away from the screen and is invisible. variable% = VSVisible% (x1%, y1%, x2%, y2%, x3%, y3%) 1=polygon is visible. 0=polygon is hidden TRIG FUNCTIONS These return values of trig functions based on a degree angle that is passed to the functions. All values returned are integers 256x the actual trig value. Be sure the angles passed fit the interval [0, 359]. If you are not sure what the angles are, used angle% MOD 360 to bring the angle into the interval. variable% = VSCosine% (DegreeAngle%)) Cosine value * 256 variable% = VSSine% (DegreeAngle%)) Sine value * 256 MOUSE MOUSE DRIVER Tells if the mouse driver is present. variable% = MouseDriver% -1=mouse driver is present. 0=no mouse driver MOUSE ON/OFF These Show and hide the mouse cursor. MouseOn MouseOff MOUSE INFO These return mouse cursor positions: variable%=MouseX% mouse x variable%=MouseY% mouse y These return the mouse button status. variable%=MouseL% 0=no button press, 1=button was pressed. variable%=MouseR% 0=no button press, 1=button was pressed. SET X AND Y This sets x and y mouse cursor positions. MouseSetXY x%, y% SET BOUNDS Sets maximum and minimum mouse cursor positions. The default range for the x-coords is 0-632; the default for y is 0-192. MouseSetBounds x1%, y1%, x2%, y2% BOX TESTS Checks for a left click inside a box. variable% = MouseClickInBox% (x1%, y1%, x2%, y2%) 1=passed test, 0=didn't pass test Checks for a left click outside a box. variable% = MouseClickOutBox% (x1%, y1%, x2%, y2%) 1=passed test, 0=didn't pass test Checks for the mouse cursor inside a box. variable% = MouseOverBox% (x1%, y1%, x2%, y2%) 1=passed test, 0=didn't pass test GAMEPAD BUTTON PRESS Returns is a certain button is pressed. variable% = JoyButton% (buttonNumber%) 1=button is pressed. 0=button is not pressed. STICK/ROCKER PRESS These return the time it took for the capacitor sensors to flood. It can be used to test for a change in the X or Y. (Note: this will not directly work to tell the state of the X and Y axis. Some calibration may need to be done to test how long it takes for the capacitor to flood at the default location.) variable%=JoyStickX% time to flood capacitor variable%=JoyStickY% time to flood capacitor CREDITS Dash programming: Danny Gump Documentation: Danny Gump SPECIAL THANKS "BloodKnight" - He helped me link Dash with QB's library to allow CALL ABSOLUTE and CALL INTERRUPT work in Dash. "LordQBASIC" - He helped me learn to read from the arrays linearly in the sprite routines. He also helped me update Dash to use TASM instead of A86 for 32-bit instructions. "Tek" - He helped revive Dash when it temporarily "died" by sending me an old copy of it to merge with the corrupt one. "Gradius" - He encouraged me through-out the production of Dash, and made several optimistic suggestions. "xpl" - He supplied me with a rotation program in QB that I converted to ASM for VSSpriteR. "Neander" - He helped me correct an error in VSSpriteR that allowed me to release it. Eric Schneider - He gave me several ideas for new Dash subs. Dave Perry - He has encouraged me through the entire production and has suggested several subs. Quinton Roberts - He helped me figure out how to make the directory listing subs. Thanks for using Dash!