创建全息 DirectX 项目

项目
07/12/2023

注意

本文与旧版 WinRT 原生 API 相关。对于新的本机应用项目，建议使用 OpenXR API。

为 HoloLens 创建的全息应用将是通用 Windows 平台 (UWP) 应用。如果面向桌面 Windows Mixed Reality 头戴显示设备，则可以创建 UWP 应用或 Win32 应用。

DirectX 11 全息 UWP 应用模板与 DirectX 11 UWP 应用模板非常相似。该模板包括一个程序循环、一个 DeviceResources 类（用于管理 Direct3D 设备和上下文），以及一个简化的上下文呈现器类。它还有一个 IFrameworkView，就像其他任何 UWP 应用一样。

然而，混合现实应用有一些其他功能，这些功能在典型 Direct3D UWP 应用中不存在。 Windows Mixed Reality 应用模板可以：

处理与全息相机关联的 Direct3D 设备资源。
从系统检索相机后台缓冲区。对于 Direct3D12，创建全息后台缓冲区资源并管理资源生存期。
处理注视输入，并识别手势。
进入全屏立体声呈现模式。

如何开始？

请按照下载 Visual Studio 2019 和 Windows Mixed Reality 应用模板中的说明，先安装这些工具。混合现实应用模板可以在 Visual Studio 市场中通过 Web 下载获得，也可以通过 Visual Studio UI 将它们安装为扩展。

现在，你已准备好创建 DirectX 11 Windows Mixed Reality 应用了！请注意，若要删除示例内容，请在 pch.h 中注释掉 DRAW_SAMPLE_CONTENT 预处理器指令。

创建 UWP 项目

安装工具后，你可以创建全息 DirectX UWP 项目。

在 Visual Studio 2019 中创建新项目：

启动 Visual Studio。
在右侧的“入门”部分中，选择“创建新项目”。
在“创建新项目”对话框的下拉菜单中，选择“C++”、“Windows Mixed Reality”和“UWP”。
选择“全息 DirectX 11 应用(通用 Windows)(C++/WinRT)”。
Visual Studio 2019 中的全息 DirectX 11 C++/WinRT UWP 应用项目模板

重要

请确保项目模板的名称包含“(C++/WinRT)”。如果没有，则安装了全息项目模板的旧版本。若要获取最新项目模板，请将它们安装为 Visual Studio 2019 的扩展。
选择下一步。
填写“项目名称”和“位置”文本框，然后选择或点击“创建”。随即创建全息应用项目。
对于仅限 HoloLens 2 的开发目标，请确保将“目标版本”和“最低版本”设置为”Windows 10 版本 1903”。如果你还以 HoloLens（第一代）或桌面 Windows Mixed Reality 头戴显示设备为目标，则可以将“最低版本”设置为“Windows 10 版本 1809”。当使用 HoloLens 2 的新功能时，这将要求在代码中进行一些版本自适应检查。
将“Windows 10 版本 1903”设置为目标版本和最低版本

重要

如果看不到“Windows 10 版本 1903”选项，则不会安装最新的 Windows 10 SDK。若要显示此选项，请安装 Windows 10 SDK 的 10.0.18362.0 版本或更高版本。

在 Visual Studio 2017 中创建新项目：

启动 Visual Studio。
在“文件”菜单上，指向“新建”，然后从上下文菜单选择“项目”。此时会打开“新建项目”对话框。
展开左侧的“已安装项”，然后展开“Visual C++”语言节点。
导航到“Windows 通用 > 全息”节点，然后选择“全息 DirectX 11 应用(通用 Windows)(C++/WinRT)。
Visual Studio 2017 中的全息 DirectX 11 C++/WinRT UWP 应用项目模板

重要

请确保项目模板的名称包含“(C++/WinRT)”。如果没有，则安装了全息项目模板的旧版本。若要获取最新项目模板，请将它们安装为 Visual Studio 2017 的扩展。
填写“名称”和“位置”文本框，然后选择或点击“确定”。随即创建全息应用项目。
对于仅限 HoloLens 2 的开发目标，请确保将“目标版本”和“最低版本”设置为”Windows 10 版本 1903”。如果你还以 HoloLens（第一代）或桌面 Windows Mixed Reality 头戴显示设备为目标，则可以将“最低版本”设置为“Windows 10 版本 1809”。当使用 HoloLens 2 的新功能时，这将要求在代码中进行一些版本自适应检查。
将“Windows 10 版本 1903”设置为目标版本和最低版本

重要

如果看不到“Windows 10 版本 1903”选项，则不会安装最新的 Windows 10 SDK。若要显示此选项，请安装 Windows 10 SDK 的 10.0.18362.0 版本或更高版本。

该模板使用 C++/WinRT 生成项目，C++/WinRT 是 Windows 运行时 API 的 C++17 语言投影，它支持任何符合标准的 C++17 编译器。该项目演示了如何创建一个世界锁定的立方体，该立方体距离用户 2 米。用户可以隔空敲击或按控制器上的按钮，将立方体置于用户注视指定的不同位置。可以修改此项目来创建任何混合现实应用。

还可以使用基于 SharpDX 的 Visual C# 全息项目模板创建一个新项目。如果你的全息 C# 项目不是从 Windows 全息应用模板开始，则需要从 Windows Mixed Reality C# 模板项目复制 ms.fxcompile.targets 文件，然后将其导入到 your.csproj 文件中，以编译添加到项目中的 HLSL 文件。 Visual Studio 的 Windows Mixed Reality 应用模板扩展中还提供了 Direct3D 12 模板。

