一个现代的Cross-PlatformLow-Level三维图形库
Diligent引擎是一个轻量级的cross-platform图形API抽象库和呈现框架。它的设计充分利用了Direct3D12、Vulkan和Metal,同时通过Direct3D11、OpenGL和OpenGLES支持较旧的平台。Diligent引擎公开公共的front-endAPI,并在所有平台上使用HLSL作为通用着色语言,并呈现back-ends。Platform-specific着色器表示(GLSL、DX字节码或SPIRV)可以与相应的back-ends一起使用。该引擎旨在用作游戏引擎或任何其他3D应用程序中的图形子系统。它是根据Apache2.0许可证分发的,可以免费使用。
#if defined(_WIN32)
。。。#elif defined(LINUX)
。。。#elif defined(ANDROID)
。。。#if defined(D3D11)
。。。#elif defined(D3D12)
。。。#elif defined(OPENGL)
。。。完全相同的HLSL着色器(VS,PS,GS,HS,DS,CS)在所有平台和所有back-ends上运行Platform | D3D11 | D3D12 | OpenGL | Vulkan | OpenGLES | Build Status |
---|---|---|---|---|---|---|
Win32(Windows桌面) | ?? | ?? | ?? | ?? | - | |
Universal Windows | ?? | ?? | - | - | - | |
Linux | - | - | ?? | ?? | - | |
MacOS | - | - | ?? | ?? (通过MoltenVK) | - | |
Android | - | - | - | ?? | ?? | |
iOS | - | - | - | ?? (通过MoltenVK) | ?? |
这是包含四个子模块的主存储库。要获取存储库和所有子模块,请使用以下命令:
git clone --recursive https://github.com/DiligentGraphics/DiligentEngine.git
更新现有存储库时,不要忘记更新所有子模块:
git pull
git submodule update --recursive
在获得最新版本后,re-runCMake并执行干净重建也是一个好主意。
主存储库包括以下子模块:
Diligent引擎使用CMake作为cross-platform构建工具。要开始使用cmake,请下载最新版本(需要3.16或更高版本)。另一个构建先决条件是Python解释器(需要3.0或更高版本)。如果在遵循下面的说明之后,您有生成/运行问题,请查看故障排除。
Build prerequisites:
使用CMake GUI或命令行工具生成生成文件。例如,要在build/Win64文件夹中生成Visual Studio 201764-bit解决方案和项目文件,请导航到引擎的根文件夹并运行以下命令:
cmake -S . -B ./build/Win64 -G "Visual Studio 15 2017" -A x64
您可以使用以下命令生成以Win8.1 SDK为目标的Win32解决方案:
cmake -D CMAKE_SYSTEM_VERSION=8.1 -S . -B ./build/Win64_8.1 -G "Visual Studio 15 2017" -A x64
如果使用MinGW,可以使用以下命令生成make文件(请注意一些已知的生成问题):
cmake -S . -B ./build/MinGW -D CMAKE_BUILD_TYPE=Release -G "MinGW Makefiles"
警告!在当前实现中,cmake生成文件夹的完整路径不能包含空格。
要启用Vulkan验证层,您需要下载Vulkan SDK并添加包含VulkanSDK安装文件夹中Bin目录路径的环境变量VK_LAYER_PATH
。
打开build/Win64文件夹中的DiligentEngine.sln文件,选择configuration并构建引擎。将所需的项目设置为startup project(默认情况下,将选择GLTF Viewer)并运行它。
默认情况下,示例和教程应用程序将显示“渲染后端选择”对话框。使用以下命令行选项强制使用D3D11、D3D12、OpenGL或Vulkan模式:-mode D3D11、-mode D3D12、-mode GL或-mode Vk。如果要在VisualStudio环境之外运行应用程序,则必须将应用程序的assets文件夹设置为工作目录。(对于Visual Studio,这是由CMake自动配置的)。或者,您可以导航到构建目标或安装文件夹并从那里运行可执行文件。
要为Universal Windows平台生成生成文件,需要定义以下两个cmake变量:
CMAKE_SYSTEM_NAME=WindowsStore
CMAKE_SYSTEM_VERSION=< Windows SDK Version >
例如,要在build/UWP64文件夹中生成Visual Studio 201764-bit解决方案和项目文件,请从引擎的根文件夹运行以下命令:
cmake -D CMAKE_SYSTEM_NAME=WindowsStore -D CMAKE_SYSTEM_VERSION=10.0 -S . -B ./build/UWP64 -G "Visual Studio 15 2017" -A x64
您可以通过优化CMAKE_SYSTEM_VERSION来针对特定的SDK版本,例如:
cmake -D CMAKE_SYSTEM_NAME=WindowsStore -D CMAKE_SYSTEM_VERSION=10.0.16299.0 -S . -B ./build/UWP64 -G "Visual Studio 15 2017" -A x64
将所需的项目设置为startup project(默认情况下,将选择GLTF Viewer)并运行它。
默认情况下,应用程序将以D3D12模式运行。可以使用以下命令行选项选择D3D11或D3D12:-模式D3D11,-模式D3D12。
注意:通过定义CMAKE_SYSTEM_VERSION=8.1cmake变量,可以生成以windows8.1为目标的解决方案,但它将无法生成,因为它将使用缺少适当的c++11支持的visualstudio2013(v120)工具集。
需要为c++开发设置Linux环境。如果已经是,请确保您的c++工具是最新的,因为Diligent引擎使用现代c++功能(建议使用gcc/g++7或更高版本)。您可能需要安装以下软件包:
1.gcc、make和其他重要的c/c++工具:
sudo apt-get update
sudo apt-get upgrade
sudo apt-get install build-essential
2.cmake
sudo apt-get install cmake
3.其他所需包装:
sudo apt-get install libx11-dev
sudo apt-get install mesa-common-dev
sudo apt-get install mesa-utils
sudo apt-get install libgl-dev
sudo apt-get install python3-distutils
要配置Vulkan,还需要:
要生成用于调试配置的make文件,请从引擎的根文件夹运行以下CMake命令:
cmake -S . -B ./build/Linux64 -G "Unix Makefiles" -DCMAKE_BUILD_TYPE="Debug"
要生成引擎,请运行以下命令:
cmake --build ./build/Linux64
引擎的根文件夹包含VisualStudio代码设置文件,这些文件配置IDE以生成引擎。您可以直接从IDE运行应用程序。要从命令行运行应用程序,应用程序的assets文件夹必须是当前目录。
请确保您的机器已设置为Android开发。下载androidstudio,安装和配置NDK和CMake等所需工具。如果您没有使用与androidstudio捆绑的CMake版本,请确保您的构建文件配置正确。要验证您的环境是否正确设置,请尝试构建teapots示例以及Vulkan Android教程。
Known issues:
PYTHON_EXECUTABLE
变量添加到NativeApp的build.gradle文件中的CMake参数:-DPYTHON_EXECUTABLE=/Path/To/Your/Python36/python.exe
使用Android Studio打开DiligentSamples/Android文件夹,在Android上构建和运行教程和示例。
默认情况下,应用程序将在OpenGLES模式下运行。要在Vulkan模式下运行它们,请添加以下启动标志:--es mode vk
(在androidstudio中,转到run->editconfigurations菜单)
克隆repo后,从引擎的根文件夹运行以下命令以生成Xcode项目(您需要在系统上安装CMake):
cmake -S . -B ./build/MacOS -G "Xcode"
项目将位于build/MacOS
文件夹中。
默认情况下,MacOS上没有Vulkan实现。Diligent引擎链接到Vulkan加载程序,并可以使用Vulkan可移植性实现,如MoltenVK或gfx-portability。安装VulkanSDK并确保您的系统按照此处所述正确配置。特别是,您可能需要定义以下环境变量(假设Vulkan SDK安装在~/LunarG/vulkansdk-macos
并且您希望使用MoltenVK):
export VULKAN_SDK=~/LunarG/vulkansdk-macos/macOS
export PATH=$VULKAN_SDK/bin:$PATH
export DYLD_LIBRARY_PATH=$VULKAN_SDK/lib:$DYLD_LIBRARY_PATH
export VK_ICD_FILENAMES=$VULKAN_SDK/share/vulkan/icd.d/MoltenVK_icd.json
export VK_LAYER_PATH=$VULKAN_SDK/share/vulkan/explicit_layer.d
请注意,从Launchpad或其他桌面GUI启动的应用程序看不到shell中设置的环境变量。因此,为了确保应用程序找到Vulkan库,需要从命令行启动它。出于同样的原因,xcode项目文件也应该使用open
命令从shell打开。对于Xcode 7及更高版本,可能需要首先使用以下命令启用此行为:
defaults write com.apple.dt.Xcode UseSanitizedBuildSystemEnvironment -bool NO
详情请参阅本页。
上次测试的LunarG SDK版本:1.2.135.0。
从引擎的根文件夹运行以下命令以生成为iOS构建配置的Xcode项目(您需要在Mac上安装CMake):
cmake -DCMAKE_TOOLCHAIN_FILE=DiligentCore/ios.toolchain.cmake -DIOS_PLATFORM=OS64 -H. -Bbuild/IOS -GXcode
打开build/IOS
文件夹中的Xcode项目文件并构建引擎。要在iOS设备上运行应用程序,您需要在“项目设置”中设置适当的开发团队。
要在iOS上启用Vulkan,请下载并安装VulkanSDK。iOS上没有Vulkan加载器,Diligent引擎直接链接到MoltenVK静态库(如MoltenVK安装指南所建议的那样)在Metal上实现Vulkan。注意,MoltenVK库只为arm64体系结构提供。要在iOS上启用Diligent Engine中的Vulkan,请在运行CMake时指定Vulkan SDK的路径(假设Vulkan SDK安装在/LunarG/vulkansdk-macos
上):
cmake -DCMAKE_TOOLCHAIN_FILE=DiligentCore/ios.toolchain.cmake -DIOS_PLATFORM=OS64 -DIOS_ARCH=arm64 -DVULKAN_SDK=/LunarG/vulkansdk-macos -H. -Bbuild/IOS -GXcode
默认情况下,引擎将链接到位于lunargsdk中的MoltenVK库的静态版本。如果不希望这样做,或者应用程序希望从特定位置使用库,它可以通过MoltenVK_LIBRARY
CMake变量提供到库的完整路径。当MoltenVK_LIBRARY
被定义时,VULKAN_SDK
被忽略。
有关MoltenVK安装和使用的更多信息,请参阅MoltenVK用户指南。
上次测试的LunarG SDK版本:1.2.135.0。
Diligent具有模块化结构,因此对于您的项目,您只能使用这些实现所需功能的子模块。下图显示了模块之间的依赖关系。
Core
|
+------>Tools----------.
| | |
| V |
+------->FX---------. |
| | |
| V V
'----------------->Samples
如果您的项目使用CMake,那么添加Diligent引擎只需要几行代码。假设目录结构如下所示:
|
+-DiligentCore
+-HelloDiligent.cpp
然后需要执行以下步骤:
add_subdirectory(DiligentCore)
以下是CMake文件的示例:
cmake_minimum_required (VERSION 3.6)
project(HelloDiligent CXX)
add_subdirectory(DiligentCore)
add_executable(HelloDiligent WIN32 HelloDiligent.cpp)
target_compile_options(HelloDiligent PRIVATE -DUNICODE -DENGINE_DLL)
target_include_directories(HelloDiligent PRIVATE "DiligentCore")
target_link_libraries(HelloDiligent
PRIVATE
Diligent-GraphicsEngineD3D11-shared
Diligent-GraphicsEngineOpenGL-shared
Diligent-GraphicsEngineD3D12-shared
Diligent-GraphicsEngineVk-shared
)
copy_required_dlls(HelloDiligent)
copy_required_dlls()
是一个方便的函数,它将共享库复制到可执行文件旁边,以便系统可以找到并加载它们。或者,您可以使用target_link_libraries()
命令链接到库的静态(以及共享)版本。在这种情况下,不需要显式地将DiligentCore添加到include目录列表中,因为目标将导出所有必需的include路径。还请查看Windows和Linux的入门教程。
如果项目不使用CMake,建议使用CMake构建库并将它们添加到构建系统中。对于Windows平台,您可以从appveyor下载最新的构建构件。
全局CMake安装目录由CMAKE_INTALL_PREFIX变量控制。注意,在UNIX上默认为/usr/local
,在Windows上默认为c:/Program Files/${PROJECT_NAME}
,这可能不是您想要的。使用-D CMAKE_INSTALL_PREFIX=install
改为使用本地install
文件夹:
cmake -S . -B ./build/Win64 -D CMAKE_INSTALL_PREFIX=install -G "Visual Studio 15 2017" -A x64
要安装库和头文件,请从生成文件夹运行以下CMake命令:
cmake --build . --target install
DiligentCore安装目录将包含集成引擎所需的所有内容:
更简单的方法是与动态库链接。静态链接时,需要列出DiligentCore以及引擎使用的所有third-party库。{326还需要指定@system}库。例如,对于Windows平台,项目需要链接的库列表可能如下所示:
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 vulkan-1.lib dxgi.lib d3d11.lib d3d12.lib d3dcompiler.lib opengl32.lib
Vulkan库可以在DiligentCore/ThirdParty/Vulkan/libs目录中找到。
Diligent引擎头需要将以下平台宏之一定义为1
:PLATFORM_WIN32
,PLATFORM_UNIVERSAL_WINDOWS
,PLATFORM_ANDROID
,PLATFORM_LINUX
,PLATFORM_MACOS
,PLATFORM_IOS
。
您可以使用以下CMake选项控制要安装的引擎组件:DILIGENT_INSTALL_CORE
、DILIGENT_INSTALL_FX
、DILIGENT_INSTALL_SAMPLES
和DILIGENT_INSTALL_TOOLS
。
集成引擎的另一种方法是生成生成文件(如visualstudio项目)并将其添加到生成系统中。下面描述的生成自定义可以帮助调整设置以满足您的特定需要。
默认情况下,将生成当前平台上所有可用的back-ends。要禁用特定的back-ends,请使用以下选项:DILIGENT_NO_DIRECT3D11
,DILIGENT_NO_DIRECT3D12
,DILIGENT_NO_OPENGL
,DILIGENT_NO_VULKAN
,DILIGENT_NO_METAL
。可以通过cmake UI或从命令行设置选项,如下例所示:
cmake -D DILIGENT_NO_DIRECT3D11=TRUE -S . -B ./build/Win64 -G "Visual Studio 15 2017" -A x64
此外,可以使用以下选项启用或禁用单个引擎组件:DILIGENT_BUILD_TOOLS
、DILIGENT_BUILD_FX
、DILIGENT_BUILD_SAMPLES
、DILIGENT_BUILD_DEMOS
、DILIGENT_BUILD_UNITY_PLUGIN
。如果您只想构建SampleBase
项目,可以使用DILIGENT_BUILD_SAMPLE_BASE_ONLY
选项。
默认情况下,Vulkanback-end与glslang链接,glslang允许在运行时将HLSL和GLSL着色器编译为SPIRV。如果不需要run-time编译,可以使用DILIGENT_NO_GLSLANG
cmake选项禁用glslang。另外,non-Direct3D后端中的HLSL支持可以通过DILIGENT_NO_HLSL
选项禁用。启用这些选项可以显著减少Vulkan和OpenGLback-end二进制文件的大小,这对于移动应用程序可能特别重要。
Diligent引擎使用clang-format来确保代码基的格式一致。可以使用DILIGENT_NO_FORMAT_VALIDATION
CMake选项禁用验证。请注意,如果发现格式问题,任何池请求都将失败。
Diligent Engine允许客户端通过提供定义以下可选cmake函数的配置脚本文件来自定义生成设置:
custom_configure_build()
-定义全局生成属性,如生成配置、c/c++编译标志、链接标志等。custom_pre_configure_target()
-为生成中的每个目标定义自定义设置,并在引擎的生成系统开始配置目标之前调用。custom_post_configure_target()
-在引擎的生成系统配置目标以允许客户端覆盖引擎设置的属性之后调用。运行cmake时,配置脚本的路径应该通过BUILD_CONFIGURATION_FILE
变量提供,并且必须与cmake根文件夹相关,例如:
cmake -D BUILD_CONFIGURATION_FILE=BuildConfig.cmake -S . -B ./build/Win64 -G "Visual Studio 15 2017" -A x64
如果已定义,custom_configure_build()
函数将在添加任何生成目标之前调用。默认情况下,cmake定义了以下四种配置:Debug、Release、RelWithDebInfo、MinSizeRel。如果需要,可以通过设置CMAKE_CONFIGURATION_TYPES
变量来定义自己的构建配置。例如,如果您只想有两个配置:Debug和ReleaseMT,请在custom_configure_build()
函数中添加以下行:
set(CMAKE_CONFIGURATION_TYPES Debug ReleaseMT CACHE STRING "Configuration types: Debug, ReleaseMT" FORCE)
生成系统需要知道调试和发布(优化)配置的列表,因此在定义CMAKE_CONFIGURATION_TYPES
变量时还必须设置以下两个变量:
set(DEBUG_CONFIGURATIONS DEBUG CACHE INTERNAL "" FORCE)
set(RELEASE_CONFIGURATIONS RELEASEMT CACHE INTERNAL "" FORCE)
注意,由于cmake的特殊性,DEBUG_CONFIGURATIONS
和RELEASE_CONFIGURATIONS
中列出的配置名称必须大写。
如果定义除四个标准cmake配置之外的任何配置,还需要为每个新配置设置以下变量:
CMAKE_C_FLAGS_<Config>
-c编译标志CMAKE_CXX_FLAGS_<Config>
-c++编译标志CMAKE_EXE_LINKER_FLAGS_<Config>
-可执行链接标志CMAKE_SHARED_LINKER_FLAGS_<Config>
-共享库链接标志For instance:
set(CMAKE_C_FLAGS_RELEASEMT "/MT" CACHE INTERNAL "" FORCE)
set(CMAKE_CXX_FLAGS_RELEASEMT "/MT" CACHE INTERNAL "" FORCE)
set(CMAKE_EXE_LINKER_FLAGS_RELEASEMT "/OPT:REF" CACHE INTERNAL "" FORCE)
set(CMAKE_SHARED_LINKER_FLAGS_RELEASEMT "/OPT:REF" CACHE INTERNAL "" FORCE)
下面是custom_configure_build()函数的示例:
function(custom_configure_build)
if(CMAKE_CONFIGURATION_TYPES)
# Debug configurations
set(DEBUG_CONFIGURATIONS DEBUG CACHE INTERNAL "" FORCE)
# Release (optimized) configurations
set(RELEASE_CONFIGURATIONS RELEASEMT CACHE INTERNAL "" FORCE)
# CMAKE_CONFIGURATION_TYPES variable defines build configurations generated by cmake
set(CMAKE_CONFIGURATION_TYPES Debug ReleaseMT CACHE STRING "Configuration types: Debug, ReleaseMT" FORCE)
set(CMAKE_CXX_FLAGS_RELEASEMT "/MT" CACHE INTERNAL "" FORCE)
set(CMAKE_C_FLAGS_RELEASEMT "/MT" CACHE INTERNAL "" FORCE)
set(CMAKE_EXE_LINKER_FLAGS_RELEASEMT "/OPT:REF" CACHE INTERNAL "" FORCE)
set(CMAKE_SHARED_LINKER_FLAGS_RELEASEMT "/OPT:REF" CACHE INTERNAL "" FORCE)
endif()
endfunction()
如果已定义,custom_pre_configure_target()
将为生成系统创建的每个目标调用,并允许配置target-specific属性。
默认情况下,生成系统设置一些目标属性。如果custom_pre_configure_target()
设置了所有必需的属性,它可以通过将TARGET_CONFIGURATION_COMPLETE
父范围变量设置为TRUE
来告诉生成系统不需要进一步处理:
set(TARGET_CONFIGURATION_COMPLETE TRUE PARENT_SCOPE)
以下是custom_pre_configure_target()
函数的示例:
function(custom_pre_configure_target TARGET)
set_target_properties(${TARGET} PROPERTIES
STATIC_LIBRARY_FLAGS_RELEASEMT /LTCG
)
set(TARGET_CONFIGURATION_COMPLETE TRUE PARENT_SCOPE)
endfunction()
如果客户端只需要覆盖一些设置,它可以定义custom_post_configure_target()
函数,该函数在引擎完成目标配置后调用,例如:
function(custom_post_configure_target TARGET)
set_target_properties(${TARGET} PROPERTIES
CXX_STANDARD 17
)
endfunction()
请参阅本页。另外,下面列出的教程和示例也是一个很好的起点。
Tutorial | Screenshot | Description |
---|---|---|
01-你好三角形 | 本教程演示如何使用Diligent引擎API呈现简单三角形。 | |
02-立方体 | 本教程演示如何渲染实际的三维对象立方体。它演示了如何从文件加载着色器,创建和使用顶点、索引和统一缓冲区。 | |
03-纹理 | 本教程演示如何将纹理应用于三维对象。它演示了如何从文件加载纹理、创建着色器资源绑定对象以及如何在着色器中采样纹理。 | |
03-Texturing-C | 本教程与Tutorial03相同,但使用C API实现。 | |
04-实例 | 本教程演示了如何使用实例化来为每个副本使用唯一的变换矩阵来渲染一个对象的多个副本。 | |
05-纹理阵列 | 本教程演示如何将实例化与纹理数组相结合,以便为每个实例使用唯一的纹理。 | |
06-多线程 | 本教程演示如何从多个线程并行生成命令列表。 | |
07-几何着色器 | 本教程演示如何使用几何体着色器渲染平滑线框。 | |
08-镶嵌 | 本教程演示如何使用硬件细分来实现简单的自适应地形渲染算法。 | |
09-四边形 | 本教程介绍如何渲染多个二维四边形,经常切换纹理和混合模式。 | |
10-数据流 | 本教程展示了使用MAP_FLAG_DISCARD 和MAP_FLAG_DO_NOT_SYNCHRONIZE 标志的动态缓冲区映射策略,以有效地将不同数量的数据流式传输到GPU。 | |
11-资源更新 | 本教程演示了在Diligent引擎中更新缓冲区和纹理的不同方法,并解释了与每个方法相关的重要内部细节和性能影响。 | |
12-渲染目标 | 本教程演示了如何将一个3d立方体渲染成屏幕外的渲染目标,并实现一个简单的post-processing效果。 | |
13-阴影图 | 本教程演示如何使用阴影贴图渲染基本阴影。 | |
14-计算着色器 | 本教程演示如何使用计算着色器实现一个简单的粒子模拟系统。 | |
15-多个窗口 | 本教程演示如何使用Diligent引擎渲染到多个窗口。 | |
16-无绑定资源 | 本教程演示如何实现无绑定资源,这是一种利用next-genapi启用的动态着色器资源索引功能来显著提高渲染性能的技术。 | |
17-MSAA | 本教程演示如何使用multisampleanti-aliasing(MSAA)使几何边看起来更平滑、更暂时更稳定。 | |
18-查询 | 本教程将演示如何使用查询来检索有关GPU操作的各种信息,例如呈现的原语数量、命令处理持续时间等。 | |
19-渲染过程 | 本教程演示如何使用渲染过程API实现简单的延迟着色。 |
Sample | Screenshot | Description |
---|---|---|
Atmosphere Sample | 这个示例演示了如何将极线光散射post-processing效果集成到渲染physically-based大气的应用程序中。 | |
GLTF Viewer | 此示例演示如何使用资产加载器和GLTF PBR呈现器加载和呈现GLTF模型。 | |
Shadows | 此示例演示如何使用Shadowing组件渲染high-quality阴影。 | |
Dear ImGui Demo | 此示例演示了引擎与亲爱的imguiui库的集成。 | |
Nuklear Demo | 此示例演示引擎与nuklear UI库的集成。 | |
Hello AR | 此示例演示如何在基本的Android AR应用程序中使用Diligent引擎。 |
Project | Screenshot | Description |
---|---|---|
Asteroids Performance Benchmark | 此演示旨在作为性能基准,并基于英特尔开发的此演示。它渲染了50000个独特的纹理小行星。每颗小行星都是由1000个独特的网格和10个独特纹理中的一个组成的。该示例使用原始的D3D11和D3D12本机实现,并添加了使用Diligent Engine API的实现,以便比较不同呈现模式的性能。 | |
Unity Integration Demo | 这个项目展示了用功引擎和Unity的集成 |
High-level呈现功能由DiligentFX模块实现。现在可以使用以下组件:
?
请参阅Apache2.0许可证。
此项目有一些third-party依赖项,每个依赖项都可能有独立的许可:
原文链接: