
               **********************************
               *       Ultimate Tracker 2.5     *
               *  A Virtual Xperience Software  *
               **********************************

            Written by : Thierry Schembri (Sharp Man)
            ----------   Didier Plaza (Checksum)



=================================================================
Introduction
=================================================================

This   software   plays  Amiga  or  Atari  Protracker   1.2a   or 
Soundtracker  (16 or 31 instruments) modules.  It works with  all 
Atari with a DMA soundchip (STe,  Mega STe, TT or Falcon). It can 
be used as a standard GEM application or as a desk accessory,  in 
that case, the musique can be played in background.

=================================================================
How to use Ultimate Tracker ?
=================================================================

1. As a standard GEM application (extension is .PRG or .APP)
~  ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Double  click  simply onto the player icon and the  desktop  will 
execute  it.  Once  the program loaded,  the main  window  (Panel 
Window  -  see lower -) is displayed on the  screen.  A  menu  is 
installed  to allow you to access to the desk  accessories  (like 
the CPX sound manager).

2. As a GEM application which needs parameters (.GTP)
~  ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Double  click  like before onto the player  icon.  A  dialog  box 
appears and asks you to enter parameters.  The needed  parameters 
are the path and the name of one or several modules, for exemple, 
if  your modules are located in the folder  C:\MODULES,  you  can 
enter as parameter C:\MODULES\SCHWARTZ.MOD where SCHWARTZ.MOD  is 
the module you wanna listen,  if you wanna listen several modules 
thanks  to  the  play list (- see lower  -),  you  can  enter  as 
parameter C:\MODULES\*.MOD. (In that case, all the modules of the 
folder C:\MODULES will be loaded in the Play List). Once the path 
and  the  name entered,  the player will load  automatically  the 
module and will be used in the same way as its extension was  PRG 
or  APP.  Notice  that  if  you  enter  Return  directly  without 
typing  any parameters,  the program will act as a  standard  GEM 
application.

Notice too that,  rather than typing the path and the name of the 
module,  you can drag the module icon and drop it onto the player 
icon. (This feature exists only with TOS versions > 1.7).

As the player supports parameters,  it is possible to install  it 
as an application for the .MOD files. To do it, proceed like this 
(on a AES > 3.3) :

- Click onto the player icon to select it.
- Click in "Install an Application" in the menu "Option"
- Type MOD in document Type
- Choose Window as path
- Choose Folder as parameters

Click  then  on Install and save the  desktop.  Then,  each  time 
you'll  double  click into the module icon,  the player  will  be 
automatically executed and will play this module.

3. As a desk accessory (extension is .ACC)
~  ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Install  the renamed player (U_TRACK.ACC) and its  resource  file 
(U_TRACK.RSC)  at the root of your boot disk (more often is  C:\) 
and reboot your machine.  The player will be automatically loaded 
and  installed in the accessories menu (first on the  left).  You 
can then invoque it from any application.  Thanks to it,  you can 
listen the music in background. Notice that it is not possible to 
use  the player as application for .MOD files when it is used  as 
accessory,   this  limit  is  outlined  by  the  program   called 
PLAY_ACC.GTP (explanations are given lower).


=================================================================
The menu
=================================================================

When  the  program  is  launched  as  standard  GEM   application 
(extension is .PRG, APP or GTP), a menu is installed to allow you 
to  access to the desk accessories.  Other options of  the  menus 
are:

Files
~~~~~

Load Module    Open the fileselector to load a module.

Stop & Quit    Stop the current music and leave the program.

Windows
~~~~~~~

Cyle windows   Activate the next window, for exemple, if you have 
               opened  two  windows  (Panel  &  oscilloscope  for 
               exemple),  if  the  active window  is  Panel,  the 
               choice   of   this  option   will   activate   the 
               oscilloscope  window  and  de-activate  the  panel 
               window.

Panel          Open or close the panel window. When the window is 
               opened, a mark appears in the menu before the word 
               Panel.

