=============================================
MODE D'EMPLOI de l'extension graphique CAML

  (C) Martial TARIZZO 11/12/95
  
  Documentation version 04.03 Rvise le 10/2/96
  Version 05.01 Rvise le 31/03/96
  Version 07.01 Rvise le 15/9/96
  Version 07.02 Rvise le 13/10/96

  Pour me contacter :
     47 rue des anciens combattants d'AFN
     57000 METZ
     Tl :  (33) 87 55 95 89
     
     E-Mail: tarizzo@world-net.sct.fr
             74014.3307@compuserve.com
     Compuserve : 74014,3307
         
=============================================

* Prsentation gnrale
  ---------------------
  Pour obtenir des tracs graphiques avec CAML sous Windows, il n'existe 
  priori qu'une seule solution :
    utiliser le noyau CAMLWIN, qui dispose d'une fentre graphique. Les 
    fonctions permettant d'y obtenir des tracs sont celles documentes
    dans le manuel de rfrence de CAML. L'ennui est qu'elles sont d'assez bas
    niveau (systme de coordonnes fig, fond sur la dimension physique de
    l'cran en pixels). De plus, il n'est pas possible de copier le dessin 
    obtenu dans le presse-papiers... dommage !
  
  CMDCAML.EXE a t conu de faon  pouvoir tracer des graphiques mme si
  CAML fonctionne dans une fentre DOS, grace  un jeu de fonctions graphiques 
  de plus haut niveau. Ces fonctions fonctionnent aussi si on prfre travailler
  avec CAMLWIN.
  
A) SI CAML TOURNE DANS UNE FENETRE DOS
   ===================================
  Le frontal dispose alors d'une possibilit de sortie graphique dans une fentre 
  indpendante. Elle a t conue pour simplifier au maximum la production 
  de courbes ou de figures telles que celles qui sont vues en mathmatiques. 
  En particulier, les caractristiques physiques de la fentre (dimension, 
  pixels...) y sont totalement occultes.
  
  Pour faire apparatre cette fentre, slectionner dans le menu "Fentre" du
  frontal la ligne "fentre graphique". Cette dernire est dplaable et 
  redimensionnable  votre convenance, le graphisme affich se redessinant 
  alors automatiquement.
  
  La partie principale reprsente une portion du plan mathmatique, dfinie
  par son extension en x et en y. Au dessus figurent trois boutons :
  - le poisson permet de demander le raffichage du dessin
  - le deuxime permet de copier le graphisme dans le presse-papier sous deux 
    formats : le bitmap et le pseudo-code utilis pour dessiner le graphisme.
    Ce dernier est pour l'instant limit  63000 caractres, ce qui 
    autorise des tracs dj fort complexes. Si cette taille est dpasse,
    le dessin pourra se faire la premire fois, mais avec son raffichage en
    cas de redimensionnement sera tronqu (signal alors dans sa barre de 
    titre : "Tampon plein")
  - le troisime permet de basculer sur la fentre de commande
    
  Fonctionnement
  --------------  
  Le problme principal est la synchronisation entre le noyau CAML, qui est
  une application DOS, et le frontal qui est une application Windows.
  
  Si CAML tait du Windows natif, on pourrait se servir des possibilits
  de dialogue du systme (DDE). Ici, il faut s'en passer....
  Il est fort difficile de pouvoir changer par l'intermdiaire de la 
  mmoire, il faut donc se rabattre sur le disque et son systme de 
  fichiers
  
  Principe :
  ==========
  un dialogue entre le noyau CAML et le frontal Windows est tabli comme 
  suit (cela ne fonctionne que parce-que l'application DOS est interrompue
  premptivement par Windows : CAML et le frontal sont actifs "en mme 
  temps" !!) :
  
  ROLE DU NOYAU
  Le noyau graphique MT CAML (le fichier MTGRAPH.ML) va crire, quand on 
  invoque la fonction graph_flush, dans un fichier $MTGCODE.GML un 
  pseudo-code qui sera interprt par le frontal, en dessinant le graphique 
  dsir. graph_flush n'crit le code sur le disque que s'il existe le 
  fichier $MTGDONE.GML, qui est effac avant criture du code graphique.
  
  --- remarque : les fonctions individuelles de trac ne declenchent pas 
  d'criture sur le disque, mais sur un port graphique virtuel, implant
  sous la forme d'une chane dynamique CAML. Il est necssaire d'appeler
  graph_flush pour obtenir la moindre sortie graphique !!!
  
  ROLE DU FRONTAL
  Quand la fentre graphique du frontal est ouverte, un scrutation du disque 
  a lieu en permanence (timer). Si un fichier $MTGCODE.GML
  est trouv, ce fichier est lu en chargeant le code graphique, puis effac,
  en crant un nouveau fichier $MTGDONE.GML de longueur nulle (ce fichier
  est aussi cr  l'ouverture de la fentre graphique du frontal)
  Cela permet donc une nouvelle intervention du noyau.
  
  EFFICACITE DE L'ENSEMBLE
  Tout a est  peu prs efficace  la condition qu'il existe un cache disque
  performant, vitant autant que faire se peut les lectures effectives du 
  disque. De toutes faons Windows n'est performant que si un tel cache 
  existe (SMARTDRIVE par exemple...)
  
B) SI CAMLWIN EST ACTIF
   ====================
  le fichier WMTGRAPH.ML implante les mmes fonctions que dans le fichier 
  MTGRAPH.ML afin de les utiliser avec CAMLWIN.
  Seules quelques-unes sont inoprantes (car la primitive correspondante 
  n'existe pas dans CAML)
  
C) Dfinitions du noyau graphique
   ==============================
  Voil toutes les exceptions, constantes et fonctions actuellement prsentes 
  dans le fichier MTGRAPH.ML ou WMTGRAPH.ML. 
  Sont implant deux types de procdures graphiques :
  - procdures "standard", i.e primitives cartsiennes.
  - procdures "tortue", reprenant le systme graphique popularis par le 
    langage LOGO. Permet en particulier le trac commode de bon nombre de 
    figures fractales, bien commodes pour introduire la rcursivit dans des
    routines graphiques.
  
- Voil les procdures standard :
  -----------------------------
  Remarque : celles marques par {DOS} n'ont d'utilit que si CAML tourne dans
             une fentre DOS...
  Exception : no_graphic_dialog       {DOS} 
    C'est l'exception correspondant  une erreur graphique rsultant d'un
    dialogue infructueux entre le noyau et le frontal. Se produit gnralement
    quand la fentre graphique n'est pas ouverte
  
  GraphicFile_check_and_delete : string -> unit = <fun>       {DOS} 
    Fonction interne de conduite du dialogue
  
  graph_port : string ref = ref ""       {DOS}
    variable interne pour la gestion des commandes graphiques
  
  file_graph_code
  file_graph_temp
  file_graph_done
    les constantes reprsentant les noms des fichiers utiliss au cours du 
    dialogue       {DOS}
  
  graph_flush : unit -> unit = <fun>       {DOS}
    la fonction qui vide le tampon de commande dans le fichier de dialogue.
    DOIT IMPERATIVEMENT tre appele en fin de trac.
  
  x_graph_cursor : float ref = ref 0
  y_graph_cursor : float ref = ref 0
    les coordonnes du curseur graphique.

  graph_display : string -> unit = <fun>       {DOS}
  graph_display_each : string list -> unit = <fun>       {DOS}
    fonctions de service pour l'affichage des commandes dans le port 
    graphique. Fonctions internes.
  
  graph_clear : unit -> unit = <fun>
    Efface la fentre graphique.
    
  graph_scale : float -> float -> float -> float -> unit = <fun>
    dfinit la fentre d'affichage par ses arguments : 
    xmin xmax ymin ymax
    
  graph_moveto : float -> float -> unit = <fun>
    dplace le curseur graphique en x y, sans aucun trac
    
  graph_plot : float -> float -> unit = <fun>
    trace un point en x y
    
  graph_lineto : float -> float -> unit = <fun>
    dplace le curseur graphique  partir de la position courante jusqu'en
    x y, en traant une ligne.
    
  graph_boxto : float -> float -> unit = <fun>
    dplace le curseur graphique  partir de la position courante jusqu'en
    x y, en traant un rectangle.
        
  graph_boxfullto : float -> float -> unit = <fun>
    dplace le curseur graphique  partir de la position courante jusqu'en
    x y, en traant un rectangle plein.
  
  graph_circle : float -> float -> float -> unit = <fun>
    dplace le curseur graphique en x y, puis trace autour de ce point un 
    cercle de rayon r.
  
  graph_color : int -> int -> int -> unit = <fun>
    dfinit la couleur de trac par les composantes rouge/vert/bleu
    
  graph_drawtext : string -> unit = <fun>
    crit un texte  partir de la position courante. Les coordonnes du
    curseur ne changent pas, et reprsentent le coin suprieur gauche du 
    texte
    
  graph_floodfill : float -> float -> unit = <fun>
    remplit la surface de couleur uniforme contenant le point x y avec la
    couleur courante de trac
    ne fonctionne pas sous CAMLWIN...

  graph_init : unit -> unit = <fun>
    initialise le systme graphique (vidage du tampon de la fentre graphique,
    curseur en 0. 0., chelle  -2. 2. en x et en y) 


- Et voil maintenant les procdures "tortue" :
  -------------------------------------------
  
  deg_par_radian : float = 57.2957795131
    constante assez explicite, donnant le nombre de degrs dans un radian
  
  type ordre_tortue = 
   origine| va_en| avance| recule| 
   tourne_gauche| tourne_droite|
   fixe_cap| leve_crayon| baisse_crayon |
   etat
   ;;
    les ordres reconnus par la tortue

  type argument_tortue = 
  a_rien of unit | a_nombre of float | a_coord of float * float;;
    pour le polymorphisme, les diffrents arguments expdiables  une tortue
    
  type etat_crayon = bas | haut;;
    l'tat du crayon de la bte

  type etat_tortue = 
  {x : float; y : float; cap : float; crayon : etat_crayon};;
   pour savoir o est l'animal, et dans quelle direction elle regarde

  type resultat_tortue = 
  r_rien of unit | r_etat of etat_tortue;;
   le type du rsultat rendu quand on interroge une tortue

  exception erreur_tortue;;
    pour les erreurs tortuesques

  type tortue == ordre_tortue -> argument_tortue -> unit;;
    une tortue est une fonction qui, en recevant une commande renvoie une
    fonction charge d'valuer l'argument de la commande.

  cree_tortue : unit -> ordre_tortue -> argument_tortue -> unit = <fun>
    cre une tortue. Plusieurs de ces animaux peuvent exister en mme temps.
  
  Les fonctions suivantes permettent une utilisation commode des tortues
  retourne_etat : tortue -> etat_tortue = <fun>
   pour rcuperer la position et le cap
  
  org : tortue -> unit = <fun>
    ramne la tortue  l'origine (0 0)
    
  va : tortue -> float -> float -> unit = <fun>
    dplace la tortue en x y. Trace selon l'tat du crayon.
    
  av : tortue -> float -> unit = <fun>
    Avance la tortue de la longueur fournie, dans la direction courante
    
  re : tortue -> float -> unit = <fun>
    Recule la tortue de la longueur fournie, dans la direction courante
    
  tg : tortue -> float -> unit = <fun>
    fait tourner la tortue  gauche de l'angle fourni en radians
    
  td : tortue -> float -> unit = <fun>
    fait tourner la tortue  droite de l'angle fourni en radians
    
  fc : tortue -> float -> unit = <fun>
    fixe le cap de la tortue (direction du mouvement) en radians. sens 
    trigonomtrique et zro vers l'Est
    
  lc : tortue -> unit = <fun>
    Lve le crayon de la tortue
    
  bc : tortue -> unit = <fun>
    Baisse le crayon de la tortue

D) Test du noyau graphique
   =======================
  - Lancer CMDCAML.EXE, 
  - chargez le fichier MTGRAPH.ML ou WMTGRAPH.ML
  - Evaluez-le (Appuyez sur F4)
  - Chargez le fichier TSTGRAPH.ML
  - lisez le dbut du fichier, qui vous donne des indications sur
    la marche  suivre pour obtenir les tracs
  - Ouvrez la fentre graphique (Ctrl-O suivi de Ctrl-G)      {DOS}
  - Essayez les fonctions. Des exemples sont fournis  la fin de chacune.

E) Compilation des fichiers
   ========================
 Si les routines vous plaisent, il est trs facile de les compiler pour les
 utiliser directement (sans valuer le fichier source)
 Placez les fichiers source dans le rpertoire LIB de caml ; ensuite
 sous CAML {DOS}, il suffit de taper (en adaptant le chemin au 
 besoin) :
 compile "c:\\caml\\lib\\mtgraph.ml";;
 (* ou : *)
 compile "c:\\caml\\lib\\wmtgraph.ml";;
 
 L'utilisation des fonctions se fera alors de faon classique :
 #open "mtgraph";;
 graph_init();;
 ...
 