查看使用 Visual Studio 进行部署和调试，了解如何生成示例并将其部署到 HoloLens、已连接沉浸式设备的 PC 或仿真器。

下面的其他说明将假设你正在使用 C++ 生成应用。

UWP 应用入口点

全息 UWP 应用在 AppView 的 wWinMain 函数中启动。 wWinMain 函数创建应用的 IFrameworkView，并通过它启动 CoreApplication。

从 AppView.cpp：

// The main function bootstraps into the IFrameworkView.
int __stdcall wWinMain(HINSTANCE, HINSTANCE, PWSTR, int)
{
    winrt::init_apartment();
    CoreApplication::Run(AppViewSource());
    return 0;
}

从这里开始，AppView 类处理与 Windows 基本输入事件、CoreWindow 事件和消息等之间的交互。它还将创建应用使用的 HolographicSpace。

创建 Win32 项目

开始生成 Win32 全息项目的最简单方法是修改 BasicHologram Win32 示例。

此 Win32 示例使用 C++/WinRT，后者是 Windows 运行时 API 的 C++17 语言投影，它支持任何符合标准的 C++17 编译器。该项目演示了如何创建一个世界锁定的立方体，该立方体距离用户 2 米。用户可以按控制器上的按钮，将立方体置于用户注视指定的不同位置。可以修改此项目来创建任何混合现实应用。

Win32 应用入口点

全息 Win32 应用在 AppMain.cpp 的 wWinMain 函数中启动。 wWinMain 函数创建应用的 HWND 并启动其消息循环。

在 AppMain.cpp 中：

int APIENTRY wWinMain(
    _In_     HINSTANCE hInstance,
    _In_opt_ HINSTANCE hPrevInstance,
    _In_     LPWSTR    lpCmdLine,
    _In_     int       nCmdShow)
{
    UNREFERENCED_PARAMETER(hPrevInstance);
    UNREFERENCED_PARAMETER(lpCmdLine);

    winrt::init_apartment();

    App app;

    // Initialize global strings, and perform application initialization.
    app.Initialize(hInstance);

    // Create the HWND and the HolographicSpace.
    app.CreateWindowAndHolographicSpace(hInstance, nCmdShow);

    // Main message loop:
    app.Run(hInstance);

    // Perform application teardown.
    app.Uninitialize();

    return 0;
}

从这里开始，AppMain 类处理与基本窗口消息等的交互。它还将创建应用使用的 HolographicSpace。

渲染全息内容

项目的“内容”文件夹包含用于在全息空间中呈现全息影像的类。模板中的默认全息图是距离用户 2 米的旋转立方体。绘制此立方体是在 SpinningCubeRenderer.cpp 中实现的，它采用以下关键方法：

方法	说明
`CreateDeviceDependentResources`	加载着色器并创建立方体网格。
`PositionHologram`	将全息图置于所提供的 SpatialPointerPose 指定的位置。
`Update`	旋转立方体，并设置模型矩阵。
`Render`	使用顶点和像素着色器呈现一个帧。

“着色器”子文件夹包含四个默认着色器实现：

着色器	说明
`GeometryShader.hlsl`	不修改几何图形的传递。
`PixelShader.hlsl`	传递颜色数据。在光栅化步骤中，将颜色数据插值并分配给一个像素。
`VertexShader.hlsl`	用于在 GPU 上执行顶点处理的简单着色器。
`VPRTVertexShader.hlsl`	用于在 GPU 上执行顶点处理的简单着色器，针对 Windows Mixed Reality 立体声呈现进行了优化。

VertexShaderShared.hlsl 包含在 VertexShader.hlsl 和 VPRTVertexShader.hlsl 之间共享的通用代码。

注意：Direct3D 12 应用模板还包括 ViewInstancingVertexShader.hlsl。此变体使用 D3D12 可选功能来更有效地呈现立体声图像。

着色器将在项目生成时编译，并在 SpinningCubeRenderer::CreateDeviceDependentResources 方法中加载。

与全息影像交互

用户输入在 SpatialInputHandler 类中处理，该类获取 SpatialInteractionManager 实例并订阅 SourcePressed 事件。这将允许检测隔空敲击手势和其他空间输入事件。

更新全息内容

混合现实应用在游戏循环中更新，默认情况下在 AppMain.cpp 的 Update 方法中实现。 Update 方法更新场景对象，如旋转立方体，并返回一个 HolographicFrame 对象，该对象用于获取最新视图和投影矩阵并显示交换链。

AppMain.cpp 中的 Render 方法采用 HolographicFrame，并根据当前应用和空间定位状态将当前帧呈现到每个全息相机。

说明

Windows Mixed Reality 应用模板现支持启用了 Spectre 缓解标志 (/Qspectre) 的编译。在编译启用了 Spectre 缓解的配置之前，请确保安装 Spectre 缓解版本的 Microsoft Visual C++ (MSVC) 运行时库。若要安装 Spectre 缓解版本的 C++ 库，请启动 Visual Studio 安装程序并选择“修改”。导航到“各个组件”并搜索“spectre”。选择与要为其编译 Spectre 缓解代码的目标平台和 MSVC 版本对应的框，然后单击“修改”开始安装。

通过