R4: Reasonably Rapid Relativistic Raytracer

An easy to use and reasonably quick raytracer capable of all the basic raytracing things (loading meshes, texture mapping, dielectric materials, path tracing, etc.), as well as ray marching geodesics of non-spinning black holes.

This 30s animation shows some of what R4 can do.

Note

This raytracer began as part of the University of Waterloo's CS488 graphics course. It's been rewritten since then.

Usage

Compile the raytracer into ./build/Raytracer:

cd raytracer && premake4 gmake
# Build the raytracer
make Raytracer config=release
# Render the default scene
./build/Raytracer

See the .lua files in assets/scenes/ for examples of building scenes!

Setup

I want setup to be as easy as possible, so everything you need is within this repo, including lua language support, clang formatting, and .vscode settings.

All you have to do is:

1. Have g++ (C++17).
2. Have make.
3. Have premake4.

Setup instructions for Linux

1. Get g++ and make, eg. sudo apt install g++ make if you're on Debian/Ubuntu.
2. Download the premake4 Windows binary.
   • Run sudo mv premake4 /usr/local/bin/ && sudo chmod +x /usr/local/bin/premake4 to set it up.
3. You may need to use Powershell or Git Bash when running commands.
4. And you're off to the races!

Setup instructions for Windows

I recommend MSYS2 to get g++, make, and premake4 configured correctly.

1. Install MSYS2. Add MSYS2 to your PATH (or, just run all future commands from the MSYS2 MinGW64 shell).
   • Run pacman -S mingw-w64-x86_64-gcc make.
2. Download the premake4 Windows binary.
   • Drop premake4.exe into /usr/local/bin inside your MSYS2 installation (e.g. C:\msys64\user\local\bin).
3. And you're off to the races!

Tools

In the tools/ directory, I've included some C++, Bash, and Python utility tools for various tasks, including:

• animation/: A standalone bash script that converts many rendered frames into a .mp4 video file.
• assets/: A c++ tool for tuning the colours and alphas of .exr and .png files, and saving them.
• blender/: A few helper python files for exporting blender scenes into scene.lua files this program can read.
• perlin/: A simple c++ perlin noise generator that can save to .png.
• spiral/: A simple c++ texture generator for spiral textures on tori that saves to .png.

Contributing

If you would like to contribute to R4, feel free to open a pull request! I'll review it within a few days. All I ask is:

1. Classify your PR as feat:, fix:, refactor:, or chore: accordingly.
2. Mention the reason for your changes in your PR description.
3. Lastly, do not submit LLM-generated code that you haven't combed over.

Thanks, and excited to see what you have to add!

Note

More detailed contribution instructions coming soon.

Special Thanks

Thank you to Gladimir Baranoski, both for teaching me most of what this raytracer does, and for permission to include SceneLua.cpp and the .obj parsing in Mesh.cpp in this open-source project.

License

Licensed under the GNU GPL v3.0. Use or fork freely with attribution, as long as you don't make it closed-source :P.