Oscilloscope   Open/close the oscilloscope window.

Vu-meter       Open/close the vu-meter window.

Play List      Open/Close the play list window.

Config         Open the configuration dialog box.

All  the  menu  options can be accessible  directly  through  the 
keyboard, you have to press the Alternate key and :

L              Load Module
Q              Stop & Quit
P              Panel
O              Oscillo
V              Vu-meter
E              Play List
C              Config

To cycle windows, you have to press Control + W.
To get information, press Control + I.

=================================================================
The panel window
=================================================================

The panel window is the main window of the Ultimate  Tracker,  it 
allows to access to all other windows and to control the way  the 
module is played.

1. Vu-meter & oscilloscipe buttons
~  ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

The  icons  which  are  on  the left and  on  the  right  of  the 
information  bloc  open  or close the  vu-meter  or  oscilloscope 
windows.

2. The next, previous and List buttons
~  ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

The  List  button opens or close the play list  window,  the  two 
arrowed  buttons located on the left and the right of the  module 
name  are used to go to the next or previous modules  if  several 
ones have been loaded in the play list.  When the begining or the 
end  of  the  list is reached,  the previous or  next  button  is 
lighted to show it is impossible to continue.

Under  these  buttons  and the module  name,  there's  a  graphic 
display of the current position of the music in the module.

3. the icons
~  ~~~~~~~~~

Under this display, there are 5 icons (from left to right):

Load      Load one or several modules.
          After  clicking  on  this  icon,  the  fileselector  is 
          displayed to choose one or several modules to load.  It 
          is  possible to choose several  modules  simultaneously 
          thanks  to  the  wildcards of the dos  (*  or  ?),  for 
          exemple,  if  we  wanna  load all the  modules  in  the 
          playlist,  we  have to enter as filename *.MOD,  if  we 
          want  to load only the modules which begin with  A,  we 
          have  to enter A*.MOD.  All combinations  are  possible 
          knowing that * replaces all characters and  ?  replaces 
          only one.

          It  is possible to load compacted modules,  the  player 
          will   unpack  it  automatically  before  playing   it. 
          Supported packers are : Pack Ice (all versions), Atomik 
          Packer 3.5 (& 3.5+),  Power Packer 2.0  (Amiga),  Speed 
          Packer 3 and Noisepakker 1.0.

          Noisepakker  is  a  packer  especially  made  for  pack 
          modules (it is in the package), its drawback is that it 
          compacts with loss (the packed modules have sound  with 
          lesser quality than the unpacked ones),  its  advantage 
          is that it can compact with a ratio of 50%, more other, 
          we can pack a Noisepakkered module with pack ice,  pack 
          ratio can approach 70% ! Ultimate Tracker supports this 
          double pack.

          *  Watch out : when  the  soft  is  launched   as  desk 
                         accessory,  the  size  of  the  unpacked 
                         module  can exceed the defined  size  in 
                         the config box (see lower).

Rewind    Fast rewind

Play      Play the music

Forward   Fast Forward

Pause     Stop the music. Click there again to play.

Stop      Stop the music,  if you click then onto Play, the music 
          will play from its begining.

4. Frequencies
~  ~~~~~~~~~~~

There are 4 buttons under the icons,  these buttons allow you  to 
choose the frequency.  Available frequencies are 6.25  Khz,  12.5 
Khz, 25 Khz and 50 Khz.
Some  frequencies are not available on all machines.  On  Falcon, 
6.25  Khz  isnt' available (the DMA soundchip of the  Falcon  can 
restitute sound at this frequency) and 50 Khz isn't available  if 
the CPU frequency is 8 MHz,  50 KHz isn't available too on STe or  
Mega STe.  On Mega STe,  50 KHz is available if the CPU frequency 
is 16 MHz with cache ON.

Notice that tha more the frequency is high, the more the sound is 
good,  but  the  more  the music  takes  CPU  time.  It's  pretty 
important to choose the right frequency if you use the player  as 
a desk accessory because other running applications will be  more 
or  less slowed by the player.  (Personnaly I think that 12.5  is 
the right value for a STe (even if you can listen at 25),  25 for 
a mega STe or Falcon030 and 50 for TT).

*  Warning :   A  lot of tests are done :  according the  machine 
   -------     and the CPU frequency,  some frequencies will  not 
               available.  If you use a MegaSTe 16 MHz and listen 
               50  KHz music,  if you switch the CPU speed  to  8 
               MHz,  the frequency will be switched automatically 
               to 12.5 KHz and 50KHz will be unavalable until the 
               CPU speed will be switched to 16 MHZ. Also for the 
               Falcon,  if  you listen a 50 KHz music and if  you 
               switch off the 68030 caches, the frequency will be 
               switched  automatically.  But Please,  don't  play 
               with caches and CPU speed when a module is played.

5. Other buttons
~  ~~~~~~~~~~~~~

Under these 5 icons, there are 3 buttons :

Quit :    Close the player windows and stop the music.
          If you use the program as PRG,  APP or GTP,  you can do 
          the  same  thing with the option "Stop & Quit"  of  the 
          menu Files.

Play :    This  button is only available if the program is a desk 
          accessory.
          Clicking  onto this button will close the  the  windows 
          but the music will continue to be played.

Config:   Configure the player.


=================================================================
The play List window
=================================================================

This window allows you to orgarnize a list of modules which  will 
be played in the order you want during the time you want.
When  you load a module with the icon "Load" in the panel  window 
or  thanks the option "Load module" in the file  menu,  this  one 
will be automatically put in the play list.  As we saw it  upper, 
il  is  also  posible  to load several  modules  (thanks  to  the 
wildcards) and to play successively them with the arrowed buttons 
located  on  the right and the left of  the  module  name.  These 
differnts  modules which gonna to be played are put in  the  play 
list.

The playlist window looks like that :

On the top, the box "Total" shows the number of loaded modules in 
the playlist,  the box "Playing" shows the number of the  current 
played module,  under these two boxes,  there is the module list, 
we can move through this list thanks to the arrowed buttons (line 
by line) or the buttons + or - (page by page).  The played module 
name is preceded by a note.  If you wanna listen directly one  of 
the modules of the list, you just have to double-click onto it.

Under this list, there are 6 icons :

Remove    If you wanna remove one of the module,  click onto  it, 
          it  will be inversed,  the Remove button is  unligthed, 
          click onto it : the module is removed from the list.

Add       You  can add a module to the list,  after  clicking  on 
          this icon,  the fileselector appears and you choose the 
          module to add to the list.  The choosen module will  be 
          added at the end of the list if no module is  selected. 
          If a module is selected before adding an other one, the 
          new module will be added after the selected module.

New       Erase the current play list.

Load      Load a play list previously saved with the "Save" icon.

Save      Save the play list in an ascii file.

Repeat    This  switch  shows according  its  selection,  if  the 
          player has to wrap once it has finished or if it has to 
          stop.

Under these 6 icons, there are 2 boxes :

The  "Play Time" box shows the play time of the module,  you  can 
change this duration,  if for exemple, you want to listen only 15 
secondes of each module, click onto this box. Enter this duration 
under  this  mask  HH:MM:SS (HH is hour,  MM  is  minute,  SS  is 
seconde),  in our exemple, you will enter 00:00:15. To invalidate 
the play time (the module will be played till its end), just type 
00:00:00.
The box located on its right shows in  hours,  minutes,  secondes 
the elapsed time since the begining of the module.

=================================================================
The Vu-meter and oscilloscope windows
=================================================================

These two windows shows respectively a "frenquency analyzer"  and 
the representation of the played sample.

=================================================================
the configuration box
=================================================================

As  we saw it upper,  this box is displayed when we click on  the 
"Config"  button  of  the  panel window or if  we  click  on  the 
"Config" entry in the "Windows" menu.  It configures the  default 
parameters of the player.

1. Buffer size
~  ~~~~~~~~~~~

When  the  program is used as  .PRG,  .APP,  .GTP,  this  box  is 
lighted.  It  is  available  only with  desk  accessory.  A  Desk 
accessory can't allocate memory dynamically. That's for why, when 
the  program is used as a accessory,  the player reserves  during 
the boot a buffer where it gonna load and unpack the modules.
By default,  the reserved size is 256000 bytes (in fact 256000  + 
36000  bytes...)  You can increase or  decrease  this  size,  but 
notice  that this new value will be effective only the next  time 
you'll  launch the accessory because allocation is done when  the 
ccessory is loaded. 
The  upper part of the box displays the current  reserved  memory 
size  and  the lower part (where you gonna enter  the  new  size) 
contains the size of the memory which gonna be reserved the  next 
time you'll launch the accessory.

2. Default path
~  ~~~~~~~~~~~~

You can choose the default path where the player will search  the 
modules.  To choose it,  click onto the "Choose path" button, the 
fileselector appears for that. The choosen path is displayed into 
the  box?  If  it doesn't fit into the box,  you can  see  it  be 
clicking onto the arrowed buttons.

3. Falcon030 replay routine
~  ~~~~~~~~~~~~~~~~~~~~~~~~

By default,  the replay routine on Falcon030 is 8 bits stereo and 
uses  the 2 DMA STe channels.  You can change (if the version  of 
Ultimate Tracker allows it) the replay mode,  you can listen  the 
sound  with 16 bits stereo (which in fact add nothing  more  than 
the 8 bits mode because all the samples of the modules are 8 bits 
samples), this option will use more CPU time. You can also choose 
to listen the sound with 16 bits stereo with the DSP.  Unlike the 
two  first  modes,  it's the DSP which is  used  here,  the  main 
advantage  is that the machine isn't slowed with a sound 16  bits 
50KHz,  however,  it is impossible to use the DSP to unpack  JPEG 
pictures in GemView or make sound effects with AFM for exemple.

To save these parameters,  click onto the SAVE button (Cancel  to 
quit). The new parameters are saved directly into the file of the 
program,  that's for why a fileselector appears to indicate where 
is  the  player.  As the parameters are saved directly  into  the 
file,  you  can't  modify the file structure by  packing  it  for 
exemple.  In  fact,  you can pack it,  but you have to unpack  it 
before saving parameters, then you will able to pack it gain.

=================================================================
Ultimate Tracker & MultiTOS
=================================================================

Ultimate  Tracker works fine with MultiTOS on all  machines  I've 
tested (STe,  TT,  Falcon).  It works fine too with great screens 
and graphic card (I've tested on Spektrum).  The resource use the 
AES features on STe or TT.
Watch  out  :  don't change the program flags (with  the  program 
PRGFLAGS.PRG),  this  program must have the bit "SUPER" set to  1 
because it uses a timer under MultiTOS,  if it is set to  0,  the 
system will crash.
WARNING  !  Never kill the process when the player is  playing  a 
module  because the memory used by the interrupt routine will  be 
free without prevent the player.  Stop the music,  then, kill the 
process.

=================================================================
The APPL_WRITE commands
=================================================================

GEM provides a way to communicate between applications through an 
event buffer. This allow an application to take conrtrol of other 
one.   Ultimate   Tracker  supporte  these  commands,   so   your 
application can pilot the player.

How does it work ?

Before all,  the player must be resident in memory.  The only way 
to do it is to install it as a desk accessory with a  monotasking 
TOS, you can install the way you want with MultiTOS.

