                      Ultimate Tracker 2.2

                   * A Retour 2048 Software *

          By : - Checksum of Equinox (Amiga adaptation)
               - Edy of Equinox (Falcon adaptation)
               - Sharp Man of The Black Cats (Program)

_________________________________________________________________                                                               

                       English Documentation
_________________________________________________________________                                                               


1. Overall
=  =======

   This program replays Amiga (or Atari) soundtracker, Noisetrac-
   ker  or  Protracker 1.2 modules.  It runs on all Atari systems 
   with a DMA soundchip (STe,  Mega STe, TT or Falcon). It can be
   used as well as a normal program as a desk  accessory. 

   Since  the version 2.0,  the player uses the MFP i7  interrupt 
   instead  of  the  timer  A.   So  now,  all  timers  are  free 
   (particulary the timer used by AES in evnt_timer).
 
2. How does it run ?
=  =================

   There's three ways to launch this program :

   As a normal program (extension is .PRG or .APP)
   ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
   Just click onto the icon of the player to launch it.  When the 
   program is loaded,  the player is displayed into a GEM window. 
   There's  also  a GEM menu to access to  the  desk  accessories 
   (like  the CPX sound manager).  You can load a module or  quit 
   the program directly or close/open one of the  windows  thanks 
   to this menu.

   As a GEM program which needs parameters (extension is .GTP)
   ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
   Click onto the icon of the player to launch it. Then, a dialog 
   box  appears  and asks you  to  enter  parameters.  Parameters 
   needed are the path and the name of a module, just type it and 
   press  return.  The  player  will load  and  play  the  module 
   automatically. If you type return without typing anything, the 
   program will act in the same way of a normal GEM program. Note 
   that  you can drag the icon of a module and drop it  onto  the 
   icon of the player, the player will load and play this module. 
   (This last feature is available only with TOS version > 1.62). 
   Thanks  to  this feature,  you can install the  player  as  an 
   application  for the files *.MOD in the menu "options" of  the 
   desktop. When you'll click onto a module, the player will play 
   it automatically.

   As a desk accessory (extension is .ACC)
   ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
   Install  the player on the root of your boot disk  and  reboot 
   the computer,  the player will automatically loaded,  then you 
   can invoque it from any application.  Moreover you can play  a 
   module  everywhere  in  background.   This  feature  is   only 
   available when the player is launched as a desk accessory. You
   can use the accessory as an application for *.MOD files thanks
   to the program "PLAY_ACC.GTP".

3. Little explanations
=  ===================

   1. The Icons
   ~~~~~~~~~~~~
   The player is displayed into a standard GEM window.  Its icons 
   are easy to understand, from left to right :

   Load  :  Loads a module into memory.  The size of  the  module 
   ----     must  fit into the buffer (see lower). If the program 
            is  launched as a PRG, APP or GTP, you can also  load 
            a module  from the menu. The player can  load  module 
            packed with Pack Ice any version (Atari packer),Power 
            Packer (Amiga packer) or Noisepakker 1.0  from  Delta 
            Force, it will depack it automatically before playing 
            it. (New ! : you can load modules packed  with  Power
            Packer or Noisepakker then packed again with pack ice
            pack ratio for Noisepakker+Ice is more than  70% !!!)
            (v2.2 supporte Atomik Packer 3.5).

			You can (>v.2.0) make a "play list", instead  of  gi-
			ving a full filename, you can use jokers (? and *).
			When a module is finished, the player will  load  au-
			tomatically the next one (matching with the jokers).
			If one of the module is too big  to  be  loaded,  the
			player will load the next one. To use  this  feature,
			you have to switch off the loop flag (otherwise,  the
			current module will play again...)
			
			Limits : The only way to load the next module is  to
			======   know when the module reaches  its  end.  If 
					 the datas are corrupted or  if  the  module
					 makes a jump by itself to the beginning  of
					 the music, the player will never know  when
					 the module will be finished so it'll  never
					 load the next one.

   Rewind : Rewinds the music (jump to the previous pattern).
   ------
   Play   : Start the music
   ----
   Forward: Forwards the music (jump to the next pattern).
   -------
   Pause  : Pauses  the music. Click an  other  time on this icon 
   -----    to restart the music.

   Stop   : Stops the music and clear the module from memory.
   ----

   2. The Frequencies
   ~~~~~~~~~~~~~~~~~~
   There's four  buttons  under the  icons,  these buttons  allow  
   you  to choose  the  frequencies.  Available  frequencies  are  
   6.25 KHz, 12.5 KHz, 25 KHz or 50 KHz. Some frequencies  aren't
   available on all machines. On Falcon, 6.25Khz is not available
   (the DMA soundchip of the Falcon  can't  restitute  sounds  at 
   this frequency) and 50Khz isn't available if the CPU speed  is
   8 Mhz. 50Khz isn't available on STe  or  MegaSTe. On  MegaSTe, 
   50Khz is available if the CPU speed is 16Mhz  and if the cache 
   is on. Note that the more the frequency is high, the  more the 
   sound is good but the more the music  takes  CPU  time.  It is 
   pretty  important to choose the good frequency if you use  the 
   player as a desk accessory coz the other running  applications 
   will  be more or less slowed  by  the  player. (Personnaly,  I
   think that 12.5 is a good value for a  STe (even  if  you  can  
   listen at 25), 25 for a MSTe or Falcon030 and 50 for a TT).

   Watch out:  There's a lot of tests which are done :  depending 
   the  machine  and  the CPU speed,  some  frequencies  will  be 
   unavailable.  If  you're using a MegaSTe at 16MHz  and  you're 
   listening at 50KHz,  if you switch the CPU time to  8MHz,  the 
   frequency  will  change automatically to 12.5  KHz  and  50KHz 
   will be unavailable until CPU speed is 16MHz like the  Falcon: 
   if  you're listening at 50KHz and if you switch off the  68030 
   caches, frequency will change automatically. But please, don't 
   play  with caches and CPU speed during the player  is  playing 
   module. Bad things can happen...

   3. Loop
   ~~~~~~~
   This  button switches the loop flag.  If it's ON,  the  module 
   will play again when it will reach its end,  if it's  OFF,  it 
   will stop and clear from memory.

   4. Position display
   ~~~~~~~~~~~~~~~~~~~
   Under these button,  there's a graphic display of the  current 
   position of the music.

   5. The other buttons
   ~~~~~~~~~~~~~~~~~~~~
   Under  these  4  buttons  (or under the icons  if  you  use  a 
   Falcon), there is 3 buttons :

   -> Quit  : Close the  player  window  and stop the music. This 
   -------    music is cleared from memory. If you use the player
              as PRG, APP or GTP, you can do the same thing  with
              the option QUIT of the menu FILE.

   -> Play  : This button is only available if the program  is  a   
   -------    desk accessory. Clicking on this button  close  the
              player window but the music  is  still  playing  on 
              background.

   Config   : This button allows you to configure the player. 
   ------     You can change the size of the allocated memory and 
              the default path for the modules.
                           
              1. The size of the buffer
              -  ----------------------
              To load the module, the program reserves an amounts 
              of memory when it is launched. By  default the size 
              is 256000 bytes. You can increase  or decrease this 
              amount, but  notice  that the new value will be ef-
              fective only  the  next time you'll launch the pro-
              gram  coz  the  memory  allocation is done only one 
              time (when the program starts). When you click onto 
              this button, a dialog box appears  and  displays in 
              the upper part the current  size  of  the  reserved 
              memory, type in the lower part the size  you  want, 
              then  click on OK or type return.

              2. The default path
              -  ----------------

              You  can  choose  the  path  where the player will 
              search the modules. To choose  it,  click  on  the 
              button "Choose path", a fileselector appears to do 
              it. The selected path is displayed into a  box. If 
              the path doesn't fit into this box, you can see it 
              by clicking on the arrows buttons to scroll it.

              To  save  these parameters, click on OK (Cancel to 
              leave). The new parameters are saved directly into 
              the file of the program, that's why a fileselector 
              appears,  choose  the player file and click on OK.  
              As this size is  saved  directly into  the program 
              file, you  must'nt  change  the structure of  this         
              file, for exemple, you can't pack the player.  
              In fact,  you can pack the player  but you'll have 
              to unpack it before modifying the size then you'll 
              be able to pack it again. 
  
   6. New windows
   ~~~~~~~~~~~~~~
   
   Just before and after the large title  button, there  are  two
   icons. The one on the left of the title is used to  open/close
   the spectrum analyzer window and the one on the right is  used
   to open/close the oscilloscope window.  You  can  close  these 
   windows by clicking on these buttons or  by  clicking  on  the
   closer box directly on the window.

4. Ultimate Tracker and Multitos
=  =============================

   Ultimate Tracker works fine with Multitos on all machines I've 
   tested (STe,  TT and Falcon). It works fine with great screens 
   and graphic card (like Spektrum).  The ressource file will use 
   AES features of Multitos on a STe and TT.  Be careful :  don't 
   modify  flags of the program (with the  program  PRGFLAG.PRG), 
   this  program  must have its  "SUPER" bit set coz  it  uses  a 
   timer under multitos,  if you switch off this flag, the system 
   will crash. WARNING ! Never kill the process when  the  player
   is playing a module, coz the memory used by the interrupt rout
   will be free without prevent the player, stop music, then kill
   the process.

5. The APPL_WRITE commands
=  =======================

   GEM  provides  a  way  to  communicate  beetween  applications 
   through an events buffer.  This allows an application to  take 
   control  of  an  other one.  Ultimate  Tracker  support  these 
   commands,  so your application can pilot the player.  How does 
   it run ?

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

   Then, you must find the  AES  identification  of  the  player,
   there's two ways to find this id. The  "nicer"  method  is  to
   use the AES function appl_find like this :  id=APPL_FIND(name)
   where name is the filename of the player without its extension
   watch out, the name must  have  8  characters.  This  function
   returns the AES id. If you don't know the current filename  of
   the player, there's an other way to proceed : the player  when
   it is installed, put a cookie into the cookie jar. This cookie
   is : "UTRK" and the data cookie is  the  current  AES  id.  Be
   careful and use this last way of finding AES id if you're sure
   that you won't able to find it with appl_find. You can imagine
   easily the problems if there's several instances of the player
   in memory, you won't able to know who belongs the AES  id  re-
   turned by appl_find or by the cookie jar. 

   1. Commands sent to the player
   ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

   Thanks to this AES id, you'll be able to control the player or
   receive messages from it. You can send commands to the  player
   with the AES function APPL_WRITE. APPL_WRITE needs  3  parame-
   ters : the identification of the player, the number  of  bytes 
   to send to the player and the adress of an array  of  integers
   (16 bits word)which contain the command to send to the player.
   
   These commands have this format :

   - 1st word : always equal to ID_TRACK (999)
   - 2nd word : number of the command
   - 3 - 8    : parameters

   The commands are :

   T_LOAD    (900)  : Load a module into the player buffer.
                      The adress of the path  and  the  name  of 
                      the  module is into the 3rd  and  the  4th 
                      words. (MSB part in 3rd and LSB in 4th).
   T_PLAY    (901)  : Plays the module loaded.
   T_FORWARD (902)  : Forwards the module.
   T_REWIND  (903)  : Rewinds the module.
   T_PAUSE   (904)  : Pauses the module.
   T_STOP    (905)  : Stops the module and clears it from memory.
   T_ABOUT   (906)  : Display an information box.
   T_OPEN    (907)  : Opens the player window.
   T_CLOSE   (908)  : Closes the player window.
   T_FREQ    (909)  : Changes the frequency. 
                      3rd word contains the frequency (0-3).                      
   T_LOOP    (910)  : Switches the loop flag ON/OFF.
   T_IDENT   (911)  : Tells to the  player  that the application 
                      wants receive messages from the player.
                      Word 3 contains AES id of the application.
                      (see next paragraph).
   T_FIDENT  (912)  : Tells to the player that  the  application
                      doesn't want no more messages. (idem).
   T_INFOS   (913)  : Ask some informations to the player.
                      See next paragraph for reception of  these
                      informations.
   T_OPN_OSCILLO (914) : Opens the oscilloscope window.
   T_CLS_OSCILLO (915) : Closes the oscilloscope window.

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

   Note: If you use this feature under Multitos, don't forget to 
   ----  switch on the "GLOBAL" flag of your program,  coz  when
         you will send a T_LOAD command to the player, the play-
         er will read at the address you gave it to get the path
         of the module, but this address is located into the me-
         mory of your application. The "GLOBAL" flag allows  the
         player to read into the memory of your application.  If
         this flag is off, Multitos  will  make  a  memory  pro-
         tection error and will remove the player from memory.

   2. Messages which are received
   ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

   You can send commands to the  player,  but  you  can  receive
   messages from the player too. These messages tell to  an  ap-
   plication all things the player does. To receive these messa-
   ges, you have to proceed this way :
   
   - Tell  to  the  player  we  want  messages  with the command 
     T_IDENT. Since the player receive this  command,  it  gonna
     send messages to the application.
   - Wait for messages in an evnt_multi loop.
   - When the application needn't no more message, send the com-
     mand T_FIDENT.

   Messages have this format :

   - 1st word  : always equel to ID_REPONSE (998)
   - 2nd word  : number of the message
   - 3 - 8     : parameters
   
   Messages are :

   R_PLAY     (951) : The module starts playing.
   R_FORWARD  (952) : Forward.
   R_REWIND   (953) : Rewind.
   R_PAUSE_ON (954) : Pause is ON.
   R_PAUSE_OFF(955) : Pause is ON.
   R_STOP     (956) : Module is stopped and cleared from memory.
   R_OPEN     (957) : Player window is opened.
   R_CLOSE    (958) : Player window is closed.
   R_FREQ     (959) : The frequency is changed (new frequency in 
                      third word).
   R_LOOP_OFF (960) : The loop flag is OFF.
   R_LOOP_ON  (961) : The loop flag is ON.
   R_BEGLOAD  (962) : Module is loading. (word  3  contains  MSB
                      part of the adress of filename and  word 4
                      contains LSB  part.)  To  access  of  this
                      filename under  MultiTOS,  you  must be in
                      supervisor mode, coz player has its  Super
                      flag ON.
   R_ENDLOAD  (963) : Module has been loaded without error.
   R_FAILOAD  (964) : Error during module loading.
   R_MOVE     (965) : Player window has been moved. New  X and Y
                      positions are in word 3 and 4.
   R_INFOS    (966) : This  message  is  sent  when  the  player
                      receives the T_INFOS command.
                      word 3 : player window handle.
                      word 4 : vdi graphic handle.
                      word 5 : AES id.
                      word 6 : Major version number.
                      word 7 : Minor version number.
   R_POSIT    (967) : Current position of the music.
                      word 3 : current position.
                      word 4 : last position.
   R_QUIT     (968) : Player is removed from memory.
   R_ENDMOD   (969) : The module has reached its  end (only  when
                      loop flag is OFF).
   R_PROTECMOD(970) : This message is received  when  the  loaded
   					  module has corrupted informations, it  will
   					  be impossible to know where the module gon-
   					  ga loop so, it will be impossible  to  for-
   					  ward, rewind or see the player counter.
   R_OPN_OSCILLO (971): The oscilloscope window is opened.
   R_CLS_OSCILLO (972): The oscilloscope window is closed.
   R_MOVE_OSCILLO (973):The oscilloscope window has  been  moved. 
   					  The new positions are in word 3 and 4.

   If you need other messages, tell it to  me.  See  the  program
   EXEMPLE\RECEIVE\RECEIVE.C.

   Note: If you use these feature under  MultiTOS,  you  have  to
   ----  be in Supervisor mode in your application to access  the
         name of the module in the message T_BEGLOAD coz you want
         to access to an address which is located into the player
         memory, and this memory area has its flag  "Super"  set.
         So this memory can only be accessed in supervisor mode.

