                       Utilisation de Raider3D sous UNIX

  Documentation Okyz

   Copyright (c) 2002 by OKYZ

   $Id: r3d-fr.sgml,v 1.10 2003/11/22 16:19:44 dockes Exp $ (C) 2002 OKYZ

   Ce document presente l'utilisation de Raider3D sous Unix. Il documente la
   version PRO de Raider3D, mais les informations concernant l'installation
   et la visualisation sont valides pour la version gratuite du visualiseur.

     ----------------------------------------------------------------------

   Table of Contents

   1. Introduction

   2. Installation

   3. Programmes

   4. Configuration

   5. Utilisation

   6. Notes

     ----------------------------------------------------------------------

                                1. Introduction

1.1. Raider3D

   Les outils Raider3D PRO permettent la capture d'images produites par des
   applications 3D. Les images capturees conservent toutes les informations
   3D et peuvent etre sauvegardees dans le format interne Raider3D, puis
   affichees et exploitees dans le visualiseur Raider3D.

   Le visualiseur Raider3D est inclus dans la distribution Raider3D PRO, ou
   il peut etre telecharge gratuitement `a partir du site d'Okyz.

     ----------------------------------------------------------------------

1.2. Principe de fonctionnement

   Raider3D intercepte le flux d'instructions OpenGL(R)[1] avant son
   traitement par le sous-ensemble graphique du systeme. Le flux est
   interprete et traduit au format Raider3D, puis sauvegarde sur demande de
   l'utilisateur.

   Concretement, l'interception est effectuee en prechargeant (LD_PRELOAD)
   une librairie dynamique au demarrage de l'application. Cette librairie
   presente `a l'application une interface OpenGL(R) standard, et appelle le
   code OpenGL(R) natif du systeme apres avoir interprete les donnees.

     ----------------------------------------------------------------------

                                2. Installation

2.1. Licence

   Les fonctions de capture de Raider3D ne fonctionnent que si un fichier de
   licence valide est installe sur la machine. En l'absence d'un fichier de
   licence, une installation Raider3D PRO peut etre faite, mais la librairie
   n'effectuera pas de captures. Vous pouvez vous procurer un fichier de
   licence valide aupres d'Okyz ou de votre distributeur. Veuillez contacter
   support@okyz.com.

   Si vous ne desirez utiliser que les fonctions de visualisation de fichiers
   Raider3D, vous pouvez egalement telecharger le visualiseur gratuit `a
   partir du site d'Okyz..

     ----------------------------------------------------------------------

2.2. Installation

   L'installation de Raider3D ne necessite aucune modification ou
   installation de fichier en dehors du repertoire r3d (sauf eventuellement
   les fichiers de configuration .r3drc propres `a chaque utilisateur). Vous
   n'avez pas besoin d'etre root si vous avez les droits d'ecriture sur le
   repertoire dans lequel vous extrayez la distribution.

   Les distributions Raider3D pour Unix sont fournies sous forme de fichier
   tar compresse. Vous pouvez extraire le fichier n'importe ou dans
   l'arborescence de la machine (typiquement /usr/local/ ou /opt/okyz/). Le
   repertoire cree s'appellera r3d-Version.

   La variable d'environnement R3D_HOME designe le repertoire cree et doit
   toujours etre positionnee pour l'execution des commandes de Raider3D. Le
   repertoire d'extraction sera designe dans la suite comme $R3D_HOME.

   Apres extraction, vous devrez executer le script r3dsetup.sh dans le
   repertoire $R3D_HOME. Ce script cree des versions adaptees `a
   l'environnement local de certains des programmes de Raider3D. r3dsetup.sh
   devra etre execute `a nouveau si vous renommez ou deplacez le repertoire
   d'installation.

   r3dsetup.sh cree en particulier $R3D_HOME/etc/r3dcshrc et
   $R3D_HOME/etc/r3dprofile. Ces fichiers contiennent des instructions `a
   inclure dans un fichier de demarrage de shell utilisateur. r3dcshrc est
   destine au shells de type csh (csh, tcsh). r3dprofile est destine aux
   shells de type Bourne (sh, ksh, bash).

   Example 1. Positionnement de l'environnement avec csh

 source r3dcshrc

   Example 2. Positionnement de l'environnement avec ksh

  . r3dprofile

   L'environnement doit etre positionne avant l'execution de tout programme
   de Raider3D, en particulier, si vous utilisez plusieurs fenetres, dans
   chaque fenetre. Il sera bien sur preferable d'include les commandes dans
   vos fichiers de demarrage shell.

   Si vous possedez un fichier de licence, vous devez ensuite copier le
   fichier de licence dans le repertoire etc/ de l'installation..

   Exemples de commandes d'installation. (/home/me et /var/tmp doivent etre
   remplaces par des chemins appropries):

   Example 3. Avec ksh et un fichier de licence

 % cd /home/me

 % gunzip < /var/tmp/r3dcapt-1.36f-solaris8.tgz | tar xf -

 % cd r3d-1.36f

 % sh r3dsetup.sh

 % cp /var/tmp/r3d_license etc/r3d_license

 % . etc/r3dprofile

   Example 4. Avec tcsh, sans fichier de licence

 % cd /home/me

 % gunzip < /var/tmp/r3dcapt-1.36f-solaris8.tgz | tar xf -

 % cd r3d-1.36f

 % sh r3dsetup.sh

 % source etc/cshrc

   Si vous n'utilisez pas r3dcshrc ou r3dprofile, vous devrez positionner
   deux variables dans l'environnement de chaque utilisateur pour permettre
   l'execution de Raider3D:

     * R3D_HOME doit contenir le nom du repertoire d'installation. Exemple
       Bourne shell:

           R3D_HOME=/home/me/r3d-1.36f/
           export R3D_HOME

     * PATH doit etre modifie pour contenir ${R3D_HOME}/bin, par exemple:

           PATH=$PATH:${R3D_HOME}/bin
           export PATH
          

     ----------------------------------------------------------------------

                                 3. Programmes

   Les principaux programmes de la distribution Raider3D PRO sont:

     * r3dwrap: un shell-script qui positionne l'environnement approprie pour
       la capture d'une application 3D.

     * r3dview: le visualiseur et outil de controle de la capture.

     * r3dsnap: une version de r3dview qui ne cree qu'un petit satellite de
       declenchement de la capture.

     * libGL.so: la librairie qui effectue la capture (elle se trouve dans
       $R3D_HOME/lib.

   La distribution legere (gratuite) du visualiseur ne contient que r3dview,
   dans une version ne permettant pas la sauvegarde.

   Il est `a noter que r3dwrap est un tres petit script qui positionne
   quelques variables d'environnement (selon les systemes, LD_PRELOAD,
   _RLD_LIST, LD_LIBRARY_PATH ...). Son utilisation n'est en aucun cas
   obligatoire, et vous pouvez parfaitement positionner, par exemple,
   LD_PRELOAD directement dans votre script de lancement de l'application, en
   dupliquant les valeurs contenues dans r3dwrap.

     ----------------------------------------------------------------------

                                4. Configuration

