		    UltiMOD v1.5 PUBLIC BETA 29

UltiMOD is a native Gravis Ultrasound modplayer for OS/2 Warp 3.0 or 
4.0 (aka Merlin) with MMPM/2 installed.
UltiMOD also supports any soundcard that works with the DART dlls.
NEW     : This version shares the audiocard! (DART)
WARNING : This version does NOT work on OS/2 2.x!

The DART dlls are downloadable from: (OS/2 Warp 4 already comes with them)
	http://wvnvaxa.wvnet.edu/~hrieke/us.html

================================================================================
   0  Contents
================================================================================
	   1  Features
	   2  Installation
	   3  UltiMOD
	   4  Ultitext (textmode version of UltiMOD)	   
	   5  A few tips to make life easier
	   6  General Information
	   7  Questions & Answers
           8  Bug Reports
	   9  How to help improve UltiMOD
	  10  Standard disclaimer

================================================================================
   1  Features
================================================================================
- support for:
	- 4 channel, 31 and 15 instrument Protracker/Noisetracker modules
        - 4 and 8 channel Startracker modules
        - 1 - 32 channel Fasttracker 1 modules
        - MTM
	- S3M
	- XM 
- ability to play samples inside a modfile at any note.
- low overhead (measured on my Pentium 75 Mhz computer using pulse and cpu tach)
	- 1%-2% for 4, 6 and 8 channel modules
	- 3%-4% for 16 channel s3m's
  (double these numbers for the textmode version of UltiMOD)
  Higher CPU usage in DART mode.
- support for songlists. (up to 512 files in one songlist)
- Graphical user interface. (graphical push & volume buttons, slidebar etc)
- Textmode version included with new user interface (and realtime display of
  channel data)
- Multithreaded. Two threads for playing modfiles and 1 for the user interface.
  This means that you can create your own songlist and save it while UltiMOD 
  plays one of your modfiles.
- support drag 'n drop of modfiles and songlists
- source code & info for device driver communication interface (GUS)

================================================================================
   2  Installation
================================================================================
Install the Manley GUS MMPM/2 drivers. (GUS mode only!)

Unzip ultimod.zip and run 'install.cmd' to put UltiMOD on your desktop.
Load your favourite modfile and fully exploit OS/2's multitasking capabilities
by running it alongside other applications.
With this release you need to put both MODULE.DLL and SNDCARD.DLL in a directory
that's in your libpath! (i.e. os2\dll)

================================================================================
   3  UltiMOD
================================================================================
This document won't explain how UltiMOD works. It's interface is self 
explaining by providing you with pushbuttons and simple menu's.
If something isn't clear just press F1 for online help.

UltiMOD accepts one songlist or one or more modfiles as a parameter on 
the command line. They may contain wildcards.

UltiMOD automatically scans for the presents of the Manley drivers. If it
can't find them it will use DART for playback. DART playback can be forced
by adding the /d switch to the command line.

NEW FEATURE: (DART only)
      - DART: support for up to 14 different sample rates:
                5510,  6620,  8000,  9600, 11025, 16000, 18900, 
               22050, 27420, 32000, 33075, 37800, 44100, 48000 hz
      	Whether you can use all of them depends on your soundcard of course.
			   

NEW FEATURE: (GUS Mode only!)
	UltiMOD can be run in two modes:
	 - exclusive mode: no other program can use the GUS while ultimod
			   is active
	 - shared mode   : OS/2 multimedia applications can use the GUS even
			   when ultimod is playing a module

Both modes have their advantages and disadvantages.
Limitations in shared mode:
	 - can't load samples > 256kb
	 - might run out of memory sooner (while PCM playback uses very little
           GUS DRAM, MIDI can use quite a lot)
	 - can only load modules that use less than the number of
 	   voices (/c: parameter in config.sys) the driver uses minus two.
	 - always plays back using the number of voices you specified in 
	   config.sys (default 28) This reduces playback quality.
	   (i.e. in exclusive mode a < 15 channel mods is played back at
	    44.1 khz; in shared mode always at 22.05 khz (28 voices))
NOTE: Limitations 1, 3 and 4 don't apply if you own a GUS PnP (Pro) or
      any other Interwave based soundcard

These restrictions don't exist in exclusive mode.
***Change in latest beta: The memory restrictions are also present in 
   exclusive mode if you don't own a GUS PnP (or other Interwave card)

Both PM UltiMOD and ultitext can run in either mode.
Shared mode    : add /s on the command line
Exclusive mode : add /e on the command line (default)
If you are a registered user, this setting will be saved in ultimod.ini
for later sessions. (GUS only; in DART mode everything is saved)

================================================================================
   4  Ultitext (textmode version of UltiMOD)
================================================================================
The textmode verison of UltiMOD also accepts one songlist or one or more 
modfiles as a parameter on the command line. They can also contain wildcards.

Keys:	Esc			- Quit
	-/+ 			- decrease/increase song speed 
	PgUp/PgDn		- scroll 9 lines up/down
	Home/End		- scroll to home/end of active window
	tab			- switch between channel & sample window
	cursor up/down  	- scroll one channel up/down
				  (red arrow points to the channel position)
	Enter			- disable or enable channel
	cursor left/right	- one position back/forward
	</>			- volume down/up
	n			- skip to next song in the songlist	

