Repository files navigation

A Modern Cross-Platform Low-Level 3D Graphics Library and Rendering Framework

Diligent Engine is a lightweight, high-performance graphics API abstraction layer and rendering framework for cross-platform development.It leverages the power of modern graphics APIs such as Direct3D12, Vulkan, Metal, and WebGPU, while also maintaining robust support forlegacy platforms through Direct3D11, OpenGL, OpenGLES, and WebGL.Providing a consistent front-end API, Diligent Engine uses HLSL as its universal shading language and also supports platform-specificshader formats (GLSL, MSL, DirectX bytecode, SPIR-V) for optimized performance.Ideal for game engines, interactive simulations, and 3D visualization applications, Diligent Engine is open-source and distributedunder the permissiveApache 2.0 license.

Platform	D3D11	D3D12	OpenGL/GLES	Vulkan	Metal	WebGPU	Build Status
Windows	✔️	✔️	✔️	✔️	-	✔️3
Universal Windows	✔️	✔️	-	-	-	-
Linux	-	-	✔️	✔️	-	✔️3
Android	-	-	✔️	✔️	-	-
MacOS	-	-	✔️	✔️1	✔️2	✔️3
iOS	-	-	✔️	✔️1	✔️2	-
tvOS	-	-	-	✔️1	✔️2	-
Web	-	-	✔️	-	-	✔️

¹ Vulkan API is not natively supported on MacOS, iOS and tvOS platforms and requires a Vulkan portability implementation such asMoltenVKorgfx-portability.

² Available under commercial license - please contact us for details.

³ Requires a native implementation of WebGPU,Dawn is recommended.

• Cross-platform
  • Exact same client code for all supported platforms and rendering backends
    • No#if defined(_WIN32) ...#elif defined(LINUX) ...#elif defined(ANDROID) ...
    • No#if defined(D3D11) ...#elif defined(D3D12) ...#elif defined(OPENGL) ...
  • Exact same HLSL shaders (VS, PS, GS, HS, DS, CS) run on all platforms and all back-ends
• High performance
• Modular design
  • Components are clearly separated logically and physically and can be used as needed
  • Only take what you need for your project
• Clear and concise API
  • C/C++/C#
  • Object-based
  • Stateless
• Key graphics features:
  • Automatic shader resource binding designed to leverage next-generation graphics APIs
  • Multithreaded command buffer generation
  • Multithreaded resource creation
  • Automatic or explicit control over resource state transitions
  • Descriptor and memory management
  • Shader resource reflection
  • Async compute and multiple command queues
  • Ray-tracing, mesh shaders, tile shaders, bindless resources, variable rate shading, sparse resources,wave operations, and other state-of-the-art capabilities
• JSON-based render state description language and state packaging tool
• Extensive validation and error reporting
• Modern c++ features to make the code fast and reliable
• Consistent high quality is ensured by continuous integration
  • Automated builds and unit testing
  • Source code formatting validation
  • Static analysis

Minimum supported low-level API versions:

• OpenGL 4.1
• OpenGLES 3.0
• WebGL 2.0
• Direct3D11.1
• Direct3D12 with SDK version 10.0.17763.0
• Vulkan 1.0
• Metal 1.0

Documentation

• Screen-Space Reflections
• Screen-Space Ambient Occlusion
• Depth of Field
• Bloom
• Temporal Anti-Aliasing
• Atmospheric light scattering post-effect
• Tone mapping utilities
• PBR renderer
• Hydrogent, an implementation of the Hydra rendering API in Diligent Engine.
• Shadows
• Integration with Dear Imguiand Nuklear

• Cloning the Repository
  • Repository Structure
• Build and Run Instructions
  • Win32
  • Universal Windows Platform
  • Linux
  • Android
  • MacOS
  • iOS
  • Web
  • Integrating Diligent Engine with Existing Build System
  • Build Options
  • Customizing Build
• Getting started with the API
• Render State Notation
• Tutorials
• Samples
• High-Level Rendering Components
• Products Using Diligent Engine
• License
• Contributing
• References
• Release History

This is the master repository that contains foursubmodules. To get the repository and all submodules, use the following command:

git clone --recursive https://github.com/DiligentGraphics/DiligentEngine.git

When updating existing repository, don't forget to update all submodules:

git pullgit submodule update --recursive

It is also a good idea to re-run CMake and perform clean rebuild after getting the latest version.

Master repository includes the following submodules:

• Core submodule implementsDirect3D11,Direct3D12,OpenGL/GLES, andVulkan back-ends.The module is self-contained and can be built by its own.
• Tools submodule containstexture loading library,asset loading library,dear imgui implementation,native application implementation,Diligent render state notation parser andoffline render state packaging tool.
• DiligentFX is a high-level rendering framework that implementsvarious rendering components. The module depends on Core and Tools modules.
• Samples submodule contains tutorials and sample applicationsintended to demonstrate the usage of the Diligent Engine API. The module depends on Core, Tools and DiligentFX modules.

