----------------------------------------------------------------------------- ÛÛÛÛÛ¿ ÛÛÛÛÛÛ¿ ÛÛÛÛÛÛ¿ ÛÛÚÄÄÛ¿ ÛÛÛ¿ÛÛÛÛÛÛ¿ ÛÛÛÛÛÛÛÛ¿ ÛÛÛÛÛÛ¿ ÛÛÛÛÛÛÛÛ¿ÛÚÄÄÄÄÄÛ¿ ÛÚÄÄÄÄÛ¿ ÛÛ³ Û¿ ÛÚÙ ÛÚÄÄÄÛ¿ ÛÛÚÄÄÄÄÙ ÛÛÚÄÄÄÄÛ¿ÀÄÄÛÛÚÄÄÙÛ³ Û³ ÛÜÜÜÜÜÛ³ ÛÛ³ Û¿ Û³ ÛÜÜÜÛÚÙ ÛÛÛÛ¿ ÛÛÚÙ ÀÙ ÛÛ³ Û³ Û¿Û³ ÛÚÄÄÄÄÄÛ¿ ÛÛ³ Û³ Û³ ÛÚÄÄÄÛ¿ ÛÛÚÄÙ ÛÛ³ Û¿ ÛÛ³ Û³ ÛÚÙ Û³ Û³ ÛÛÛÛÛÛÛÚÙÛÛÛ¿ÛÛÛ¿ ÛÛÛ¿ÛÛÛÛÛÛÛÛ¿ ÛÛÛÛÛÛÛÚÙ ÛÛ³ ÛÛÛÛÛÚÛÛ¿ÛÛÛÛÛÛÛÚÙ ÀÄÄÄÄÄÄÙ ÀÄÄÙÀÄÄÙ ÀÄÄÙÀÄÄÄÄÄÄÄÙ ÀÄÄÄÄÄÄÙ ÀÄÙ ÀÄÄÄÄÙÀÄÙÀÄÄÄÄÄÄÙ version 1.5 þ 25/3/1999 DirectQB: a Game Programming Library for QuickBasic 4.5 (but it could be easily adapted to your own programming language!) by Angelo Mottola - Enhanced Creations 1998-99 ----------------------------------------------------------------------------- A few words of intro to DirectQB 1.5 Finally a new DQB release!!! Many of you out there were waiting for an update, so here we are. And what an update! Version 1.5 was ready since February, the 15th, but a serie of events forced me to postpone the release date... Meanwhile I continued adding new features to DQB, and believe me, there are a lot of differences from the version that was ready in February; the last great addition (huff! That was a hard task, and I'm really proud of it!) is a FLI player: now you can add full-screen professional-like animated cut-scenes to your games!! I'M ALSO LOOKING FOR SOMEONE INTERESTED IN CREATING AN ANIMATED LOGO FOR DIRECTQB ITSELF: IF YOU THINK YOU'RE GOOD ENOUGH WITH 3D STUDIO (OR ANY RENDERING PROGRAM THAT CREATES FLIs), CONTACT ME! What's new in version 1.5 Now, as always, here's a brief description on the new library features: - The sound engine has been almost entirely rewritten; now it allows to play sounds at different frequencies on each voice, by resampling the sound data - Volume table is now built in memory at runtime: this means smaller LIB/QLB files, but also that you have to call SETMEM to free 16K of base memory before DQBinstallSB, otherwise you may get an out of memory error. Also, volume now ranges 0-63 to be completely MOD compatible - DQBsetSamplingRate has been removed: now sampling rate is set when calling DQBinstallSB - DQBloadSound bug should have been fixed: I've tried with a lot of WAVs, and it loads them all. I've tried to load those unreadable under DMAplay6 and it also refused to load them, so I suppose they're not saved in the standard PCM WAV file format - You don't need to clear your EMS layers at startup anymore, as DQBinit clears them for you - DQBclose now also automatically switches to text mode - Added DQBscrollArea, that allows to scroll a specified area of any layer into any direction - Two new put routines: DQBhPut draws a whole sprite with the same specified color, so that you can achieve special effects like when an enemy is hit, and DQBtPut lets you apply bitwise operations between your sprite and the background - DQBfindPalCol allows to search for a specified color into any palette, it's faster than normal DQBfindCol, and it does not produce that bad looking flickering side effect - Internal high precision timer now allows to synchronize your graphics with a specified framerate - DQBangle returns the angle between two given points, in the range 0-255 - Sprites collision detection functions, with selectable method between bounding box (fast) and pixel perfect (accurate) - DQBscroll old bug with high negative dy values is finally fixed, and DQBline has been speeded up a little (thanks for the hints Terminator_Z!) - Support for blended and textured text, more font functions, to load and set a font file without requiring any intermediate buffer, to set the characters spacing and to automatically center text on the screen - Removed DQBsetTransText and DQBsetSolidText; they were obsolete since DQBsetTextStyle was added - FLI animations player - DQBerror$ returns a short message explaining the last error occured (if any) You can take a look at the new appendix G of this manual for details - All the 3D functions have been accelerated - DQBid$ now returns a small string containing the library version and my name in case you want to show them somewhere in your credits section (so you don't have to worry about how my name is spelled, and I'll never see again things like "DirectQBasic by Angelo Motella" or similar; my name is Angelo Mottola and this library is DirectQB!! =) ) - DQBsort (did you even know that it was a DQB function?) is now something useful: instead of the useless integer sorting, now it allows you to sort entire array of records, and it's really more versatile; check it out! - Added a "test font" feature to DQBtools: now you can see how your font looks like in normal, bold, italic and underlined styles, without having to quit the editor... - New DirectQB Library Manager utility, that allows you to create and customize your copy of DirectQB in an easy way. List of new functions and modified ones: DQBinit, DQBclose, DQBinstallSB, DQBloadSound, DQBplaySound, DQBsetVoiceVol, DQBremoveSB, DQBscroll, DQBscrollArea, DQBsetFrameRate, DQBwaitFrame, DQBhPut, DQBtPut, DQBline, DQBcollide, DQBsetCollideMethod, DQBprint, DQBloadFont, DQBlen, DQBsetTextSpacing, DQBerror$, DQBfindCol, DQBfindPalCol, DQBangle, DQBremoveBMap, DQBwaitKey, DQBplayFLI, DQBopenFLI, DQBplayFLIstep, DQBcloseFLI, DQBid$, DQBsetFontTexture, DQBsort Check out part 2 of this manual for details on each function. Also, as the library still has limitations, be sure to check out section 1.7. Of course DirectQB is still under development, so expect new versions in the future. My actual goals are: þ Free EMS for the user to store any kind of data Many people are still claiming for this, and I know I could add it at any time, but the main problem is that I want a serie of routines that allows to work with EMS pages in a transparent way, so that the user would just have to specify an absolute address, and DQB does the appropriate page swithing to accomplish whatever task the user wants to do (memory move, copy to/from a buffer in conventional memory) þ Matrix-based 3D calculation algorithms To handle 3d transformations, projection, and all the complex mathematical stuff that's behind 3d graphics handling. These routines will use the FPU (QB never uses the FPU, also when you're handling real numbers!) And what about the music you ask?!? Well, currently the FM handling module is under development by Masamune_q (people on my wwwboard should know him!), as I really have a little free time, and any help is always welcomed... About MIDI, it's almost impossible for me to do it at the moment: it would require too much time, as I still don't have the needed knowledge. A solution would be to add internal SBMIDI support (as QMIDI does) to DQB, as it's a very quick and easy way to solve the problem... What do you think? If you want to develop your own DQB module, let me know! There are just some things you must keep in mind to make it DQB-compatible, so if you're an intermediate-advanced assembly programmer and you want to contribute DQB with your own routines, just ask me. ============================================================================= TABLE OF CONTENTS 1 Introduction to DirectQB 1.1 Legal stuff 1.2 What is DirectQB 1.3 System requirements 1.4 Features 1.5 Installing the library 1.6 Basic concepts 1.7 Limits of the library 2 Functions reference DQBangle FUNCTION DQBasc FUNCTION DQBbgtri SUB DQBbox SUB DQBboxf SUB DQBbPut SUB DQBbtri SUB DQBbttri SUB DQBclearLayer SUB DQBclose SUB DQBcloseFLI SUB DQBcollide FUNCTION DQBcopyLayer SUB DQBcopyTransLayer SUB DQBcreateBMap FUNCTION DQBdir$ FUNCTION DQBdrive$ FUNCTION DQBellipse SUB DQBemsSeg FUNCTION DQBerror$ FUNCTION DQBfadeIn SUB DQBfadeStepIn SUB DQBfadeStepTo SUB DQBfadeTo SUB DQBfilterBox SUB DQBfindCol FUNCTION DQBfindPalCol FUNCTION DQBfPut SUB DQBget SUB DQBgetBMap FUNCTION DQBgetCol SUB DQBgetPal SUB DQBgtri SUB DQBhPut SUB DQBid$ FUNCTION DQBinit FUNCTION DQBinitText SUB DQBinitVGA SUB DQBinkey$ FUNCTION DQBinstallKeyboard SUB DQBinstallSB FUNCTION DQBinUse FUNCTION DQBjoyDetected FUNCTION DQBjoyFire FUNCTION DQBjoyMove FUNCTION DQBjoyX FUNCTION DQBjoyY FUNCTION DQBkey FUNCTION DQBlen FUNCTION DQBline SUB DQBloadBMap FUNCTION DQBloadFont FUNCTION DQBloadLayer FUNCTION DQBloadRawSound FUNCTION DQBloadSound FUNCTION DQBmouseDetected FUNCTION DQBmouseHide SUB DQBmouseLB FUNCTION DQBmouseRB FUNCTION DQBmouseShow SUB DQBmouseX FUNCTION DQBmouseY FUNCTION DQBmPut SUB DQBnumDrives FUNCTION DQBopenFLI FUNCTION DQBpaint SUB DQBpalOff SUB DQBpath$ FUNCTION DQBpauseSound SUB DQBplayFLI FUNCTION DQBplayFLIstep SUB DQBplaySound SUB DQBpoint FUNCTION DQBpollJoy SUB DQBprint SUB DQBprints SUB DQBpset SUB DQBput SUB DQBputOver SUB DQBreadBit FUNCTION DQBreadKey FUNCTION DQBremoveBMap SUB DQBremoveKeyboard SUB DQBremoveSB SUB DQBresetBit FUNCTION DQBresetJoy SUB DQBresetMouse SUB DQBresumeSound SUB DQBrPut SUB DQBsaveBMap FUNCTION DQBsaveLayer FUNCTION DQBscroll SUB DQBscrollArea SUB DQBsetBaseLayer FUNCTION DQBsetBIOSfont SUB DQBsetBit FUNCTION DQBsetBMap SUB DQBsetClipBox SUB DQBsetCol SUB DQBsetCollideMethod SUB DQBsetDrive SUB DQBsetFont SUB DQBsetFontTexture SUB DQBsetFrameRate SUB DQBsetMousePos SUB DQBsetMouseRange SUB DQBsetMouseShape SUB DQBsetMouseSpeed SUB DQBsetPal SUB DQBsetSolidPut SUB DQBsetTextBackCol SUB DQBsetTextSpacing SUB DQBsetTextStyle SUB DQBsetTextureSize SUB DQBsetTransPut SUB DQBsetVoiceVol SUB DQBsetVolume SUB DQBshiftLeft FUNCTION DQBshiftRight FUNCTION DQBsize FUNCTION DQBsort SUB DQBsPut SUB DQBstopVoice SUB DQBtoggleBit FUNCTION DQBtPut SUB DQBtri SUB DQBttri SUB DQBver FUNCTION DQBwait SUB DQBwaitFrame SUB DQBwaitKey SUB DQBxPut SUB APPENDIX A Library constants APPENDIX B Keyboard scancodes list APPENDIX C Palette, cursor, font and blender map data format APPENDIX D Known bugs APPENDIX E Versions history APPENDIX F Inside library modules APPENDIX G Error messages Credits and final words ----------------------------------------------------------------------------- ============================================================================= 1. INTRODUCTION TO DIRECTQB ============================================================================= ----------------------------------------------------------------------------- 1.1 - Legal stuff ----------------------------------------------------------------------------- THIS SOFTWARE FOLLOWS THE RULES OF THE FREEWARE CONCEPT: YOU CAN SHARE IT WITH YOUR FRIENDS, AND YOU'RE ENCOURAGED IN DOING SO, BUT THE AUTHOR IS ANYWAY NOT LIABLE FOR ANY DAMAGES CAUSED BY THE USE OF THIS LIBRARY. IT IS NOT COPYRIGHTED, BUT IF YOU WANT TO MODIFY IT, PLEASE TELL ME FIRST. IF YOU USE THE DIRECTQB ROUTINES, PLEASE GIVE ME SOME CREDITS IN YOUR PROGRAM. ----------------------------------------------------------------------------- 1.2 - What is DirectQB ----------------------------------------------------------------------------- DirectQB is a game programming library entirely written in assembly 386 for QuickBasic 4.5. It has been mainly coded to fill the void into the weak graphics, input and sound capabilities of QB; it works in screen mode 13h (320x200 with 256 colors - the common SCREEN 13 for QB), supports keyboard, mouse and joysticks as input devices, and has a built-in sound engine that works with almost any SB. It has really lots of features, as you'll discover reading this manual... ----------------------------------------------------------------------------- 1.3 - System requirements ----------------------------------------------------------------------------- First of all you'll need a copy of QuickBasic 4.5. DirectQB is a quicklibrary, and therefore is made to run only under this programming environment. As DirectQB has been entirely coded in assembly using several advanced 386 instructions, a 386 or better CPU is required. EMS is also needed in order to have off-screen buffers, the so named "layers", as we'll see later. For every layer you need 64 KB of free base or EMS memory; if you don't know what is EMS, or you've problems with it, try adding these lines at the beginning of your CONFIG.SYS file: DEVICE=C:\WINDOWS\HIMEM.SYS DEVICE=C:\WINDOWS\EMM386.EXE RAM Where must be a number specifying the amount of EMS memory in KB to make available under DOS. Here I also suppose you have Windows 95 under the C:\WINDOWS directory. So to have 4 MB of free EMS memory, you should add: DEVICE=C:\WINDOWS\EMM386.EXE 4000 RAM That's all. After adding those lines, reboot your system, and EMS will be available, and ready to be used by the library. To work with the sound engine, you'll need at least a SoundBlaster 2.0 compatible sound card; DirectQB uses autoinit mode for DMA transfers, so a DSP version 2.00 (contained in the SB 2.0) or better is required. If you use DQBinstallSB with autodetection mode, you must have set the BLASTER environmental variable. Add the following line to your AUTOEXEC.BAT file: SET BLASTER = Aaaa Ii Dd Where "aaa" is the exadecimal base address of your sound card (commonly 220), "i" is the IRQ number and "d" is the DMA channel to be used. A common setting would be like this: SET BLASTER = A220 I7 D1 which sets the base address as 220h, IRQ 7 and DMA channel 1. DirectQB supports any range of base address, IRQ 2, 3, 5 and 7, and DMA channels 0 to 3. There are other settings for the BLASTER variable, such as H and T, but I'll not explain them here, as they're not required for our purposes. The sound engine also requires 16K of extra CONVENTIONAL memory, as it builds an internal volume table at runtime. It is expected that you run into an out of memory error if you call the few DQB functions that require extra base memory without calling the SETMEM function first. See the QB online help and the examples on this manual for details on how to use it. To create a blender map to use with the blending graphical functions, you'll also need other additional 64K of free conventional memory. The blender map is automatically stored in base memory to speed things up; the allocation and deallocation of it is hidden to the user, who must just be sure to have enough free available memory. Well, as by now there are no more requirements to run DirectQB. ----------------------------------------------------------------------------- 1.4 - Features ----------------------------------------------------------------------------- DirectQB version 1.5 has the following features: Graphical features: - Supports 320x200 with 256 colors video mode, with almost unlimited number of off-screen buffers stored into EMS memory or into conventional memory. EMS is automatically handled for you by the library - All the functions act on the screen as well as on the off-screen buffers - Several drawing primitives, including pset, line, ellipse, box and full box - Fast sprite handling functions, compatible with standard GET and PUT, also with support for sprite flipping, scaling, roto-zooming and translucency, and direct sprite drawing from EMS without requiring any external QB array - Sprites collision detection with selectable method (bounding box or pixel perfect) - Color blending routines to handle a customizable blender map, allowing to create any color combination - Clipping for almost all the graphical functions - Loads and saves 320x200 images in BSAVE, BMP and PCX format - Plays FLI animation files - Font routines with customizable font set, non-fixed sized fonts support and custom styles, such as bold, italic, underlined, or a combination of them, also with support for color blending and textured text - Smooth palette handling with routines to fade the current palette into any new one as well as into any specified color - Multidirectional scrolling for an entire layer or only a portion of it - Transparent screen copy for parallax scrolling effects - Fast triangle drawing primitives allowing flat-shading, gouraud-shading and textures, all with support for color blending Input features: - Custom keyboard interrupt handler that allows to know the state (pressed or released) of any key at any time - Several keyboard handling functions working under this IRQ handler, to read a key, to get the ascii code from its scancode, and more - Fast and easy to use joystick routines, with auto detection and auto calibration, with support for 1 or 2 2-button joysticks or 1 4-button joypad - Mouse handler: the mouse variables (coordinates and buttons status) are automatically updated when you move the mouse, allowing you to know the actual mouse state at any time without calling other routines - Mouse routines to change the cursor shape, mouse range, speed and position Sound features: - IRQ driven sound engine for fast and easy sounds playback via DMA transfers - Loads and plays sound effects directly from EMS - Supports only 8-bit mono WAV files up to 22000 Hz - Customizable number of channels, from 1 up to 32, for up to 32 sound effects simultaneously playing - Realtime sound resampling - Customizable volume setting for each of the voices - Customizable master volume setting Misc features: - Bit handling routines, including read/set/reset/toggle bit, shift left and right - Routines to find the color in any specified palette that best fits with the specified red, green and blue hues - Useful routine to find the angle between any two given points - Directory scanning routines - Fast multi-purpose records array sorting routine - Internal high precision timer for framerate synchronization - Error messaging system ----------------------------------------------------------------------------- 1.5 - Installing the library ----------------------------------------------------------------------------- The DirectQB library is now shipped as a set of OBJ files, together with their own assembly source codes. You should have these files into the library directory: MAIN.OBJ - Holds main library functions and common variables DRAW.OBJ - Primitive drawing functions IMAGE.OBJ - Bsave/BMP/PCX image files handling SPRITE.OBJ - Special sprites drawing routines BIT.OBJ - Bit handling routines PALETTE.OBJ - Palette handling routines FONT.OBJ - Font functions DISK.OBJ - Disk and directory handling functions BLENDING.OBJ - Color blending support module KEYBOARD.OBJ - Custom keyboard handler routines JOYSTICK.OBJ - Joystick/joypad support module MOUSE.OBJ - Mouse handling routines SOUND.OBJ - Sound engine module 3D.OBJ - Triangle drawing functions All these files together make the DirectQB library; we'll examine later how to work with them. Additional files you must have in your DQB directory, other than the ASM source files, are: ERRORS.INC - Include file used by MAIN.ASM; contains error messages README.1ST - Welcome message FILELIST.TXT - Complete list of all the files in the DirectQB package DIRECTQB.DOC - Library manual (this file) DQBMAN.BAS - DirectQB Library Manager utility DQBMAN.MHL - Datafile for the library manager DQBTOOLS.BAS - Fonts and mouse cursors editor SMALL.FNT - Small font created with DQB Tools HITECH.FNT - Another font created with DQB Tools SCRIPT.FNT - Script font created with DQB Tools So, what's up now? You need to create the LIB and QLB files to work with DirectQB under QB 4.5... For this purpose, there's the DirectQB Library Manager utility, which will guide you into this process. Run that program now! Once built, to load the quicklibrary run QB at the DOS prompt by typing: QB/LDQB The IDE will appear, and you'll be able to use the DirectQB functions. DirectQB is made of several OBJ files, and this means you can link some of them to create your own quicklibrary, depending on your needs. For example, if you're not planning to use the sound engine, there's no need to include the SOUND.OBJ file in the library... The library manager utility allows you to select each of these DirectQB modules, and creates the following files depending on your selections: DQB.LIB - Quicklibrary file to be linked to your executable programs DQB.QLB - Quicklibrary file to be used from inside the QB IDE DIRECTQB.BI - Include file for the DirectQB library and INSTALL.DAT - Data on installed modules for library manager INSTALL.LOG - Installation log file CALLS.BAS - Used during the library building process, it can be deleted For a list of the functions contained within each of the OBJ modules, take a look at appendix F of this manual. ----------------------------------------------------------------------------- 1.6 - Basic concepts ----------------------------------------------------------------------------- The DirectQB library makes an extensive use of the EMS memory to store off- screen buffers, named "layers", plus sounds. A layers is basically a buffer where you act as you do with the screen. You can draw pixels on it, as well as using all the graphical functions of this library. The EMS memory is automatically handled for you, so all you have to do when calling every graphical function is to specify a layer where to act. To draw something directly to the screen, just use layer number 0 (there's also a constant named VIDEO, as specified into APPENDIX A). You can specify the number of layers to allocate in EMS by calling the DQBinit function, as well as the number of sounds to allocate space for (again in EMS); DQBinit must be ALWAYS called before calling any other function of this library, or you'll probably crash your system. Remember also to call DQBclose just before ending your programs; this will free previously allocated memory and it'll turn off the custom keyboard handler and the sound engine if they were on (plus doing other tasks) You can also avoid using EMS, by declaring up to 10 extra layers stored in conventional memory. To setup these "base layers" refer to the DQBsetBaseLayer function. Other than this, you should also keep in mind the following things: þ To speed things up, a lot of checks are skipped, so for example if you initialize the library with 3 extra layers, DO NOT refer to layer -1 or 4! þ When referring to base layers, be sure you've previously set up them, because by drawing something onto a layer that has not be configured with the DQBsetBaseLayer function, you're probably going to crash your system. þ Every graphical function that draws something, except DQBbox, DQBboxf, DQBfPut and DQBfilterBox supports clipping; this means that every pixel that lies outside the current clipping box will not be drawn. Clipping box is set at startup (when calling DQBinit) to (0,0)-(319,199), and it can be changed at any time by calling the DQBsetClipBox function. þ The sprite data format for DQBget, DQBput, DQBfPut, DQBsPut, DQBrPut and DQBbPut is the same used by the standard GET and PUT statement; the advantage of using DirectQB functions is that they act on layers, they support clipping (except DQBfPut) and they're faster than GET and PUT... þ DQBxPut has the great advantage that it does not require you to store the sprites into an array and then to use this to draw it; this means you save extra memory for your application, but the bad thing is that DQBxPut is slower than normal DQBput, and it can handle only sprites with an height up to 50 pixels. þ The transparent color is color number 0 and cannot be changed. þ When calling a function that requires a box by passing the upper-left (x1,y1) and lower-right (x2,y2) corners, always remember that it must be x1