Copyright © 2002 by OKYZ
$Id: r3d-fr.sgml,v 1.10 2003/11/22 16:19:44 dockes Exp $ (C) 2002
OKYZ
Les outils Raider3D PRO permettent la capture d'images produites par des applications 3D. Les images capturées conservent toutes les informations 3D et peuvent être sauvegardées dans le format interne Raider3D, puis affichées et exploitées dans le visualiseur Raider3D.
Le visualiseur Raider3D est inclus dans la distribution Raider3D PRO, ou il peut être téléchargé gratuitement à partir du site d'Okyz.
Raider3D intercepte le flux d'instructions OpenGL®[1] avant son traitement par le sous-ensemble graphique du système. Le flux est interprété et traduit au format Raider3D, puis sauvegardé sur demande de l'utilisateur.
Concrètement, l'interception est effectuée en préchargeant (LD_PRELOAD) une librairie dynamique au démarrage de l'application. Cette librairie présente à l'application une interface OpenGL® standard, et appelle le code OpenGL® natif du système après avoir interprété les données.
Les fonctions de capture de Raider3D ne fonctionnent que si un fichier de licence valide est installé sur la machine. En l'absence d'un fichier de licence, une installation Raider3D PRO peut être faite, mais la librairie n'effectuera pas de captures. Vous pouvez vous procurer un fichier de licence valide auprès d'Okyz ou de votre distributeur. Veuillez contacter support@okyz.com.
Si vous ne désirez utiliser que les fonctions de visualisation de fichiers Raider3D, vous pouvez également télécharger le visualiseur gratuit à partir du site d'Okyz..
L'installation de Raider3D ne nécessite aucune modification ou installation de fichier en dehors du répertoire r3d (sauf éventuellement les fichiers de configuration .r3drc propres à chaque utilisateur). Vous n'avez pas besoin d'être root si vous avez les droits d'écriture sur le répertoire dans lequel vous extrayez la distribution.
Les distributions Raider3D pour Unix sont fournies sous forme de fichier tar compressé. Vous pouvez extraire le fichier n'importe où dans l'arborescence de la machine (typiquement /usr/local/ ou /opt/okyz/). Le répertoire créé s'appellera r3d-Version.
La variable d'environnement R3D_HOME désigne le répertoire créé et doit toujours être positionnée pour l'exécution des commandes de Raider3D. Le répertoire d'extraction sera désigné dans la suite comme $R3D_HOME.
Après extraction, vous devrez exécuter le script r3dsetup.sh dans le répertoire $R3D_HOME. Ce script crée des versions adaptées à l'environnement local de certains des programmes de Raider3D. r3dsetup.sh devra être exécuté à nouveau si vous renommez ou déplacez le répertoire d'installation.
r3dsetup.sh crée en particulier $R3D_HOME/etc/r3dcshrc et $R3D_HOME/etc/r3dprofile. Ces fichiers contiennent des instructions à inclure dans un fichier de démarrage de shell utilisateur. r3dcshrc est destiné au shells de type csh (csh, tcsh). r3dprofile est destiné aux shells de type Bourne (sh, ksh, bash).
L'environnement doit être positionné avant l'exécution de tout programme de Raider3D, en particulier, si vous utilisez plusieurs fenêtres, dans chaque fenêtre. Il sera bien sûr préférable d'include les commandes dans vos fichiers de démarrage shell.
Si vous possédez un fichier de licence, vous devez ensuite copier le fichier de licence dans le répertoire etc/ de l'installation..
Exemples de commandes d'installation. (/home/me et /var/tmp doivent être remplacés par des chemins appropriés):
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'exécution de Raider3D:
R3D_HOME doit contenir le nom du répertoire d'installation. Exemple Bourne shell:
R3D_HOME=/home/me/r3d-1.36f/
export R3D_HOME
PATH doit être modifié pour contenir ${R3D_HOME}/bin, par exemple:
PATH=$PATH:${R3D_HOME}/bin
export PATH
Les principaux programmes de la distribution Raider3D PRO sont:
r3dwrap: un shell-script qui positionne l'environnement approprié pour la capture d'une application 3D.
r3dview: le visualiseur et outil de contrôle de la capture.
r3dsnap: une version de r3dview qui ne crée qu'un petit satellite de déclenchement de la capture.
libGL.so: la librairie qui effectue la capture (elle se trouve dans $R3D_HOME/lib.
La distribution légère (gratuite) du visualiseur ne contient que r3dview, dans une version ne permettant pas la sauvegarde.
Il est à noter que r3dwrap est un très petit script qui positionne quelques variables d'environnement (selon les systèmes, 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.
R3D_HOME désigne le répertoire d'installation de Raider3D. Exemple: /usr/local/r3d-0.99b/. Cette variable doit en général être définie, il n'existe pas de valeur par défaut.
R3D_RC désigne le fichier de configuration de l'utilisateur. Voir plus loin pour les valeurs par défaut.
R3D_LICENSE désigne le fichier de licence à utiliser. Voir plus loin pour les valeurs par défaut.
R3D_CAPTUREFILE définit le nom par défaut du fichier de capture (cette valeur peut être changée dynamiquement dans l'interface de capture). Si la variable n'est pas définie, la valeur par défaut est $HOME/Lastcapture.r3d
R3D_LOGFILE désigne le nom du fichier où la librairie de capture émettra d'éventuels messages d'erreurs ou d'information. La valeur par défaut est $HOME/r3dcaptrace.
R3D_LOGLEVEL définit le niveau de verbosité de la librairie de capture. Par défaut, seuls les messages d'erreur sont émis. La valeur 4 permet d'obtenir une trace détaillée de tous les appels OpenGL effectués par le programme capturé. Les valeurs supérieures sont normalement uniquement utilisées pour le debug. À partir du niveau 4, le volume de traces émises et l'impact sur les performances peuvent être importants.
R3D_SNAPNOASK permet de supprimer le dialogue de confirmation qui apparaît normalement quand le fichier qui serait créé par la capture existe déjà.
R3D_LIBGL désigne la librairie qui sera chargée pour résoudre les appels OpenGL du système. Par défaut (si la variable n'est pas défini) la librairie Raider3D ouvre X11LIBDIR/libGL.so où X11LIBDIR est le répertoire habituel des librairies X11 pour le système (Exemples: /usr/openwin/lib, /usr/X11R6/lib).
R3D_BINDIR R3D_LIBDIR R3D_SHAREDIR R3D_CONFDIR peuvent être utilisées dans certains cas particuliers pour désigner individuellement les sous-répertoires de R3D_HOME. Leur utilisation n'est pas conseillée.
R3D_TEXDIR désigne le répertoire où seront créés les fichiers images de textures si LOGTEXTURESTOBMP est positionné dans le fichier de configuration.
Les programmes de Raider3D lisent des variables de configuration à partir de deux fichiers de configuration, l'un pour les paramètres de capture, l'autre pour les paramètres utilisateur du visualiseur (ces fichiers sont séparés pour des raisons de performance).
Ce fichier est recherché comme suit:
Si la variable d'environnement R3D_RC est définie, sa valeur est le nom du fichier d'initialisation.
Autrement, le programme teste la présence du fichier .r3drc dans le répertoire de l'utilisateur (HOME). Ce fichier sera créé s'il n'existe pas.
Le contenu du fichier de configuration de capture est indépendant du système d'exploitation. Il est décrit dans la documentation générique. Les variables du fichier ont des définitions généralement convenables dans le fichier distribué en standard.
Dans le cas courant où l'installation est partagée par plusieurs utilisateurs, il est très souhaitable que chacun crée une copie privée du fichier de configuration dans son répertoire ($HOME/.r3drc), ou ailleurs, en utilisant la variable R3D_RC. Certaines fonctions du contrôle de capture ne sont activables que si le fichier de configuration est accessible en écriture par l'utilisateur.
Ce fichier contient des valeurs telles que l'adresse de messagerie de l'utilisateur ou les valeurs mémorisées pour la connection à une conférence.
Le fichier utilisé se nomme .r3drc_user, et se trouve dans le répertoire de l'utilisateur.
Au moment du premier accès à ce fichier (première utilisation du visualiseur par l'utilisateur), et s'il n'existe pas, il est copié à partir du fichier $R3D_HOME/etc/r3drc_user.
L'utilisation d'un fichier central permet à un administrateur de positionner des valeurs initiales pour les valeurs communes globales au site. Pour créer le fichier central, le plus simple est de partir d'un fichier utilisateur créé par le visualiseur (il s'agit d'un fichier texte de format évident), et de détruire les lignes non souhaitées pour l'initialisation commune.
Le fichier de licence est recherché comme suit:
Si la variable d'environnement R3D_LICENSE est définie, 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 présence du fichier .r3d_license dans le répertoire de l'utilisateur (HOME).
Sinon le fichier utilisé est le fichier par défaut $R3D_HOME/etc/r3d_licence
L'utilisation des fonctions de visualisation ne présente pas de particularités sous Unix et ne sera pas décrite ici.
Une capture se déroule comme suit:
Démarrer r3dsnap, ou cliquer le bouton de capture dans r3dview. Vous verrez apparaître une petite fenêtre de contrôle. Le bouton du haut permet de changer le nom du fichier de capture, le suivant déclenche la capture, celui du bas affiche des informations d'état. r3dsnap a été volontairement réduit au minimum pour ne pas encombrer votre écran. Vous pouvez le laisser s'exécuter en permanence.
Démarrer l'application en utilisant le script r3dwrap. Par exemple:
% r3dwrap monappli monappliparam1 monappliparam2
Afficher dans l'application ce que vous désirez capturer, puis cliquer le bouton ``Capture'' de r3dsnap. Le curseur de la souris se transforme alors en une petite croix. Cliquer dans la fenêtre à capturer. r3dsnap affiche ensuite un dialogue confirmant l'exécution de la capture. Si la capture a été déclenchée à partir de r3dview, l'image capturée apparaît dans le visualiseur.
Il n'est pas conseillé en général d'exécuter en permanence l'application dans l'environnement r3dwrap, en raison de la possible influence négative sur les performances. Cette influence étant très variable selon les applications et les configurations, il est possible qu'elle soit faible dans votre cas, ce qui autorise l'utilisation systématique de r3dwrap, permettant ainsi d'être à tout moment prêt à effectuer une capture
| [1] |
OpenGL est une marque enregistrée de Silicon Graphics Inc. |