4.1. Variables d'environnement

     * R3D_HOME designe le repertoire d'installation de Raider3D. Exemple:
       /usr/local/r3d-0.99b/. Cette variable doit en general etre definie, il
       n'existe pas de valeur par defaut.

     * R3D_RC designe le fichier de configuration de l'utilisateur. Voir plus
       loin pour les valeurs par defaut.

     * R3D_LICENSE designe le fichier de licence `a utiliser. Voir plus loin
       pour les valeurs par defaut.

     * R3D_CAPTUREFILE definit le nom par defaut du fichier de capture (cette
       valeur peut etre changee dynamiquement dans l'interface de capture).
       Si la variable n'est pas definie, la valeur par defaut est
       $HOME/Lastcapture.r3d

     * R3D_LOGFILE designe le nom du fichier ou la librairie de capture
       emettra d'eventuels messages d'erreurs ou d'information. La valeur par
       defaut est $HOME/r3dcaptrace.

     * R3D_LOGLEVEL definit le niveau de verbosite de la librairie de
       capture. Par defaut, seuls les messages d'erreur sont emis. La valeur
       4 permet d'obtenir une trace detaillee de tous les appels OpenGL
       effectues par le programme capture. Les valeurs superieures sont
       normalement uniquement utilisees pour le debug. A partir du niveau 4,
       le volume de traces emises et l'impact sur les performances peuvent
       etre importants.

     * R3D_SNAPNOASK permet de supprimer le dialogue de confirmation qui
       apparait normalement quand le fichier qui serait cree par la capture
       existe dej`a.

     * R3D_LIBGL designe la librairie qui sera chargee pour resoudre les
       appels OpenGL du systeme. Par defaut (si la variable n'est pas defini)
       la librairie Raider3D ouvre X11LIBDIR/libGL.so ou X11LIBDIR est le
       repertoire habituel des librairies X11 pour le systeme (Exemples:
       /usr/openwin/lib, /usr/X11R6/lib).

     * R3D_BINDIR R3D_LIBDIR R3D_SHAREDIR R3D_CONFDIR peuvent etre utilisees
       dans certains cas particuliers pour designer individuellement les
       sous-repertoires de R3D_HOME. Leur utilisation n'est pas conseillee.

     * R3D_TEXDIR designe le repertoire ou seront crees les fichiers images
       de textures si LOGTEXTURESTOBMP est positionne dans le fichier de
       configuration.

     ----------------------------------------------------------------------

4.2. Fichiers de configuration

   Les programmes de Raider3D lisent des variables de configuration `a partir
   de deux fichiers de configuration, l'un pour les parametres de capture,
   l'autre pour les parametres utilisateur du visualiseur (ces fichiers sont
   separes pour des raisons de performance).

     ----------------------------------------------------------------------

  4.2.1. Parametres de capture

   Ce fichier est recherche comme suit:

     * Si la variable d'environnement R3D_RC est definie, sa valeur est le
       nom du fichier d'initialisation.

     * Autrement, le programme teste la presence du fichier .r3drc dans le
       repertoire de l'utilisateur (HOME). Ce fichier sera cree s'il n'existe
       pas.

   Le contenu du fichier de configuration de capture est independant du
   systeme d'exploitation. Il est decrit dans la documentation generique. Les
   variables du fichier ont des definitions generalement convenables dans le
   fichier distribue en standard.

   Dans le cas courant ou l'installation est partagee par plusieurs
   utilisateurs, il est tres souhaitable que chacun cree une copie privee du
   fichier de configuration dans son repertoire ($HOME/.r3drc), ou ailleurs,
   en utilisant la variable R3D_RC. Certaines fonctions du controle de
   capture ne sont activables que si le fichier de configuration est
   accessible en ecriture par l'utilisateur.

     ----------------------------------------------------------------------

  4.2.2. Parametres utilisateur

   Ce fichier contient des valeurs telles que l'adresse de messagerie de
   l'utilisateur ou les valeurs memorisees pour la connection `a une
   conference.

   Le fichier utilise se nomme .r3drc_user, et se trouve dans le repertoire
   de l'utilisateur.

   Au moment du premier acces `a ce fichier (premiere utilisation du
   visualiseur par l'utilisateur), et s'il n'existe pas, il est copie `a
   partir du fichier $R3D_HOME/etc/r3drc_user.

   L'utilisation d'un fichier central permet `a un administrateur de
   positionner des valeurs initiales pour les valeurs communes globales au
   site. Pour creer le fichier central, le plus simple est de partir d'un
   fichier utilisateur cree par le visualiseur (il s'agit d'un fichier texte
   de format evident), et de detruire les lignes non souhaitees pour
   l'initialisation commune.

     ----------------------------------------------------------------------

4.3. Fichier de licence

   Le fichier de licence est recherche comme suit:

     * Si la variable d'environnement R3D_LICENSE est definie, sa valeur est
       le nom du fichier de license. Si ce dernier n'existe pas, le programme
       ne fonctionne pas.

     * Autrement, le programme teste la presence du fichier .r3d_license dans
       le repertoire de l'utilisateur (HOME).

     * Sinon le fichier utilise est le fichier par defaut
       $R3D_HOME/etc/r3d_licence

     ----------------------------------------------------------------------

                                 5. Utilisation

   L'utilisation des fonctions de visualisation ne presente pas de
   particularites sous Unix et ne sera pas decrite ici.

     ----------------------------------------------------------------------

5.1. Capture

   Une capture se deroule comme suit:

    1. Demarrer r3dsnap, ou cliquer le bouton de capture dans r3dview. Vous
       verrez apparaitre une petite fenetre de controle. Le bouton du haut
       permet de changer le nom du fichier de capture, le suivant declenche
       la capture, celui du bas affiche des informations d'etat. r3dsnap a
       ete volontairement reduit au minimum pour ne pas encombrer votre
       ecran. Vous pouvez le laisser s'executer en permanence.

    2. Demarrer l'application en utilisant le script r3dwrap. Par exemple:

 % r3dwrap monappli monappliparam1 monappliparam2

    3. Afficher dans l'application ce que vous desirez capturer, puis cliquer
       le bouton ``Capture'' de r3dsnap. Le curseur de la souris se
       transforme alors en une petite croix. Cliquer dans la fenetre `a
       capturer. r3dsnap affiche ensuite un dialogue confirmant l'execution
       de la capture. Si la capture a ete declenchee `a partir de r3dview,
       l'image capturee apparait dans le visualiseur.

   Il n'est pas conseille en general d'executer en permanence l'application
   dans l'environnement r3dwrap, en raison de la possible influence negative
   sur les performances. Cette influence etant tres variable selon les
   applications et les configurations, il est possible qu'elle soit faible
   dans votre cas, ce qui autorise l'utilisation systematique de r3dwrap,
   permettant ainsi d'etre `a tout moment pret `a effectuer une capture

     ----------------------------------------------------------------------

                                    6. Notes

  Notes

   [1] OpenGL est une marque enregistree de Silicon Graphics Inc.             

     ----------------------------------------------------------------------
