How diligentgraphics/diligentcore works
1. Repository role
- This is the core, low-level graphics layer for Diligent Engine.
- It is not an application; it is a cross-platform engine foundation that exposes a unified API over multiple graphics backends.
2. Top-level architecture
- The codebase is organized into reusable strata:
- Primitives for base types, reference counting, memory utilities, and C-style interface helpers.
- Platforms for OS-specific filesystem, window, debug, and platform glue.
- Common for engine-agnostic utilities shared across all graphics backends.
- Graphics for the graphics API, backend implementations, shader tools, and auxiliary graphics modules.
- Tests for API, include, and GPU validation.
- ThirdParty for bundled external libraries used by shader compilation, graphics API loading, testing, and math/hash utilities.
3. Core runtime flow
- An application starts by obtaining a backend-specific factory, then creates:
- a RenderDevice
- one or more DeviceContexts
- an SwapChain
- From there, resources are created on the device, state is encoded in pipeline objects, shader resources are bound, and commands are submitted through the device context.
- The engine performs resource state tracking and transitions internally, so the API is closer to D3D12/Vulkan than to older immediate-mode APIs.
4. Backend split
- There are separate backend modules for:
- D3D11
- D3D12
- OpenGL / OpenGLES
- Vulkan
- WebGPU
- Metal appears as a commercial backend
- Each backend has its own GraphicsEngine<API> module with:
- interface headers for API-specific extensions
- include for internal implementation types
- src for concrete object implementations
- These backends implement the same conceptual object model, but map it to different native APIs and lifetime rules.
5. Shared graphics core
- Graphics/GraphicsEngine contains the backend-neutral interfaces and base implementations for engine objects such as buffers, textures, shaders, pipeline states, render passes, fences, queries, resource mappings, and swap chains.
- This is the central abstraction layer that all backend-specific implementations inherit from or wrap.
- It is where the common object model is defined, while backend modules specialize behavior.
6. Platform boundary
- Platforms/* encapsulates OS-specific integration:
- native window handles
- filesystem access for shader/source loading
- debug output
- platform capability and misc helpers
- This keeps the graphics layer decoupled from the host OS, especially for shader source loading and swap chain creation.
- The repository supports Win32, UWP, Linux, Android, Apple platforms, and Emscripten/Web.
7. Shader and pipeline compilation toolchain
- Graphics/ShaderTools and ThirdParty/DirectXShaderCompiler, glslang, SPIRV-Tools, SPIRV-Cross, and volk form the shader compilation and translation toolchain.
- ShaderTools handles parsing, preprocessing, resource binding analysis, HLSL/GLSL/WGSL utilities, and DXBC/DXIL-related helpers.
- This subsystem materially affects architecture because shader sources may be compiled differently per backend:
- HLSL can be compiled to DXIL, SPIR-V, GLSL, or MSL depending on target
- GLSL and WGSL paths have their own validation/resource extraction helpers
8. Resource binding and PSO model
- The engine centers around monolithic pipeline state objects and explicit shader resource binding.
- Resource layout is split into static, mutable, and dynamic variables to reflect binding frequency and performance expectations.
- This model is consistent across backends, but each backend stores and resolves bindings using its own native descriptor, root signature, or binding-layout structures.
- Immutable samplers and resource mappings are first-class parts of the pipeline/resource architecture.
9. Command submission and synchronization
- DeviceContext is the main submission boundary for drawing, dispatch, clearing, and resource transitions.
- Synchronization is represented by fences, queries, and backend-specific command queues or managers.
- The architecture separates:
- resource creation on RenderDevice
- command encoding on DeviceContext
- presentation through SwapChain
- Backends like D3D12/Vulkan/WebGPU use more explicit queue, descriptor, and heap management internally, while D3D11/OpenGL adapt the same API to more implicit driver models.
10. Backend support modules
- Some shared helper layers exist for families of APIs:
- GraphicsEngineD3DBase for D3D11/D3D12 common conversions and shader/resource validation
- GraphicsEngineNextGenBase for shared next-gen patterns
- GraphicsAccessories for cross-backend utilities such as dynamic atlases, upload helpers, ring buffers, caches, and screen capture
- These modules reduce duplication across implementations and are important diagram nodes because they sit between the generic engine and individual backends.
11. Specialized feature modules
- Graphics/Archiver provides serialization/de-serialization for engine objects and pipeline state assets.
- Graphics/SuperResolution wraps upscaling features such as DLSS, FSR, and DSR-style providers behind a common factory/provider API.
- Graphics/GraphicsEngine.NET exposes the core engine to .NET consumers through interop bindings.
- Graphics/HLSL2GLSLConverterLib is a standalone shader translation library used by shader tooling.
12. Tests and validation
- Tests/DiligentCoreTest and Tests/DiligentCoreAPITest validate the common utilities, shader tools, graphics utilities, and runtime API behavior.
- Tests/GPUTestFramework provides backend-specific test environments and swap chains.
- Tests/IncludeTest checks header usability and C/C++ interface stability.
- There are also .NET tests under Tests/DiligentCoreTest.NET.
- These tests are architecture-relevant because they mirror the repo’s public layering and backend separation.
13. Build, packaging, and CI
- CMake is the primary build system, with extra build tooling for Android, .NET/NuGet packaging, formatting validation, and sanitizer support.
- GitHub Actions workflows build per platform and backend, including Windows, Linux, Android, Apple, Emscripten, and NuGet publication.
- The presence of separate workflows and per-platform build tools reflects the repo’s multi-target deployment model.
14. External dependencies that shape the design
- The repo vendors graphics and shader dependencies directly under ThirdParty.
- OpenGL and Vulkan loading/header layers, shader compiler stacks, testing framework, and utility libraries are not incidental; they are part of the engine’s portability and cross-API strategy.
- These dependencies make the architecture highly modular but also backend-sensitive, especially for shader compilation and native API interop.
15. How to draw the diagram
- A good architecture diagram should show:
- the application at the top
- the unified Diligent Core API in the middle
- platform glue and shader tooling as supporting subsystems
- multiple backend implementations underneath the shared API
- native graphics APIs and OS services at the bottom
- Then show the optional side paths for archiving, super-resolution, .NET bindings, and test harnesses.
Main entry points: GraphicsEngine Graphics core · ShaderTools Shader tools · GraphicsEngineD3D12 D3D12 backend · DiligentCoreAPITest API tests
Components 31
Primitives
Base types, memory, ref counting, and C-style interface macros.
- Base layer · Fundamental types, allocators, object model, and interface macros.
Primitives
Platforms
OS-specific filesystem, window, and debug glue.
- Platform glue · Native windows, filesystem, debug output, and platform capabilities.
Platforms
Common
Engine-agnostic utilities shared across the core.
- Shared utils · Common allocators, math, strings, threading, serialization, and image helpers.
Common
Graphics
Unified graphics API, backend implementations, shader tooling, and helpers.
- Graphics core · Backend-neutral engine object model and common base implementations.
Graphics/GraphicsEngine - Shader tools · Shader parsing, preprocessing, reflection, resource binding analysis, and translation helpers.
Graphics/ShaderTools - Accessories · Atlases, ring buffers, upload helpers, caches, and screen capture utilities.
Graphics/GraphicsAccessories - Graphics tools · Caching, async PSO, upload, reloadable shaders, and render-state helpers.
Graphics/GraphicsTools - Archiver · Serialization and deserialization of engine objects and pipeline assets.
Graphics/Archiver - Super resolution · Common factory/provider layer for DLSS, FSR, and related features.
Graphics/SuperResolution - .NET binding · Managed bindings exposing core graphics concepts to .NET consumers.
Graphics/GraphicsEngine.NET - D3D base · Common conversions, validation, and base helpers for D3D11/D3D12.
Graphics/GraphicsEngineD3DBase - Next-gen base · Shared patterns for modern explicit backends.
Graphics/GraphicsEngineNextGenBase - D3D11 backend · D3D11-specific render device, context, swap chain, and resource objects.
Graphics/GraphicsEngineD3D11 - D3D12 backend · D3D12-specific explicit queues, descriptors, heaps, and resource objects.
Graphics/GraphicsEngineD3D12 - OpenGL backend · OpenGL/OpenGLES implementation plus platform GL context handling.
Graphics/GraphicsEngineOpenGL - Vulkan backend · Vulkan implementation with explicit command, descriptor, and sync management.
Graphics/GraphicsEngineVulkan - WebGPU backend · WebGPU implementation with explicit resource and command translation.
Graphics/GraphicsEngineWebGPU - Metal backend · Metal-specific backend module.
Graphics/GraphicsEngineMetal
Tests
API, include, GPU, and .NET validation.
- Core tests · Common utility, graphics utility, shader tool, and API behavior tests.
Tests/DiligentCoreTest - API tests · Runtime API, shader resource, archiver, and backend reference tests.
Tests/DiligentCoreAPITest - Include tests · Header usability and interface stability checks.
Tests/IncludeTest - GPU framework · Backend-specific testing environments and swap chains.
Tests/GPUTestFramework - .NET tests · Managed tests for graphics engine and archiver bindings.
Tests/DiligentCoreTest.NET
ThirdParty
Vendored external dependencies for APIs, shader tools, and utilities.
- DXC · DirectX Shader Compiler used for HLSL and DXIL paths.
ThirdParty/DirectXShaderCompiler - glslang · GLSL and SPIR-V shader language tooling.
ThirdParty/glslang - SPIRV-Tools · SPIR-V validation and manipulation utilities.
ThirdParty/SPIRV-Tools - SPIRV-Cross · SPIR-V cross-compilation to target shading languages.
ThirdParty/SPIRV-Cross - volk · Vulkan function loading layer.
ThirdParty/volk - dawn · WebGPU native implementation support.
ThirdParty/dawn - glew · OpenGL extension loading and context bootstrapping.
ThirdParty/glew
Other components
- Application · Host application or game using the core API.
Connections 37
- Application → Graphics core: creates device/context/swapchain · Application uses the unified engine API to obtain backend factories and core objects.
- Application → Platform glue: uses host services · Windowing, filesystem, and debug integration come from platform glue.
- Graphics core → Base layer: built on · Core engine objects rely on base object, memory, and interface primitives.
- Graphics core → Shared utils: reuses utilities · Engine base code uses shared allocators, serialization, threading, and image helpers.
- Graphics core → Platform glue: depends on · Swap chains, native windows, and shader source loading use platform abstractions.
- Graphics core → Shader tools: feeds shader data · Shader compilation and reflection are central to pipeline setup.
- Graphics tools → Graphics core: extends · Higher-level helpers wrap the core API for caching, upload, and reload flows.
- Accessories → Graphics core: supports · Reusable utility layer above the core graphics objects.
- Archiver → Graphics core: serializes · Archived pipeline state and engine objects are derived from the core model.
- Super resolution → Graphics core: uses · Upscaling providers integrate with devices, contexts, and swap chains.
- .NET binding → Graphics core: binds · Managed wrappers map the native graphics engine API into .NET.
- Core tests → Shared utils: validates · Covers common utilities and shared helpers.
- Core tests → Shader tools: validates · Exercises shader preprocessing, reflection, and language utilities.
- API tests → Graphics core: validates · Checks runtime API behavior and backend object model consistency.
- API tests → Archiver: validates · Exercises serialization and dearchiving flows.
- API tests → Super resolution: validates · Checks the common super-resolution provider API.
- Include tests → Graphics core: checks headers · Ensures public and backend headers remain usable and stable.
- GPU framework → Graphics core: hosts · Provides backend-specific test environments and swap chains.
- .NET tests → .NET binding: validates · Exercises managed interop and .NET-facing API surface.
- Shader tools → DXC: uses · HLSL/DXIL compilation and validation paths.
- Shader tools → glslang: uses · GLSL/SPIR-V parsing and compilation support.
- Shader tools → SPIRV-Tools: uses · SPIR-V validation and processing.
- Shader tools → SPIRV-Cross: uses · Target-language translation, especially non-DX backends.
- D3D base → Graphics core: specializes · Shared D3D support sits between the core and D3D backends.
- Next-gen base → Graphics core: specializes · Shared patterns for explicit backends.
- D3D11 backend → D3D base: inherits patterns · D3D11 backend uses common D3D conversions and validation.
- D3D12 backend → D3D base: inherits patterns · D3D12 backend uses common D3D conversions and validation.
- D3D12 backend → Next-gen base: inherits patterns · D3D12 uses explicit command and descriptor management patterns.
- D3D11 backend → DXC: shader path · HLSL compilation and validation support.
- D3D12 backend → DXC: shader path · HLSL and DXIL compilation support.
- OpenGL backend → glew: loads API · OpenGL backend depends on GL extension loading.
- Vulkan backend → volk: loads API · Vulkan backend depends on Vulkan function loading.
- WebGPU backend → dawn: integrates · WebGPU backend is built around Dawn support.
- OpenGL backend → Shader tools: uses · OpenGL backend consumes shared shader tooling and translation.
- Vulkan backend → Shader tools: uses · Vulkan backend consumes SPIR-V-centric shader tooling.
- WebGPU backend → Shader tools: uses · WebGPU backend consumes WGSL and translation helpers.
- Metal backend → Shader tools: uses · Metal backend relies on cross-language shader tooling.