Usage: ULTITEXT /vXXX /pYY filename
        /vXXX       - volume (0-100)
        /pXX        - panning (chn 1: XX, chn 2 : 15 -XX etc)
	/l	    - enable looping (not valid in songlists)
        /noj        - disable backward position jumps

	Gravis UltraSound Options:
	/g	    - GUS playback  (default if you own a GUS)
        /s          - shared mode (run ultimod with PCM and/or MIDI)
        /e          - exclusive mode

	DART Options:
	/d	    - DART playback (default for other soundcards)
        /16	    - 16 bits playback (default is 8 bits)
	/8	    - 8 bits playback
	/f:xxxxx    - frequency (2000hz up to 48000 hz; default 44100 hz)
	/b:xxxxx    - buffer size (default 8192; 16kb for 16 bits playback)

        filename    - songlist or modfile(s)

If you're a registered user, Ultitext can also read the settings stored inside
'ultimod.ini'. Just copy the ini-file used by UltiMOD to the directory with
Ultitext.

********************************************************************************
********************************************************************************
From now on UltiMOD stands for both the PM and textmode version. Only
when the two version don't behave identically, a distinction is made between
them.
********************************************************************************
********************************************************************************

================================================================================
   5  A few tips to make life easier
================================================================================

- To quickly construct songlists you can run UltiMOD as follows:
	ultimod d:\mods\*.s3m d:\mods\*.mtm d:\mods\*.mod
  By default ultimod saves all these filenames in '########.lst' in the
  directory where ultimod is located.
  To save this songlist, select file->save songlist. (PM UltiMOD)
  Ultitext offers no help, so you must copy the songlist manually.

- When UltiMOD is running, you can launch a second copy of ultimod to
  pass (a) new modfile(s) or a songlist to the first one.

- Next.exe is for command line freaks (like me) who don't like switching to
  the desktop every time a boring modfile is playing, just to press the next 
  button.
  When executed, next.exe orders UltiMOD so skip to the next song in the
  songlist.

================================================================================
   6  General Information
================================================================================
UltiMOD (in GUS mode) is shareware and needs to be registered after 30 days 
of use.
UltiMOD in DART mode is freeware. 
Please see the registration document for more details.

For known bugs see bugs.txt.

Future plans for UltiMOD:
	- WPS integration

Finally I want to thank the beta testers for their extensive testing:
	Anssi Saari		Olli Mannisto		Mark Ruys
	John Rohland		Samuel Audet		Mikael Kjellstrom
	Juha Kauppinen		Harry Pulley		Hayo Baan
		
I hope you will enjoy UltiMOD,

			Sander van Leeuwen
			Meikoninginlaan 4
			2645 NT Delfgauw
			the Netherlands
			email: sandervl@xs4all.nl

For the latest updates of UltiMOD and the Manley drivers visit my webpage:
	http://www.polsci.wvu.edu/Henry/Sander or
	http://www.xs4all.nl/~sandervl
   
Greets go to:
	-  Robert Manley
	-  Timo Maier for the Pascal version of the GUS toolkit
	-  Juho Pesonen for his Pascal modplayer (ntsr3.zip)
	-  Henry Rieke for giving me my very own webpage
	-  Erik Hofman for borrowing his GUS Daughterboard (you will get
	   it back when I'm done, honest :) )
================================================================================
   7  Questions & Answers
================================================================================
Q: When I try to play a modfile nothing happens or OS/2 crashes. (GUS mode only)
A: Did you install the MMPM/2 drivers and specify the correct irq/dma/address?
   If nothing helps, send me a bug report and we'll try to work it out.
Q: What's wrong when UltiMOD reports it can't open the GUS MMPM/2 driver?
A: You shouldn't have Dos/WinOS2 sessions running that use the GUS or
   initialize the GUS in autoexec.bat. Close them and try again.
   In exclusive mode MMPM/2 applications should also be closed before 
   running UltiMOD.
Q: When I try to load a modfile, UltiMOD reports it can't load this file.
A: There are two possibilities: - you don't have enough memory on your GUS
				  to load all the instruments 
				- the file you selected isn't a valid modfile

================================================================================
   8  Bug Reports
================================================================================
If you experience crashes or bugs when you use UltiMOD, please send me mail
(email or snail mail) explaining the problem along with the following filled
in form and your config.sys. 

OS/2 version         : ______

GUS hardware revision: ___

Codec Daughtercard?  : _	(yes, no)

Onboard GUS memory   : ____ K

If you own another soundcard, specify the type and model.

================================================================================
   9 How to help improving UltiMOD
================================================================================
I and the beta testers try to locate any effect problems with UltiMOD.
Unfortunately we don't have unlimited amounts of time, so it's possible 
you have a modfile that UltiMOD doesn't play completely right.
I'd appreciate it when you report these problems to me. Please provide
as much information as possible:
	- file (send uuencoded by email or an address of an ftp site)
	- pattern and song position where the problem occurs
	- description 
	- if possible position inside pattern, channel and effect

Thanks in advance.

================================================================================
  10 Standard disclaimer
================================================================================
This software is provided AS IS.  No warranty of any kind, expressed or
implied, is granted including any warranties of quality or fitness for
a particular purpose.  Under no circumstances will Sander van Leeuwen be held
responsible for any damage that results directly or indirectly from the use of
this product.