Agility SDK 入门

最新推荐文章于 2025-02-13 18:42:43 发布

顺其自然~

最新推荐文章于 2025-02-13 18:42:43 发布

阅读量470

点赞数

文章标签： 3d

原文链接：https://devblogs.microsoft.com/directx/gettingstarted-dx12agility/

版权

什么是 Agility SDK 以及它如何工作？

DirectX 团队过去完全依赖 Windows 10 操作系统更新来将 DirectX 功能更新安装到游戏机上。尽管随操作系统一起发布意味着所有 DirectX 12 功能最终都会惠及大量游戏玩家，但这也意味着 DirectX 功能在操作系统升级时受到限制。

某个操作系统版本的某个特定功能通常需要 1-2 年的时间才能吸引到足够多的用户，然后开发人员才能证明采用该功能的合理性，这意味着操作系统的推出曾经是最新 DirectX 创新的瓶颈。

借助 Agility SDK 模型，DirectX 团队解决了这个问题，允许任何应用程序启用比给定操作系统更新的 DirectX 12 功能。Agility SDK 模型可以实现这一点，同时确保依赖 System32 DirectX 12 运行时 D3D12.dll 的现有游戏不会中断。

这是通过操作系统更改实现的，其中 DirectX 团队将 D3D12.dll 分成两部分：

1）D3D12.dll，现在只是一个薄加载器

2）D3D12Core.dll，现在包含旧 DirectX 12 运行时的大部分内容

对于不选择使用 Agility SDK 的现有游戏，D3D12.dll 只需加载 D3D12Core.dll：

对于使用 Agility SDK 的开发人员，D3D12.dll 可以加载比 System32 中的更新的 D3D12Core.dll，该开发人员将把该 D3D12Core.dll 包含在其应用程序中：

DirectX 团队将通过在每个新版本的 Windows 10 中包含最新版本的 D3D12Core.dll 来继续向 DirectX 发送更新。

当操作系统的 D3D12Core 比游戏附带的版本更新时，将加载操作系统版本的 D3D12Core：

这种模式意味着 DirectX 团队可以继续随最新的 Windows 10 操作系统发布 DirectX 12 更新，同时也为想要获得新功能的开发人员提供这样做的选项。

这也意味着使用 Agility SDK 的游戏开发者不必担心他们的游戏是否使用最新版本的 DirectX——一旦他们发布了他们的游戏，一旦更高版本的 DirectX 与操作系统一起推出，这种情况就会自动发生。

寻求更多细节的开发人员可以在规范中找到它。

设置你的机器

这是一个方便的小复选框，以确保您的机器已准备好开始开发：

支持 Agility SDK 的操作系统	查看
支持您所针对的功能的驱动程序	查看
Visual Studio（我们推荐 VS 2019）	查看
派克斯	查看
您要使用的 DirectX Shader 编译器	查看

支持 Agility SDK 的操作系统

进入“设置”>“系统”>“关于”检查您的操作系统版本和修订号

在“关于”菜单中，向下滚动到“Windows 规格”部分

操作系统版本

Version旁边的数字是你的OS 版本。只要这个数字等于或大于1909，就表明你的机器支持 Agility SDK。

修订编号

如果您的操作系统版本是 1909、2004 或 20H2，您还需要检查您的修订号。

对于后续操作系统，此项检查不是必需的。

附加到您的操作系统内部版本号的数字（修订号）会随着您的操作系统获得的每个 KB 补丁而增加。

对于 Windows 10 版本 1909，修订号应大于或等于.1350（如上图所示）
对于 Windows 10 版本 2004 和 20H2，修订号应大于或等于.789

有关支持 Agility SDK 的特定 KB 补丁的更多信息请参见这里和这里。

另一种检查方法是进入机器的 System32 文件夹（通常在 C:\Windows\System32 中；您也可以在文件资源管理器中输入 %systemroot%\system32），以查看您的机器是否支持 Agility SDK。

