# Utilisation de Raider3D sous UNIX

### Documentation Okyz

Copyright © 2002 by OKYZ

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

Ce document présente 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.

# 1. Introduction

## 1.1. Raider3D

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.

## 1.2. Principe de fonctionnement

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.

# 2. Installation

## 2.1. Licence

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..

## 2.2. Installation

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`).

Example 1. Positionnement de l'environnement avec csh

    source r3dcshrc

Example 2. Positionnement de l'environnement avec ksh

     . r3dprofile

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

# 3. Programmes

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`.

# 4. Configuration

## 4.1. Variables d'environnement

- `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.

## 4.2. Fichiers 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).

### 4.2.1. Paramètres de capture

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.

### 4.2.2. Paramètres 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.

## 4.3. Fichier de licence

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`

# 5. Utilisation

L'utilisation des fonctions de visualisation ne présente pas de particularités sous Unix et ne sera pas décrite ici.

## 5.1. Capture

Une capture se déroule comme suit:

1. 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.

2. Démarrer l'application en utilisant le script `r3dwrap`. Par exemple:

       % r3dwrap monappli monappliparam1 monappliparam2

3. 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

# 6. Notes

### Notes

[1] | OpenGL est une marque enregistrée de Silicon Graphics Inc.