Kataglyphis-Renderer

A graphics engine built on top of Vulkan+OpenGL .

(see also Official homepage)

Official homepage

Key Features • How To Use • Download • Credits • Related • License

Table of Contents

1. About The Project
   • Built With
   • Key Features
2. Getting Started
   • Prerequisites
   • Installation
3. Shaders
4. Tests
5. Roadmap
6. Contributing
7. License
8. Contact
9. Acknowledgements
10. Literature
11. Common issues

About The Project

This project provides me a solid Vulkan renderer starting point for implementing modern established rendering techniques and getting quickly started in own research topics. Frequently tested under

• [latest windows and ubuntu version]
• [GCC/CLANG/MSVC]

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

Built With

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

Useful tools (you might also considering :) )

• cppcheck
• renderdoc
• nsightgraphics
• valgrind
• clangtidy
• visualstudio
• ClangPowerTools
• Codecov

Getting Started

Prerequisites

Dependencies to libraries are stated above.
C++23 or higher required.
C17 or higher required.
CMake 3.28.3 or higher required.

NOTE: This project relies on the new hardware capabilities for RRT.

Installation

1. Clone the repo

   git clone --recurse-submodules [email protected]:Kataglyphis/Kataglyphis-Renderer.git

2. Then build your solution with [CMAKE] (https://cmake.org/)
   Here the recommended way over command line after cloning the repo:
   

NOTE: Here we use CmakePresets to simplify things. Consider using it too or just build on a common way ...

(for clarity: Assumption you are in the dir you have cloned the repo into)

$ mkdir build ; cd build
# enlisting all available presets
$ cmake --list-presets=all ../
$ cmake --preset <configurePreset-name> ../
$ cmake --build --preset <buildPreset-name> .

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

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

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

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 have two tests suites.

1. Compilation Test Suite: This suite gets executed every compilation step. This ensures the very most important functionality is correct before every compilation.

2. Commit Test Suite: This gets executed on every push. More expensive tests are allowed :)

Static Analyzers

clang --analyze --output-format html $(find Src -name '*.cpp' -o -name '*.cc')
scan-build cmake --build .
clang-tidy -p=./build/compile_commands.json  $(find Src -name '*.cpp' -o -name '*.cc')

Format cmake files

conda create -n cmake_formating python=3.10
pip install pyyaml
pip install cmake-format
cmake-format -c ./.cmake-format.yaml -i $(find cmake -name '*.cmake' -o -name 'CMakeLists.txt')

Format code files

clang-format -i $(find include -name "*.cpp" -or -name "*.h" -or -name "*.hpp")

Docs

Build the docs

pip install sphinx
pip install sphinx-press-theme
pip install myst-parser
cd docs 
make html

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 BSD 3-Clause "New" or "Revised" License. See LICENSE for more information.

Contact

Jonas Heinle - @Cataglyphis_ - [email protected]

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

CMake/C++

• Cpp best practices

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

Common issues