		La programmation de M_PLAYER
		****************************

	Vous dsirez ajouter de l'animation  vos crations? Rien de plus
simple: M_PLAYER en accessoire se comporte comme une extension vido de
votre systme. Il dispose donc d'appels systmes et ragit en consquence.
Ce qui suit est aussi valable pour les versions dmos ainsi que les
versions STE du player.

Les identifiants
----------------
	Pour dialoguer avec n'importe quel accessoire, il faut connatre
son identifiant GEM, il faut aussi connatre le notre pour s'assurer de la
rponse ventuelle.
	Pour mon programme, c'est facile: j'obtiens l'identifiant ds le
dbut de l'excution lorsque j'appelle appl_init.
	Pour l'accessoire, il faut utiliser appl_find en donnant le nom de
l'accessoire. Ce nom est compos de huit caractres ventuellement
complts par des espaces si le nom comporte moins de 8 signes. Pour
M_PLAYER la chane est ... (suspense)... "M_PLAYER"! De mme, pour les
autres versions, prenez le nom de votre fichier sans l'extension ACC
("MP_STE  ", "MPLYR_SW", "MPSTE_SW").

	L'appel en 'C':

	int mon_id,player_id;
	mon_id=appl_init();
	player_id=appl_find("M_PLAYER");

	Si mon_id=-1, c'est que l'AES ne veut pas de moi (rare!). Si
player_id=-1, c'est que l'accessoire n'est pas prsent (dj plus
courant).


Le message AES
--------------

	A l'aide de la fonction appl_write, on transmet au player un buffer de
16 octets contenant les informations suivantes:

	typedef struct
	{
	int mess; /* identifiant du message */
	int id;   /* identifiant de votre application (pour la rponse) */
	int taille; /* pas plus de 16 octets, donc zro ici */
	char *adr;  /* adresse de la ligne de commande ou zro */
	int retour; /* voir plus loin */
	int res1;
	int res2;   /* deux mots inutiliss */
	} MESSAGE;

	On prendra toujours mess='MP', taille=0 et res1=res2=0.


Premier appel
-------------

	Le plus simple est d'ouvrir M_Player comme si on cliquait sur
l'entre du menu: vous aurez droit aux botes de dialogue ainsi qu'au
slecteur de fichiers. Le message tient en deux valeurs, le premier mot
'MP' et mon identifiant, tout le reste tant  zro.

	L'appel correspondant en 'C':

	MESSAGE msg;

	msg.mess='MP';
	msg.id=mon_id;
	msg.taille=0;
	msg.adr=NULL;
	msg.retour=0;
	msg.res1=0;
	msg.res2=0;

	appl_write(player_id,16,&msg);

Appel avec ligne de commande
----------------------------

	Il suffit d'utiliser le paramtre 'adr' en lui passant une valeur
diffrente de zro qui sera interprte comme un pointeur sur une chane
de caractres dfinissant la ligne de commande. Cette ligne a exactement
le mme structure que celle que vous emploieriez avec un TTP. Je peux donc
utiliser:
	"f:\anims\test.avi"
	Ce qui sautera le slecteur de fichiers pour remplir directement
la bote de dialogue avec l'animation voulue.
	"-d f:\anims\test.avi"
	Mme effet sauf que l'option '-d' fait sauter galement toutes les
botes de dialogue et rejoue directement l'animation.

	L'appel en 'C':

        MESSAGE msg;

	msg.mess='MP';
	msg.id=mon_id;
	msg.taille=0;
	msg.adr="-d f:\\anims\\test.avi";
	msg.retour=0;
	msg.res1=0;
	msg.res2=0;

	appl_write(player_id,16,&msg);

	Vous noterez les doubles "\\" dans la chane de caractres puisque
la barre sert de contrle au Pure C, notamment pour insrer des sauts de
lignes ou des retours chariots.

Appel avec ligne de commande et message de retour
-------------------------------------------------

	L'appel  appl_write ne vous assure pas que M_Player est lanc
tout de suite, pas plus que la fin d'appl_write ne signale la fin de
l'animation. On a donc besoin d'un message de retour de la part de
M_Player signalant que son travail est termin. Ce systme de rponse
n'est implant qu' partir de la version 2.9A de M_PLAYER et 2.83 de
MP_STE.
	La valeur 'retour' correspond au code du message que vous dsirez
recevoir. Si cette valeur est nulle, M_Player ne renvoit rien. Vous ne
pouvez pas non plus utiliser n'importe quel message: une partie est
rserve  l'AES (de 0  100) ou a Kobold (de $2F10  $2F17). Faute de
mieux, utilisez 'MP'!
	Comment obtiendrez vous ce message? Tout simplement en appelant
evnt_mesag comme pour tout autre vnement GEM.

	L'appel en 'C':

	MESSAGE msg;

	msg.mess='MP';
	msg.id=mon_id;
	msg.taille=0;
	msg.adr="-d F:\\ANIMS\\TEST.AVI";
	msg.retour='GT';
	msg.res1=0;
	msg.res2=0;

	appl_write(player_id,16,&msg);

	do evnt_mesag(&msg);
	while (msg.mess!='GT');


Quelques paramtres intressants
--------------------------------

	Pour intgrer une animation  un projet, il est utile, voire mme
indispensable, de pouvoir positionner l'animation au pixel prs. Pour cela,
la ligne de commande peut contenir les deux options suivantes:
	-xnnn -ynnn
	'nnn' tant un nombre cod en dcimal et exprimant la position
en x et en y du coin suprieur gauche de l'animation. Ces paramtres ne
sont pris en compte que si ils sont tous deux prsents et si un changement
de rsolution n'est pas ncessaire pour rejouer l'animation.

	Si vous ne connaissez pas  l'avance la taille de l'animation,
M_Player peut vous fournir tout ce dont vous avez besoin grce  l'option
'-rnnn'. dans ce mode, l'animation n'est pas joue mais une structure
d'information est remplie, elle est ainsi dfinie:

	typedef struct
	{
	int etat;
		/* 1=Ok
		0=fichier non trouv
		-1=fichier trouv, mais type inconnu */
	char nom_fichier[12];
		/* chaine du nom+extension+zro */
	char type_fichier[28];
		/* chaine dcrivant le type+zro */
	int etat_graphique;
		/* 1=images avec compression supporte
		0=pas d'images
		-1=images avec compression non supporte */
	int largeur;
	int hauteur;
	long nombre_images;
	unsigned long compression;
		/* dcrit sur 4 octets le type de compression d'image, par
		exemple 'CVID', 'MPEG', 'FLM4', etc... */
	int etat_son;
		/* 1=son prsent avec compression supporte
		0=pas de son
		-1=son prsent mais compression non supporte */
	int bits;
		/* bits par chantillon (8 ou 16) */
	int canaux;
		/* 1 pour mono et 2 pour stro */
	long frequence;
	unsigned long version;
		/* dcrit sur 4 octets la version de M_Player que vous
		appelez, "2.9A" par exemple */
	} MP_INFO;

	Si par exemple l'adresse de votre stucture est 256100, la ligne de
commande  utiliser est celle-ci:
	"-r256100 F:\\ANIMS\\TEST.AVI"
	Mais  ce stade, je vous laisse le soin de programmer le 'C' que
je trouve obscur au niveau des conversions adresse vers entier et entier
vers chane.
	Pour les autres options, je vous renvoie  la documentation de
chaque player d'animations.


Et l'assembleur?
----------------

	Voici en assembleur l'quivalent du programme d'appel avec ligne
de commande et message de retour:


GEM_AES MACRO
   move.l #\1,d1
   move.l #$c8,d0
   trap #2
   ENDM

	text

	GEM_AES appl_init
	GEM_AES appl_find

	GEM_AES appl_write

attente:
	GEM_AES evnt_mesag
	lea message,a0
	cmp #'GT',(a0)
	bne.s attente


	data

appl_init: dc.l ai_cont,global,dum,mon_id,dum,dum
ai_cont: dc.w 10,0,1,0,0
	; l'appel a appl_init remplit directement la structure
	; msg  l'endroit 'mon_id'

msg: dc.w 'MP'
mon_id: dc.w 0,0
	dc.l mp_chaine
	dc.w 'GT',0,0

appl_find: dc.l af_cont,global,dum,player_id,af_addr,dum
af_cont: dc.w 13,0,1,1,0
af_addr: dc.l mp_name
	; l'appel  appl_find remplit directement la stucture
	; utilise par appl_write  l'endroit 'player_id'

appl_write: dc.l aw_cont,global,player_id,dum,aw_addr,dum
aw_cont: dc.w 12,2,1,1,0

player_id: dc.w -1,16
aw_addr: dc.l msg

evnt_mesag: dc.l em_cont,global,dum,dum,em_add,dum
em_cont: dc.w 23,0,1,1,0
em_add: dc.l message

mp_name: dc.b "M_PLAYER",0
mp_chaine: dc.b "-d F:\ANIMS\TEST.AVI",0
	even

	bss

dum: ds.l 4
global: ds.w 15
message: ds.w 16

	end

Et le FORTH?
------------

	Toujours la mme squence mais avec le FORTH. Ce code l est
utilisable tel quel sous l'interprteur (l'avantage du FORTH...).

variable p

appl_init
intout w@ constant mon_id

" M_PLAYER" appl_find
intout w@ constant player_id

16 allot constant MSG
16 allot constant RETOUR

>comp

MSG p ! .w size
%h4D50 p )+!  \ %h4D50='MP'
mon_id p )+!
0      p )+!
.l size
" -d G:\ANIM\MOV\LOGO_QT.MOV" p )+!
.w size
%h4754 p )+!  \ %h4754='GT'
0      p )+!
0      p )+!

player_id 16 MSG appl_write

begin
   RETOUR evnt_mesag
   RETOUR w@ %h4754 =
until

Conclusion
----------
	J'espre vous avoir donn assez d'explications pour que vous vous
lanciez. Sachez pour finir qu'ANIPLAY supporte aussi ce message 'MP' et
qu'une application tournant avec M_Player tournera presque de la mme
manire (aux diffrentes options prs) avec ANIPLAY. Ceci vous laisse le
choix de l'accessoire sans avoir  modifier votre source.

	Guillaume Tello
	gtello@wanadoo.fr

-->legende de l'image MPACC.JPG----
	Exemple d'intgration de M_PLAYER dans le pilote Encyclo. La vido
apparat en fentre au centre de l'cran.
-----------------------------------