Diligent Engine usesCMake as a cross-platform build tool.To start using cmake, download thelatest release (3.20 or later is required).Another build prerequisite isPython interpreter (3.0 or later is required).If after following the instructions below you have build/run issues, please take a look attroubleshooting.

Build prerequisites:

• Windows SDK 10.0.17763.0 or later (10.0.19041.0 is required for mesh shaders)
• C++ build tools
• Visual C++ ATL Support

.NET support requires .NET SDK 6.0 or later.

Use either CMake GUI or command line tool to generate build files. For example, to generateVisual Studio 2022 64-bit solution and project files inbuild/Win64 folder,navigate to the engine's root folder and run the following command:

cmake -S . -B ./build/Win64 -G "Visual Studio 17 2022" -A x64

You can generate Win32 solution that targets Win8.1 SDK using the following command:

cmake -D CMAKE_SYSTEM_VERSION=8.1 -S . -B ./build/Win64_8.1 -G "Visual Studio 17 2022" -A x64

If you use MinGW, you can generate the make files using the command below (note however that the functionalitywill be limited and that MinGW is not a recommended way to build the engine):

cmake -S . -B ./build/MinGW -D CMAKE_BUILD_TYPE=Release -G "MinGW Makefiles"

⚠️ In current implementation, full path to cmake build foldermust not contain white spaces.

To enable Vulkan validation layers, you will need to download theVulkan SDK and add environmentvariableVK_LAYER_PATH that contains the path to theBin directory in VulkanSDK installation folder.

OpenDiligentEngine.sln file inbuild/Win64 folder, select configuration and build the engine. Set the desired projectas startup project (by default, GLTF Viewer will be selected) and run it.

By default, sample and tutorial applications will show rendering backend selection dialog box. Use the following command line options to forceD3D11, D3D12, OpenGL, or Vulkan mode:--mode d3d11,--mode d3d12,--mode gl, or--mode vk. If you want to run an applicationoutside of Visual Studio environment, the application's assets folder must be set as working directory. (For Visual Studio, thisis automatically configured by CMake). Alternatively, you can navigate to the build target or install folder and run the executable from there.

To generate build files for Universal Windows platform, you need to define the following two cmake variables:

• CMAKE_SYSTEM_NAME=WindowsStore
• CMAKE_SYSTEM_VERSION=< Windows Version >

For example, to generate Visual Studio 2022 64-bit solution and project files inbuild/UWP64 folder, run the following commandfrom the engine's root folder:

cmake -D CMAKE_SYSTEM_NAME=WindowsStore -D CMAKE_SYSTEM_VERSION=10.0 -S . -B ./build/UWP64 -G "Visual Studio 17 2022" -A x64

Set the desired project as startup project (by default, GLTF Viewer will be selected) and run it.

By default, applications will run in D3D12 mode. You can select D3D11 or D3D12 using the following command line options:--mode d3d11,--mode d3d12.

Note: it is possible to generate solution that targets Windows 8.1 by defining CMAKE_SYSTEM_VERSION=8.1 cmake variable, but it will failto build as it will use Visual Studio 2013 (v120) toolset that lacks proper c++14 support.

Your Linux environment needs to be set up for c++ development. If it already is, make sure your c++ tools are up to dateas Diligent Engine uses modern c++ features (clang 10 or later is recommended).

⚠️ gcc 9 and above seemingly produces invalid binary code with O2 and O3 optimization levels. To avoid crashes,optimization level is downgraded to O1 in release configurations. It is recommended to use clang or gcc 7 or 8.

You may need to install the following packages:

1. gcc, clang, make and other essential c/c++ tools:

sudo apt-get updatesudo apt-get upgradesudo apt-get install build-essential

2. cmake

sudo apt-get install cmake

3. Other required packages:

sudo apt-get install libx11-devsudo apt-get install mesa-common-devsudo apt-get install mesa-utilssudo apt-get install libgl-devsudo apt-get install python3-distutilssudo apt-get install libgl1-mesa-devsudo apt-get install libxrandr-devsudo apt-get install libxinerama-devsudo apt-get install libxcursor-devsudo apt-get install libxi-dev

To configure Vulkan you will also need to:

• Install latest Vulkan drivers and libraries for your GPU
• InstallVulkan SDK
  • To make sure that you system is properly configured you can try to build and run samples from the SDK

To generate make files for debug configuration, run the following CMake command from the engine's root folder:

cmake -S . -B ./build -G "Unix Makefiles" -DCMAKE_BUILD_TYPE="Debug"

To build the engine, run the following command:

cmake --build ./build

On Ubuntu 23 and newer, it may crash if you don't have libtinfo5 installed, you'll need toadd it.

The engine's root folder containsVisual Studio Code settings files that configurethe IDE to build the engine. You can run applications directly from the IDE. To run an application from the command line,the app's assets folder must be current directory.

