ktstephano / stratusgfx

Realtime 3D rendering engine

Release State: Pre-Release/Beta

Engine Version: 0.10

Realtime 3D rendering engine. Expect bugs and instability as it is still under development. The engine is free and open source (licensed under MPL-2.0). Please feel free to contact me about any questions or issues you have!

(3D Model: Intel Sponza)

(3D Model: Bistro)

(3D Model: San Miguel)

(3D Model: Cornell Box)

-> Video Feature Reel

-> Graphics Image Feature Reel

-> High Level Architecture Overview

-> How A Frame Is Rendered

Roadmap for Engine Version 0.11 (in development)

• Virtual shadow maps
• New Vulkan + DirectX 12 graphics backend (dropping OpenGL support)
• Two-pass occlusion culling
• Texture streaming
• Improved GI quality and performance
• New engine module system for easier extensibility
• Refactored renderer to make adding custom passes easier

Purpose

This project was created as a hobby research project for learning low level engine development and implementing modern graphics techniques.

Use Cases

At its core Stratus is a rendering engine first with minimal features found in general purpose engines. Its focus is on modern 3D graphics capabilities. Because of this it has two main use cases:

1. People taking it and using it as a learning resource.

2. Integration into other general purpose engines (new or existing) and modeling tools.

Because of the MPL license, any community changes made to the rendering code will continue to help others in new and existing projects that use it.

Current Supported Features

Graphics

• Physically based metallic-roughness pipeline
• Realtime global illumination
• Spatiotemporal image denoising
• Raymarched volumetric lighting and shadowing
• Cascaded shadow mapping
• Deferred lighting
• Mesh LOD generation and selection
• GPU Frustum Culling
• Screen Space Ambient Occlusion (SSAO)
• Reinhard or ACES Tonemapping
• Fog
• Bloom
• Fast Approximate Anti-Aliasing (FXAA)
• Temporal Anti-Aliasing (TAA)

Engine

• Pool allocators
• GPU memory allocators/managers
• Multi threaded utilities
• Concurrent hash map
• Entity-Component System (ECS)
• Logging

Modern graphics API features used

• Compute shaders
• Direct state access
• Programmable vertex pulling
• Multi draw elements indirect
• Shader storage buffer

Software/Driver Requirements

Type	Requirement
OS	Windows 10/11 or Linux
Compiler	Support for C++17
Graphics	Support for OpenGL 4.6

Minimum Hardware Requirements

Type	Minimum
CPU	Ryzen 3 1200 (quad core)
RAM	8 GB
GPU	Nvidia GTX 1050 Ti

Downloading Sample 3D Model Data

1. A zip file containing Sponza, Interrogation Room, San Miguel, Bistro, Bathroom, etc. can be found here: https://drive.google.com/file/d/1nVkEuhDaSK61XmTSoNOUUEU5a-U-mtKO/view?usp=share_link

