DiligentCore

Diligent Core

Diligent Core is a modern, cross-platform low-level graphics API that forms the foundation of Diligent Engine. It provides implementations for Direct3D11, Direct3D12, OpenGL, OpenGLES, Vulkan, and WebGPU rendering backends. A Metal backend is also available for commercial clients. In addition, the module includes essential platform-specific utilities. Diligent Core is fully self-contained and can be built independently of the rest of the engine. For details on supported platforms, features, and build instructions, please refer to the main repository.

Table of Contents

• Cloning the Repository
• API Basics
  • Initializing the Engine
    • Win32
    • Universal Windows Platform
    • Linux
    • macOS
    • Android
    • iOS
    • Web
    • Destroying the Engine
  • Creating Resources
  • Creating Shaders
  • Initializing Pipeline State
    • Pipeline Resource Layout
  • Binding Shader Resources
  • Setting the Pipeline State and Invoking Draw Command
• Low-level API interoperability
• NuGet package build instructions
• License
• Contributing
• Release History

Cloning the Repository

To get the repository and all submodules, use the following command:

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

To build the module, see build instructions in the master repository.

API Basics

Initializing the Engine

Before you can use any functionality provided by the engine, you need to create a render device, an immediate context and a swap chain.

Win32

On Win32 platform, you can create OpenGL, Direct3D11, Direct3D12 or Vulkan device as shown below:

…

If the engine is built as dynamic library, the library needs to be loaded by the native activity. The following code shows one possible way:

static
{
    try{
        System.loadLibrary("GraphicsEngineOpenGL");
    } catch (UnsatisfiedLinkError e) {
        Log.e("native-activity", "Failed to load GraphicsEngineOpenGL library.\n" + e);
    }
}

iOS

iOS implementation supports OpenGLES, Vulkan and Metal backend. Initialization of GL context on iOS is performed by the application, and the engine attaches to the context initialized by the app; see EAGLView.mm for details.

Web

On the Web, you can create OpenGLES or WebGPU device. The following code snippet shows an example:

//You need to pass the id of the canvas to NativeWindow
auto* pFactoryOpenGL = GetEngineFactoryOpenGL();
EngineGLCreateInfo EngineCI = {};
EngineCI.Window = NativeWindow{"#canvas"};
pFactoryOpenGL->CreateDeviceAndSwapChainGL(EngineCI, &m_pDevice, &m_pContext, SCDesc, &m_pSwapChain);

If you are using SDL or GLFW with existing context, you can provide null as the native window handle: EngineCI.Window = NativeWindow{nullptr}

Destroying the Engine

The engine performs automatic reference counting and shuts down when the last reference to an engine object is released.

Creating Resources

Device resources are created by the render device. The two main resource types are buffers, which represent linear memory, and textures, which use memory layouts optimized for fast filtering. To create a buffer, you need to populate BufferDesc structure and call IRenderDevice::CreateBuffer(). The following code creates a uniform (constant) buffer:

BufferDesc BuffDesc;
BuffDesc.Name           = "Uniform buffer";
BuffDesc.BindFlags      = BIND_UNIFORM_BUFFER;
BuffDesc.Usage          = USAGE_DYNAMIC;
BuffDesc.uiSizeInBytes  = sizeof(ShaderConstants);
BuffDesc.CPUAccessFlags = CPU_ACCESS_WRITE;
m_pDevice->CreateBuffer(BuffDesc, nullptr, &m_pConstantBuffer);

Similar, to create a texture, populate TextureDesc structure and call IRenderDevice::CreateTexture() as in the following example:

TextureDesc TexDesc;
TexDesc.Name      = "My texture 2D";
TexDesc.Type      = TEXTURE_TYPE_2D;
TexDesc.Width     = 1024;
TexDesc.Height    = 1024;
TexDesc.Format    = TEX_FORMAT_RGBA8_UNORM;
TexDesc.Usage     = USAGE_DEFAULT;
TexDesc.BindFlags = BIND_SHADER_RESOURCE | BIND_RENDER_TARGET | BIND_UNORDERED_ACCESS;
TexDesc.Name      = "Sample 2D Texture";
m_pRenderDevice->CreateTexture(TexDesc, nullptr, &m_pTestTex);

There is only one function CreateTexture() that is capable of creating all types of textures. Type, format, array size and all other parameters are specified by the members of the TextureDesc structure.

For every bind flag specified during the texture creation time, the texture object creates a default view. Default shader resource view addresses the entire texture, default render target and depth stencil views reference all array slices in the most detailed mip level, and unordered access view references the entire texture. To get a default view from the texture, use ITexture::GetDefaultView() function. Note that this function does not increment the reference counter of the returned interface. You can create additional texture views using ITexture::CreateView(). Use IBuffer::CreateView() to create additional views of a buffer.

Creating Shaders

To create a shader, populate ShaderCreateInfo structure:

ShaderCreateInfo ShaderCI;

There are three ways to create a shader. The first way is to provide a pointer to the shader source code through ShaderCreateInfo::Source member. The second way is to provide a file name. The third way is to provide a pointer to the compiled byte code through ShaderCreateInfo::ByteCode member. Graphics Engine is entirely decoupled from the platform. Since the host file system is platform-dependent, the structure exposes ShaderCreateInfo::pShaderSourceStreamFactory member that is intended to give the engine access to the file system. If you provided the source file name, you must also provide a non-null pointer to the shader source stream factory. If the shader source contains any #include directives, the source stream factory will also be used to load these files. The engine provides default implementation for every supported platform that should be sufficient in most cases. You can however define your own implementation.

An important member is ShaderCreateInfo::SourceLanguage. The following are valid values for this member:

• SHADER_SOURCE_LANGUAGE_DEFAULT - The shader source format matches the underlying graphics API: HLSL for D3D11 or D3D12 mode, and GLSL for OpenGL, OpenGLES, and Vulkan modes.
• SHADER_SOURCE_LANGUAGE_HLSL - The shader source is in HLSL. For OpenGL and OpenGLES modes, the source code will be converted to GLSL. In Vulkan back-end, the code will be compiled to SPIRV directly.
• SHADER_SOURCE_LANGUAGE_GLSL - The shader source is in GLSL.
• SHADER_SOURCE_LANGUAGE_GLSL_VERBATIM - The shader source language is GLSL and should be compiled verbatim.
• SHADER_SOURCE_LANGUAGE_MSL - The source language is Metal Shading Language.

Other members of the ShaderCreateInfo structure define the shader include search directories, shader macro definitions, shader entry point and other parameters.

ShaderMacroHelper Macros;
Macros.AddShaderMacro("USE_SHADOWS", 1);
Macros.AddShaderMacro("NUM_SHADOW_SAMPLES", 4);
Macros.Finalize();
ShaderCI.Macros = Macros;

When everything is ready, call IRenderDevice::CreateShader() to create the shader object:

…

Initializing Pipeline State

Diligent Engine follows Direct3D12/Vulkan style to configure the graphics/compute pipeline. One monolithic Pipelines State Object (PSO) encompasses all required states (all shader stages, input layout description, depth stencil, rasterizer and blend state descriptions etc.). To create a graphics pipeline state object, define an instance of GraphicsPipelineStateCreateInfo structure:

GraphicsPipelineStateCreateInfo PSOCreateInfo;
PipelineStateDesc&              PSODesc = PSOCreateInfo.PSODesc;

PSODesc.Name = "My pipeline state";

Describe the pipeline specifics such as the number and format of render targets as well as depth-stencil format:

// This is a graphics pipeline
PSODesc.PipelineType                            = PIPELINE_TYPE_GRAPHICS;
PSOCreateInfo.GraphicsPipeline.NumRenderTargets = 1;
PSOCreateInfo.GraphicsPipeline.RTVFormats[0]    = TEX_FORMAT_RGBA8_UNORM_SRGB;
PSOCreateInfo.GraphicsPipeline.DSVFormat        = TEX_FORMAT_D32_FLOAT;

Initialize depth-stencil state description DepthStencilStateDesc. Note that the constructor initializes the members with default values and you may only set the ones that are different from default.

// Init depth-stencil state
DepthStencilStateDesc& DepthStencilDesc = PSOCreateInfo.GraphicsPipeline.DepthStencilDesc;
DepthStencilDesc.DepthEnable            = true;
DepthStencilDesc.DepthWriteEnable       = true;

Initialize blend state description BlendStateDesc:

// Init blend state
BlendStateDesc& BSDesc = PSOCreateInfo.GraphicsPipeline.BlendDesc;
BSDesc.IndependentBlendEnable = False;
auto &RT0 = BSDesc.RenderTargets[0];
RT0.BlendEnable           = True;
RT0.RenderTargetWriteMask = COLOR_MASK_ALL;
RT0.SrcBlend              = BLEND_FACTOR_SRC_ALPHA;
RT0.DestBlend             = BLEND_FACTOR_INV_SRC_ALPHA;
RT0.BlendOp               = BLEND_OPERATION_ADD;
RT0.SrcBlendAlpha         = BLEND_FACTOR_SRC_ALPHA;
RT0.DestBlendAlpha        = BLEND_FACTOR_INV_SRC_ALPHA;
RT0.BlendOpAlpha          = BLEND_OPERATION_ADD;

Initialize rasterizer state description RasterizerStateDesc:

// Init rasterizer state
RasterizerStateDesc& RasterizerDesc = PSOCreateInfo.GraphicsPipeline.RasterizerDesc;
RasterizerDesc.FillMode              = FILL_MODE_SOLID;
RasterizerDesc.CullMode              = CULL_MODE_NONE;
RasterizerDesc.FrontCounterClockwise = True;
RasterizerDe