Please make sure that your machine is set up for Android development. DownloadAndroid Studio,install and configure the NDK and CMakeand other required tools. NDK r24 or later is required. If you are not using CMake version bundled with Android Studio, make sureyour build files areproperly configured.To verify that your environment is properly set up, try building theteapots sample as well asVulkan Android tutorials.

OpenDiligentSamples/Android folder with Android Studio to build and run tutorials and samples on Android.

By default, applications will run in Vulkan mode. To run them in Vulkan mode, add the following launch flags:--es mode gles (in Android Studio, go to Run->Edit Configurations menu)

Prerequisites:

• Xcode 14 or later
• Vulkan SDK 1.3.290.0 or later to enable Vulkan

After you clone the repo, run the following command from the engine's root folder to generate Xcode project:

cmake -S . -B ./build/MacOS -G "Xcode"

The project will be located inbuild/MacOS folder.

Note that if CMake fails to find the compiler, you may need to run the following command:

sudo xcode-select --reset

By default there is no Vulkan implementation on MacOS. Diligent Engine loads Vulkan dynamicallyand can use a Vulkan Portability implementation such asMoltenVKorgfx-portability. InstallVulkanSDKand make sure that your system is properly configured as describedhere.In particular, you may need to define the following environment variables (assuming that Vulkan SDK is installed at/Users/MyName/VulkanSDK/1.3.290.0 and you want to use MoltenVK):

export VULKAN_SDK=/Users/MyName/VulkanSDK/1.3.290.0/macOSexport PATH=$VULKAN_SDK/bin:$PATHexport DYLD_LIBRARY_PATH=$VULKAN_SDK/lib:$DYLD_LIBRARY_PATHexport VK_ADD_LAYER_PATH=$VULKAN_SDK/share/vulkan/explicit_layer.dexport VK_ICD_FILENAMES=$VULKAN_SDK/share/vulkan/icd.d/MoltenVK_icd.jsonexport VK_DRIVER_FILES=$VULKAN_SDK/share/vulkan/icd.d/MoltenVK_icd.json

Note that environment variables set in the shell are not seen by the applications launched from Launchpador other desktop GUI. Thus to make sure that an application finds Vulkan libraries, it needs to be started fromthe command line. Due to the same reason, the xcode project file should also be opened from the shell usingopen command. With Xcode versions 7 and later, this behavior may need to be enabled first using thefollowing command:

defaults write com.apple.dt.Xcode UseSanitizedBuildSystemEnvironment -bool NO

Please refer tothis page for more details.

⚠️DYLD_LIBRARY_PATH andLD_LIBRARY_PATH environment variables are ignored on MacOS unlessSystem Integrity Protection is disabled (which generally is not recommended). In order for executables to find theVulkan library, it must be in rpath. IfVULKAN_SDK environment variable is set and points to correct location, DiligentEngine will configure the rpath for all applications automatically.

Latest tested Vulkan SDK version: 1.3.290.0.

⚠️ There are known issues with later versions of the SDK, so it is recommended to use the latest tested version.

Prerequisites:

• Xcode 14 or later
• Vulkan SDK 1.3.290.0 or later to enable Vulkan

Run the command below from the engine's root folder to generate Xcode project configured foriOS build:

cmake-S.-B./build/iOS-DCMAKE_SYSTEM_NAME=iOS-G"Xcode"

If needed, you can provide iOS deployment target (13.0 or later is required) as well as other parameters, e.g.:

cmake-S.-B./build/iOS-DCMAKE_SYSTEM_NAME=iOS-DCMAKE_OSX_DEPLOYMENT_TARGET=13.0-G"Xcode"

⚠️ To build for iPhone simulator, use theiphonesimulator system root. You may also use theCMAKE_OSX_ARCHITECTURES variable to specify target architecture, for example:

cmake-S.-B./build/iOSSim-DCMAKE_SYSTEM_NAME=iOS-DCMAKE_OSX_SYSROOT=iphonesimulator-DCMAKE_OSX_ARCHITECTURES=arm64-G"Xcode"

Open Xcode project file inbuild/IOS folder and build the engine. To run the applications on an iOS device,you will need to set appropriate development team in the project settings.

To enable Vulkan on iOS, download and install theVulkanSDK. There is no Vulkan loaderon iOS, and Diligent Engine links directly with MoltenVK XCFramework (seeMoltenVk install guide)that implements Vulkan on Metal. To enable Vulkan in Diligent Engine on iOS, specify the path to Vulkan SDKwhen running CMake, for example (assuming that Vulkan SDK is installed at/Users/MyName/VulkanSDK/1.3.290.0):

cmake-DCMAKE_SYSTEM_NAME=iOS-DVULKAN_SDK=/Users/MyName/VulkanSDK/1.3.290.0-S.-B./build/iOS-G"Xcode"

By default, the engine links with MoltenVK XCFramework located in Vulkan SDK. If this is not desired or an application wantsto use a specific library, it can provide the full path to the library viaMOLTENVK_LIBRARY CMake variable.

Refer toMoltenVK user guidefor more information about MoltenVK installation and usage.

Latest tested Vulkan SDK version: 1.3.290.0.

⚠️ There are known issues with later versions of the SDK, so it is recommended to use the latest tested version.

Build prerequisites:

• Emscripten SDK 3.1.65
• Ninja 1.10.2

To activate PATH and other environment variables in the current terminal

source${PATH_TO_EMSDK}/emsdk/emsdk_env.sh

⚠️ On Windows, run${PATH_TO_EMSDK}/emsdk/emsdk_env.bat instead ofsource ${PATH_TO_EMSDK}/emsdk/emsdk_env.sh

To generate project, run the following CMake command from the engine's root folder:

emcmakecmake-S.-B./build/Emscripten-G"Ninja"

To build the engine, run the following command:

cmake--build./build/Emscripten

To test Web applications, run a basic web server

cd ./build/Emscriptenpython https_server.py

Open a browser and navigate tohttp://localhost

For example, the Hello Triangle tutorial will be available at

http://localhost/DiligentSamples/Tutorials/Tutorial01_HelloTriangle/Tutorial01_HelloTriangle.html

To access the server from another computer on the local network, use the HTTPS server.To enable this, first install thecryptography module. You can do so by running the following command:

pip install cryptography

To start the HTTPS server, use the following command:

python https_server.py --mode=https

Use the HTTPS protocol to open the pages. For example:

https://localhost/DiligentSamples/Tutorials/Tutorial01_HelloTriangle/Tutorial01_HelloTriangle.html

When using the HTTPS server, unlike with the HTTP server, you may encounter the following errorwhen loading the page:net::ERR_CERT_AUTHORITY_INVALID.

There are two ways to resolve this issue:

1. Click theAdvanced button and then selectProceed to localhost (unsafe).
2. Alternatively, start the terminal as administrator and run the following command:

python https_server.py --mode=https --register

We use the default ports for HTTP/HTTPS protocols,80 and443 respectively.If you already have a server running on those ports, you may specify a different port number using the--portargument and include the corresponding port number in the URL after the IP address. For example:

http://localhost:${YOUR_PORT}/DiligentSamples/Tutorials/Tutorial01_HelloTriangle/Tutorial01_HelloTriangle.html

Diligent has modular structure, so for your project you can only use thosesubmodules that implement the required functionality.The diagram below shows the dependencies between modules.

  Core   |   +------>Tools----------.   |        |             |   |        V             |   +------->FX---------.  |   |                   |  |   |                   V  V   '----------------->Samples

Don't forget to recursively initialize submodules if you are adding Diligent reposas submodules to your project.

If your project uses CMake, adding Diligent Engine requires just few lines of code.Suppose that the directory structure looks like this:

|+-DiligentCore+-HelloDiligent.cpp

Then the following steps need to be done:

• Calladd_subdirectory(DiligentCore)
• Add dependencies on the targets implementing required rendering backends

Below is an example of a CMake file:

cmake_minimum_required (VERSION3.6)project(HelloDiligentCXX)add_subdirectory(DiligentCore)add_executable(HelloDiligentWIN32HelloDiligent.cpp)target_compile_options(HelloDiligentPRIVATE-DUNICODE)target_link_libraries(HelloDiligentPRIVATEDiligent-GraphicsEngineD3D11-sharedDiligent-GraphicsEngineOpenGL-sharedDiligent-GraphicsEngineD3D12-sharedDiligent-GraphicsEngineVk-shared)copy_required_dlls(HelloDiligent)

copy_required_dlls() is a convenience function that copies shared libraries next tothe executable so that the system can find and load them.Please also take a look at getting started tutorials forWindows andLinux.

On most platforms, core engine libraries are built in both static and dynamic versions(for example,Diligent-GraphicsEngineD3D12-static andDiligent-GraphicsEngineD3D12-shared).You can choose which version to link with by changing the target name intarget_link_libraries() CMake command.When linking with dynamic libraries, theENGINE_DLL macro will be defined, and the libraries will need to be loadedat runtime. For example, for Direct3D12 backend:

#if ENGINE_DLL// Load the dll and import GetEngineFactoryD3D12() functionauto GetEngineFactoryD3D12 = LoadGraphicsEngineD3D12();#endifauto* pFactoryD3D12 = GetEngineFactoryD3D12();

When using static linking, theENGINE_DLL macro will not be defined, and theGetEngineFactoryD3D12 function will bestatically linked with the executable.

SampleApp.cpp file providesan example of how to initialize the engine on different platforms using static or dynamic linking.

You can useFetchContent to download Diligent Engine modules.The only caveat is that you need to specify the source directory for each module to be the same as the module name,so that header files can be found. Below is an example of a CMake file that uses FetchContent:

