Diligent Engine Documentation

To build on Windows, you need the Windows SDK (10.0.19041.0+), C++ build tools, and Visual C++ ATL Support. .NET SDK 6.0+ is required for .NET support.

Important: The full path to your CMake build folder must not contain white spaces.

To enable Vulkan validation layers, install the Vulkan SDK and set the VK_LAYER_PATH environment variable to the Bin directory of the VulkanSDK installation.

Use CMake to generate Visual Studio solution files. For example, to generate a 64-bit solution in build/Win64:

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

To target the Win8.1 SDK:

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

Running Applications: Open the generated .sln file in Visual Studio. You can force a specific rendering backend using command line arguments:

• --mode d3d11
• --mode d3d12
• --mode gl
• --mode vk

If running outside of Visual Studio, ensure the application's assets folder is set as the working directory.

By default, macOS has no Vulkan implementation. Diligent Engine loads Vulkan dynamically and can use implementations like MoltenVK or gfx-portability.

Environment Configuration

To use MoltenVK, install the Vulkan SDK and set the following environment variables (example path: /Users/MyName/VulkanSDK/1.4.335.1):

export VULKAN_SDK=/Users/MyName/VulkanSDK/1.4.335.1/macOS
export PATH=$VULKAN_SDK/bin:$PATH
export DYLD_LIBRARY_PATH=$VULKAN_SDK/lib:$DYLD_LIBRARY_PATH
export VK_ADD_LAYER_PATH=$VULKAN_SDK/share/vulkan/explicit_layer.d
export VK_ICD_FILENAMES=$VULKAN_SDK/share/vulkan/icd.d/MoltenVK_icd.json
export VK_DRIVER_FILES=$VULKAN_SDK/share/vulkan/icd.d/MoltenVK_icd.json

Important Notes

• Launching Applications: Environment variables set in the shell are not visible to applications launched via Launchpad. You must start applications from the command line. To ensure Xcode sees these variables, open the project from the shell using the open command.
• Xcode Environment: For Xcode 7+, you may need to disable the sanitized build system environment:

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

• Library Loading: DYLD_LIBRARY_PATH is often ignored on macOS due to System Integrity Protection. Diligent Engine automatically configures the rpath for applications if the VULKAN_SDK environment variable is set correctly.

Diligent Engine provides a comprehensive set of tutorials covering various graphics programming topics, from basic triangle rendering to advanced techniques like Ray Tracing and Mesh Shaders. These tutorials are available in the DiligentSamples repository and can be implemented using the standard API, the C API, or the .NET API.

Core Graphics Topics

• Basics: Hello Triangle, Cube rendering, Texturing, and Instancing.
• Advanced Rendering: Geometry Shaders, Tessellation, Compute Shaders, and Render Passes (Deferred Shading).
• Modern GPU Features: Bindless Resources, Mesh Shaders, Ray Tracing, and Variable Rate Shading (VRS).
• Optimization & Performance: Multithreading (parallel command list generation), Data Streaming (MAP_FLAG_DISCARD, MAP_FLAG_DO_NOT_SYNCHRONIZE), and Render State Caching.
• Specialized Techniques: Order-Independent Transparency (OIT), Shadow Mapping, MSAA, and Post-Processing via the DiligentFX module.
• Platform Specifics: OpenXR (VR), visionOS (Apple), and Multiple Windows support.

In version 2.4.b, the API for shader initialization and pipeline state (PSO) creation changed. Shader variable types and static sampler definitions were moved from the shader creation stage to the PSO creation stage.

Key changes:

• Use PipelineResourceLayoutDesc and the ResourceLayout member of PipelineStateDesc to define variables and samplers.
• Use IPipelineState::GetStaticShaderVariable (or GetStaticVariableByName/ByIndex) to set constants on the PSO rather than on the shader object.
• IShaderVariable was renamed to IShaderResourceVariable.
• ShaderVariableDesc was renamed to ShaderResourceVariableDesc.

// New API Pattern (v2.4.b+)
RefCntAutoPtr<IShader> pVS;
{
    ShaderCI.Desc.ShaderType = SHADER_TYPE_VERTEX;
    ShaderCI.EntryPoint      = "main";
    ShaderCI.Desc.Name       = "Cube VS";
    ShaderCI.FilePath        = "cube.vsh";
    pDevice->CreateShader(ShaderCI, &pVS);
}
// ...
ShaderResourceVariableDesc Vars[] =
{
    {SHADER_TYPE_PIXEL, "g_Texture", SHADER_RESOURCE_VARIABLE_TYPE_MUTABLE}
};
PSODesc.ResourceLayout.Variables    = Vars;
PSODesc.ResourceLayout.NumVariables = _countof(Vars);

// Define static sampler for g_Texture
SamplerDesc SamLinearClampDesc( FILTER_TYPE_LINEAR, FILTER_TYPE_LINEAR, FILTER_TYPE_LINEAR, 
                                TEXTURE_ADDRESS_CLAMP, TEXTURE_ADDRESS_CLAMP, TEXTURE_ADDRESS_CLAMP);
StaticSamplerDesc StaticSamplers[] =
{
    {SHADER_TYPE_PIXEL, "g_Texture", SamLinearClampDesc}
};
PSODesc.ResourceLayout.StaticSamplers    = StaticSamplers;
PSODesc.ResourceLayout.NumStaticSamplers = _countof(StaticSamplers);

pDevice->CreatePipelineState(PSODesc, &m_pPSO);
m_pPSO->GetStaticShaderVariable(SHADER_TYPE_VERTEX, "Constants")->Set(m_VSConstants);