Raytracer docs
🌐 FR

Home / FAQ

FAQ — common problems

The situations most often encountered when building, launching and rendering, with the exact messages the engine prints and how to fix them.

No renderer / interface loads

The .so plugins are looked up in the ./plugins directory relative to the current working directory, not to the executable’s location. If you launch the program from another folder, that path does not exist and no renderer or interface is loaded. Always run the binary from the project root:

cd /path/to/raytracer_V2
./raytracer tests/configs/subject.json

If ./plugins is missing or empty, (re)build with make: the build produces both ./raytracer and the .so plugins in ./plugins. A correct load prints to standard output:

Loaded 2 renderer plugin(s)

The reported count reflects the plugins actually found in ./plugins. If it shows 0, the directory is empty or cannot be found from the launch directory.

“Failed to load font”

The graphical interface loads its font from assets/font.ttf using a relative path. This message appears when the program is launched from a folder where assets/ does not exist. The fix is the same as for plugins: run the program from the project root, where both assets/ and plugins/ live.

“Setting vertical sync not supported”

This is an informational SFML message with no effect on rendering. It is common under WSL, where OpenGL display goes through software rendering (Mesa/llvmpipe), which does not support vertical sync. You can safely ignore it: the image displays and renders normally.

A “LeakSanitizer: detected memory leaks” report on exit

The project is built with AddressSanitizer (-fsanitize=address in the Makefile), which bundles a leak detector (LeakSanitizer) run automatically when the program exits.

If the report points at <unknown module> addresses coming from calloc, with no stack frame belonging to the project code, it is a single small allocation from the Mesa/swrast graphics driver (software rendering under WSL), external to the engine. These driver allocations are not symbolized and therefore cannot be filtered by function name.

To audit only the application code’s leaks — which must be zero — run a render in headless mode: it opens no graphics context, so no driver allocation occurs.

# Audit engine leaks (no graphical interface)
ASAN_OPTIONS=detect_leaks=1 ./raytracer -r sortie.png scene.json

For a graphical session, you can disable just the leak report so the driver allocation does not get in the way:

# Disable the leak report for a graphical session
ASAN_OPTIONS=detect_leaks=0 ./raytracer scene.json

detect_leaks=0 disables only the leak detector. AddressSanitizer’s other checks (use-after-free, buffer overflows, double-free…) remain active in all cases.

“object "…": …” or “Missing camera / objects”

The SceneParser reports scene-file problems on standard error. The key structural messages include:

MessageCause
Missing camera sectionThe camera section is absent from the JSON.
Missing objects sectionThe objects section is absent from the JSON.
Missing camera resolutionThe camera has no resolution key.
Camera resolution must be [width, height]resolution is not an array of 2 numbers.
Missing camera fovThe camera has no fieldOfView key.
Missing object typeAn object has no type key (string).
object "…": Unknown or incomplete object definitionThe type is unknown or required fields are missing.

So make sure that:

  • the file is valid JSON and has the .json extension (otherwise INVALID_FILE_EXTENSION);
  • the camera and objects sections are present;
  • the camera provides resolution ([width, height]) and fieldOfView, which are required;
  • every object has a valid type (see the list of types).

Unknown keys on an object are silently ignored: the parser only processes the fields it knows. A misspelled parameter (e.g. normal instead of axis for a plane) therefore raises no error: the object simply falls back to its default values.

My material is not applied

An object references a material by its name ("material": "My material"). This name must match exactly a name entry in the materials section. Otherwise the parser prints to standard error:

object "…" material: Unknown material "…"

and the object is skipped. Check the name’s spelling and case, and that the material is declared in materials before being referenced.

Metallic or glass objects look very dark

The engine has no environment (skybox): a highly reflective or transparent material therefore mostly returns dark “emptiness” wherever there is no geometry or light to reflect or refract. Two remedies:

  • add geometry and lights around the object, so it has something to reflect;
  • or lower the material’s reflectivity/transparency for a more readable result.

“--render cannot be combined with --server” and other option errors

Some command-line options are mutually exclusive. The exact messages printed to standard error are:

MessageCause
Error: --render (headless) cannot be combined with --server or --connect.Headless mode (-r/--render) cannot be combined with the cluster.
Error: --server and --connect cannot be used together.--server and --connect are exclusive.
Error: --connect requires an IP address and a PORT.--connect expects two arguments: IP then PORT.
Error: unknown option '…'. Use --help for usage.Unrecognized option.

Use --help to print the full usage and examples.

Windows / interface under WSL

Under WSL, the interface makes windowing thread-safe (XInitThreads) and forces software OpenGL rendering so that multiple windows (pop-ups) can open without crashing. If the interface does not open:

  • make sure WSLg (or an X server) is available;
  • check that the DISPLAY variable is actually set.

An .obj mesh does not load

Check that the file key’s path is correct relative to the directory you launch from, not relative to the scene file: a relative path is resolved from the current working directory. Example meshes are provided in tests/obj/.

On import, faces are triangulated and a local BVH is built for the mesh; for very large models, this first build may take a moment.