The Psychic Monks present... ŪŪŪŪŪŪŪŪŪŪŪŪ ŪŪŪŪŪŪŪÜ ßßßßŪŪŪŪßßßß ŪŪŪŻ ßŪŪŪ ŪŪŪŪ ŪŪŪŻ ŪŪŪ ŪŪŪŪ ŪŪŪŪ ŽŪŪ ŪŪŪÜŪŪÜ ŪŪŪ ŪŪŪ ŪŪŪŻ ÜŪŪŪ ŽŪŪ ŪŪŪŪŪÜ ŪŪŪ ŪŪŪ ŪŪŪŪ ŪŪŪßßŪŪŪ ŪŪŪ ŪŪŪ ŪŪŪŪŪŪŪß ŽŪŪ ŪŪŻ ŪŪŪ ŪŪŪ ŪŪŪŪ ŪŪŪŪ ŪŪŪ ŪŪŪ ŪŪŪ ŪŪŪ ŪŪŪŻ ŽŪŪ ÜŪŪŪŪŪŪŻ ŪŪŪ ŪŪŪ ŪŪŪŪ ŽŪŪ ŪŪŪ ŪŪŪ ßŪŪŪŪŪŪ ŪŪŪŻ ŽŪŪ ŪŪŪ ŽŪŪŻ ßŪŪŪŪŪŪ ŪŪŪŪ ŽŪŪ ŪŪŪ ŪŪŪ ŪŪŻ ŪŪŪŻ ŽŪŪ ŪŪŪ ŽŪŪŻ ŪŪŻ ŪŪŪŪ ŽŪŪŪŪ ŪŪŪ ŪŪŪ ŪŪŪŪŪß ŪŪŪŻ ŽŪŪŪŪ ßŪŪŪŪßŪŪŪ ŪŪŪŪŪß Sound Blaster Module Player Version 2.11 The first public digital sound player routines for use with Watcom C/C++32 Compiler and DOS/4GW DOS Extender and Borland C++ 3.1 Compiler Copyright (c)1994 Carlos Hasan (a.k.a. Pel/PM) Introduction ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ 1.1 What is Tiny Player? The Tiny Module Player is a system by which you can play digital music in your software programs. It was designed for the Watcom C/C++ C compiler and the DOS/4GW Rational Systems DOS Extender. Also, It was translated to 16-bits to work with Borland C++ 3.1 compiler. It only supports the Soundblaster(tm) or compatible sound cards. 1.2 Hardware requirements The requirements for this system are a 386 computer and the Soundblaster(tm) or compatible sound card. It is much better if you have a fast 386 because you can achive higher mixing rates. 1.3 Smileware and contributions This program has been released as Smileware, which means you can use this program freely. Anyone can try it out without paying for the software. However, if you find this program useful and you want to use it indefinitely, I will be expecting some contributions. Also, if you are using this program, do not forget to give me credits in your productions. For those which are expecting GUS support in the next release of this sound player, please send contributions so I can buy a GUS sound card. :) For contributions, comments, suggestions, etc use the following mail addresses to contact the author: Snail Mail: Carlos Hasan Lo Encalada 144, Depto 22 „u¤oa, Santiago CHILE Internet E-Mail: chasan@cec.uchile.cl cvaldovi@dcc.uchile.cl Using the Player ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ 2.1 Playing music modules The player is pretty easy to use. First, you must load any Protracker or Fastracker music module file using the loading routines. To play the music module you need the Soundblaster(tm) configuration parameters. To ease things there is a routine called MODDetect which will automatically detect the card configuration parameters (I/O port address, IRQ level and DMA channel). This routine may fail on some systems, so it is always safer to ask the user those hardware parameters. Now, call the routine MODPlayModule to start playing the music file in the background. The routine parameters are the music module address, the mixing rate, sound card parameters and polling mode. If you do not want to play music in the background, but use the sound effect channels, you can call this routine passing NULL instead of a valid music module address. The MODStopModule will deinitialize the sound system, and should be called before exiting your program. This routine will close all the sound channels (music and sound effect channels). 2.2 Playing sound effects The player supports up to 8 sound channels. The program itself uses the first channels to play the music module. For example, for a normal 4 channels module file, the channels 0, 1, 2, and 3 will be used to play the music module. You can use the others unused channels to play sound effects and the like. The digital sound samples can be loaded from disk using the routine MODLoadSample which can read standard RIFF/WAV sample files, only 8-bit mono sound files are supported. After loading the sample, you can play it using the routine MODPlaySample. There are also routines to change the frequency and volume of the sound channels. You can control the overall volume of the music channels and the sound effects channels using two routines called MODSetMusicVolume and MODSetSampleVolume. These routines are very useful to do volume fades of the music, and for games which are playing sound effects over the music. 2.3 Closing Words First, I'd like to thank Vernor for helping me to write this document, and to Necros for the wonderful 8 channels module specially maded for this release. Also, I send greetings to all the others Psychic Monks dudes around. I should say that the Protracker tune was created from a S3M file, so it does not sound as good as the original Scream Tracker 3.01 module file. I really hope that you find this program useful. It is not the best or fastest player around, but the multiple sound channels capabilities should make it very useful to create games, demos, etc. Reference Guide ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ 3.1 LISTING OF ROUTINES MODDetectCard ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ Function: Detect Sound Blaster card. Prototype: int MODDetectCard(&Port,&IRQ,&DRQ) Parameters: Port - I/O Port address IRQ - IRQ level DRQ - DMA channel Returns: On success, return a zero value. On error, return a non zero value. Remarks: This function will detect the Sound Blaster card and will return the configuration parameters. You cannot call this routine while playing a module. WARNING: Actually the routine only detects the I/O Port address and the IRQ level, the DMA channel 1 is always returned by this routine. MODPlayModule ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ Function: Start playing a Modulefile. Prototype: int MODPlayModule(Song,Chans,Rate,Port,IRQ,DRQ,Mode) Parameters: Song - Address of the Module Chans - Number of channels (1-8) Rate - Mixing speed in Hertz (4kHz-22kHz) Port - I/O Port address (210h..260h) IRQ - IRQ level (2,3,5,7,10) DRQ - DMA channel (0,1,3) Mode - Polling mode (PM_TIMER or PM_MANUAL) Returns: On success, return a zero value. On error, return a non zero value. Remarks: This function will initialize the Sound Blaster card and will start playing the module file immediately. The module file must be a 4,6 or 8 channels Protracker or FastTracker music module file. The player supports two kinds of channels, music and sample audio channels. The music channels are used by the player to play the module, and the sample channels are used for sound effects and the like. The channels voices 0 to N-1 are used for music channels, where N is the number of channels of the module file. WARNING: Using the timer polling mode the system will use the timer interrupt IRQ 0 and will speedup the timer to 70 Hz. The old timer routine is called 18.2 times per second. MODPoll ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ Function: Polls the music system in manual mode. Prototype: void MODPoll() Parameters: None. Returns: None. Remarks: You MUST call this routine at least 50 times per second when using the manual polling mode while playing a module. There is no need to call it if you are using the timer polling mode. The routine preserves all the 80386 32-bit registers, so there is no need to save the registers if you are calling this routine from your timer interrupt service. MODStopModule ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ Function: Stop playing the current Modulefile. Prototype: void MODStopModule() Parameters: None. Returns: None. Remarks: This function shuts down the playing system. Must be called before exiting the user program. MODPlaySample ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ Function: Play instrument at specified period and volume. Prototype: void MODPlaySample(Voice,Instr) Parameters: Voice - Audio channel number (0-7) Instr - Instrument address Returns: None. Remarks: This function is useful to play samples over music. The sample structure holds the period, volume and the address of the 8-bit signed samples to be played in the channel. The amiga period value can be translated to hertz using the following formula: Hertz = 8363*428/Period MODStopSample ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ Function: Stop a sample channel. Prototype: void MODStopSample(Voice) Parameters: Voice - Audio channel number (0-7) Remarks: This function will stop the specified voice setting the channel volume to zero. The voice should be a sample channel. MODSetPeriod ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ Function: Set the sample channel period value. Prototype: void MODSetPeriod(Voice,Period) Parameters: Voice - Audio channel number (0-7) Period - Amiga Period (113-856) Returns: None. Remarks: This function will change the current frequency of the sample channel. The voice should be a sample channel. MODSetVolume ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ Function: Set the sample channel volume. Prototype: void MODSetVolume(Voice,Volume) Parameters: Voice - Audio channel number (0-7) Volume - Volume (0-64) Returns: None. Remarks: This function will change the channel volume. The voice should be a sample channel. MODSetMusicVolume ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ Function: Set the global music channels volume. Prototype: void MODSetMusicVolume(Volume) Parameters: Volume - Volume (0-255) Returns: None. Remarks: This function will set the global volume for all the music channels. MODSetSampleVolume ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ Function: Set the global sample channels volume. Prototype: void MODSetSampleVolume(Volume) Parameters: Volume - Volume (0-255) Returns: None. Remarks: This function will set the global volume for all the sample channels. MODLoadModule ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ Function: Load Module file from disk. Prototype: Module *MODLoadModule(Path) Parameters: Path - Module file name. Returns: The module structure address or NULL of error. Remarks: This function loads a 4,6 or 8 channels standard Protracker or Fastracker module music file from disk. MODFreeModule ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ Function: Free Module file from memory. Prototype: void MODFreeModule(Song) Parameters: Song - Module file address. Returns: None. Remarks: This function frees the module music from memory. You cannot free a module while it is being played. MODLoadSample ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ Function: Load sample file from disk. Prototype: Sample *MODLoadSample(Path) Parameters: Path - WAV file name. Returns: The sample structure address or NULL of error. Remarks: This function loads a RIFF/WAV sample file, the player only supports 8-bit mono unsigned sample file formats. MODFreeSample ÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄÄ Function: Free Sample file from memory. Prototype: void MODFreeSample(Instr) Parameters: Instr - Sample file address. Returns: None. Remarks: This function frees the sample file from memory. You cannot free a sample while it is being played.