Okapi Renderer

Description

Okapi is a 3D ray tracer.

Quickstart

This project uses Bazel as a build system. The current used version is defined in .bazelversion.

Prerequisites:

The following tools should be installed:

• Git
• Bazel
• A C++ compiler (GCC, Visual Studio, Clang, etc.)

Checkout, build, and run:

All platforms:

git clone https://github.com/Vertexwahn/OkapiRT.git # clone the repository
cd OkapiRT # change directory to cloned repository
cd devertexwahn # switch to the location where the MODULE.bazel file is located

Render a scene with macOS 11/12:

bazel run --config=macos --compilation_mode=opt //okapi/ui:okapi.ui -- \
--scene_filename=$(pwd)//okapi/scenes/ajax/ajax.normal.okapi.xml \
--samples_per_pixel=100

Render a scene with Ubuntu 22.04:

bazel run --config=gcc11 --compilation_mode=opt //okapi/ui:okapi.ui -- \
--scene_filename=$(pwd)//okapi/scenes/ajax/ajax.normal.okapi.xml \
--samples_per_pixel=100

Render a scene with Ubuntu 24.04:

bazel run --config=gcc13 --compilation_mode=opt //okapi/ui:okapi.ui -- \
--scene_filename=$(pwd)//okapi/scenes/ajax/ajax.normal.okapi.xml \
--samples_per_pixel=100

Render a scene with Windows 10/11 x64 with Visual Studio 2019:

bazel --output_base=G:/bazel_output_base run --config=vs2022 --compilation_mode=opt //okapi/ui:okapi.ui -- --scene_filename=okapi/scenes/ajax/ajax.normal.okapi.xml

Render a scene with Windows 10/11 x64 with Visual Studio 2022:

bazel --output_base=G:/bazel_output_base run --config=vs2022 --compilation_mode=opt //okapi/ui:okapi.ui -- --scene_filename=okapi/scenes/ajax/ajax.normal.okapi.xml

Building

Ubuntu 24.04

Command line (bash/zsh)

# Run all tests using GCC 13
bazel test --config=gcc13 //...
# Build all targets using GCC 13
bazel build --config=gcc13 //... 
# Run all tests using Clang19 (ree can not be build using Clang19)
bazel test --config=clang19 -- //... -//ree/...
# Build all targets using Clang19 (ree can not be build using Clang19)
bazel build --config=clang19 -- //... -//ree/...

CLion

There is a Bazel Plugin for CLion. It can be downloaded from here.

You can use the following .bazelproject file:

directories:
  .

test_sources:
  flatland/tests
  okapi/tests

derive_targets_from_directories: true

additional_languages:
  python

build_flags:
  --config=gcc13 # on Ubuntu 24.04
  #--config=macos # on macOS 15
  #--config=vs2022 # on Windows 11
  #--config=clang19

Clang 14

Bazel supports different toolchains. Usually gcc is used a C++ default compiler when using Ubuntu 22.04. But you can also easily use Clang 14 to compile Okapi.

# Build with LLVM
bazel build --config=clang14 //...
# Test with LLVM
bazel test --config=clang14 //...

Remote Build Cache

When switching configuration (--config=gcc11 vs. --config=clang14) it turns out that using a (local) remote build cache server results in better build performance.

You can spin up your own local instance via:

sudo docker run -u 1000:1000 -v ~/bazel_remote_cache:/data \                       
        -p 9090:8080 -p 9092:9092 buchgr/bazel-remote-cache --max_size=30

You can set up a home RC file (.bazelrc) to use the remote build cache:

cd ~
echo "build --remote_cache=http://localhost:9090" >> .bazelrc

Code coverage

Make sure that lcov is installed.

sudo apt install lcov

Go to the directory that contains the WORKSPACE.bazel file and execute:

./coverage.sh --additional_bazel_config=buchgr_remote_cache

Address Sanitizer

There is a build config called asan that can be used for detection of memory errors.

bazel run --config=asan --compilation_mode=opt //okapi/cli:okapi.cli ~/scenes/sphere.okapi.xml

Clang Tidy

bazel build //flatland.cli:flatland --aspects clang_tidy/clang_tidy.bzl%clang_tidy_aspect --output_groups=report

Windows 10/11

Command line (Powershell)

# Build with Visual Studio 2022 C++ Compiler
bazel build --config=vs2022 //...

Using Visual Studio 2022

Use Lavender to generate a solution and project files for Visual Studio.

python3 D:\dev\lavender\generate.py --config=vs2022  //...

Lavender is far from being perfect. It might be necessary to do some modifications to the generated solution and project files.

macOS

bazel build --config=clang14 //...

Development process

I made a short video where I describe how I use test driven development to implement this project:

License

See LICENSE.md.

Copyright notes

The Okapi Project makes use of several software libraries. Besides this, some source code was directly copied from other open-source software libraries or programs. This is always clearly stated as a comment in the source code of Flatland. Additionally, some tools where copied to this repository. The corresponding licenses can be found in the Licenses folder distributed with this source code:

Copied source code/ideas

• Mitsuba Renderer 2 (https://github.com/mitsuba-renderer/mitsuba2) (scene file format) (License)
• pbrt, Version 3 (https://github.com/mmp/pbrt-v3) (Refract, face_forward functions) (License)
• pbrt, Version 4 (https://github.com/mmp/pbrt-v4) (concentric sampling of unit disk) (License)
• bazel_clang_tidy (https://github.com/erenon/bazel_clang_tidy) (almost everything) (License)
• appleseed (https://github.com/appleseedhq/appleseed)

Build related

• LLVM toolchain for Bazel (https://github.com/grailbio/bazel-toolchain) (building Flatland with LLVM) (License)

Third-party dependencies

• {fmt} (https://github.com/fmtlib/fmt) (third party dependency) (License)
• Boost (https://www.boost.org/) (third party dependency) (License)
• catch2 (https://github.com/catchorg/Catch2) (third party dependency) (License)
• gflags (https://github.com/gflags/gflags/) (third party dependency) (License)
• glog (https://github.com/google/glog) (third party dependency) (License)
• Google Test (https://github.com/google/googletest) (third party dependency) (License)
• hypothesis (https://github.com/wjakob/hypothesis) (third party dependency) (License)
• pcg-cpp (https://github.com/imneme/pcg-cpp/) (third party dependency) (License)
• pugixml (https://pugixml.org/, https://github.com/zeux/pugixml) (third party dependency) (License)
• yaml-cpp (https://github.com/jbeder/yaml-cpp) (third party dependency) (License)
• zlib (https://zlib.net/) (License)

Tools

• Bazelisk (https://github.com/bazelbuild/bazelisk) (License)

Artwork

The Stanford Bunny was derived from the Stanford Bunny provided from the Stanford 3D Scanning Repository (see here).

Credits

A big thank goes to all the providers, developers and maintainers of the aforementioned artifacts.