digisnap's XM player now released!
----------------------------------
            RXM v1.0
- for pmode/w or pmode 2.51
- supports GUS, IW, SB and AWE
- resampling if out of memory
- includes the smallest GUS player
  (5.2k, 3.2k with pmwlite)
- now includes wav convert source

introduction:
Finally I released my XM player. This I already wanted to do two years ago.
RXM means "Reduced instruction set XM player". Normal XM players implement
the commands more than once, while this one includes only the minimum. The
tiny version of this player can become less than 3k (packed) if you don't
use all effects. If you want to include a tune directly into your source,
convet it with xm2bin.exe -b to a .bin file. This you have to convert into
db lines. If you want to load the tune from disk or out of your demo-
datafile, convert it with xm2bin.exe -B to a .rxm file. The only difference
is that this format includes the filesize at the beginning. After opening
it you just need to read the first four bytes into a int to see how much
mem you have to allocate.

IMPORTANT: depack the archive with subdirectories!

normal player:
Look into the file test.c and search and see how to initialize the player
from c/c++. The makefile.2 is there to recompile the xm2wav.exe file.
Parameter von xm2wav.exe:

xm2wav xmname.xm [parameters]

Demo/Intro XM file convert options:
-b                 : Convert to .bin file to include into intros
-B                 : Convert to .rxm file to load from hard disk (or archives)
                     for demos. It is exactly like the .bin format except
                     that the file length (without itself) is prepended.
                     Load the length, allocate mem and load the rest into the
                     mem to pass it to rxmplay().
General parameters:
xmname.xm          : XM-name, wildcards possible (default: *.xm)
-v x               : Volume (1 - 32, default: 12, FT2 compatible)
-r x               : Mixing rate (8000 - 48000, default: 44100)
-P x               : Maximum number of patterns to use
-R                 : Reverse stereo
Wav Convert parameters:
-c                 : Convert in 16 bit
-3                 : Convert in 32 bit
-p                 : Peak search (and convert)
-A x               : Amplification value in percent (does peak search)
-f                 : Fast convert (SB16 quality instead of best quality)
Play parameters:
-u                 : GUS: force GUS mode
-i                 : IW: force IW-mode
-8                 : SB16 : play in 8 bit mode
-m                 : SB16, SBPro : play mono 8 bit
-1                 : SB: play in DSP 1.xx mode (compatibility mode)
-a                 : AWE: use the ram to play back (2Mb recommended)
-M x               : SB, AWE: master volume (0-255, default: 0 = don't change)


tiny player:
Look into the file example.asm. If you convert your tune with xm2bin.exe -b
to a .bin file, a file fx.inc will be generated. It is included from
switches.inc. The player only becomes very small if you don't use interwave
support (enhanced = 0 in switches.inc) and don't use the resampling feature
(noResample = 1 in fx.inc).

pmode 2.51:
The player used to work with this extender, but I didn't test it for a long
time. For 64k intros it is the best to write and debug them with pmode/w,
and then port them to pmode 2.51. I then used wwpack to pack it. This saves
about 5k. I included pmode 2.51 with an extension to access the linear
framebuffer.

games:
There is a feature to allocate some channels for sound effects. Just set
gamesound = 1 in switches.inc. With the tiny player you can call playsound
(al = note, ah = instrument, dl = volume) to play a sound. With the normal
player you have to initialize this with gameinit() before you call
playsound().

synchronisation:
A variable "maincount" is provided for synchronisation. It counts with
1000Hz. You must not write on it. It has always the same speed relative
to the sound, even on Sound Blaster. If you need a procedure which is
called with constant speed, just do this:

mov eax,(frequency in Hz)*65536
mov edx,offset myhandler
call newhandler

Since the timer runs with 1000Hz the resolution is one millisecond. This is
not synchronized to the sound like "maincount". To remove the handler:

mov eax,0
mov edx,offset myhandler
call newhandler

If you need a procedure which is called some milliseconds later, do this:

mov eax,milliseconds (up to 65535)
mov edx,offset myhandler
call newhandler

You can use all registers in your hander. Finish it with a normal ret. If
you want to use more than two of these, you have to increase "hnum" either
in int.asm (normal) or tinyrxm.asm (tiny). The player also needs two.


conclusion:
This documentation is far from complete. But I hope enough for version 0.9 :)
if something seems buggy mail digisnap@cs.tu-berlin.de