cmake_minimum_required (VERSION3.6)project(HelloDiligentCXX)include(FetchContent)FetchContent_Declare(DiligentCoreGIT_REPOSITORYhttps://github.com/DiligentGraphics/DiligentCore.gitSOURCE_DIR_deps/DiligentCore)FetchContent_Declare(DiligentToolsGIT_REPOSITORYhttps://github.com/DiligentGraphics/DiligentTools.gitSOURCE_DIR_deps/DiligentTools)FetchContent_Declare(DiligentFXGIT_REPOSITORYhttps://github.com/DiligentGraphics/DiligentFX.gitSOURCE_DIR_deps/DiligentFX)FetchContent_MakeAvailable(DiligentCoreDiligentToolsDiligentFX)add_executable(HelloDiligentWIN32HelloDiligent.cpp)target_include_directories(HelloDiligentPRIVATE${diligentcore_SOURCE_DIR}${diligenttools_SOURCE_DIR}${diligentfx_SOURCE_DIR})target_compile_definitions(HelloDiligentPRIVATEUNICODE)target_link_libraries(HelloDiligentPRIVATEDiligent-BuildSettingsDiligent-GraphicsEngineD3D11-sharedDiligent-GraphicsEngineD3D12-sharedDiligent-GraphicsEngineOpenGL-sharedDiligent-GraphicsEngineVk-sharedDiligentFX)copy_required_dlls(HelloDiligent)

If your project doesn't use CMake, it is recommended to build libraries with CMake and add them to your build system.You can download the latest build artifacts fromGitHub.

Global CMake installation directory is controlled byCMAKE_INTALL_PREFIX variable.Note that it defaults to/usr/local on UNIX andc:/Program Files/${PROJECT_NAME} on Windows, which may notbe what you want. Use-D CMAKE_INSTALL_PREFIX=install to use localinstall folder instead:

cmake -S . -B ./build/Win64 -D CMAKE_INSTALL_PREFIX=install -G "Visual Studio 17 2022" -A x64

To install libraries and header files, run the following CMake command from the build folder:

cmake--build.--targetinstall

DiligentCore installation directory will contain everything required to integrate the engine:

• include subdirectory will contain all required header files. Add this directory to your include search directories.
• lib subdirectory will contain static libraries.
• bin subdirectory will contain dynamic libraries.

An easier way is to link with dynamic libraries. When linking statically, you will need to list DiligentCore as wellas all third-party libraries used by the engine. Besides that, you will also need to specify platform-specific system libraries.For example, for Windows platform, the list of libraries your project will need to link against may look like this:

DiligentCore.lib glslang.lib HLSL.lib OGLCompiler.lib OSDependent.lib spirv-cross-core.lib SPIRV.lib SPIRV-Tools-opt.lib SPIRV-Tools.lib glew-static.lib GenericCodeGen.lib MachineIndependent.lib dxgi.lib d3d11.lib d3d12.lib d3dcompiler.lib opengl32.lib

Diligent Engine headers require one of the following platform macros to be defined as1:PLATFORM_WIN32,PLATFORM_UNIVERSAL_WINDOWS,PLATFORM_ANDROID,PLATFORM_LINUX,PLATFORM_MACOS,PLATFORM_IOS.

You can control which components of the engine you want to install using the following CMake options:DILIGENT_INSTALL_CORE,DILIGENT_INSTALL_FX,DILIGENT_INSTALL_SAMPLES, andDILIGENT_INSTALL_TOOLS.

Another way to integrate the engine is to generate build files (such as Visual Studio projects) and add them to yourbuild system. Build customization described below can help tweak the settings for your specific needs.

Available CMake options are summarized in the table below:

By default, all back-ends available on the current platform are built. To disable specific back-ends,use the following options:DILIGENT_NO_DIRECT3D11,DILIGENT_NO_DIRECT3D12,DILIGENT_NO_OPENGL,DILIGENT_NO_VULKAN,DILIGENT_NO_METAL,DILIGENT_NO_WEBGPU. WebGPU backend is enabled by default when buildingfor the Web. To enable it on other platforms, useDILIGENT_NO_WEBGPU=OFF.The options can be set through cmake UI or from the command line as in the example below:

cmake -D DILIGENT_NO_DIRECT3D11=TRUE -S . -B ./build/Win64 -G "Visual Studio 17 2022" -A x64

Additionally, individual engine components can be enabled or disabled using the following options:DILIGENT_BUILD_TOOLS,DILIGENT_BUILD_FX,DILIGENT_BUILD_SAMPLES.If you only want to buildSampleBase project, you can useDILIGENT_BUILD_SAMPLE_BASE_ONLY option.

By default Vulkan back-end is linked with glslang that enables compiling HLSL and GLSL shaders to SPIRV at run time.If run-time compilation is not required, glslang can be disabled withDILIGENT_NO_GLSLANG cmake option.Additionally, HLSL support in non-Direct3D backends can be disabled withDILIGENT_NO_HLSL option.Enabling the options significantly reduces the size of Vulkan and OpenGL back-end binaries, which may beespecially important for mobile applications.

Diligent Engine usesclang-format to ensure consistentformatting throughout the code base. The validation can be disabled usingDILIGENT_NO_FORMAT_VALIDATIONCMake option. Note that any pull request will fail if formatting issues are found.

Diligent Engine uses extensive validation that is always enabled in Debug build. Some of the checks may beenabled in release configurations by settingDILIGENT_DEVELOPMENT CMake option.

To enable PIX events support, setDILIGENT_LOAD_PIX_EVENT_RUNTIME CMake flag.

To enable some advanced features on NVidia GPUs (such as native multi draw indirect support in Direct3D11),downloadNVAPI and set theDILIGENT_NVAPI_PATH CMake variable.

Diligent Engine uses multiple third-party libraries. If an application's CMake file defines any ofthose libraries, Diligent will use existing targets. The application will need to make sure thatbuild settings are compatible with Diligent.

Diligent Engine allows clients to customize build settings by providing configuration script file that defines the following optionalcmake functions:

• custom_configure_build() - defines global build properties such as build configurations, c/c++ compile flags, link flags etc.
• custom_pre_configure_target() - defines custom settings for every target in the build and is called before the engine'sbuild system starts configuring the target.
• custom_post_configure_target() - called after the engine's build system has configured the target to let the clientoverride properties set by the engine.

The path to the configuration script should be provided throughBUILD_CONFIGURATION_FILE variable when runningcmake and must be relative to the cmake root folder, for example:

cmake -D BUILD_CONFIGURATION_FILE=BuildConfig.cmake -S . -B ./build/Win64 -G "Visual Studio 17 2022" -A x64

If defined,custom_configure_build() function is called before any build target is added. By default,cmake defines the following four configurations: Debug, Release, RelWithDebInfo, MinSizeRel. If you want,you can define your own build configurations by settingCMAKE_CONFIGURATION_TYPES variable. For instance,if you want to have only two configuration: Debug and ReleaseMT, add the following line to thecustom_configure_build()function:

set(CMAKE_CONFIGURATION_TYPESDebugReleaseMTCACHESTRING"Configuration types: Debug, ReleaseMT"FORCE)

The build system needs to know the list of debug and release (optimized) configurations, so the followingtwo variables must also be set whenCMAKE_CONFIGURATION_TYPES variable is defined:

set(DEBUG_CONFIGURATIONSDEBUGCACHEINTERNAL""FORCE)set(RELEASE_CONFIGURATIONSRELEASEMTCACHEINTERNAL""FORCE)

Note that due to cmake specifics, configuration names listed inDEBUG_CONFIGURATIONS andRELEASE_CONFIGURATIONSmust be capitalized.

If you define any configuration other than four standard cmake ones, you also need to set the following variables, for everynew configuration:

• CMAKE_C_FLAGS_<Config> - c compile flags
• CMAKE_CXX_FLAGS_<Config> - c++ compile flags
• CMAKE_EXE_LINKER_FLAGS_<Config> - executable link flags
• CMAKE_SHARED_LINKER_FLAGS_<Config> - shared library link flags

For instance:

set(CMAKE_C_FLAGS_RELEASEMT"/MT"CACHEINTERNAL""FORCE)set(CMAKE_CXX_FLAGS_RELEASEMT"/MT"CACHEINTERNAL""FORCE)set(CMAKE_EXE_LINKER_FLAGS_RELEASEMT"/OPT:REF"CACHEINTERNAL""FORCE)set(CMAKE_SHARED_LINKER_FLAGS_RELEASEMT"/OPT:REF"CACHEINTERNAL""FORCE)

Below is an example of custom_configure_build() function:

function(custom_configure_build)    if(CMAKE_CONFIGURATION_TYPES)# Debug configurationsset(DEBUG_CONFIGURATIONSDEBUGCACHEINTERNAL""FORCE)# Release (optimized) configurationsset(RELEASE_CONFIGURATIONSRELEASEMTCACHEINTERNAL""FORCE)# CMAKE_CONFIGURATION_TYPES variable defines build configurations generated by cmakeset(CMAKE_CONFIGURATION_TYPESDebugReleaseMTCACHESTRING"Configuration types: Debug, ReleaseMT"FORCE)set(CMAKE_CXX_FLAGS_RELEASEMT"/MT"CACHEINTERNAL""FORCE)set(CMAKE_C_FLAGS_RELEASEMT"/MT"CACHEINTERNAL""FORCE)set(CMAKE_EXE_LINKER_FLAGS_RELEASEMT"/OPT:REF"CACHEINTERNAL""FORCE)set(CMAKE_SHARED_LINKER_FLAGS_RELEASEMT"/OPT:REF"CACHEINTERNAL""FORCE)    endif()endfunction()

If defined,custom_pre_configure_target() is called for every target created by the build system andallows configuring target-specific properties.

By default, the build system sets some target properties. Ifcustom_pre_configure_target() sets all required properties,it can tell the build system that no further processing is required by settingTARGET_CONFIGURATION_COMPLETEparent scope variable toTRUE:

set(TARGET_CONFIGURATION_COMPLETETRUEPARENT_SCOPE)

The following is an example ofcustom_pre_configure_target() function:

function(custom_pre_configure_targetTARGET)set_target_properties(${TARGET}PROPERTIESSTATIC_LIBRARY_FLAGS_RELEASEMT/LTCG    )set(TARGET_CONFIGURATION_COMPLETETRUEPARENT_SCOPE)endfunction()

If the client only needs to override some settings, it may definecustom_post_configure_target() function that is calledafter the engine has completed configuring the target, for example:

function(custom_post_configure_targetTARGET)set_target_properties(${TARGET}PROPERTIESCXX_STANDARD17    )endfunction()

Please refer tothis page. Also, tutorials and samples listed below is a good place to start.

Diligent Render State Notation is a JSON-based language that describes shaders, pipeline states,resource signatures and other objects in a convenient form, e.g.:

{"Shaders": [        {"Desc": {"Name":"My Vertex shader","ShaderType":"VERTEX"            },"SourceLanguage":"HLSL","FilePath":"cube.vsh"        },        {"Desc": {"Name":"My Pixel shader","ShaderType":"PIXEL"            },"SourceLanguage":"HLSL","FilePath":"cube.psh",        }    ],"Pipeleines": [        {"GraphicsPipeline": {"DepthStencilDesc": {"DepthEnable":true                },"RTVFormats": {"0":"RGBA8_UNORM_SRGB"                },"RasterizerDesc": {"CullMode":"FRONT"                },"BlendDesc": {"RenderTargets": {"0": {"BlendEnable":true                        }                    }                }            },"PSODesc": {"Name":"My Pipeline State","PipelineType":"GRAPHICS"            },"pVS":"My Vertex shader","pPS":"My Pixel shader"        }    ]}

JSON files can beparsed dynamically at run time.Alternatively, an application can use thepackager tool to preprocess pipelinedescriptions (compile shaders for target platforms, define internal resource layouts, etc.) into a binary archive optimized for run-time loading performance.

Tutorial	Screenshot	Description
01 - Hello Triangle ▶️ Run		This tutorial shows how to render simple triangle using Diligent Engine API.
02 - Cube ▶️ Run		This tutorial demonstrates how to render an actual 3D object, a cube. It shows how to load shaders from files, create and use vertex, index and uniform buffers.
03 - Texturing ▶️ Run		This tutorial demonstrates how to apply a texture to a 3D object. It shows how to load a texture from file, create shader resource binding object and how to sample a texture in the shader.
03 - Texturing-C		This tutorial is identical to Tutorial03, but is implemented using C API.
03 - Texturing-DotNet		This tutorial demonstrates how to use the Diligent Engine API in .NET applications.
04 - Instancing ▶️ Run		This tutorial demonstrates how to use instancing to render multiple copies of one object using unique transformation matrix for every copy.
05 - Texture Array ▶️ Run		This tutorial demonstrates how to combine instancing with texture arrays to use unique texture for every instance.
06 - Multithreading ▶️ Run		This tutorial shows how to generate command lists in parallel from multiple threads.
07 - Geometry Shader		This tutorial shows how to use geometry shader to render smooth wireframe.
08 - Tessellation		This tutorial shows how to use hardware tessellation to implement simple adaptive terrain rendering algorithm.
09 - Quads ▶️ Run		This tutorial shows how to render multiple 2D quads, frequently switching textures and blend modes.
10 - Data Streaming ▶️ Run		This tutorial shows dynamic buffer mapping strategy usingMAP_FLAG_DISCARD andMAP_FLAG_DO_NOT_SYNCHRONIZE flags to efficiently stream varying amounts of data to GPU.
11 - Resource Updates ▶️ Run		This tutorial demonstrates different ways to update buffers and textures in Diligent Engine and explains important internal details and performance implications related to each method.
12 - Render Target ▶️ Run		This tutorial demonstrates how to render a 3d cube into an offscreen render target and do a simple post-processing effect.
13 - Shadow Map ▶️ Run		This tutorial demonstrates how to render basic shadows using a shadow map.
14 - Compute Shader ▶️ Run		This tutorial shows how to implement a simple particle simulation system using compute shaders.
15 - Multiple Windows		This tutorial demonstrates how to use Diligent Engine to render to multiple windows.
16 - Bindless Resources ▶️ Run		This tutorial shows how to implement bindless resources, a technique that leverages dynamic shader resource indexing feature enabled by the next-gen APIs to significantly improve rendering performance.
17 - MSAA ▶️ Run		This tutorial demonstrates how to use multisample anti-aliasing (MSAA) to make geometrical edges look smoother and more temporarily stable.
18 - Queries ▶️ Run		This tutorial demonstrates how to use queries to retrieve various information about the GPU operation, such as the number of primitives rendered, command processing duration, etc.
19 - Render Passes ▶️ Run		This tutorial demonstrates how to use the render passes API to implement simple deferred shading.
20 - Mesh Shader		This tutorial demonstrates how to use amplification and mesh shaders, the new programmable stages, to implement view frustum culling and object LOD calculation on the GPU.
21 - Ray Tracing		This tutorial demonstrates the basics of using ray tracing API in Diligent Engine.
22 - Hybrid Rendering		This tutorial demonstrates how to implement a simple hybrid renderer that combines rasterization with ray tracing.
23 - Command Queues		This tutorial demonstrates how to use multiple command queues to perform rendering in parallel with copy and compute operations.
24 - Variable Rate Shading		This tutorial demonstrates how to use variable rate shading to reduce the pixel shading load.
25 - Render State Packager		This tutorial shows how to create and archive pipeline states with the render state packager off-line tool on the example of a simple path tracer.
26 - Render State Cache ▶️ Run		This tutorial expands the path tracing technique implemented in previous tutorial and demonstrates how to use the render state cache to save pipeline states created at run time and load them when the application starts.
27 - Post-Processing ▶️ Run		This tutorial demonstrates how to use post-processing effects from the DiligentFX module.
28 - OpenXR		This tutorial demonstrates how to use Diligent Engine with OpenXR API to render a simple scene in a VR headset.
29 - OIT ▶️ Run		This tutorial demonstrates how to implement order-independent transparency (OIT) methods to render transparent objects without sorting.

Sample	Screenshot	Description
Atmosphere Sample ▶️ Run		This sample demonstrates how to integrateEpipolar Light Scattering post-processing effect into an application to render physically-based atmosphere.
GLFW Demo		This maze mini-game demonstrates how to use GLFW to create window and handle keyboard and mouse input.
GLTF Viewer ▶️ Run		This sample demonstrates how to use theAsset Loader andPBR Renderer to load and render GLTF models.
USD Viewer		This sample demonstrates how to render USD files usingHydrogent, an implementation of the Hydra rendering API in Diligent Engine.
Shadows ▶️ Run		This sample demonstrates how to use theShadowing component to render high-quality shadows.
Dear ImGui Demo ▶️ Run		This sample demonstrates the integration of the engine withdear imgui UI library.
Nuklear Demo		This sample demonstrates the integration of the engine withnuklear UI library.
Hello AR		This sample demonstrates how to use Diligent Engine in a basic Android AR application.
Asteroids		This sampple is a performance benchmark that renders 50,000 unique textured asteroids and allows comparing performance of different rendering modes.
Unity Integration Demo		This project demonstrates integration of Diligent Engine with Unity.

High-level rendering functionality is implemented byDiligentFX module.The following components are now available:

• GLTF2.0 LoaderandPhysically-based renderer with image-based lighting.

• Hydrogent, an implementation of the Hydra rendering API in Diligent Engine.
  

• Shadows
  

• Screen-Space Reflections
  

• Screen-Space Ambient Occlusion
  

• Depth of Field
  

• Bloom
  

• Epipolar light scattering
  

• Temporal Anti-Aliasing

• Tone mapping shader utilities

We would appreciate it if you could send us a link in case your product uses Diligent Engine.

• Large-scale terrain visualization system for pilot training simulators byElbit Systems
  

• LumenRT: A Visualization and Reality Modeling Software byBentley Systems

• Godus: An award-winning sandbox game by22cans
  

• Vrmac Graphics: A cross-platform graphics library for .NET
  

Diligent Engine is an open project that may be freely used by everyone. We started it to empower the communityand help people achieve their goals. Sadly enough, not everyone's goals are worthy. Please don't associate us withsuspicious projects you may find on the Web that appear to be using Diligent Engine. We neither can possibly trackall such uses nor can we really do anything about them because our permissive license does not give us a lot of leverage.

SeeApache 2.0 license.

Each module has some third-party dependencies, each of which may have independent licensing:

• Core module
• Tools module
• Samples module

To contribute your code, submit aPull Requestto this repository.Diligent Engine is licensed under theApache 2.0 license that guaranteesthat content in theDiligentEngine repository is free of Intellectual Property encumbrances.In submitting any content to this repository,you license that content under the same terms,and you agree that the content is free of any Intellectual Property claims and you have the right to license it under those terms.

Diligent Engine usesclang-format to ensureconsistent source code style throughout the code base. The format is validated by CIfor each commit and pull request, and the build will fail if any code formatting issue is found. Please refertothis page for instructionson how to set up clang-format and automatic code formatting.

Documentation

Coding Guidelines

Performance Best Practices

Code Formatting

SeeRelease History

diligentgraphics.com