2. Extract the Resources.zip folder into the root of StratusGFX. It will then be at the same level as Bin/, Examples/, Source/, Tests/. Make sure that the folder structure looks like StratusGFX/Resources/* where * will be folders such as Sponza, Bistro, etc.

(see further down this README for a full list of credits for where the sample 3D model data came from)

Building For Windows & Linux

This code base will currently not work on MacOS. Linux and Windows should both be fine so long as the graphics driver supports OpenGL 4.6 and the compiler supports C++17.

First set up the repo

git clone --recursive https://github.com/KTStephano/StratusGFX.git
cd StratusGFX

Prerequisites

Make sure your graphics drivers are up-to-date.

On Linux you will likely need to install the following packages:

libgl1-mesa-dev
libxext-dev

(or the equivalent for your distro)

Option 1: Standard Build

This is the preferred build if all you want to do is build the examples and run them.

python3 ./build_examples.py --assimp

-> LINUX NOTE: If you get an error during the assimp build of the above step, use your local package manager to install assimp instead. Then re-run the above step as:

python3 ./build_examples.py

Now you should be able to go into the StratusGFX/Bin/ folder and run the examples!

Option 2: Development Build

Use this if you plan to make source code changes to anything in Examples/ Source/ or Tests/. You will only need to build the dependencies once and then after that you can just re-run the cmake build step any time you make changes.

Build 3rd party dependencies -> should only need to do this once per clone

python3 ./dependency_build.py --assimp

-> LINUX NOTE: If you get an error while building assimp, use your local package manager to install assimp instead. Then re-run the above step as:

python3 ./dependency_build.py

Now build the StratusGFX source

Windows

cmake -Bbuild -S. -DBUILD_TESTS=ON
cmake --build build/ -j 8 --config RelWithDebInfo

Linux

cmake -Bbuild -S. -DCMAKE_BUILD_TYPE=RelWithDebInfo -DBUILD_TESTS=ON
cmake --build build/ -j 8

All executables will be put into StratusGFX/Bin folder. Make sure you run them while inside StratusGFX/Bin/. Good ones to run to see if it worked are

Ex00_StartupShutdown.exe (runs through initialize, run one frame, shutdown sequence)
Ex01_StratusGFX.exe (you should see a forest of red cubes since textures aren't bundled with source)
StratusEngineUnitTests.exe
StratusEngineIntegrationTests.exe

Running The Examples

If you are having trouble with the downloading of the 3D assets or running the examples, a good place to check is here:

https://github.com/KTStephano/StratusGFX/wiki/Examples

If this does not help then feel free to send me an email ([email protected]) or open an issue.

Credits For 3D Assets Used In Examples

Credits for the 3D assets used in the examples/demos are as follows:

Crytek Sponza

Intel Sponza

San Miguel

Bistro

Junk Shop

The Bathroom

Interrogation Room

Abandoned Warehouse

First Places to Look

You can check High Level Architecture Overview, or you can start by looking through the code under Examples/ExampleEnv00 and Examples/ExampleEnv01. They both depend on code that is inside of Examples/Common which is another good place to look around.

None of the test scenes are bundled with this source so the rest of the environments will be completely blank when running.

Controls For Example Environments

WASD to move

Left mouse to fly up, right mouse to fly down

U unlocks look up/look down for camera

F toggles camera light

E toggles directional light

G toggles global illumination

R recompiles all shaders

stratusgfx's Issues

Shader cross-platform issue

Shader cross-platform issue

I can't run the programs due to shader compile errors.
It turns out that some function signatures used in the shaders do not exist in the GLSL standard.

• textureLod(sampler2DArrayShadow, vec4, int): This one can be fixed by adding #extension GL_EXT_texture_shadow_lod : require directive to the next line of #version. Found at

  StratusGFX/Source/Shaders/pbr.glsl

  Line 126 in 6a93798

  return textureLod(shadow, coords, 0);

• textureSize(sampler2DRect, int): I don't know how to fix it yet. Found at

  StratusGFX/Source/Shaders/atmospheric_postfx.fs

  Line 20 in 6a93798

  vec2 widthHeight = textureSize(atmosphereBuffer, 0).xy;

Here are the specifications of the functions mentioned above:

• textureLod: https://registry.khronos.org/OpenGL-Refpages/gl4/html/textureLod.xhtml
• textureSize: https://registry.khronos.org/OpenGL-Refpages/gl4/html/textureSize.xhtml

Environment

OS: Linux
API: OpenGL v: 4.6 Mesa 22.3.7
Renderer: AMD Radeon RX 580 Series

CMake minimum version?

Hi, just trying to build it now and, after following the previous steps listed in the REAME file without errors, I get to cmake .. with this result:

cmake --build . -j 8 --config RelWithDebInfo
-- The C compiler identification is GNU 10.2.1
-- The CXX compiler identification is GNU 10.2.1
-- Detecting C compiler ABI info
-- Detecting C compiler ABI info - done
-- Check for working C compiler: /usr/bin/cc - skipped
-- Detecting C compile features
-- Detecting C compile features - done
-- Detecting CXX compiler ABI info
-- Detecting CXX compiler ABI info - done
-- Check for working CXX compiler: /usr/bin/c++ - skipped
-- Detecting CXX compile features
-- Detecting CXX compile features - done
-- Found OpenGL: /usr/lib/libOpenGL.so   
Linux
/usr/lib/libOpenGL.so/usr/lib/libGLX.so/usr/lib/libGLU.sopthreaddlz
StratusEngine
CMake Error at Tests/CMakeLists.txt:20 (include):
  include could not find requested file:

    /tmp/ramdisk/StratusGFX/Tests/..//ThirdParty/lib/cmake/Catch2/Catch.cmake


CMake Error at Tests/UnitTests/CMakeLists.txt:25 (catch_discover_tests):
  Unknown CMake command "catch_discover_tests".


-- Configuring incomplete, errors occurred!
See also "/tmp/ramdisk/StratusGFX/build/CMakeFiles/CMakeOutput.log".
make: Makefile: No such file or directory
make: *** No rule to make target 'Makefile'.  Stop.

CMake is version 3.25.0, which one is the one it was been tested with?

This is an unusual system, PowerPC CPU and Void Linux, so I do not expect you to find a solution, just to document the situation.
If there is some simple test I could do, please let me know.

Edit: that file exists, it’s just under a directory called lib64 insted of lib, I do not know why but I’ve seen similar problems before:

$ find .. -name Catch.cmake
../ThirdParty/lib64/cmake/Catch2/Catch.cmake
../Catch2/extras/Catch.cmake

gl3w build 403 error

gl3w has merged a PR, which helps downloading the files. Maybe you can update the dependency?