6. Limitations
=  ===========
 
   There's  some  limitations in this  program.  Up  to  now,  it 
   doesn't test if the file loaded is a module or not, if you try 
   to load anything instead of a module,  the program will crash. 
   There's  sometimes  on Falcon a bug :  the player  makes  some 
   strange  noise instead of playing music. It  seems  that  this 
   bug is fixed.  Anyway,  to avoid this problem, put the program 
   called  FPATCH.PRG in your AUTO folder,  it fixes 2 bugs  (and 
   one of them is the sound initialization, it concern  only  TOS
   lesser than 4.05). 

   !!! PLEASE DON'T LAUNCH TWO INSTANCES OF THIS PROGRAM  IN  THE
   SAME SESSION. BAD THINGS CAN HAPPEN (Why do you  wanna  listen
   two modules in same time ???)

7. Sources and other...
=  ====================

   There three sources given with this program :

   -  SHELL  :  It's a small shell which can control  the  player 
   thanks to the appl_write commands. Use it with MintShell under 
   MultiTOS or with a shell into a window under TOS.

   - RECEIVE :  A sample of program which show messages which are 
   sent  by the player to an application.  Thanks to this  sample 
   and  the first one,  you can see how to make communication  in 
   two directions between the player and an application.

   To see how these programs run, use them  simultaneously  under
   MultiTOS with TCShell (or other) (funny !).

   -  PLAY_ACC  :  A program which allows you to use  the  player 
   which  is  a  desk accessory as an application  for  the  .MOD 
   files.  Install this program in the desktop as an  application 
   and  then,  every time you'll click onto a  module  icon,  the 
   accessory will load and play it.
     
   I don't spread the sources of the player now coz there's still 
   bugs to fix and I want to make the memory management again.


   CPU used
   ~~~~~~~~
   
   I made some little tests with GEMBENCH to see how CPU time the
   player takes. I made these tests in 736X560 mode (with 16  co-
   lors) on Falcon030. 
   
   12.5 Khz : 16 % CPU time used
   25   Khz : 27 % CPU time used
   50   Khz : 50 % CPU time used

   To contact us :
   ~~~~~~~~~~~~~

   The Black Cats / Equinox
   Chlet de Riqueval
   02420 Bellicourt
   France

   3614 RTEL1/RTEL2 or 3614 TEASER or 3615 STMAG bal Sharpman


8. 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 (Thanks !)
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 ?)
		   What a fucking bug ! *NEVER* use the system DTA in an
		   accessory ! create your own !!!
v.2.2	 - Supports Atomik Packer 3.5
		 - New menu bar
		 - Oscilloscope window (and new shell messages)
		 
soon coming :

- Replay routine 100% DSP
- Spectrum analyzer
- Iconize + Drag'n'drop

