search

MilchRatchet / Luminary

CUDA based Pathtracing Offline and Realtime Renderer
MIT License
30 stars 1 forks source link
c cuda global-illumination gpu graphics path-tracing ray-tracing raytracing

readme

Luminary

CUDA Pathtracing Renderer

About • Usage • Building • Licences • Literature

Daxx Example

Todano Example

Aranos Example

Aranos Example

About

Luminary is a renderer using pathtracing. It aims at rendering high quality images while maintaining usable performance in realtime mode. Usage is supposed to be non-artist friendly, that is, the input consists of only meshes with albedo, material, illuminance and normal textures. All other effects come parameterized. This project is for fun and to learn more about rendering.

The goal is to use as few libraries as feasible. Currently, the following libraries are used: SDL2, zlib, qoi, OptiX and Ceb.

Meshes and textures in the example images are taken from the Ratchet and Clank HD Trilogy and were exported using Replanetizer.

Usage

The scene is described through the Luminary Scene Description format (*.lum). The format is documented in the Luminary File Documentations. It is possible to specify a *.obj file instead of a *.lum file. This will load the mesh and use the default settings. Then one can make changes to the settings and automatically generate a *.lum file.

You can start as:

Luminary [File] [Option]

where File is a relative or absolute path to a *.obj or *.lum file and Option is one or more of:

-o, --offline
        start in offline mode, which renders one image using the specified settings

-t, --timings
        print execution times of some CPU functions

-l, --logs
        write a log file at the end of execution

-s, --samples
        set custom sample count for offline rendering (overrides value set by input file)

-w, --width
        set custom width (overrides value set by input file)

-h, --height
        set custom height (overrides value set by input file)

-p, --post-menu
        open post process menu after rendering an image in offline mode

-u, --unittest
        run a test suite, no rendering is done

-v, --version
        print build information and exit

    --force-displacement
        turn on displacement map usage on Ampere and Turing architecture GPUs

    --no-omm
        turn off opacity micromap usage

    --aov-mode
        generate and output additional variables like albedo, normal, direct lighting and indirect lighting

    --qoi
        set output image format to QOI

    --png
        set output image format to PNG

    --optix-validation
        enables OptiX validation for debugging

Realtime Mode

UI Example

In realtime mode, which is used by default, you can control the camera through WASD, LCTRL, SPACE and the mouse. The sun can be controlled with the arrow keys. A snapshot can be made by pressing [F12]. You can open a user interface with [E] in which you can change most parameters.

📝 In a UI panel, if the number is colored when hovering, you can change the value by holding the left mouse button and moving the mouse left/right.

Building

Requirements:

📝 The use of opacity micromaps and displacement micromaps at the same time is only possible on Ada Lovelace Arch GPUs. (This seems to not be documented anywhere.)

zlib comes as a submodule and is compiled with Luminary, it is not required to have zlib installed. This is due to the compiler limitations of CUDA on Windows which makes usage of zlib-ng inconvenient.

📝 zlib and qoi come as git submodules. Make sure to clone the submodules by using git submodule update --init after cloning Luminary.

CMake Options

Option Description
-DDEBUG=ON/OFF Enable Debug Mode. Default: OFF
-DNATIVE_CUDA_ARCH=ON/OFF Enable that the CUDA architecture is based on the installed GPU. Default: ON
-DSHOW_KERNEL_STATS=ON/OFF Enable that CUDA kernel stats are printed at compilation. Default: OFF

Linux

You need a nvcc compatible host compiler. Which compilers are supported can be found in the CUDA Installation Guide. In general, any modern GCC, ICC or clang will work. By default, nvcc uses gcc/g++.

mkdir build
cmake -B ./build -S .
cd build
make

If cmake fails to find some packages you will have to specify the directory. For this look at the Windows section.

Windows

Additional requirements:

Clang-cl comes for example with mingw-w64 or Visual Studio. MSVC and Windows SDK come with Visual Studio. However, if at some point it is possible to get them standalone, that would probably also suffice. Note that the paths to the CUDA Toolkit, OptiX, SDL2 and SDL2_ttf must be defined in the PATH environment variable, otherwise they need to be defined in CMake using -D{PACKAGENAME}_ROOT="{PATH}".

Regarding MSVC and Windows SDK paths, there are two possibilities:

Option 1:

call "{VS Path}/VC/Auxiliary/Build/vcvarsall.bat" amd64

This sets the environment variables containing all the paths in this terminal instance.

Option 2: Add the paths of the binaries to the PATH environment variable, they look something like that:

{VS Path}/VC/Tools/MSVC/{Version}/bin/Hostx64/x64
{Windows SDK Path}/10/bin/{Version}/x64

Additionally, you need to pass the path to the libraries to cmake, the paths look like this:

{VS Path}/VC/Tools/MSVC/{Version}/lib/x64
{Windows SDK Path}/10/Lib/{Version}

Regarding SDL2: You need to download SDL2_devel and SDL2_ttf_devel for VC, these are for example available on Github.

You can build using the following commands in the main project directory:

mkdir build
call "{VS Path}/VC/Auxiliary/Build/vcvarsall.bat" amd64
cmake -B ./build -S . -G Ninja -DCMAKE_C_COMPILER="{Path}/clang-cl.exe"
cd build && ninja

or alternatively:

mkdir build
cmake -B ./build -S . -G Ninja -DCMAKE_C_COMPILER="{Path}/clang-cl.exe" -DWIN_LIB_DIR="{Windows SDK Path}/10/Lib/10.0.19041.0" -DMSVC_LIB_DIR="{VS Path}/VC/Tools/MSVC/{Version}/lib/x64"
cd build && ninja

Notes:

📝 This is all only necessary because CUDA only supports MSVC as a host compiler on Windows. If this changes in the future then the Windows build will look similar to the Linux build.

Licences

The licence for this code can be found in the LICENCE file.

The default font provided by Luminary is the font Tuffy by Ulrich Thatcher which he placed in the Public Domain.

Literature

This is a list of papers I have used for this project so far. Note that some techniques presented in these papers are not implemented at the moment but their ideas were helpful nonetheless: