Accueil / FAQ

FAQ — problèmes courants

Les situations les plus fréquentes rencontrées à la compilation, au lancement et au rendu, avec les messages exacts émis par le moteur et la marche à suivre.

Aucun renderer / interface ne se charge

Les plugins .so sont recherchés dans le dossier ./plugins relatif au répertoire courant, et non à l’emplacement de l’exécutable. Si vous lancez le programme depuis un autre dossier, ce chemin n’existe pas et aucun renderer ni interface n’est chargé. Lancez toujours le binaire depuis la racine du projet :

cd /chemin/vers/raytracer_V2
./raytracer tests/configs/subject.json

Si ./plugins est absent ou vide, (re)compilez avec make : la compilation produit à la fois ./raytracer et les plugins .so dans ./plugins. Un chargement correct affiche sur la sortie standard :

Loaded 2 renderer plugin(s)

« Failed to load font »

L’interface graphique charge sa police depuis assets/font.ttf par un chemin relatif. Ce message apparaît lorsque le programme est lancé depuis un dossier où assets/ n’existe pas. La solution est identique à celle des plugins : lancez le programme depuis la racine du projet, là où se trouvent assets/ et plugins/.

« Setting vertical sync not supported »

Il s’agit d’un message informatif de SFML, sans conséquence sur le rendu. Il est fréquent sous WSL, où l’affichage OpenGL passe par un rendu logiciel (Mesa/llvmpipe) qui ne gère pas la synchronisation verticale. Vous pouvez l’ignorer : l’image s’affiche et se rend normalement.

Un rapport « LeakSanitizer: detected memory leaks » à la fermeture

Le projet est compilé avec AddressSanitizer (-fsanitize=address dans le Makefile), qui embarque un détecteur de fuites (LeakSanitizer) exécuté automatiquement à la fermeture du programme.

Si le rapport pointe des adresses <unknown module> issues de calloc, sans aucune image de la pile appartenant au code du projet, il s’agit d’une petite allocation unique du pilote graphique Mesa/swrast (rendu logiciel sous WSL), extérieure au moteur. Ces allocations de pilote ne sont pas symbolisées et ne peuvent donc pas être filtrées par nom de fonction.

Pour n’auditer que les fuites du code applicatif — qui, elles, doivent être nulles — lancez un rendu en mode headless : il n’ouvre aucun contexte graphique, donc aucune allocation du pilote n’intervient.

# Audit des fuites du moteur (sans interface graphique)
ASAN_OPTIONS=detect_leaks=1 ./raytracer -r sortie.png scene.json

Pour une session graphique, vous pouvez désactiver uniquement le rapport de fuites afin de ne pas être gêné par l’allocation du pilote :

# Désactiver le rapport de fuites pour une session graphique
ASAN_OPTIONS=detect_leaks=0 ./raytracer scene.json

« object "…" : … » ou « Missing camera / objects »

Le SceneParser signale les problèmes du fichier de scène sur la sortie d’erreur. Les messages structurants sont notamment :

Vérifiez donc que :

• le fichier est un JSON valide et porte l’extension .json (sinon INVALID_FILE_EXTENSION) ;
• les sections camera et objects sont présentes ;
• la caméra fournit resolution ([largeur, hauteur]) et fieldOfView, qui sont obligatoires ;
• chaque objet possède un type valide (voir la liste des types).

Mon matériau ne s’applique pas

Un objet référence un matériau par son nom ("material": "Mon matériau"). Ce nom doit correspondre exactement à une entrée name de la section materials. Dans le cas contraire, le parseur émet sur la sortie d’erreur :

object "…" material: Unknown material "…"

et l’objet est ignoré. Vérifiez l’orthographe et la casse du nom, et que le matériau est bien déclaré dans materials avant d’être référencé.

Les objets métalliques ou en verre paraissent très sombres

Le moteur ne dispose pas d’environnement (skybox) : un matériau très réfléchissant ou transparent renvoie donc principalement du « vide » sombre là où il n’y a ni géométrie ni lumière à réfléchir ou à réfracter. Deux remèdes :

• ajoutez de la géométrie et des lumières autour de l’objet, pour lui donner quelque chose à réfléchir ;
• ou réduisez reflectivity/transparency du matériau pour un rendu plus lisible.

« --render cannot be combined with --server » et autres erreurs d’options

Certaines options de la ligne de commande sont mutuellement exclusives. Les messages exacts émis sur la sortie d’erreur sont :

Utilisez --help pour afficher l’usage complet et les exemples.

Fenêtres / interface sous WSL

Sous WSL, l’interface rend le fenêtrage thread-safe (XInitThreads) et force le rendu OpenGL logiciel afin de supporter plusieurs fenêtres (pop-ups) sans planter. Si l’interface ne s’ouvre pas :

• assurez-vous que WSLg (ou un serveur X) est disponible ;
• vérifiez que la variable DISPLAY est bien définie.

Un maillage .obj ne se charge pas

Vérifiez que le chemin de la clé file est correct par rapport au répertoire d’où vous lancez le programme, et non par rapport au fichier de scène : un chemin relatif est résolu depuis le répertoire courant. Des maillages d’exemple sont fournis dans tests/obj/.

À l’import, les faces sont triangulées et un BVH local est construit pour le maillage ; pour de très gros modèles, cette première construction peut prendre un instant.