GV-SOUND(tm) Digital Sound Toolkit Version 1.00 User Manual Copyright (c) 1994,94 Jarrod Davis Software Co. All rights reserved. 1 If you are looking for a high-quality, easy-to-use, digital sound toolkit that works in native protected mode and is object-oriented, then your search is over. We are proud to introduce GV-SOUND, from Jarrod Davis Software Co. Now, Borland Pascal 7.0 programmers can enjoy the same benefits thats been available to "C" programmers. To discover more about GV-SOUND and the company behind it, read on... ABOUT JARROD DAVIS SOFTWARE CO. ------------------------------- JDS is a small software development company owned by me, Jarrod Davis. We develop cutting-edge software products for IBM and compatible personal computers. GV-SOUND is our first product release. It is also a member of our game development system for BP7 called GameVision, which is currently in development. GV gives you an object-oriented, extendable foundation for developing games in DOS protected mode. Each of its components can be used either separately or combined to form a robust application framework. Look for additions to GV as well as other exciting products coming soon to a BBS near you! Your feedback is very, very important to us. Please, feel free to contact us with any suggestions or comments about our products. Thank You. 2 ORDERING INFORMATION -------------------- To order by phone, call (904) 542-2252. Our hours are from 10-6 Mon thru Fri. We accept Check/Money Order, AMEX, and VISA/MC. Send all mail orders to: Jarrod Davis Software Co. P.O. Box 1285 Old Town, FL 32680-1285 3 GV-SOUND TOOLKIT ORDER FORM ************************************************************************* (Please Print or Type Clearly) FIRST NAME _______________________________________________________ LAST NAME _______________________________________________________ ADDRESS _______________________________________________________ CITY _______________________________________________________ STATE _______________________________________________________ ZIP/POSTAL CODE _______________________________________________________ COUNTRY _______________________________________________________ PHONE #: _______________________________________________________ GV-SOUND Digital Toolkit $24.95 Shipping & Handling in US $ 0.00 Shipping & Handling outside US $ 6.00 Florida residents sales tax add $ 1.53 Make check payable to "Jarrod Davis Software Co." Total $_________ Credit Card information Card number ___________________________________ Expiration ____________ (Note: Please allow 1 to 2 weeks for delivery ) - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - Please take the time to tell us how you got your shareware copy of this program: ______ America Online ______ CompuServ ______ Prodigy ______ ZiffNet ______ Software Creations ______ Friend ______ Local BBS (Name & #): __________________________________________ ______ Catalog (Name): ________________________________________________ ______ CD (Name): _____________________________________________________ ______ Other (Please specify): ________________________________________ ************************************************************************* Jarrod Davis Software Co. * P.O. Box 1285 * Old Town, FL * 32680 4 GV-SOUND LICENSE AGREEMENT -------------------------- GV-SOUND(tm) Digital Toolkit is a shareware program which is copyrighted by Jarrod Davis Software Co. As a shareware product, you are encouraged to freely distribute this product, with the following exceptions. If you would like to distribute this program commercially, there are several guidelines that you must follow. These guidelines are set in place to ensure that the most recent version of this product is provided to the commercial distributor. To distribute the shareware version of GV-SOUND commercially, you must contact Jarrod Davis Software Co. to ensure that you have the latest version. You must also include all the accompanying files in an unmodified form. This is for your benefit as well as ours, all it takes is a phone call. Commercial distribution includes, but is not limited to, advertisement of this program in any published catalog, shareware CD, or magazine. If you desire to distribute GV-SOUND via retail rack sales, you must first obtain written permission from Jarrod Davis Software Co. BBS owners and operators may feel free, and are encouraged to place this program in any library for public or private access. It is a violation of this license to reverse engineer, or to modify the program and/or any accompanying files. GV-SOUND is distributed "as-is" and no warranty is granted or implied. JDS will not be held responsible for any damage that the use of this program may cause to any individual or organization. It is at your own risk to use this product on your system. You must include all the files listed in PACKING.LST. JDS can be contacted at: Address: P.O. Box 1285 Old Town, FL 32680-1285 Voice : (904) 542-2252 5 CREDITS ------- GV-SOUND Digital Toolkit, documentation, example source code, demo programs and graphics, was designed and developed by Jarrod Davis. Additional design for GV-SOUND by Richard Benson. Additional sound effects by Richard Benson Music scores by Mr. Spleen Additional graphics by Mike Johnson and Richard Benson. Additional documentation by Christi M. Davis and George Griffin. Proofreading by Christi M. Davis and George Griffin. Additional BBS distribution by Bill DeSha. Special thanks to Richard Benson, George Griffin, Bill DeSha, Steve Ericson and Mike Johnson for testing. 6 TRADEMARKS ---------- GV-SOUND(tm) Digital Toolkit and documentation are copyright 1994,95 by Jarrod Davis Software Co. of 1600 Suwannee Street, P.O. Box 1285, Old Town, FL 32680-1285. All rights reserved. Jarrod Davis Software, JDS, "a new vision for the gaming experience", GV-SOUND, GameVision, Quest, "Invasion of Earth Alliance", are trademarks of Jarrod Davis Software Co. No part of this manual may be reproduced in any form without the written consent of Jarrod Davis Software Co. IBM(r)-PC, XT, AT, PS/2 are registered trademarks of International Business Machines. Sound Blaster(r), Sound Blaster Pro(r) are registered trademarks of Creative Labs, Inc. Pro Audio Spectrum(r) is a registered trademark of Mediavision. Gravis Ultrasound(r) is a registered trademark of Gravis. Borland Pascal(r) is a registered trademark of Borland(r) International. Cool Edit is a trademark of David Johnston. Windows(r), .WAV file are registered trademarks of Micorsoft(r) Corporation. WAVE for Windows(r) is a registered trademark of Turtle Beach Systems. Blaster Master 16 is a trademark of Gary Maddox. 7 WHAT IS GV-SOUND? ---------------- When we began developing games for DOS protected mode, we looked for a good digital sound toolkit for Borland Pascal 7.0 that: * worked in native protected-mode * had a simple, clean interface * provided excellent playback quality (no ticks or hissing). We found no such toolkit with all the above requirements. So, we began to develop one in-house and this program is the result of those many hours of research and development. GV-SOUND is the premiere digital sound toolkit for Borland Pascal 7.0. It allows your application to playback digitized speech while it is running in native PM. By native we mean that the supplied GVSOUND.TPP unit links directly into your application and is instantly available for use. No loading sound drivers or first loading a kernel that contains the real-mode version of the toolkit which then spawns your PM application. You have full control over all the features of GV-SOUND through your native PM program. GV-SOUND is built to take advantage of the OOP extensions of BP7. This provides a simple, clean API that's fully extendable. You have the freedom to enhance the toolkit by creating descendant types that add additional functionality to the base ancestor object, TSample. The registered version of GV-SOUND can playback up to 16 digital samples (the shareware version plays up to 4) simultaneously. Time critical sections were hand-coded in assembler, so CPU overhead is minimized. Combining OOP, PM and excellent playback quality, you have a powerfully digital toolkit for game development. WHAT DO YOU GET WHEN YOU REGISTER? ---------------------------------- The registered version of GV-SOUND removes the shareware messages, gives you the full 16 channel playback and gives you the latest version which include a bonus unit that has some very useful routines. The unit contains a high resolution timer object, routines to manage link lists, and the ability for your game to detect multiple keystrokes as well as many other features. Included will be a program for processing your sound samples. You can change the sample rate, volume and much more. Also, you get free technical support, you talk directly to the actual programmers. SYSTEM REQUIREMENTS ------------------- Although BP7 PM works on 286s and higher CPUs, GV-SOUND works best on a 386 CPU or higher. GV-SOUND allocates a 2k buffer internally for digital playback and links into the hardware interrupt. Beyond this, the only hardware requirements are those needed by Borland's DPMI kernel. See BP7's Language Guide for more information on memory requirements for DOS Protected Mode programming. SOUND CARD COMPATIBILITY ------------------------ GV-SOUND will work only with Sound Blaster Pro or higher HARDWARE 8 compatible cards. To get the highest quality playback requires the hardware hosted feature of the SBPro or higher card called AUTO INIT or DMA BACKFILL mode. Once GV-SOUND has initialized the Digital-To-Analog converter (DAC), it will continuously play whatever is in the sound buffer. GV-SOUND only has to update the contents of the buffer after each interrupt. There is a small amount of time between each interrupt in which no sound is being played. This pause can cause 'ticks' during playback. In AUTO INIT mode, the Sound Blaster is constantly playing the contents of the sound buffer, GV-SOUND only has to update the next piece of the sample that is to be played, placing it behind the piece that is currently playing, hence the term "Backfill." The result is smooth, continuous playback. Some sound cards claim to be "Sound Blaster compatible," but actually are only compatible when emulation drivers are loaded. Such as: * Mediavision Pro Audio Spectrum * Gravis Ultrasound (GUS) There are several parallel port type devices which use this method as well. Jarrod Davis Software Co. does not guarantee perfect performance on any device utilizing emulation software to make it "Sound Blaster compatible." If you discover you have a card that does not work and it's supposed to be compatible, contact us and we will do our best to rectify the problem. To help us support you, gather the following information prior to calling: 1. The sound card manufacturer 2. Hardware configuration including DMA channel, IRQ and port address. 3. A copy of your CONFIG.SYS file. 4. A copy of your AUTOEXEC.BAT file. Try to reproduce the problem outside the scope of your application. Writing a short program that reproduces the problem will assist us in solving it. DEVELOPMENT PLATFORM -------------------- GV-SOUND works only with Borland Pascal 7.0 or higher. USING GV-SOUND -------------- Starting GV-SOUND could not any easier. Include the GVSOUND.TPP unit in your uses statement and when your application runs, GV-SOUND will initialize itself. It will first check for the BLASTER string to determine the sound card settings (port address, DMA channel and IRQ number). If the BLASTER string can not be found, it will attempt to auto-detect the sound card. If auto-detection fails, the public variable SBInstalled is set to FALSE and all further calls to GV-SOUND will immediately return. If the sound card is initialized, SBInstalled will be set to TRUE. 9 To playback a digital sample, declare an instance of the object TSample and initialize it: program Test; var Sample: TSample; Channel: Byte; begin Sample.Init('sound.wav'); Channel := Sample.Play(False); repeat until not Sample.Playing; Sample.Done; end; In the above program, the object is initialized by the Init method, passing the name of the sound sample file to be used. To play the sample, call the object's Play method. If the sample is to loop continuously, you pass TRUE as the argument or FALSE to have GV-SOUND play the sample just once. Next, GV-SOUND will find a free channel and playback begins. The Play method will return a value between 1 and 16 (1-4 shareware version) which is the channel on which the sample is currently playing. The status of the playback can be checked with the Playing method. It will return TRUE as long as the sample is playing. Then lastly the sample object is disposed. GV-SOUND is fully streamable. It automatically registers itself with Turbo Vision's stream manager. This capability allows you to place all your sound samples in a resource file. The samples can be loaded in on demand. See the Turbo Vision Programming Guide for more information on streams and resource files. DIGITIZED SPEECH ---------------- GV-SOUND works only with RAW or FLAT digital samples (straight data with no header). Microsoft .WAV files can be passed directly as GV-SOUND will automatically skip the header and play the data. Creative Labs .VOC files, for example or any other type of digital sample will have to be converted to RAW format before submitting them to GV-SOUND. Also individual sample volume must be preprocessed before hand. However, the overall volume of all the samples can be controlled with the gvSetDigitalVolume routine. By processing the sound data first there is less overhead during playback. Speed is the essence in game programming. There are a number of good shareware and commercial utilities that can convert your sound to RAW format and manipulate the volume for you: The shareware program Cool Edit by David Johnston, WAVE for Windows from Turtle Beach System (a commercial digital sound editor for Microsoft Windows), and this programmers personal choice, the shareware program Master Blaster 16 by Gary Maddox. Master Blaster is an excellent program that allows you to convert your samples to RAW format and change the volume level. It also has many other special effects. GV-SOUND does not currently support stereo or 16 bit format and the sound data must be sampled at 11000Hz. This sample rate provides a good balance between performance and playback quality, especially running in PM. 10 GV-SOUND REFERENCE ------------------ This section describes all the elements of GV-SOUND, including all the object types, procedures, functions, types, variables, and constants. All items are listed alphabetically. PROCEDURES, FUNCTIONS, DECLARATIONS ----------------------------------- Declaration: function gvChannelPlaying(C: Byte): Boolean; Purpose: Returns the playing status of a digital channel. Specify a channel between 1-16 (1-4 for shareware version) and gvChannelPlaying will return TRUE if that channel is currently playing or FALSE if it is not. Example: if gvChannelPlaying(3) then gvStopChannel(3); Declaration: function gvSamplesPlaying: Boolean; Purpose: Returns TRUE if any digital samples are playing. Example: if not gvSamplesPlaying then Exit; Declaration: function gvSBCard: String; Purpose: Returns name of Sound Blaster compatible card found. Example: Writeln('Sound Card: ', gvSBCard); Declaration: SBDma: Byte; Purpose: Returns the Sound Blaster DMA channel number. Example: WriteLn('Sound Card DMA: ', SBDma); Declaration: SBInstalled: Boolean; Purpose: Returns TRUE if GV-SOUND found and initialized a SBPro or higher card, or FALSE if doesn't. 11 Example: if not SBInstalled then begin WriteLn('GV-SOUND could not found a compatible sound card.'); Exit; end; Declaration: SBPort: Word; Purpose: Returns the port address of the sound card. Example: WriteLn('Sound card found at: ', SBPort); Declaration: SBIrq: Byte; Purpose: Returns the IRQ number of the sound card. Example: WriteLn('Sound card is using IRQ: ', SBIrq); Declaration: procedure gvSetDigitalVolume(Vol: Byte); Purpose: Sets overall volume of all the digital samples. You specify a volume between 1 and 15, where 1 is the lowest volume and 15 is the highest. Example: gvSetDigitalVolume(8); Declaration: procedure gvStopAllChannels; Purpose: Stops playback of all active channels. All samples that are currently playing will stop instantly. Example: procedure gvStopAllChannels; Declaration: procedure gvStopChannel(C: Byte); Purpose: Stop playback of specified channel. Example: if gvChannelPlaying(4) then gvStopChannel(4); 12 TSAMPLE OBJECT: Declaration: destructor Done; Purpose: Disposes an instance of a TSample object. Example: Sample.Done; Declaration: constructor Init(FName: OpenString); Purpose: Creates a TSample object. Passes the name of a Microsoft .WAV or RAW digital sample file to the object. Example: if not Sample.Init('sample.wav') then WriteLn('Failed to Init Sample'); Declaration: constructor Load(var S: TStream); Purpose: Constructs and loads a TSample object from the stream S. Declaration: function Play(Loop: Boolean): Byte; Purpose: Starts playback of sample. Makes the sample loop continuously by passing TRUE as an argument or plays it once by passing FALSE. Example: Sample.Play(True); Declaration: function Playing: Boolean; Purpose: Returns the play status of sample. TRUE if sample is currently playing or FALSE if not. Example: if Sample.Playing then Sample.Stop; Declaration: procedure PlayOnChannel(AChannel: Byte; Loop: Boolean); Purpose: Starts sample on a specific channel. Like the Play method, this can specify whether or not to continuously loop the sample. 13 Example: Sample.PlayOnChannel(4, True); Declaration: procedure Store(var S: TStream); virtual; Purpose: Stores the sample on the stream S. 14