Kataglyphis-BeschleunigerBallett

A modern graphics engine built on top of Vulkan+OpenGL. Serves also as playground for learning various best practices in Graphic APIs, CMake, Rust, Modern C++ ... 🌋🌋🌋

see also Official homepage.

Table of Contents

• About The Project
  • Built With
  • Key Features
  • Dependencies
  • Useful tools
  • Benchmarking
  • VSCode Extensions
• Getting Started
  • Specific version requirements
  • Installation
• Shaders
• Tests
• Docker
  • Linux
  • Windows
• Roadmap
• Contributing
• License
• Contact
• Acknowledgements
• Literature
• Common issues

About The Project

This project provides me a solid Vulkan/OpenGL renderer starting point for implementing modern established rendering techniques and getting quickly started in own research topics.
As this project evolved it gained additional functionality:

• collecting/using CMake best practices
• collecting/using C++ best practices and testing new lang features 😊
• collecting experience in fuzzy/benchmark testing in C++
• collecting experience in integrating 💌 Rust 💌 code in Cmake projects

I frequently test under Linux and Windows.
For more information regarding the build environment refer to my Kataglyphis-ContainerHub repository.

Key Features

Category	Feature	Implement Status
Vulkan Render agnostic	Rasterizer	✔️
	Raytracing	✔️
	Path tracing	✔️
	PBR support (UE4, Disney, etc.)	✔️
	.obj Model loading	✔️
	Mip Mapping	✔️
OpenGL Render agnostic
	Directional Lights	✔️
	Point Lights	✔️
	Spot Lights	✔️
	Directional Shadow Mapping	✔️
	Omni-Directional Shadow Mapping	✔️
	Cascaded Shadow Mapping	✔️
	Cloud system	✔️
	3D-worley noise generation	✔️
	.obj Model loading	✔️
	PBR support (UE4,disney,phong, etc.)	✔️
	Support for #include directives in shaders.	✔️
	Sky box	✔️
	Supporting compute shader	✔️
	On the fly 3D worley/perlin noise creation	✔️
C++/CMake agnostic	Code coverage for Clang	✔️
	Advanced unit testing	🔶
	Advanced performance testing	🔶
	Advanced fuzz testing	🔶

Legend:

• ✔️ - completed
• 🔶 - in progress
• ❌ - not started

Dependencies

• Vulkan 1.4
• OpenGL 4.6
• GLAD
• glm
• glfw
• tinyobjloader
• stb
• vma
• tinygltf
• gtest
• gbenchmark
• google fuzztest
• cmake
• gsl
• nlohmann_json
• SPDLOG

Optional

• Rust
• corrision-rs
• cxx
• uv

Useful tools (you might also considering :) )

• NSIS
• doxygen
• cppcheck
• renderdoc
• nsightgraphics
• valgrind
• clangtidy
• visualstudio
• ClangPowerTools
• Codecov
• Ccache
• Sccache

Benchmarking

• gperftools

VSCode Extensions

• CMake format
• CMake tools
• CppTools

Getting Started

Specific version requirements

C++23 or higher required.
C17 or higher required.
CMake 4.2.0 or higher required.

Installation

NOTE: On Windows use Git Bash

1. Clone the repo

   git clone --branch develop --recurse-submodules git@github.com:Kataglyphis/Kataglyphis-BeschleunigerBallett.git

2. Use the scripts (in the Scripts folder for installing dependencies on your system)
3. Then build your solution with [CMAKE] (https://cmake.org/)
   You can follow my steps from my CMake best practices repo.
   For now the features in Rust are experimental. If you want to use them install Rust and set RUST_FEATURES=ON on your CMake build.

Alternatively you can use the build scripts I use for my standard configuration:

• [buildEngine.sh]
• [buildEngine.bat]

$ {WORKING_DIR}/GraphicsEngineVulkan/buildEngine[.sh/.bat]

Packaging

On Linux, binary packages are generated with CPack (TGZ and DEB). Use this repeatable workflow after a clean checkout or after deleting build folders:

1. Configure and build in Release mode
2. Generate release packages (TGZ, DEB)
3. Generate AppImage packages as standard packaging step

# 1) Release configure + build
bash ./Scripts/Linux/cmake-configure-build.sh \
  --vulkan-setup-script /opt/vulkan/1.4.341.1/setup-env.sh \
  --preset linux-release-clang \
  --build-dir build-release \
  --build-config Release

# 2) CPack package target (TGZ + DEB)
bash ./Scripts/Linux/cmake-configure-build.sh \
  --vulkan-setup-script /opt/vulkan/1.4.341.1/setup-env.sh \
  --build-dir build-release \
  --skip-configure true \
  --build-target package

# 3) Standard AppImage packaging
cmake -S . -B build-release-appimage \
  --preset linux-release-clang \
  -DCPACK_ENABLE_APPIMAGE=ON
cmake --build build-release-appimage --config Release --target package

Generated artifacts are written to the selected build folder (for example *.tar.gz, *.deb, and AppImage artifacts). For AppImage builds, appimagetool must be available in your PATH.

Shaders

I provide two ways for compiling shaders with. Hence if you want to add new files as #include in your shaders you have to modify the files: (should be self-explanatory)

• [include/vulkan_base/ShaderIncludes.hpp]
• [cmake/CompileShadersToSPV.cmake]

appropriately.

Tests

I follow the test setup as descriped in: CMake best practices

Docker

You can find all details in my Kataglyphis-ContainerHub repository.

Linux

If you want to run it on NVIDIA GPUs you will have to
install the NVIDIA Container Toolkit
before you proceed with the next steps.

Windows

NOTE: Pls for GPU accelerated Windows Docker have a look here

Roadmap

Watch the refman generated by doxygen.

• Watch it here

Contributing

Contributions are what make the open source community such an amazing place to be learn, inspire, and create. Any contributions you make are greatly appreciated.

1. Fork the Project
2. Create your Feature Branch (git checkout -b feature/AmazingFeature)
3. Commit your Changes (git commit -m 'Add some AmazingFeature')
4. Push to the Branch (git push origin feature/AmazingFeature)
5. Open a Pull Request

License

Distributed under the MIT-License. See LICENSE for more information.

Contact

Jonas Heinle - @Cataglyphis_ - renderdude@jotrockenmitlocken.de

Project Link: https://github.com/Kataglyphis/GraphicsEngineVulkan

Acknowledgements

You will find important links to information in the code. But here in general some good sources of information:

Thanks for free 3D Models:

• Morgan McGuire, Computer Graphics Archive, July 2017 (https://casual-effects.com/data)

• Viking room

• Loading Screen Image

Literature

Some very helpful literature, tutorials, etc.

• View Frustum Culling

OpenGL

• learnopengl.com
• ogldev.org
• Cascaded Shadow Maps
• Compute Shader in OpenGL

Clouds

• pbr-book
• Inigo Quilez
• Shadertoy Horizon Zero Dawn
• Sebastian Lague
• Horizon Zero Dawn
• Clouds and noise
• Shadertoy Clouds using 3D Perlin noise

Noise

• Worley noise online demo

Vulkan

• Udemy course by Ben Cook
• Vulkan Tutorial
• Vulkan Raytracing Tutorial
• Vulkan Tutorial; especially chapter about integrating imgui
• NVidia Raytracing tutorial with Vulkan
• Blog from Sascha Willems

Physically Based Shading

• Advanced Global Illumination by Dutre, Bala, Bekaert
• The Bible: PBR book
• Real shading in Unreal engine 4
• Physically Based Shading at Disney
• RealTimeRendering
• Understanding the Masking-Shadowing Function in Microfacet-Based BRDFs
• Sampling the GGX Distribution of Visible Normals

Path tracing

• NVIDIA Path tracing Tutorial

Docker

• Vulkan Minimal Docker setup
• scoop
• Docker container windows GPU
• Docker windows

Common issues

• Problem: If Validation Layers could not be found:

  A value given directly by extern c function 322
  [XXXX-XX-XX 10:30:40.877] [error] Validation layers requested, but not available!
  [XXXX-XX-XX 10:30:40.879] [error] Failed to create a Vulkan instance!
  [XXXX-XX-XX 10:30:40.880] [error] Validation layers requested, but not available!
  [XXXX-XX-XX 10:30:40.882] [error] Failed to create a Vulkan instance!
  ERROR:             vkGetInstanceProcAddr: Invalid instance [VUID-vkGetInstanceProcAddr-instance-parameter]

  Solution for linux:

  sudo apt install libvulkan1 vulkan-tools vulkan-validationlayers

  Otherwise you would have to install them via sdk.