Bells, Whistles, and Sound Boards TUTORIAL DOCUMENTATION This is BWSB v1.02 for QuickBASIC, PDS, and Turbo Pascal Copyright (c) 1993-94, Edward Schlunder All Rights Reserved This project was started on 07-14-93 and now completed on 12-24-94. Contents: 1. Introduction 1.1 Packing List 1.2 Hardware Requirements 1.3 Feature List 1.4 License Agreement/Disclaimer 1.5 Credits 2. Brief Tutorial 2.1 File Types Used 2.2 Getting Music Going 2.3 Adding Sound Effects 2.4 Things to Keep in Mind 3. Turbo Pascal Differences/Notes 4. Miscellaneous 4.1 Need Music? Read Here! 4.2 Technical Support/Contact Information 4.3 Distribution List 4.4 Closing Words Chapter 1. Introduction 컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴 BWSB is a digital sound and music programming library for use in games, demos, intros, etc. All music and sound effects are played in the background, allowing your program to do anything it likes while the sound and music is playing. BWSB uses a seamless interface to support different sound devices through the use of runtime loadable music & sound engines (more on this coming up), so adding support for many different sound cards in your programs is no problem at all (just a simple recompile and tada!). 1.1 Packing List Documentation: BWSB.DOC This document. Tutorial. BWSB.REV BWSB revision document. Learn about previous releases and other useless nonsense. BWSB-REF.DOC Function reference. Documents all functions TTP.TXT Tailgunner Target Practice documentation. WHY-REG.TXT Read this! It tells about all the wonderful reasons to register BWSB. REGISTER.FRM Registration form. You'll need to print this file out to purchase the registered version of BWSB. LICENSE.DOC License agreement for the registered version. G-> See section 1.4 for the license agreement when using the unregistered evaluation copy of BWSB. Example Programs: SETUP.EXE Program to setup some of the example programs for your sound card and configuration. [PDS ONLY] MMP.EXE Simple example module player. [Basic] SND-PAD.EXE Instrument player for demonstrating the PlaySample routine. [Basic] GDMPLAY.EXE Example module player. [Pascal] GDMSCOPE.EXE Nifty module player that displays a digital scope in tune with the music! [Pascal] TTP.EXE Tailgunner Target Practice example game [Pascal] Utilities: OL.EXE OverLoader - a program to tack files onto the end of your EXE files for demos, games, etc so that you don't have lots of different data files 2GDM.EXE Converts many different module formats to the GDM format, which is the only format BWSB currently G-> loads directly. See section 2.1.1 Example Music: TTP.GDM 'Tek Gets Off' - 4 channel digital music by Tek/OTM. This was originally composed in S3M format. CONTROL.GDM 'Soul Control' - 6 channel digital music by Stalker/OTM. This was also composed in S3M format originally. Include Files: BWSB.BI Declarations of BWSB routines. GDMTYPE.BI GDM file structure type definitions for Basic. CHANTYPE.BI Type definitions for the GetChannelTable routine. Libraries/Units: MSE_QB.LIB Library for QuickBASIC 4.5 to make EXEs MSE_QB.QLB QuickLibrary for QuickBASIC 4.5 to use BWSB in the QB environment. MSE_PDS.LIB Library for PDS 7.1 to make EXEs MSE_PDS.QLB QuickLibrary for PDS 7.1 to use BWSB in the QBX environment. MSE_TP.PAS Turbo Pascal unit source code. Make sure you compile this to create the MSE_TP.TPU unit so that you can use BWSB's routines. There are quite a few addition files, but they are fairly self explanatory. 1.2 Hardware Requirements BWSB requires a 386SX or better CPU. This is due to the intense popularity of 386 and 486 machines today. XTs and 286s are quickly going out of style, and programming something this complex for a 286 would make development take much longer. If there is sufficient demand for a 286/8086 version of BWSB, it might be possible as a separate (and less powerful) package later on. Naturally, a sound card is required. BWSB currently only supports the Sound Blaster family of sound cards, the Gravis Ultrasound, and the Pro AudioSpectrum or 100% compatibles. Some of the included example programs require a VGA card for display of oscilloscopes, animations, etc. However, no part of the sound library requires any type of video card, and therefore your programs do not have to require a VGA or better. 1.3 Feature List o Seamless support for different sound devices. No code needs changing to support different sound devices, output on each device acts (almost) exactly the same as it would on another, from your application's point of view. BWSB takes care of hiding any differences from you. o Support for several sound devices. Sound devices currently supported are: Gravis Ultrasound (Stereo up to 41KHz) Sound Blaster 1.xx (Mono up to 21KHz) Sound Blaster 2.xx (Mono up to 43KHz) Sound Blaster Pro (Stereo up to 22KHz) Sound Blaster 16 (Stereo up to 45KHz) Pro AudioSpectrum (Stereo up to 45KHz) Any sound card 100% compatible with one or more of the above. More sound devices will be added later. They will work with your programs with only a simple recompilation. o Conversion of many module formats to GDM. With the included utility (2GDM) you can convert your modules to GDM format, which are loaded very quickly because it is almost identical to how modules are stored in memory with BWSB. The following can be converted: MOD WOW OCT S3M MTM 669 FAR MED STM ULT o All sample data can be kept in EMS (expanded memory) if available. This frees up base memory for your program. Note: On the Gravis Ultrasound, all sample data is kept in DRAM on the card at all times. No base or EMS memory is used for sample data. o Ability to play music and sound effects together at the same time. For instance, you could have some digital music going on in your game, then have gun shots and explosion sound effects playing too, all at the same time, without stopping anything! * In the unregistered version of BWSB, sound effects can not be played at all for demonstration purposes. o Support of up to 32 digital sound channels. This means that you can play up to 32 digital sounds at one time (provided that your computer is fast enough for this). * In the unregistered version of BWSB, 6 channels are the limit for demonstration purposes. Note, due to the nature of the GUS's hardware, this limit is actually 14 when playing on a GUS. o IRQ 0 Free. Everything plays in the background without reprogramming the timer chip (which is slightly incompatible with multitaskers, etc). This lets you use IRQ 0 for more important things, such as video retrace timing for fast page flipping or snowless palette switching on VGAs. o All major Protracker effects are implemented. Effects left out are Set Filter On/Off and Glissando, both of which do not get used very often. In fact, we found no modules using Glissando, so this wasn't implemented. o Most major Scream Tracker 3.01 effects are implemented. This includes such effects as Retrigger+Volume Slide and Set Global Volume which many module players do not support. o Many more brainless things forgotten here. 1.4 License Agreement/Disclaimer This license agreement pertains to the SHAREWARE/UNREGISTERED evaluation version of BWSB. To see your rights as a registered user, consult the file LICENSE.TXT (Standard and Advanced only, LICENSE.TXT does not cover Commercial registration). Use of the unregistered shareware version of BWSB is subject to a 30 day trial period. If, after the 30 days are over, you want to continue using BWSB in your programs, you must register it with the authors by paying a nominal fee (please read the file WHY-REG.TXT). This evaluation version may *not* be used for programs that are released to the public. It is for your own evaluation only, and if you wish to release a program created with BWSB, you *must* register first. The included source code may be edited any way you wish, except that original copyright notices must remain in the code unaltered. You are prohibited from reverse engineering, decompiling, or disassembling any part of BWSB. BWSB is provided as is and the author disclaims all other warranties, either expressed or implied, including but not limited to implied warranties of merchantability and fitness for a particular purpose. In no event shall the author be liable for any damages whatsoever (including, without limitation, damages for loss of business profits, business interruption, loss of business data, or any other pecuniary loss) arising out of the use of or inability to use this product, even if the author has been advised of the possibility of such damages. Some states/jurisdictions do not allow the exclusion or limitation of liability for consequential or incidental damages. We can not sell to people from such perverse places. You may distribute copies of this unregistered shareware version of BWSB to BBSes, FTP sites, CDs, etc provided that nothing is changed, deleted, or added in the archive. You may *not* distributed the registered versions of BWSB. 1.5 Credits Edward Schlunder - Project head. All major coding zilym@hndymn.stat.com and some of the documentation. Alex Chaflin - All Turbo Pascal support and lots of achalfin@uceng.uc.edu documentation. Zach Mortensen - Working on Watcom C 32 bit support. This will be added to a future version of BWSB. Ryan Petrie - Misc original coding. Wrote some of the first mixer prototypes and output routines. Ariel Gross and - Composed the example music files Taylor Pakula included here and provided us with many more to test BWSB with. Many other people helped out greatly with the development of BWSB. There are so many it would be very hard to list them all here. Chapter 2. Brief Tutorial 컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴 This chapter is for those of you just starting out with BWSB or any other digital interface kit. It gives you the basic idea of how to make a simple S3M or raw sample play using BWSB. If you've already used BWSB before, or have used another similar interface kit, you can probably skip this chapter and just look at the example source code and the function reference for further information. 2.1 File Types Used Digital music is made up of two distinct parts: samples (instruments) and pattern data (music notation). Patterns tell which samples to play at what time and frequency. Samples are small digital recordings of real instruments. This system of music reproduction can be very realistic yet not require massive amounts of disk space for a full digital recording of an entire musical piece. Digital music is the only type of music that BWSB supports, MIDI and FM based music formats are not supported in BWSB. Future versions of BWSB may accomadate FM or MIDI music, if enough demand is appearant, but currently no plans exist. BWSB supports the following formats through the use of the 2GDM G-> utility (see section 2.1.1): MOD, NST, OCT, WOW, MED, STM, MTM S3M, 669, FAR, and ULT. More formats may be added later, provided that documentation and time is available for implementing them. 2.1.1 2GDM Module Conversion Utility Included with BWSB is a simple utility to convert almost any module file format to GDM format (the internal format used in BWSB). In this version of BWSB, you must convert all modules you wish to use in your programs to GDMs first. In future versions, there will be run time loading routines for other module formats, but because they don't work with all compilers yet, they are not included in this version. 2GDM is easy to use, just use: C:\> 2GDM filename [new filename] 'filename' does not need to include a file extension. 2.1.2 Runtime Loadable Music and Sound Engines (MSEs) Music and Sound Engines (MSEs) are the modules actually doing all the work in BWSB. MSEs consist of all the data, tables, and code used to mix multichannel digital sound, process music, and output sound on various sound devices. For each sound device, there is a separate MSE file. This saves memory by not loading code and tables for sound devices that aren't actually being used at runtime. In the current version of BWSB, there are five MSE files included: GUS .MSE - Gravis Ultrasound SB1X .MSE - Sound Blaster 1.xx SB2X .MSE - Sound Blaster 2.xx SBPRO .MSE - Sound Blaster Pro SB16 .MSE - Sound Blaster 16 PAS .MSE - Pro AudioSpectrum When you tell BWSB which MSE file you want to use, it loads it into memory ready to use. MSEs are always kept in base memory (except, possibly, in future 32 bit versions). Through this system, it is very easy to add support for other sound devices in the future, and it's very easy to program for devices you may not even own. 2.1.3 Libraries, QuickLibraries, and Units All LIBs, QLBs, and TPUs are in the \LIB directory. The TPU file may need to be created first by compiling MSE_TP.PAS if the TPU version is not already there. These are the files: MSE_QB.LIB - QuickBASIC 4.5 library for making EXEs MSE_QB.QLB - QuickBASIC 4.5 quicklibrary for loading into QB.EXE MSE_PDS.LIB - PDS 7.x library for making EXEs MSE_PDS.QLB - PDS 7.x quicklibrary for loading into QBX.EXE MSE_TP.PAS - You may need to compile this to get the file below: MSE_TP.TPU - Turbo Pascal Unit file. Make sure you tell the IDE where to find this in the options menu. To use any of the routines in the QuickBASIC or QuickBASIC Extended programming environment, you must load the appropriate QLB: [QB] C:\BWSB\LIB>QB /L MSE_QB [PDS] C:\BWSB\LIB>QBX /L MSE_PDS Please note the PDS 7.1 seems to conflict with BWSB's EMS routines in the environment. You can either disable QBX's EMS support ('/E:0') or you can disable BWSB's EMS support. If you don't do one of these two, running programs in QBX will likely crash the machine. This only applies to the environment; compiled versions of your programs in EXE form do not have this problem. 2.2 Getting Music Going The first thing to do is load and initialize your MSE. This is done in the code fragment that follows. Note, however, this assumes you're using a Sound Blaster 1.xx with the SB1X.MSE in the current directory. Basic and Pascal uses all of the computer's memory, which gives our routines no room to store pattern data, sample data, etc. To get around this, you must deallocate some heap memory using the SETMEM function in Basic or the $M directive in Pascal. Note: Loading the MSE prior to calling any other routines in the BWSB library is paramount for avoiding system crashes. If *any* other routines in BWSB are called before loading a MSE, the system will likely reboot or lockup. - QuickBASIC/PDS ------------------------------------------------------------- 'Declare all the BWSB subs and functions: '$INCLUDE: 'BWSB.BI' '$INCLUDE: 'GDMTYPE.BI' DIM ModHeader AS GDMHeaderType 'Module Header Freemem& = FRE(-1) - 80000 'Basic Heap - EXE Memory (80000) A& = SETMEM(-Freemem&) 'This is the memory freed for 'module and MSE usage. ' 旼 Oversampling rate (sound quality) '  ErrorFlag = LoadMSE("SB1X.MSE", 45, 4096, &HFFFF, &HFF, &HFF) '      ' MSE file name 컴� � 쳐컴컴컨컴컴� ' Buffer size 켸 읕 Autodetect IRQ, base I/O ' address, and DMA channel - Turbo Pascal --------------------------------------------------------------- {$M 16384,0,65360} { Leave some memory for the module, don't hog } { all the heap space } Program PlayGDM; Uses MSE_TP; { Include all the MSE functions and Types } Var ModHeader : GDMHeaderType; { Declare a module header } BaseIO : Word; IRQ : Byte; DMA : Byte; ErrorFlag : Word; Begin BaseIO := $FFFF; { Variables are used because values are returned } IRQ := $FF; { Direct values are not supported with reference } DMA := $FF; { parameters. } { 旼 Oversampling rate (quality) } {  } ErrorFlag := LoadMSE('SB1X.MSE', 45, 4096, BaseIO, IRQ, DMA); } {      } { MSE file name 컴� � 쳐컴컴컨컴컴� } { Buffer size 켸 읕 Autodetect IRQ, base I/O } { address, and DMA channel } End. ------------------------------------------------------------------------------ The next step is to load your module. The module load routine can load your module into base memory, EMS memory, or GUS DRAM (only on the GUS MSE). It'll only load the module into EMS memory if you tell it to. However, you must first detect whether EMS services actually exist, or you'll probably end up crashing the system. Included with BWSB is an EMS detection routine (EmsExist), just for this purpose. The following code assumes you're loading the module "NRG.GDM" from the current directory. It detects EMS memory and loads it into EMS if detected. - QuickBASIC/PDS ------------------------------------------------------------- IF EmsExist THEN 'Are there EMS services available? Flags = 1 'Enable EMS use ELSE Flags = 0 'No EMS use. END IF File = FREEFILE 'Get a free file handle number OPEN "NRG.GDM" FOR BINARY AS File 'Open the module in binary mode ' 旼 Calling: Load Flags (EMS enable) 'Load our module:  Returns: Error flag (0 - no errors) LoadGDM File, 0, Flags, VARSEG(ModHeader), VARPTR(ModHeader) '    ' File 켸 읕 Offset into 읕 Module header that you can use later ' Handle file to load to get information on the GDM loaded. ' from. CLOSE File 'Close the file handle.. - Turbo Pascal --------------------------------------------------------------- Begin If EmsExist { Are there EMS services available? } Then Flags := 1 { Yes, then use it } Else Flags := 0; { No, disable EMS use } File := OpenFile('NRG.GDM'); { Open the module file } { Use handle file routines to open the file instead of FCBs } { 旼 Calling: Load Flags (EMS enable) } { Load our module:  Returns: Error flag (0 - no errors) } ErrorFlag := LoadGDM(File, 0, Flags, ModHeader); {    } { File handle 켸 읕 Offset into 읕 Module header that can be } { file to load used later to get info on } { from. the GDM loaded. } CloseFile(File); { Close the file handle using the handle file routines } End. ------------------------------------------------------------------------------ Then you'll want to start up the music engine and enable the music. Note that GDMs do not include a byte telling how many channels are used; you must scan through the channel default panning table to count how many channels are in use. Pan position of FFh implies that the channel is not used in the module. Any other value means that the channel is used in the music file. - QuickBASIC/PDS ------------------------------------------------------------- MusChans = 0 'Start out at zero.. FOR J = 1 TO 32 'Scan for used music channels IF ASC(MID$(ModHeader.PanMap, J, 1)) <> &HFF THEN MusChans = MusChans + 1 END IF NEXT ' 旼 Actual oversampling rate in use (Hz) '  OverRate& = StartOutput(MusChans, 0) 'Start your (sound) engines '   '# of Music+Sound channels 켸 읕 Amplication level (0 - none) StartMusic 'Enable the music play flag 'Music should be playing now. - Turbo Pascal --------------------------------------------------------------- Begin MusChans := 0; { Start out with zero channels } For J := 1 to 32 do { Scan for used channels in then Pan mapping } If ModHeader.PanMap[J] <> $FF Then MusChans := MusChans + 1; { 旼 Actual oversampling rate in use (Hz) } {  } OverRate := StartOutput(MusChans, 0); { Start your (sound) engines } {   } { # of Music+Sound channels 켸 읕 Amplification level (0 - none)} StartMusic; { Enable the music play flag } { The music should be playing now } End; ------------------------------------------------------------------------------ Of course, once you're tired of the music, you'll use this: - QuickBASIC/PDS ------------------------------------------------------------- StopMusic 'Disable music processing StopOutput 'Stop all sound output UnloadModule 'Free module memory FreeMSE 'Remove MSE from memory - Turbo Pascal --------------------------------------------------------------- Begin StopMusic; { Disable music processing } StopOutput; { Stop all sound output } UnLoadModule; { Free module memory } FreeMSE; { Remove MSE from memory } End. ------------------------------------------------------------------------------ 2.3 Adding Sound Effects Note: Sound effect playing is not available in unregistered shareware version of BWSB. The PlaySample routine can be called, but it does nothing (ie, just does a RET). Adding sound effects to your programs is not a hard task. You first must create a GDM with the sound effects you will be using. Say you have a sound effect named LASER.VOC. You are also using the music file RAINBOW.S3M. The first thing you would do is load up Scream Tracker 3 (or any other module editor that supports loading and saving S3Ms, or for that matter, whatever module format your music is currently in). Once your in your module editor, load RAINBOW.S3M as if you were about to edit it. Press F3 (or whatever in your module editor) to get to the sample editing screen in ST3. Then move down to an empty sample slot and load the LASER.VOC into that slot. Remember which sample number this slot is for later use.. If you forget, you can always go back with the SND-PAD.EXE program to load the GDM form of your music file and look at the sample numbers along the left hand side of the screen. Ok, now you've got a S3M (or whatever format you're using) with all the music and sound effects you want. Save this module and exit the editor. Now you've got to convert it to a GDM with the 2GDM utility (included with BWSB). Now you have RAINBOW.GDM, with both your music and sound effects stored in the file. Keep a copy of RAINBOW.S3M in case you later want to add or remove sound effects. In your program, you would set things up as normal for just plain G-> module playing (see section 2.2). The only difference is that you must allocate more sound channels when calling StartOutput. Here is an example of the modification to make: - QuickBASIC/PDS ------------------------------------------------------------- ' 旼 Actual oversampling rate in use (Hz) '  OverRate& = StartOutput(MusChans + 4, 0) 'Start your (sound) engines '    ' # of Music channels 켸 � 읕 Amplication level (0 - none) ' # of sound effect channels 켸 - Turbo Pascal --------------------------------------------------------------- Begin { 旼 Actual oversampling rate in use (Hz) } {  } OverRate := StartOutput(MusChans + 4, 0); { Start your (sound) engines } {    } { # of Music channels 켸 � 읕 Amplification level (0 - none) } { # of sound effect channels 켸 } End; ------------------------------------------------------------------------------ Note that the total number of channels you allocate can not exceed 32. Another thing to keep in mind that the more channels you allocate, the more CPU power being used up (except on the GUS). So, try to keep the number of channels required for use down to a minimum. Note: In the unregistered evaluation version of BWSB, 6 channels if the actual limit. On the GUS, this is really 14 because of the way the GUS hardware works. Once you've got everything initialized and the music is playing (note: music does not have to be enabled to play sound effects, but in most games you will be having both playing at the same time), you need to call the PlaySample routine to play some sound effects. - QuickBASIC/PDS ------------------------------------------------------------- DO DO Key$ = INKEY$ LOOP UNTIL LEN(Key$) 'Loop until key pressed Sample = VAL(Key$) 'Find which sample # to play SNDFX = SNDFX + 1 'Step through sound effect channels IF SNDFX = 5 THEN SNDFX = 1 ' 旼 Digital sound channel to play on '  PlaySample MusChans + SNDFX, Sample, 16000, 64, &HFF '     ' Sample # to play 켸 � � 읕 Use default panning ' Play sample at 16KHz 켸 읕 Maximum volume LOOP UNTIL Key$ = CHR$(27) 'Exit loop if Esc pressed - Turbo Pascal --------------------------------------------------------------- Uses Crt; { Required for ReadKey function } Var Key : Char; SndFX : Integer; Sample : Integer; Begin Repeat Key := ReadKey; { Read in a key } If Key <> #27 { Make sure it wasn't ESC } Then Begin Sample := Ord(Key) - Ord('0'); { Get Sample number to Play } SndFX := SndFX + 1; If SndFX >= 5 Then SndFX := 5; { 旼 Digital sound channel to play on } {  } PlaySample(MusChans + SndFX, Sample, 22000, 64, $FF); {     { Sample # to play 켸 � � 읕 Use default panning } { Play sample at 22KHz 켸 읕 Maximum volume } End; Until Key = #27; { User has pressed ESC so exit } End. ------------------------------------------------------------------------------ This short piece of code would let the user press the number keys (0-9) to play samples 0-9 in the loaded GDM file at 16KHz, while not disturbing the music that is also playing. It cycles through 4 different sound effect channels so that each sound effect will not cut off the sound effect played just before it. 2.4 Things to Keep in Mind ) There are many more features to BWSB not documented here, this is just a little bit of help for those getting started. You can learn much more by looking at the example programs and reading about the other routines in BWSB, documented in the function reference guide (BWSB-REF.DOC). You will probably want to print that file out; it does not contain high order ASCII specifically for this purpose. ) You may have problems running a printer while music or sound is enabled. This happens if the sound card shares an IRQ with the LPT port. ) Don't use any routines before loading a MSE with LoadMSE! Otherwise, watch the system reboot! ) Do not enable music processing without first loading a music file! Or, watch the system crash! ) Do not free a module from memory before disabling music processing! Or, watch the possible system crash (won't always happen, but would be very likely with time). ) If you have problems working on the QB(x) environment, disable EMS use or just run your program in compiled form (EXE) each time. QB(x) seems to dislike EMS routines to a degree. ) FreeMSE will automatically be called on exit in normal cases, but it doesn't hurt to call it again. *That* won't lock up the system. Note: In the Turbo Pascal implementation, FreeMSE will not be automatically called unless you specify it (see G-> section 3.). ) BWSB currently does not support samples of over 64K long. This is usually not a problem for music files, but for sound effects (mainly voice samples) you will need to watch your back. ) SAVE YOUR WORK OFTEN AND KEEP RECENT BACKUPS!! ) Yes, there are an uncounted number of ways to crash the system using these routines incorrectly. Don't let that make you think that this library is buggy or hard to use!! BWSB was created with speed (highest priority) and size (second priority) in mind, Putting in a bunch of safe guards in the code would only bloat the library so that your product would be considerably larger. ) If you have problems with your source code (it locks up the machine all the time), just take a look at the example programs given. If that doesn't help, you can always look back in the documentation here! Chapter 3. Turbo Pascal Differences/Notes 컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴 ) Because Turbo Pascal uses FCBs instead of file handles like BWSB, you must use the routines OpenFile and CloseFile in MSE_TP.TPU to open a GDM for loading. ) The $M Compiler directive must be used to lower the maximum heap value. BWSB bypasses the TP heap manager when allocating memory. Set the maximum heap value at least (655535-(Size of Module)+(Size of MSE)+(Size of Mixing Buffer)). This is a best case scenario, so you will probably need to set it even lower. To get started, use the following: {$M $8000, 0, 65535} This sets up a 64K heap, which is plenty for most of your needs and leaves well enough room for almost any module out there. ) In the QuickBASIC/PDS version of BWSB, the FreeMSE function is registered with Basic's exit routine, so that if you get an unexpected runtime error, the computer will not crash because of left over IRQ handlers and such from BWSB. With Turbo Pascal, this is not automatic. You can specifically ask TP to do this with the following: ExitProc := @FreeMSE; ) OpenFile. A function that opens a file and returns its handle. Bypasses TP's file routines. Syntax: Function OpenFile(Filename : String) : Word; Parameters: Filename - name of file to open. Returns: $FFFF - an error has occurred opening file or file not found. OTHER - The handle of the opened file. ) CloseFile. Closes a file opened by OpenFile. Syntax: Procedure CloseFile(FileHandle : Word); Parameters: FileHandle - handle of file to close ) EmsExist. A function to check if EMS memory is installed in the system. Syntax: Function EMSExist : Boolean; Returns: True - if EMS is available False - if EMS is not available Chapter 4. Miscellaneous 컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴 4.1 Need Music? Read Here! So you're writing a game and you need lots of original, creative, and earth shaking music for your first class game? Well, the music composers of OverThrowMachine are ready to serve you in all your music and sound effect needs, at a reasonable price! The two example music files included here in this version of BWSB were composed by Stalker (aka Ariel Gross) and Tek (aka Taylor Pakula) of OverThrowMachine. If you like what you heard there, wait till you hear some of their >100K songs (all the modules included here were kept compact so that the BWSB distribution file would not be bloated). If you're interested in buying music from the OTM music composers (in S3M or MOD format, we do not write STMs, FARs, ULTs, or other arcane file formats), please contact us by internet email for pricing information (it varies from project to project): Stalker -: stalker@primenet.com Tek -: tek@hndymn.stat.com If you don't have internet access, send mail to Edward Schlunder who will promptly forward your mail to Stalker and Tek: Edward Schlunder 554 North Acacia Road Apache Junction, AZ 85219-4313 USA 4.2 Technical Support/Contact Information Technical support is FREE for all users of BWSB (although registered users get a heck of a lot more attention :-). BWSB-TALK Mailing List (Internet Only) The BWSB mailing list for technical support, questions, comments, concerns, etc will be operational SOON. Please email us for current status and subscribing information. Edward Schlunder (Project Head) Internet: email address zilym@hndymn.stat.com Zilym in the #coders or #otm channel on IRC FidoNet: Edward Schlunder at 1:114/268 Mail: 554 N. Acacia Road Apache Junction, AZ 85219-4313 USA Alex Chalfin (Turbo Pascal) Internet: email address achalfin@uceng.uc.edu OR achalfin@ddt.eng.uc.edu (alternate) FidoNet: Alex Chalfin at 1:108/180 Mail: 6244 Beech View Circle Cincinnati, Ohio 45213 USA 4.3 Distribution List Internet FTP 컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴 hornet.eng.ufl.edu I'm not quite sure where the BWSB file will end up yet, directory wise. Do a search in the /demos directory. Internet Email 컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴 BWSB-LIST Mailing List (uuencode) The BWSB mailing list for latest releases and bug fixes will be operational SOON. Please email us for current status and subscribing information. Email zilym@hndymn.stat.com for a uuencoded copy. FidoNet FREQ (request BWSBxxx.ZIP, where xxx is the version number) 컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴 Chandler Programmer's Connection (mail node 3) Chandler, AZ (602)759-6290 or 1:114/268 28.8k bps Note: Latest releases always get uploaded to this BBS first thing, so this one is always a couple days ahead of the other distribution sites. Private BBSes 컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴컴 Chandler Programmer's Connection (public node 1) Chandler, AZ (602)759-7789 9600 bps Note: Latest releases always get uploaded to this BBS first thing, so this one is always a couple days ahead of the other distribution sites. Small Time BBS Apache Junction, AZ (602)983-7204 14.4 bps 4.4 Closing Words Finally, it's done. Ah, it's been a long two years.. Hmm, feels like more than that, but the calendar says it's only two. I'm glad I finally got this released, I kept meaning to release it and then put it off to add a few more features, and then later, fix bugs in those few more features I just added. At least now I'm slightly satisfied with the amount of features in BWSB that I can happily release it to the public. Yes, indeed, this was meant to be something completely different when I first started out on it. It was mainly going to be a lot of documents on how to write your own music routines, not a bunch of music routines. However, as time went by, I saw more and more people write docs on how to write a module player, and less solid code to actually do it. All talk and no action :-). So, BWSB decided to go the source code route, now it has fast routines and stable operation, compared to what someone might be able to create after reading a "how-to" document. Please excuse any errors I might have left in the documentation. Everything in BWSB changed so fast on the programming side that the documents were always completely outdated. This is one reason why it didn't released for so long; I'd document it and then fix a bunch of things to make it easier to work with, then have to redocument it all, and then fix more things.. A very evil cycle it was indeed, but at least it made BWSB better and better. Even if you don't like BWSB enough to register, please send me some email with your comments, suggestions, etc.. Like I said, I've spent around two years of my life on this (ok, not a big chunk if you're a 40 year old, but...) project. I'd at least like to hear how many people have just looked at it. My email address is found G-> in section 4.2. I have a lot of ideas for the next release. I do *not* plan on waiting forever to release a new version; that would lead into the old documentation vs. actual code problem I had before. There are many things I would have liked to put in this version, but didn't have time to. Besides, a lot of people are screaming for me to hurry up and let them use BWSB! I've already gotten one registration (thank you John Peasley!) and he had to put up with the outdated documentation at the time. Of course, that's what you get if you register before it's officially released! :-) Have fun and send me email!