                    * PROTRACKER PLAYER 2.3 *
      Par Checksum (Equinox) et Sharp Man (The Black Cats)


1. Introduction

     Ce  programme vous permet de rejouer des modules  protracker 
sur tous les micro-ordinateurs Atari quips d'un circuit  sonore 
DMA (STe,  TT et Falcon).  Attention,  il s'agit bien de  modules 
protrackers,  les vieux modules soundtrackers ( 15  instruments) 
ne  seront pas rejous,  en revanche,  tous les  nouveaux  effets 
implants   sur  les  dernires  versions  du   ProTracker   sont 
parfaitement supports. Protracker Player fonctionne compltement 
sous GEM et peut tre utilis en tant qu'application PRG,  TTP ou 
accessoire de bureau.

2. Lancement du programme

     Le lancement du programme va dpendre de la faon dont  vous 
avez nomm son extension.     

     2.1 PLAYER.PRG

     Vous tes dans le cas d'une application GEM  standard.  Pour 
la lancer, double-cliquez sur son icne ou son nom dans le bureau 
ou, si vous utilisez un shell, tapez : PLAYER.

     2.2 PLAYER.GTP ou PLAYER.TTP

     Dans  ces  cas,  un  paramtre va tre  ncessaire  pour  le 
lancement de l'application.  Ce paramtre est le chemin et le nom 
d'un  module  protracker   jouer.  Si  vous  double-cliquez  sur 
l'icne  ou  le  nom du fichier dans  le  bureau,  une  bote  de 
dialogue va vous demander d'entrer le paramtre,  tapez alors  le 
chemin   et   le   nom  du  module    jouer   (par   exemple   : 
C:\MODULES\MOBY.MOD).  Si vous utilisez un shell,  tapez la ligne 
PLAYER  C:\MODULES\MOBY.MOD.  Enfin,  si  vous  tes  un  heureux 
possesseur  d'un tos 2.05 ou suprieur,  il vous suffit  d'amener 
l'icne  du  module  sur  l'icne ou le  nom  du  fichier  (cette 
remarque  est  valable aussi si l'extension  est  PRG).  Si  vous 
omettez de taper un nom dans la bote de dialogue lorsqu'il  vous 
sera demand  d'entrer le paramtre,  le programme ragira de  la 
mme faon que s'il possdait l'extension PRG.

     2.3 PLAYER.ACC

     L'utilisation  du  player  en tant  qu'accessoire  est  trs 
interessante  car  elle  vous  permettra  d'couter  des  modules 
protrackers   de  faon  transparente  durant  l'utilisation   de 
n'importe  quelle application.  Le fichier PLAYER.ACC  doit  tre 
plac   la racine de votre disque de dmarrage (C:\ ou  A:\)  ou 
dans  le  dossier  des  accessoires  (avec  Multitos).   Il  sera 
automatiquement execut au dmarrage.



                              - 1 -


Note:  Une seule version du player peut se trouver en mmoire  au 
mme moment (inutile d'essayer vouloir jouer deux modules en mme 
temps).  Donc,  si  vous  essayez de charger le  programme  alors 
qu'une version en accessoire est rsidente ou si,  avec multitos, 
vous  essayez de lancer plusieurs fois  le  mme  programme,  une 
bote d'alerte vous prviendra de l'impossibilit de la chose.

3. Utilisation

     Lors  de l'ouverture de la fentre,  une boite  de  dialogue 
s'affiche, vous pouvez alors cliquer sur plusieurs boutons :

     Frequency

     Ces  4  boutons  permettent  de  choisir  la  frquence   de 
restitution du module,  plus la frquence est leve, plus le son 
va  tre  clair  et  de  bonne  qualit.  Cela  se  paie  par  un 
inconvnient,  plus  la  frquence  est leve et  plus  cela  va 
prendre  de temps machine,  si ceci n'est pas important quand  le 
programme  est  utilise comme PRG,  si il est  utilis  en  tant 
qu'accessoire de bureau,  une restitution du son  une  frquence 
leve va ralentir sensiblement les autres applications.  Essayez 
donc  de  faire  un bon compromis :  pour un  STe,  12.5  kHz  ne 
ralentit pas vraiment la machine, sur un TT, on peut se permettre 
un 50 kHz.
     Si  la machine n'est pas assez rapide pour traiter le son   
50  kHz,  cette  option  sera grise  et  inactivable,  elle  est 
utilisable sur Mega STe  16 mHz, sur TT ou Falcon (!!!).

     Load

     Vous  choisissez ici le module  charger,  un  selecteur  de 
fichier s'ouvre et vous faites votre choix.  Si le fichier  n'est 
pas un module protracker,  le programme l'affichera. Si la taille 
de mmoire rserve est trop faible pour contenir le  module,  un 
message d'erreur sera affich (voir plus loin, paragraphe 5). Ds 
que le module est correctement charg, son nom va s'afficher dans 
la bote : Module Name.

     Config

     Vous configurez ici les paramtres par dfaut utiliss  lors 
du lancement du programme. (voir paragraphe 4).

     Free

     Cette option coupe la musique, libre la mmoire rserve et 
ferme  la fentre,  elle peut tre utile si une application a  un 
besoin  ponctuel de mmoire.  C'est le seul moyen de  quitter  le 
player quand celui-ci est utilis en tant que PRG ou GTP/TTP.
     




                              - 2 -


     Exit

     Cette  option est seulement validable lorsque le player  est 
utilis   comme accessoire,  elle ferme la fentre et  laisse  le 
player jouer le module en tche de fond.

     Control

     Ces quatre boutons permettent de contrler le droulement de 
la musique.  << fait reculer la musique (que si elle est en train 
d'tre  joue),  > joue la musique,  >> avance la  musique  (mme 
remarque) et O fait une pause.  L'tat en cours de la musique est 
indiqu sur la ligne STATUS.

     Spectrum Analyzer


     NE MARCHE PAS !!!

     La fentre

     Elle  peut  tre  dplace comme  toute  fentre  GEM,  sous 
Multitos, elle supporte d'tre dplace derrire une autre.

     
4. Configuration et fichier de configuration

     Lorsque  vous  cliquez sur CONFIG ,  une bote  de  dialogue 
s'affiche.  Celle-ci  vous permet de configurer les  valeurs  par 
dfaut que prendra le player lors de son lancement.

     Enable Key & Bell

     Cette option vous permet d'inhiber les bip du clavier et  le 
bruit produit lorsqu'on clique hors d'une bote de dialogue. Ceci 
est particulirement agrable lorsque l'on tape du texte et qu'on 
veut  viter  que  la  musique  soit  parasite  avec  des  clics 
intempestifs.  Cliquez  sur NO  pour couper le clic et YES   pour 
l'activer.

     Default Frequency

     Vous  choisissez ici la frquence qui sera slectionne  par 
dfaut  lors du lancement du programme.  Comme  prcdemment,  si 
votre  machine  n'est  pas assez rapide,  l'option  50  kHz  sera 
indisponible est grise.









                              - 3 -


     Default Module

     Choisissez ici le module qui,  si le programme n'est pas  un 
GTP/TTP,  sera  charg  et jou lors du dmarrage  du  programme. 
Cliquez  sur  la ligne o le nom doit  s'afficher.  Un  selecteur 
d'objet apparat et choisissez le module par dfaut.  ATTENTION ! 
le  module  par  dfaut doit se trouver dans  le  rprtoire  par 
dfaut des modules (voir aprs).  Si aucun dossier de module  par 
dfaut  n'est spcifi,  ce module sera cherch dans  le  dossier 
courant. Bien entendu, vous pouvez ne choisir aucun module !

     Module Path

     Choisissez  ici le dossier qui va contenir vos  modules.  La 
procdure    suivre est la mme que  prcedemment.  Si  vous  ne 
choisissez  aucun dossier pour les modules,  lors du  chargement, 
la bote de selection s'ouvrira sur le dossier courant.

     Resource Path

     Vous  choisissez  ici  le dossier et  le  nom  des  fichiers 
ressources. La procdure est la mme que prcdemment. Attention, 
vous  ne devez pas simplement choisir le dossier  des  ressources 
mais  galement  slectionner un des  trois  fichiers  ressources 
(dont  l'extension est .RSC),  peu importe lequel des trois  vous 
choisissez.  Si  vous  ne choisissez aucun  dossier,  le  fichier 
ressource sera recherch dans le dossier courant.

     Si vous voulez changer le nom des fichiers ressources,  vous 
pouvez  le  faire    condition  de  respecter  les   conventions 
suivantes :  il y a 3 fichiers,  chaque fichier correspond   une 
rsolution d'cran prcise :  si la rsolution de l'cran est  de 
320  pixels de large ou moins,  le fichier doit se  terminer  par 
_L.RSC. Si la rsolution de l'cran est de 640 pixels de large et 
de moins de 201 pixels de haut,  le fichier doit se terminer  par 
_M.RSC,  les autres rsolutions (Haute ST,  VGA, Haute TT, toutes 
les  autres rsolutions Falcon) doivent utiliser le fichier  dont 
la  fin  est _H.RSC.  Les caractres prcdents  cette  extension 
doivent  tre  les  mmes pour les  3  fichiers.  Par  exemple  : 
TOTO_L.RSC, TOTO_M.RSC et TOTO_H.RSC.

     CANCEL

     En cliquant sur ce bouton,  vous annulez les slections  que 
vous venez d'effectuer.  Les paramtres seront replacs dans leur 
tat prcdent et vous revenez sur la premiere boite de dialogue.

     OK

     En cliquant sur ce bouton, vous validez les options de faon 
provisoire  :   lors  du  lancement  suivant  du  programme,  les 
anciennes  valeurs seront reprises.  Les options  ainsi  valides 
sont  immdiatement actives,   l'exception de la frquence  par 
dfaut.

                              - 4 -


     SAVE

     Vous  sauvegardez ici les valeurs qui seront utilises  pour 
le prochain lancement du programme. Les informations sont sauves 
dans un fichier nomm PLAYER.CFG.  Veillez  ce que ce fichier se 
trouve  au mme endroit sur le disque que le programme   lancer, 
si   au  dmarrage  le  player  ne  trouve  pas  le  fichier   de 
configuration,  il  vous  avertira et utilisera ses  valeurs  par 
dfaut.  Le  fichier est un fichier texte ASCII normal  qui  peut 
tre dit sans problme par n'importe quel traitement de  texte. 

Voici son contenu :

- Dossier des ressources
- Dossier des modules
- Module par dfaut
- Frequence par dfaut (0/1/2/3 -> 6.25/12.5/25/50 kHz)
- Bip clavier (0/1 -> Non/Oui)
- Mmoire rserve (voir aprs) en octets

5. Gestion de la mmoire

     On peut peut imaginer que le player, lorsqu'il va charger un 
module va se rserver un bloc de mmoire de la taille du  module, 
charger ce module dedans et ds qu'on aura fini de l'couter,  va 
librer ce bloc de mmoire. Ceci est tout  fait possible avec un 
programme  de  type PRG ou sous Multitos,  par  contre,  avec  un 
accessoire sous TOS monotche,  ca devient vite infernal !!  : On 
ne  peut pas se reserver des blocs de mmoire dans un  accessoire 
sans risquer  tout moment une catastrophe. La seule solution est 
de se rserver une bonne fois pour toute un bloc de mmoire  lors 
du lancement du programme et, si possible, viter d'y toucher par 
la suite. C'est  ceci que sert l'option Size of Reserved Memory.
Grce  aux boutons flchs,  vous allez augmenter ou diminuer  la 
taille  du bloc de mmoire qui va tre rserv lors du  lancement 
du  programme.  Par dfaut,  cette taille est fixe sur  230  Ko, 
Attention !  ce bloc de mmoire sera rserv tout le temps  (mme 
quand aucun module n'est charg), veillez donc  ce qu'il ne soit 
pas  trop important (et pas trop petit non plus).  J'ai fix  une 
taille de 230 Ko,  ce qui ne me gne pas trop avec mes 4 Mo  mais 
pour certains ca peut tre trop... 

     Cette option sera grise et inaccessible dans certains cas : 
un  module  est dj en mmoire,  on ne va donc  pas  changer  la 
taille du bloc rserv vu qu'il y a dj quelque chose dedans  ou 
alors  l'accessoire a t ouvert alors qu'il ne se  trouvait  pas 
sur  le  bureau et dans ce cas,  la rservation  de  mmoire  est 
impossible.  Le  seul  moyen de se rserver de la  mmoire  "sans 
danger"  avec  un accessoire,  c'est lorsqu'il se trouve  sur  le 
bureau.  Si  vous voulez augmenter la taille de mmoire  rserve 
dans ce cas, quittez votre application.




                              - 5 -


     Notes: 

     -  Sous  cette option,  vous voyez la taille de  la  mmoire 
libre. Attention, cette taille englobe la mmoire rserve par le 
programme,  par exemple si il est crit : memory free : 262144 et 
que  la  mmoire rserve est de 128 Ko,  la  mmoire  REELLEMENT 
libre est de 128 Ko seulement (256 Ko - 128 ko),  ceci pour  vous 
permettre de voir jusqu'o vous pouvez monter la taille mmoire  
rserver. 

     -  Lorsque vous cliquerez sur OK,  la mmoire rserve  sera 
efface et la nouvelle taille choisie sera reserve.  Il se  peut 
qu'  ce  moment  l  (je  n'entre  pas  dans  les  dtails),  la 
rservation  soit  impossible (du moins  dans  sa  totalit),  le 
programme  essayera  donc de rserver le plus  de  mmoire  qu'il 
puisse sans pour autant "nuire" au systme.

     - Lors du prochain lancement du programme, il se peut que la 
mmoire  reserver indique dans le fichier de configuration soit 
trop  importante  (certains  accessoires  ou  rsidents  ont  t 
installs ou la machine sur laquelle  t effectu la sauvegarde 
de la configuration n'est pas la mme).  Dans ce cas,  le systme 
utilisera  la  mmoire  par dfaut (230  Ko,  ou  si  c'est  trop 
important, la mmoire disponible divise par deux).

     -  SI  VOUS AVEZ UN TT,  ne mettez SURTOUT pas  1  le  flag 
indiquant au programme de se charger en ram TT,  d'abord ce n'est 
pas le but de la ram TT,  ensuite, vous ferez vite tout planter : 
la  ram TT est prvue pour fonctionner en 32 bits et  le  circuit 
dma sonore fonctionne en 24 bits.

     - Lors du chargement d'un module (option LOAD),  il peut  se 
produire 2 cas : soit le module "rentre" dans la mmoire rserve 
et dans ce cas, pas de problme, soit il est trop important, dans 
ce cas prcis,  le programme vous proposera d'augmenter la taille 
de  la mmoire rserve afin de "faire tenir" le  module  dedans. 
Vous pouvez accepter ou refuser.  Si vous tes dans un accessoire 
qui n'est pas ouvert sur le bureau,  le programme vous  indiquera 
que  la  taille  rserve  est trop faible  mais  ne  pourra  pas 
l'agrandir,  pour cela,  vous devrez pralablement tre revenu au 
bureau.

6. La gestion des erreurs

     Je  pense  (enfin j'espre) que toutes les erreurs  ont  t 
corriges et qu'il n'y a plus de bug.  Cependant,  on n'est pas  
l'abri des erreurs  100% (surtout au niveau de la gestion de  la 
mmoire).  Je  pense  que tous les cas ont t  prvus.  Si  vous 
trouvez un bug, crivez-moi en m'expliquant ce qui l'a provoqu.







                              - 6 -

7. P_CHRES.PRG

     Les informations ci-dessous ne concernent que  l'utilisation 
du player en tant qu'accessoire de bureau.
     
     Comme  vous l'avez peut-tre  remarqu,  certains  logiciels 
proposant les mmes fonctionnalits que Protracker Player (et  je 
pense ici notamment  Jukebox),  ont une facheuse tendance,  lors 
de  leur utilisation en tant qu'accessoire  planter  la  machine 
lors d'un changement de rsolution.  La raison est simple, il n'y 
a aucun moyen pour un accessoire de dtecter (du moins tant qu'on 
est  pas  sous multitos) le changement de  rsolution,  or    ce 
moment prcis,  l'accessoire est effac de la mmoire. Ceci n'est 
pas  trop  grave tant qu'il ne fait pas appel  des  routines  en 
interruption.  

     Ce  n'est  pas le cas dans ce genre  de  programme,  un  des 
timers joue la musique et utilise la mmoire qui va tre efface, 
ce qui va provoquer  coup sur, un plantage de la machine lors du 
changement de rsolution.  Le seul moyen de "contrer" cet inconn-
vnient  est d'utiliser le programme P_CHRES.PRG.  Ce  programme, 
plac  dans  le  dossier AUTO de votre  disque  de  dmarrage  va 
dtecter le changement de rsolution et dans ce cas,  va  stopper 
la musique.  Ceci est le SEUL moyen d'viter le plantage,  n'oub-
liez donc pas placer ce fichier dans le dossier AUTO !!!

     Note   propos de multitos:  Les machines fonctionnant  sous 
Multitos  n'ont pas besoin de ce programme dans le dossier  AUTO, 
les  accessoires  de  bureau pouvant dtecter  le  changement  de 
rsolution.

8. Utilisation avec Multitos

     L'utilisation avec multitos ne pose aucun problme sur Atari 
STe ou Mega STe,  cependant,  sur TT,   cause,  je pense, de son 
mode  d'adressage sur 32 bits,  le programme plante lorsque  l'on 
dmarre la musique.  Ce bug devrait tre corrig rapidement et ne 
devrait, en thorie, pas exister sur Falcon, son mode d'adressage 
tant sur 24 bits.  
     De plus, quittez proprement le programme avec le bouton FREE 
avant de jeter le processus  la poubelle.  Evitez IMPERATIVEMENT 
de jeter le processus  poubelle lorsqu'un module est en train de 
jouer,  vitez aussi les Kill -9 ou -15.  En rsum et pour faire 
simple  :  NE  TUEZ LE PROCESSUS QUE SI VOUS N'AVEZ  PAS  D'AUTRE 
POSSIBILITE (gros plantage) sinon vous risquez d'avoir des  prob-
lmes.









                              - 8 -


9. Sources

     Comme d'habitude, les sources se trouvent avec le programme. 
Lorsque  vous diffuserez ce programme,  essayez de  diffuser  les 
sources  avec.  Si  vous  modifiez les sources  ou  amliorez  le 
programme, envoyez moi la version modifie, ca m'vitera  crire 
quelque chose qui  dj t fait ! 
     
Les parties crites en C :

- PLAYER.C
- COOKIE.C
ont  t  crites  avec Pure C 1.0.  Si vous  utilisez  Turbo  C, 
utilisez  le projet TPLAYER.PRJ  la place du  projet  PLAYER.PRJ 
prvu pour Pure C. 
Le programme COOKIE.C a t crit par Jacques Caron de ST MAG.

ATTENTION:  les utilisateurs du TT doivent bien vrifier que  les 
allocations  de mmoires se font en ST RAM (SURTOUT !),  si  vous 
avez Pure C,  choisissez l'option "malloc in ST ram" dans le menu 
linker, si vous n'avez pas cette option, remplacez les malloc par 
un  Mxalloc (taille,0),  les coreleft() par  un  Malloc(-1),  les 
free()  par  Mfree()  et les realloc par  un  Free()  suivi  d'un 
Mxalloc (taille,0).  

Les parties crites en assembleur:

- MC.S
- ACC_PLAY.S
- P_CHRES.S
ont  t crites avec Devpac 2.17.  Vous devez les  assembler  en 
code  objet utilisable par Pure/Turbo C.  Pour  cela,  choisissez 
comme  paramtre  d'assemblage  :   

Program Type : DRI linkable
Symbol Case  : Dependant
Output       : Disk

- COOKIE_S.S
a t crite avec l'assembleur de Pure/Turbo C. Utilisez l'option 
Compile  de Pure/Turbo C.  Cette partie a t crite par  Jacques 
Caron de ST MAG. J'en ai rajout un morceau.













                              - 8 -


Les ressources

Elles ont t dessines avec RCS 2.02 (et 2.08),  vous  trouverez 
dans  le dossier SOURCES,  les fichiers DFN ncessaires  RCS  2. 
Certains objets des ressources ont t placs  des positions qui 
ne  sont  pas  des  multiples  de  8  (les  utilisateurs  de  RCS 
comprendront  de  quoi je parle) grce  WERCS.  Si  vous  voulez 
modifier  les resources avec WERCS,  vous trouverez les  fichiers 
HRD qui lui sont ncessaires.

10. Fonctionnement

     PLAYER.PRG

     Le  programme PLAYER utilise pour rejouer les  modules,  une 
routine  place  en Timer A.  Si vous avez besoin  de  ce  timer, 
modifiez le source assembleur et remplacez dans les appels  xbios 
31,  le move.w #0,-(a7) qui prcde le numro de la fonction  par 
un move.w #1,-(a7), cela utilisera le timer B  la place du timer 
A. Cherchez la ligne BCLR #5,$FF8A0F par BCLR #0,$FF8A0F.
     Le  programme  utilise pour dtecter sa prsence  un  cookie 
plac  dans le cookie Jar.  Ce cookie est  :  PMOD.  Il  contient 
l'adresse d'une table de routines. Ces routines sont :

- Arret de la musique (mt_stop)
- Effacement du cookie (remove_cookie)
- Initialisation de la musique (mt_init)
- Demarrage de la musique (mt_play)
- Avance rapide (mt_forward)
- Retour rapide (mt_rewind)
     
     P_CHRES.PRG

     Ce   programme   teste  en  permanence  le   changement   de 
rsolution.   Il  le  fait  en  dtournant  la  VBL.   Lors  d'un 
changement,  il  excute les routines dont l'adresse est dans  le 
cookie. Pour pouvoir rutiliser la VBL, il utilise la norme XBRA.     

10. Shareware

     Ce programme est un shareware,  il est diffusable sans aucun 
droit  ainsi que ses sources.  Ne vous en privez donc pas  !!  Si 
vous avez des suggestions  faire,  si vous avez trouv des  bugs 
(hh et il doit en rester...), crivez nous :

TBC/EQUINOX
Chlet de Riqueval
02420 Bellicourt
France


                                             Sharp Man




                              - 9 -


     
