------------------------------------------------------------------------------
 Borland Pascal/Turbo Pascal 7.0 player units. (C) Charles Attard / April 1997
------------------------------------------------------------------------------
   E-mail: Charles.Attard@bigfoot.com

   As player units able to play 669/MOD/MTM/NST/S3M/WAV/XI/XM are not
   so common (!), I decided to make them available to anybody wishing
   to add sound in his/her Pascal applications.
   I have also taken much from Internet, so,
   I give now one more contribution !

   The supported sound cards are SBPro, SB16 and SB32/AWE32/AWE64
   in SB16 mode. I will probably add support for SB32/AWE32/AWE64 in native
   mode soon, but I can't give any date.

   Patterns and effects are as perfectly as possible executed; all effects
   for all types of modules are implemented; ping-pong loop and instrument
   vibrato are not implemented in XM/XI formats.

   Those units are the engine of the Multi Module Player v5.2xx, a very
   high quality module/sample/instrument player with a Tone Generator
   mode to play instruments/samples with MIDI input (all sound cards
   but SBPro) and PC keyboard. A disk writer is also available to create
   a WAV file from a module/instrument/sample.
   If you want to try MMP, you'll find it on ftp.cdrom.com, ftp.simtel.net
   and other mirror sites.
   Take also a look at MAZ's home page, www.maz-sound.com, you'll find
   interesting stuff about sound and digital music.

   WHAT'S NEW ?

   You should see MMP_REV.TXT in the Multi Module Player Archive for more
   details. But here's a summary:

   Faster routines (Pentium optimizations and data alignement),
   16-bit samples support, less DOS memory used: patterns are loaded to XMS
   when available and volume table is not created when all samples are 16-bit
   (33KB freed), some bug fixes (patterns etc.), MIDI input, WAV and XI
   format supported, disk writer to create WAVs ...
   
   WHAT'S OLD ...

   Very accurate patterns and effects interpretation for all types of
   modules, real-time oversampling/digital low-pass filtering/clipping
   for a TOP quality output in full 16-bit resolution on SB16/32/AWE32/AWE64,
   SB Pro support for SB compatible sound cards

*****************************************************************************

   Content of  MODUNIT2.ZIP  

        DMA      TPU                 DMA routines            (*)
        DMA      TXT                
        EMS      TPU                 EMS routines            (*)
        ERRORS_E TPU                                         (*)
        ERRORS_E TXT                 Errors description
        LOADMODS TPU                 Loader routines         (*)
        LOADMODS TXT                
        MIXERS   TPU                 Digital mixers          (*)
        MIXERS   TXT               
        MMEM     TPU                 DOS memory routines     (*)
        NEWCRT   TPU                 Misc. routines          (*) 
        NEWCRT   TXT                
        NEWTYPES PAS                
        NEWTYPES TPU                 Data types              (*)
        PLAYMODS TPU                
        PLAYMODS TXT               
        SB       TPU                 Sound Blaster routines  (*)
        SB       TXT               
        README   TXT                 This file
        SYSPROC  PAS                
        SYSPROC  TPU                 System procedures       (*)
        TESTMOD  EXE                 Basic player
        TESTMOD  PAS                 Basic player source     
        WAV      TPU                 RIFF waves routines     (*)
        WAV      TXT                
        XMS      TPU                 XMS routines            (*)
        XMS      TXT               

        (*) You don't need to bother about those units, they are
            used by other units.
            But you could use some for other applications such as WAV and XMS.

       I suggest you read the documention coming with the Multi Module
       Player to learn more about memory management.

       The source TESTMOD.PAS should be clear enough to code many applications,
       but I must give some important RECOMMENDATIONS:

       Avoid expanded memory managers (EMM386, QEMM386 ...), and protected
       mode (windows or OS/2 DOS box ...) because the player won't be
       able to initialize in XMS-32 bit flat addressing mode; It'll have
       to switch to DOS/EMS mode (if available) which is slow and limits
       samples to 64KB.

       If you have problems with vertical retrace synchronization in your
       graphical applications (slow or choppy scrollings ...), you
       could try setting the DMA buffer size (DMASize) to a bigger value
       (default is 4096), for example 16384. To do this, add 'DMASize:=16384'
       before hardware initialization (it will be the very first instruction
       in TESTMOD.PAS).
       Why this would solve such problems ? Because the interrupt frequency
       with a buffer size of 4096 bytes, in 16-bit/stereo/45KHz output, is
       about 88 Hz which is close to the vertical refresh frequency (70 Hz),
       thus 'stucking' frequently the CPU in the synchronization routine.
       Another possibility is to take a very big DMA buffer (30-60KB) to
       have a very low interrupt frequency ...

       In any case, you should avoid disabling interrupts (by using 'cli')
       because the player is supposed to have priority ! and you should
       try to lower as much as possible the CPU load; to do this:
        - avoid EMS mode (disable EMM386, QEMM386 ...)
        - avoid protected mode (Windows/OS-2 in DOS box ...)
        - use mono mode, when viewing graphics stereo is useless
        - lower output frequency to 32KHz or even 22KHz, there's almost
          no difference in quality with "standard" modules
       Disabling oversampling is not really useful for lowering the CPU load,
       because it'll be less active with a low output frequency, moreover 
       it greatly improves the output quality of low pitch notes.


       That's all for now, good coding !

****************************************************************************

   *****************
   Conditions of use
   *****************

    You can use those units in personal or freeware applications only, but
    you must give my name and e-mail address in your documentation.

    You must mail me for authorization if you intend to use them in a
    shareware or commercial application.

    The archive MODUNIT2.ZIP can be transfered on any server or CD-ROM.
    For CD-ROMs, you must mail me for at least two things:
    you may not have the last version and I'll know where it's distributed.

    I am not legally responsible for any difficulty arising from the use of
    the files included in MODUNIT2.ZIP. You use them at your own risk(s).
    But I am morally responsible, as I have done many efforts to make them
    work properly, and if you have problems, I'm always ready to help you !

    Charles Attard

    Charles.Attard@bigfoot.com
----------------------------------------------------------------------------



