heX-Ray

The C++ raytracer for the v6 FMI raytracing course. raytracing-bg.net

Setup on Windows

Recommended setup on Windows if you don't have Visual Studio (e.g. you only have Visual Studio Code)

1. Use the following instructions. It boils down to:
   • Installing MSYS2
   • Installing the MinGW-w64 toolchain using pacman -S --needed base-devel mingw-w64-ucrt-x86_64-toolchain
     • You may also need the make package: pacman -S mingw-w64-ucrt-x86_64-make
   • Adding the path to gcc.exe to the system PATH variable. Likely you'd want to modify it from Environment variables editor in Windows Settings, so that it points to C:\msys64\ucrt64\bin
2. Install CMake — any version later than 3.7 is OK.
3. Setup SDL with one of the following options:
   • (Recommended) Use the development package for MinGW using pacman -S mingw-w64-ucrt-x86_64-SDL2
   • Download the libSDL2 development package for MinGW from here.
     • E.g., use SDL2-devel-2.30.1-mingw.zip
     • Make a "SDK" directory, either in a "develop" subfolder in your user directory (e.g. C:\Users\«USERNAME»\develop) or in C:\
     • Unarchive the SDL2-devel there, e.g. so that CMake can see C:\Users\«USERNAME»\develop\SDK\SDL2-2.30.1\cmake
4. Download the OpenEXR development package for MinGW using pacman -S mingw-w64-ucrt-x86_64-openexr

Useful Visual Studio Code extensions

• C/C++
• CMake tools
• clarity/navigation: Boomkarks, Trailing Spaces, Overtype

To compile hexray manually:

1. Create a "build" sub-directory: mkdir build
2. Change into it: cd build
3. Run CMake, targeting MinGW: cmake -G "MinGW Makefiles" ..
4. Run make to build your code
   • Using the Windows cmd may require using mingw32-make instead of make.

To run it:

1. Copy SDL2.dll from SDL2\x86_64-w64-mingw32\bin\ to your "build" directory (only necessary if you did not use pacman and do not have the ucrt64/bin in $PATH)
2. You may need to copy the OpenEXR .DLLs in the same manner - again, depends on whether they are in your $PATH.
3. You're all set - run hexray.exe

Additional tips for debugging:

The setup works best if you install the CMake Tools extension for Visual Studio Code. This adds an option to change the build type (Debug, Release, MinSizeRel, ...) from the blue ribbon at the bottom of Visual Studio Code screen; the default setting is Debug, which is suitable for debugging. If you want to time how your changes contributed to the rendering speed, compile with Release.

Setup on Windows with Visual Studio

1. Install Visual Studio Community edition (free for personal use). It can be downloaded from here.
   • Only the Desktop Development with C++ is necessary for building the project. There are additional instructions here.
2. Download the SDL2 development package for VC from here
   • E.g., use SDL-devel-2.30.1-VC.zip
3. Install CMake — version 3.13 or newer is OK.
4. (Same as regular setup) Make a "SDK" directory, either in a "develop" subfolder in your user directory (e.g. C:\Users\«USERNAME»\develop) or in C:\
5. (Same as regular setup) Unarchive the SDL2-devel there, e.g. so that CMake can see C:\Users\«USERNAME»\develop\SDK\SDL2-2.30.1\cmake
6. Setup OpenEXR with one of the following options:
   • Using vcpkg. OpenEXR can be built and setup with the following command line vcpkg install openexr:x64-windows --x-install-root="C:\Users\«USERNAME»\develop\SDK".
     • Details on setting up vcpkg can be found here.
     • OR directly use the following command line: git clone https://github.com/microsoft/vcpkg.git && cd vcpkg && bootstrap-vcpkg.bat, then simply execute the install command above.
   • Build OpenEXR during CMake configuration, by adding -DHEXRAY_BUILD_OPENEXR to the cmake configuration line (or with cmake-gui).

To create a Visual Studio solution for hexray

1. Create a "build" sub-directory: mkdir build
2. Change into it: cd build
3. Run CMake, targeting a supported Visual Studio version:
   • Visual Studio 2022 (recommended): cmake -G "Visual Studio 17 2022" -A x64 ..
   • Visual Studio 2019: cmake -G "Visual Studio 16 2019" -A x64 ..
   • Visual Studio 2017: cmake -G "Visual Studio 15 2017 Win64" ..

Build and run inside Visual Studio:

1. Open the generated heX-Ray.sln solution file.
2. Build the solution (Build -> Build Solution OR [Ctrl]+[Shift]+[B] (some VS may have [F7] as shortcut for building)).
3. Start the build (Debug -> Start Debugging OR [F5]).

Setup on Linux

1. (Recommended): install Visual Studio Code (with the recommended extensions like CMake Tools)
2. Download the SDK:
   1. RedHat-based distros like Fedora, CentOS: sudo dnf install SDL2-devel OpenEXR-devel
   2. Debian-based distros like Debian, Ubuntu: sudo apt install libsdl2-dev openexr-dev
3. Open the folder via Visual Studio code, let CMake Tools to configure it, then it should be buildable from Visual Studio code
4. (alternatively): you can always go to the hexray dir, and do mkdir build; cd build; cmake ..; make to build it manually as per above