System32 中存在 D3D12Core.dll 意味着您的系统已收到上一节中解释的支持 Agility SDK 的加载器更改。

请注意，已经处于预览阶段的 Windows Server 2022 支持 Agility SDK。所有后续服务器版本也将支持 Agility SDK。

有关获取支持 Agility SDK 的操作系统的更多信息，请参阅故障排除部分。

支持您所针对的功能的驱动程序

DirectX 团队一直与我们的 IHV 合作伙伴合作，以确保驱动程序能够与 Agility SDK 一起按预期运行，并点亮比给定操作系统上更新的功能。

与以前一样，开发人员需要确保他们使用的驱动程序支持他们所针对的功能。对于我们的第一个 SDK 启用的新功能（完整的DirectX 12 Ultimate功能集和Shader Model 6.6），请务必获取：

来自 AMD 的开发驱动程序；请参阅此处下载。
对于 NVIDIA，它是任何驱动程序 466.11 及以上版本，请参阅此处下载

视觉工作室

我们建议使用Visual Studio 2019，但 Visual 2017 也可以。如果您尚未拥有专业版或企业版，则可以使用免费的社区版。

Windows 上的 PIX

我们的图形调试器 PIX 原生支持 Agility SDK、DirectX 12 Ultimate 和 Shader Model 6.6

前往下载 | Windows 上的 PIX以获取最新版本的 PIX

您要使用的 DirectX Shader 编译器

Windows 10 SDK已经附带了 DirectX Shader 编译器的副本。

但是，如果您使用的是Shader Model 6.6，您还需要获取正确的 DirectX Shader Compiler版本，以便您能够编译和运行使用我们最新着色器模型的着色器。

如何使用 Agility SDK

本节内容包括：

1. 从 NuGet.org 安装您选择的 Agility SDK

您现在需要获取您选择的 Agility SDK 并安装它。

方法 a：使用 Visual Studio 的 NuGet UI 适用于使用 stock .vcxproj 作为构建系统并希望使用 Visual Studio 的 UI 安装 Agility SDK NuGet 包的开发人员。

方法 b：手动包含 Agiliy SDK适用于使用不同构建系统、无法使用 Visual Studio 内置 NuGet 安装 UI 的开发人员。

方法 c：提取 Agility SDK .nupkg 的内容适用于想要避免使用 NuGet 的开发人员。

方法 a：使用 Visual Studio 的 NuGet UI

在 Visual Studio 中，可以按如下方式完成此操作：右键单击您的项目并转到管理 NuGet 包。到达此处后，从 nuget.org 搜索 Agility SDK（输入“Microsoft.Direct3D.D3D12”或“DirectX 12 Agility”）。找到所需的版本后，点击安装。

截至撰写本文时，只有一个 Agility SDK 可用，但请参阅Agility SDK 下载页面以获取最新信息。

默认情况下，Agility SDK (D3D12SDKPath) 中的组件路径设置为“.\D3D12\”。这意味着构建项目所需的 Agility SDK 组件将放在名为 D3D12 的子目录中，与您的应用程序 exe 位于同一文件夹中。

但是，您也可以右键单击项目并选择属性来设置自定义路径 D3D12SDKPath：

。

DirectX 团队建议开发人员避免将 Agility SDK 组件与其应用程序 exe 放在同一目录中，以避免 D3D12SDKLayers 与 D3D12Core.dll 的 D3D12SDKVersion 不匹配（有关更多详细信息，请参阅已知问题）

方法 b：手动包含 Agility SDK

使用不同构建系统的开发人员可以下载我们的 NuGet 包并解压。要解压任何 NuGet 包，只需在提取文件之前将其扩展名从 .nupkg 更改为 .zip。

其他选项是使用 NuGet 从 nuget.org 安装：

NuGet.exe install Microsoft.Direct3D.D3D12 -Source https://api.nuget.org/v3/index.json -OutputDirectory <DestinationFolder>

开发人员还可以使用 NuGet 从文件夹安装：

NuGet.exe install Microsoft.Direct3D.D3D12 -Source <FolderWith.nupkg> -OutputDirectory <DestinationFolder>

确保将 D3D12Core.dll 和您要使用的其他 SDK 组件放入适当的应用本地目录中。下面的“设置 Agility SDK参数”中的代码要求 Agility SDK 组件位于与应用程序 exe 位于同一目录中名为 D3D12 的文件夹中，这是开发人员避免已知问题的好选择。

方法 a 会自动更新您的包含路径以使用新标头。这必须在此处手动完成，即包含目录顺序应为 NuGet 包含目录在 Windows SDK 包含目录之前。

对于方法 b，我们还建议使用 Windows SDK 中的 d3d12.lib。

方法 c：提取 Agility SDK .nupkg 的内容

想要提取任何 Agility SDK 内容的开发人员可以使用两个 PowerShell 命令来实现。第一个命令获取 Agility SDK NuGet 包并将其保存为 .zip 文件。第二个命令提取此 zip 文件的内容。

请参阅下面的示例：

PS C:\Users\user\Desktop> Invoke-WebRequest -Uri https://www.nuget.org/api/v2/package/Microsoft.Direct3D.D3D12/1.4.10 -OutFile agility.zip
PS C:\Users\user\Desktop> Expand-Archive agility.zip -DestinationPath d3d

请注意，此示例抓取的是 SDK 版本1.4.10；请务必指定要提取的版本。最新版本及其相关信息可在下载页面上找到。

请注意，第二个命令中的 -DestinationPath 指定应将包的内容提取到名为 d3d 的目录中。请确保将 D3D12Core.dll 移动到您打算作为 D3D12SDKPath 的正确应用本地目录（见下文）。

2. 设置 Agility SDK 参数

您几乎已准备好构建项目，但首先您需要注册一些数据以允许收件箱 D3D12.dll 加载器选择是否加载收件箱 System32 D3D12Core.dll 或您与 Agility SDK 一起使用的应用程序本地 D3D12Core.dll。

具体来说，您需要通过两个众所周知的符号 D3D12SDKVersion 和 D3D12SDKPath 导出常量数据。

请注意，这些参数需要从进程的主.exe 中导出。

D3D12SDKVersion是您用于构建应用程序的 Agility SDK 中 D3D12Core.dll 的 SDK 版本。

请注意，对于我们的第一个 Agility SDK，该数字将等于 4。此数字将随着后续 SDK 而递增；每个 Agility SDK 的 D3D12SDKVersion 均在下载页面的表格中注明。

另请注意，如果导出的 D3D12SDKVersion 与 D3D12Core.dll 的 SDK 版本不匹配，D3D12CreateDevice 将失败。

D3D12SDKPath是您相对于应用程序 exe 使用的 Agility SDK 二进制文件的路径。

如果你使用Visual Studio 的 NuGet UI 安装 SDK（方法 a）并且未设置自定义 D3D12SDKPath，则该路径将为“.\\D3D12\\”

您可以使用方法 a：__declspec(dllexport) 关键字或方法：通过模块定义文件导出 D3D12SDKVersion 和 D3D12SDKPath 。

方法a：__declspec(dllexport) 关键字

A 可以使用__declspec(dllexport) 关键字按如下方式导出这些常量：

复制

extern "C" { __declspec(dllexport) extern const UINT D3D12SDKVersion = n;}

extern "C" { __declspec(dllexport) extern const char* D3D12SDKPath = u8".\\D3D12\\"; }

此处n对应于您使用的 D3D12SDKVersion。对于我们的第一个 Agility SDK，此值为 4。

方法 b：模块定义文件

另一种选择是通过 .def 文件导出这些常量：

EXPORTS

  D3D12SDKVersion DATA PRIVATE

  D3D12SDKPath DATA PRIVATE

然后在代码中声明常量，如下所示：

extern "C" extern const uint32_t D3D12SDKVersion = n;

extern "C" extern LPCSTR D3D12SDKPath = ".\\D3D12\\";

此处n 对应于您使用的 D3D12SDKVersion。对于我们的第一个 Agility SDK，此值为 4。

3. 构建并发布你的游戏

如果您已经设置并导出这些参数，那么您就可以构建可执行文件了。

要发布你的游戏，你必须包含用于构建游戏的 D3D12Core.dll，并使用与 D3D12SDKPath 声明的相同文件夹结构。

请记住还要从应用程序的安装程序中删除调试层 (D3D12SDKLayers.dll)。DirectX 团队强烈建议使用调试层进行开发，但没有必要用它来发布游戏。

故障排除

我进入“关于”，发现我的操作系统版本或修订号较旧

每个 Windows 10 操作系统版本 1909（2019 年 11 月更新）及以上版本都支持 Agility SDK。

截至撰写本指南时，版本 1909 之前的操作系统已不再提供服务支持。我们建议升级到正在使用的操作系统，不仅是为了获得 Agility SDK 的支持，也是为了确保您获得安全更新。

请参阅此处了解有关 Microsoft 支持时间表的更多信息。

要获取较新的操作系统版本和/或查找最新的 Windows 更新，请进入“设置”>“Windows 更新”，然后单击“检查更新”。

如果单击“检查更新”在您的计算机上不起作用，并且您的计算机由 IT 部门管理，则可能是您的 IT 部门阻止了对您计算机的更新。如果是这种情况，请与您所在组织的 IT 部门合作，以使用较新的操作系统。

有关为 redist 支持的特定 KB 补丁的更多信息请参见这里和这里。

请注意，已经处于预览阶段的 Windows Server 2022 支持 Agility SDK。所有后续服务器版本也将支持 Agility SDK。

请注意，Windows 10 之前的操作系统不支持 Agility SDK。

我遇到了 D3D12_ERROR_INVALID_REDIST – 887e0003 … 缺少来自 D3D12Core 的 D3D12GetInterface 导出

此错误消息表示在为 D3D12SDKPath 指定的位置未找到 D3D12Core.dll。请务必包含尾部斜杠！

在微软发布的下一个操作系统版本中，这个错误消息会更清晰：“无法加载 D3D12Core.dll。请验证 D3D12SDKPath 是否正确。”

我遇到了 D3D12_ERROR_INVALID_REDIST – 887e0003 … D3D12SDKVersion 来自 D3D12Core != 请求的 D3D12SDKVersion

此错误消息意味着您请求的 D3D12SDKVersion 与您安装的 Agility SDK 中的 D3D12Core.dll 的 D3D12SDKVersion 不匹配。

您可以通过右键单击项目并进入管理 NuGet 包来检查已安装的 Agility SDK 的 D3D12SDKVersion。NuGet 包次要版本号与 D3D12SDKVersion 相同，例如 1.4.9，中间的数字表示 D3D12SDKVersion 等于 4。

这也嵌入在 dll 版本中。右键单击 D3D12Core.dll，转到“属性”、“详细信息”选项卡，查看文件版本。同样，次要版本是 D3D12SDKVersion，并将与其来源的 NuGet 包相匹配。

我遇到了 D3D12_ERROR_INVALID_REDIST – 887e0003 .... D3D12 SDKLayers dll 与 D3D12 Core dll 的 D3D12SDKVersion 不匹配

如果加载的是 System32 D3D12Core.dll 而不是 D3D12Core.dll 的应用本地副本，则 D3D12SDKLayers（调试层）和 D3D12Core.dll 的 D3D12SDKVersion 之间可能会不匹配。通过确保所有 Agility SDK 组件不与应用程序 exe 位于同一目录中，而是位于子目录中，可以避免此问题。