Then,  you  have  to find the AES identification of  the  player, 
there are two ways to find this id.  The "nice" method is to  use 
the AES function appl_find like this:
id=appl_find(name)  where name is the name of the player  without 
its  extension,  the name must have 8 characters.  This  function 
returns the AES id. If you don't know the player name, there's an 
other  way to proceed,  when it is installed,  the player  put  a 
cookie into the cookie jar.  This cookie is "UTRK" and the  datas 
of  the cookie are its AES id.  Watch out and use this method  if 
you're sure you can't find the id with the appl_find command. You 
can  imagine easily the problems if there's sevaral instances  of 
the program in memory,  you can't be able to know who belong  the 
AES id returned by appl_find or by the cookie jar.

* Warning :  up to now,  the player can't communicate with only a 
program once a time.  If two programs try to be identified by the 
player, only the last identified one will be recognized. 

1. The commands
~  ~~~~~~~~~~~~

Thanks to this AES id,  you can control the player by sending  it 
messages with the AES function APPL_WRITE.  This function needs 3 
parameters :  the player identification,  the number of bytes  to 
send  (ALWAYS <= 16) and the address of an array of integers  (16 
bits).  This  array  will  contain the command to  send  and  its 
parameters.

The  commands have this format (I want to excuse myself before  I 
had  to  change  the  format of these  commands  since  the  last 
version, because their format wasn't the AES format).

- 1st word     (0)   : # command
- 2nd word     (1)   : AES id of the program which send command
- 3rd word     (2)   : always 0
- 4th word & + (3-7) : parameters

Commands are :

T_LOAD         (900) : Load a module. The address of the path and 
                       the  name of the module are in the word  3 
                       and 4 (high part in 3 and low in 4).
T_PLAY         (901) : Starts the music.
T_FORWARD      (902) : Forward.
T_REWIND       (903) : Rewind.
T_PAUSE        (904) : Pause ON/OFF.
T_STOP         (905) : Stop the music and re-initialize it.
T_ABOUT        (906) : Displays the information box.
T_OPEN         (907) : Open the panel window.
T_CLOSE        (908) : Close the panel window.
T_FREQ         (909) : Change  the frequency. the frequency is in 
                       the word 3 (0/1/2/3 -> 6/12/25/50 Khz).
T_LOOP         (910) : Switch the Loop mode ON/OFF.
T_IDENT        (911) : Tell  to  the player that the  application 
                       want to receive messages from it.
T_FIDENT       (912) : Tell  to  the player that the  application 
                       doesn't want more messages.
T_INFOS        (913) : Ask informations to the player
                       (see lower for the answer)
T_OPN_OSCILLO  (914) : Open the oscilloscope window.
T_CLS_OSCILLO  (915) : Close the oscilloscope window.
T_OPN_PLAYLIST (916) : Open the play list window.
T_CLS_PLAYLIST (917) : Close the play list window.
T_NEXT_MOD     (918) : Jump to the next module.
T_PREV_MOD     (919) : Jump to the previous module.
T_OPN_VUM      (920) : Open the vu-meter window.
T_CLS_VUM      (921) : Close the vu-meter window.
T_SEL_PLST     (922) : Select  a  module in the  play  list.  The 
                       number  of the selected module is  in  the 
                       3rd word.
T_REMOVE_PLST  (923) : Remove the selected module from the list.
T_ADD_PLST     (924) : Add  a module to the play list,  the  path 
                       and  the  name are in the words  3  and  4 
                       (like T_LOAD).
T_NEW_PLST     (925) : Erase the current play list.
T_LOAD_PLST    (926) : Load a new play list.
                       See T_ADD_PLST for the play list name.
T_SAVE_PLST    (927) : Save the current play list.
                       See T_LOAD_PLST for the filename.
T_LOOP_PLST    (928) : Switch the REPEAT flag ON/OFF.
T_TIME_PLST    (929) : Set the play time.
                       Hours are in word 3, minutes in word 4 and 
                       seconds in word 5.
T_CYCLE_WIN    (930) : Cycle windows.
T_PLAYLIST     (931) : Ask for the play list address.
                       (see R_PLAYLIST for the answer).

To  see  how to use these commands,  have a look in  the  program 
called \EXEMPLE\SHELL\CMD_TRAX.C.  It's a shell which control the 
player.

Note:     If you use this with MultiTOS,  don't forget to set the 
----      "GLOBAL" flag of your application because when you will 
          send the command T_LOAD (or any command which give  the 
          address  of  a string),  the player will  read  at  the 
          address  you gave it to find the pathname  module,  but 
          this address is located in your application memory.
          The  "GLOBAL" flag allows the player to read  into  the 
          memory application.  If this flag isn't  set,  MultiTOS 
          gonna  make  a memory protection error and  remove  the 
          player from memory. 

2. Received messages
~  ~~~~~~~~~~~~~~~~~

If you can send messages to the player,  you can receive messages 
too.  These  messages tells to the application all the player  is 
doing. To receive these message, you have to proceed like this :

- Tells  to the player that you wanna receive messages  with  the 
  command T_IDENT. 
- Wait for messages in a EVNT_MULTI or EVNT_MESAG loop.
- When  the application needs no more message,  send the  command 
  T_FIDENT.

Message have this format :

- 1st word          (0) : message number
- 2nd word          (1) : player AES id
- 3rd word          (2) : always 0
- 4th word and +  (3-7) : informations

Messages are :

R_PLAY         (951) : The music is starting.
R_FORWARD      (952) : Fast Forward.
R_REWIND       (953) : Fast Rewind.
R_PAUSE_ON     (954) : Pause ON.
R_PAUSE_OFF    (955) : Pause OFF.
R_STOP         (956) : The music is stopped.
R_OPEN         (957) : The panel window is opening.
R_CLOSE        (958) : The panel window is closing.
R_FREQ         (959) : The frequency has changed (in word 3).
R_LOOP_OFF     (960) : Loop mode OFF.
R_LOOP_ON      (961) : Loop mode ON.
R_BEGLOAD      (962) : Module starts to be loaded.
R_ENDLOAD      (963) : End of loading.
R_FAILOAD      (964) : Error during loading module.
R_MOVE         (965) : Panel window is moving.
                       word 3 : new X coord.
                       word 4 : new Y coord.
R_INFOS        (966) : Answer to the command T_INFOS.
                       word 3 : panel window handle.
                       word 4 : VDI handle.
                       word 5 : version  (major number in high  8 
                                bits and minor in low 8 bits).
                       word 6 : oscilloscope window handle.
                       word 7 : vu-meter window handle.
                       word 8 : play list window handle.
R_POSIT        (967) : Music position.
                       word 3 : current position.
                       word 4 : last position.
R_QUIT         (968) : Quit the player (& stop the music).
R_ENDMOD       (969) : Module has reached its end.
R_PROTECMOD    (970) : Protected module.
                       This  message is received when the  loaded 
                       module contains corrupted informations. So 
                       it  is impossible to know when the  module 
                       is finished,  so it will be impossible  to 
                       go   forward,   go  back  or  receive   an 
                       available  R_POSIT  message.  (It  arrives 
                       when the module is badly ripped...)
R_OPN_OSCILLO  (971) : The oscilloscope window is opening.
R_CLS_OSCILLO  (972) : The oscilloscope window is closing.
R_MOVE_OSCILLO (973) : The oscillo window is moved.
                       word 3 : new X coord.
                       word 4 : new Y coord.
R_OPN_PLAYLIST (974) : The playlist window is opening.
R_CLS_PLAYLIST (975) : The playlist window is closing.
R_MOVE_PLAYLIST(976) : The playlist window is moved.
R_NEXT_MOD     (977) : Jump to the next module.
R_PREV_MOD     (978) : Jump to the previous module.
R_OPN_VUM      (979) : The vu-meter window is opening.
R_CLS_VUM      (980) : The vu-meter window is closing.
R_MOVE_VUM     (981) : The vu-meter window is moving.
R_PLAYLIST     (982) : Give the  playlist address in the words  3 
                       (high part) and 4 (low part). The playlist 
                       can be defined by the following C struct :

                       typedef struct liste_mod
                         {
                         char                *nom;
                         struct liste_mod    *suivant;
                         struct liste_mod    *precedent;
                         }LISTE_MOD;

                       It's  a  chained list in  two  ways  which 
                       contains a char pointer.
R_SEL_PLST     (983) : A  module has been selected. Its number is 
                       in word 3.
R_REMOVE_PLST  (984) : Remove the selected module from the list.
R_ADD_PLST     (985) : Add  a module to the  play  list.  Module 
                       address is in words 3 and 4.
R_NEW_PLST     (986) : The playlist has been deleted.
R_BEG_LOAD_PLST(987) : The playlist starts to be loaded.
R_BEG_SAVE_PLST(988) : The playlist starts to be saved.
R_LOOP_PLST_ON (989) : Repeat switch ON.
R_LOOP_PLST_OFF(990) : Repeat switch OFF.
R_TIME_PLST    (991) : The play time has been changed.
                       word 3 : hour
                       word 4 : minute
                       word 5 : seconde
R_CUR_TIME     (992) : Elapsed time since the module starts.
                       (time like R_TIME_PLST).
R_CYLCLE_WIN   (993) : Windows have been cycled.
R_DEL_PLST     (994) : Playlist  has  been deleted (internal  way 
                       not with New List).
R_END_SAVE_PLST(995) : End of saving playlist.
R_END_LOAD_PLST(996) : End of loading playlist.
R_FAIL_LOAD_PLST(997): Error during loading the list.
R_FAIL_SAVE_PLST(998): Error during saving playlist.

To  see  how run the message reception,  see the  program  called 
\EXEMPLE\RECEIVE\RECEIVE.C

Note:  If you use the reception with MultiTOS,  you have to be in 
----   Supervisor mode if your application access to the filename 
       module  in  the  message  T_BEGLOAD  or  to  the  filename 
       playlist in the message T_LOAD_PLST or T_SAVE_PLST because 
       you want to access  to an address which is located in  the 
       player  memory and this memory area has its  "SUPER"  flag 
       set,  so  this memory can only be accessed  in  supervisor 
       mode.

=================================================================
Limitations
=================================================================

There are some limitations in this program :

- The program doesn't test if the loaded file is a module or not, 
  if  you  load  a Degas picture  for  exemple,  it  doesn't  say 
  anything, it will crash...
- To  be sure that the sound will be correct,  put in  your  AUTO 
  folder the program called FPATCH.PRG (only for Falcon030 with a 
  TOS version lower than 4.92). This program is usually found  in 
  the disks given with the Falcon030.
- It seems that there's incompatibility between Ultimate  Tracker   
  and  the screen saver Midnight ONLY on TT with TTram  (???).  I 
  gonna try to fix this bug.

There's  problems which can happen when the program is used as  a 
desk  accessory.  An accessory can't allocate memory  dynamically 
(with monotask TOS),  so AVOID LOADING OR MODIFYING playlist when 
the accessory is opened on an application. (You can do it when it 
is  opened  onto the desktop).  I have great  problems  with  the 
fucking memory manager of the TOS,  if you have solutions, please 
write to me !!!
Always when the program is used as a desk accessory,  you have to 
stop  the  music (not pause,  but really  STOP)  before  changing 
resolution.  If you change resolution without stopping music, the 
system will crash.

=================================================================
External programs
=================================================================

There's three programs in this pack :

- SHELL :  A little shell which use the APPL_WRITE commands.  Use 
  it  with  a windowed shell or with MultiTOS and  MintShell  (or 
  your favorite shell).  Watch out !  if you use it with TCShell, 
  don't  forget  that this shell interpret the character  \  like 
  the C,  for all files operations, you have to double the \. For 
  exemple to load a module, tou have to enter :
  cmd_trax LOAD C:\\MODULES\\SCHWARTZ.MOD

- RECEIVE :  A  sample program which displays the  sent  messages 
  from the player to an application.  Thanks to this example  and 
  the first one, you can see how establish a communication in two 
  ways between Ultimate Tracker and an application.

- PLAY_ACC :  A program which allows you to use the player  which 
  is  installed  as an accessory as an application for  all  .MOD 
  files.  Install this program as an application in the  desktop, 
  and  each time you'll double click onto the icon  module,  this 
  program  will be executed and will send the loading command  to 
  the desk accessory.

=================================================================
Sources
=================================================================

I decided to give the whole sources of this program.  The sources 
can't be given separately from the rest of the pack.  If you  fix 
bugs in the program or if you modify the sources, PLEASE, send me
your modification,  it's a bit stupid if a lot of version of this 
program exist ! 

This program was done with Pure C 1.1. I hate conditional assemby 
to allow to different compilers to use the sources. These sources 
will work fine only with Pure C 1.1 (you'll probably have problem 
with  older  version  or with Turbo C coz  the  Falcon  libraries 
doesn't exist).
All assembler parts were done with Pure Assembler, so you can use 
them  directly from the Pure C EDI. However, there are some files 
which were done with Devpac 3 (assembled as DRI object file). 
These files are ATOMIK.S (ATOMIK unpacker)  and  the  two  replay 
routines (m_play_f.s for the Falcon030 and m_play_s.s for Ste-TT) 
The resource were done with RCS 3.1. Be careful, make a backup of 
your resource before saving it in low resolution :  all the  high 
resolution  trees in this ressource will be destroyed  (with  all 
ressource editors).

That's all for the sources, good luck with them...

=================================================================
Informations
=================================================================


To contact us, you can write to :

Thierry Schembri / Didier Plaza
Virtual Xperience
21 rue de la Fontaine-Au-Roi
75011 PARIS
FRANCE.

or to :

TBC / EQUINOX
Chlet de Riqueval
02430 BELLICOURT
FRANCE

You can join too us on :

* our mailbox on french minitel :
  3614 RTEL2 - BAL SHARPMAN or BAL CHECKSUM

* On CompuServe : 70735,532

* On InterNet : 70735.532@Compuserve.com

=================================================================
History
=================================================================

v.1.0   - Just load and plays modules on Falcon
v.1.1   - Plays modules as a desk accessory (accept Packed 
           modules with Pack Ice)
v.1.2   - New graphix interface.
v.1.4   - Correct lots of bugs. 
v.1.5   - Supports Power Packer 
v.1.6   - Supports STe/TT replay routines
v.1.7   - works fine under Multitos/supports APPL_WRITE cmds
v.1.0    - Supports AES 4.0 on STe or TT
v.1.1    - Supports all Pack Ice version and Noisepakker 1.0
v.1.2    - Allows to save default path
v.1.3    - Speeded up Falcon replay routine by NOP/DSP CREW 
v.1.4    - I fixed a lot of fucking memory bugs
v.1.5    - "New" player routine
         - Allows to change frequency on Falcon030
         - Fixes display bugs
         - Uses 030 cache on TT and memory cache on MSTe
v.1.7    - Fix a lot of bugs
v.2.0    - Allows communication with a shell in two ways
         - Use MFP i7 instead of Timer A
         - Shows current position
v.2.1    - Fixes memory bugs
         - Check CPU speed changes on Falcon & Mega STe
         - Supports jokers (* and ?)
v.2.2    - Supports Atomik Packer 3.5
         - New menu bar
         - Oscilloscope window (and new shell messages)
v.2.3    - New menu bar
         - Vu-meter window (and new messages)
v.2.5    - New panel menu
         - Play List
         - Fixe bugs
         - New messages

Soon coming :

- DSP & 16 Bits replay routine : In fact there are already done 
  but I have fucking timing problems to use then with GEM.
- "True" spectrum analyzer on Falcon030.
- Limited edition features.
- different Play Time for each module.
- Drag'n'drop with MultiTOS (already done...)


