-----------------------------------------------------------------------------
File name:	DSPT.DOC			Revision date:	1999.19.21
Createded by: 	Ronald Andersson		Creation date:	1999.19.21
-----------------------------------------------------------------------------
Copyright (c)1999 Ronald Andersson		Released as:	FREEWARE
-----------------------------------------------------------------------------
Addresses for Mail and updates:			mailto:dlanor@ettnet.se
http://www.ettnet.se/~dlanor/	or (same page)	http://dlanor.atari.org/
-----------------------------------------------------------------------------
DSPT is a module player with some differencies from most of them, in that it
boots from the \AUTO\ folder and installs a cookie interface allowing other
programs to call its functions to play MOD-files, and manipulate various
parameters to that playing, as well as to request that DSPT find out some
information about a loaded mod.
-----------------------------------------------------------------------------
NB: DSPT is at present dependent on a DSP existing in the system, so if you
    use only a normal ST/STe or TT, then this program suite is not for you.
    Sorry about that guys, but I simply can't emulate a DSP even for you,
    and I don't have time to work on DMA sample stuff (not to mention PSG)
    at present, being far too busy with work on STinG components.
-----------------------------------------------------------------------------
NB: DSPT does not at present support MODs packed with ICE etc, so if you do
    not have room for unpacked modfiles, then forget it.  Perhaps a later
    version may support such things, but I have no motivation for it myself.
    My own MOD collection is in unpacked form on a CDROM, so why bother...
-----------------------------------------------------------------------------
Thanks go to NoCrew for passing the info on the Dsp_ExecProg bug in TOS, so
that I could finally release this project, which has been in the works for
over two years now, unreleased because that bug locked up the system...
-----------------------------------------------------------------------------
Thanks also go to Simplet, from whose sources I learned much DSP programming.
-----------------------------------------------------------------------------
DSPT's cookie interface is still in a rather early stage of development, but
has already sufficient functions to make some simple client implementations
possible, thus making an early release meaningful.
-----------------------------------------------------------------------------
Module playing clients currently available for DSPT:

MODYIELD.PRG	;TSR program for \AUTO\ useful as singleTOS background player
RND_PLAY.APP	;GEM program most useful as background player in multitasking
PASS_MOD.APP	;useful only for drag&drop selection of MODs to be played

All three of the above are 'interfaceless' clients. They do what needs to
be done without any dialogs or other common communication with the user.

PASS_MOD is used only by drag&drop or d-click on modfiles to play modules,
or by d-click on PASS_MOD itself to stop the playing.

RND_PLAY and MODYIELD are both mainly intended for continuous random playing
of modfiles out of a large collection folder, which can have subfolders too.
Read the comments in AUTO_MOD.INF to find out some more details on this.

RND_PLAY will also accept drag&drop or normal argument lines giving the path
of a single module to play, but as that module ends it will automatically
take up the random playing again, from the collection folder specified in
the AUTO_MOD.INF file, which must reside in the root directory of the boot
drive/partition.  Note however, that in order to do continuous random play
RND_PLAY needs to be run in multitasking.  Under singletasking it will only
pass the randomly chosen modfile to DSPT for playing and will then exit.
That module will then play continuously until you run a DSPT client again.

For singletasking continuous random play you need to install MODYIELD.PRG
in the \AUTO\ folder on the boot drive\partition such that it starts after
DSPT.PRG.  It will then read AUTO_MOD.INF and interpret it identically to
how RND_PLAY does. Again I refer you to that INF file to read the comments.

MODYIELD has been tested error free under MagiC 6 as well, and may well be
compatible to other multitaskers too.  One good thing about having player
clients as TSR under multitasking is that no other program can remove a TSR,
whereas they can easily kill a parallel APP, either wantonly or by mistake.

It is also fully legal to mix use of MODYIELD, RND_PLAY, and PASS_MOD, though
some of the combinations make little sense, but PASS_MOD is useful with both
of the others, both to play specific user-selected MODs and to turn playing
off.  The mini-clients discussed below may also mix freely with the above.
-----------------------------------------------------------------------------
Mini-clients currently available for DSPT:

MOD_PATH.APP	shows the pathname of the latest modfile loaded by DSPT
		in a simple alert

All the ones below make no display whatever of any results, as all they do
is to send a single command each to the DSPT server.

DT_BEGIN.PRG	Instantly restarts the current mod from the beginning
DT_STOP.PRG	Stops the playing of a mod, but keeps it and its position
DT_PLAY.PRG	Starts the playing of a mod, at current position
DT_DUMP.PRG	Stops the playing of a mod, and dumps it from memory

The two clients directly following do not take full effect until the next
module is loaded, as the new mode must be selected when adapting samples
for the mode to be effective.  This means that when used during play of
one mod, to switch interrupt mode, that mod will continue playing in the
new mode, but with samples that are not so well adapted for it. (reload)

DT_TIM_A.PRG	Selects use of timer A (default) for module tracker routines
DT_VBI.PRG	Selects use VBI interrupts for module tracker routines

The next four clients set a volume boost level.  This acts directly on
the sample scaling, so top level can cause distortion for modules that
themselves use high amplitude settings.

DT_VOL_0.PRG	Sets boost at normal level -12dB
DT_VOL_1.PRG	Sets boost at normal level -6dB
DT_VOL_2.PRG	Sets boost at normal level (default)
DT_VOL_3.PRG	Sets boost at normal level +6dB

The next four clients reorder the voices (up to 8 voices at present),
amongst the right and left channels.

DT_ORD_0.PRG	Sets order LRRLLRRL	normal		(default)
DT_ORD_1.PRG	Sets order RLLRRLLR	reversed
DT_ORD_2.PRG	Sets order LRLRLRLR     Odd pairs reversed
DT_ORD_3.PRG	Sets order RLRLRLRL     Even pairs reversed

Note that there is a Thing group file available for the above clients that
may simplify their use.  I designed this in 1280x960, so you may need to
adjust position and size of the window, and if you do not already have my
ANSI6PIX font family, then you need to copy this to GEMSYS\ and ASSIGN.SYS
of course.  Users of TT-Medium or similar resolutions will find that font
very useful as it also allows GEM windows with 101 characters width of the
work area even when the window has the full gadget set.
-----------------------------------------------------------------------------
APOLOGIA:

DSPT does not really have top quality sound, compared to what I know I could
achieve if I had more time to work on it, but it does have a unique system
for background play, which I feel makes it well worth using.  The quality of
the sound will hopefully be improved when I have more time for that, as will
the breadth of support for various MOD variants, and packing systems.  At
present it does work fine for 99+ % of the standard MODs I have, and that
suffices for my own needs at present.

Still, there are apparently some holes in my knowlwedge about MOD commands
(the internal ones used in 'patterns' of songs), as some MODs sound quite
strange while others sound excellent.  Also, one MOD that I  know of has
the effect of crashing my player (U96.MOD == "Das Boot" of 351546 bytes).

I would appreciate it if anyone discovering more such report this to me,
and if anyone has a clue as to any misimplemented MOD commands then I
would naturally appreciate information on that subject as well.
-----------------------------------------------------------------------------
End of file:	DSPT.DOC
-----------------------------------------------------------------------------
