                    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.


