创建全息 DirectX 项目Creating a holographic DirectX project

备注

本文与旧版 WinRT 本机 Api 相关。This article relates to the legacy WinRT native APIs. 对于新的本机应用项目,建议使用 OPENXR APIFor new native app projects, we recommend using the OpenXR API.

为 HoloLens 创建的全息版应用将是 通用 Windows 平台 (UWP) 应用A holographic app you create for a HoloLens will be a Universal Windows Platform (UWP) app. 如果面向桌面 Windows Mixed Reality 耳机,则可以创建 UWP 应用或 Win32 应用。If targeting desktop Windows Mixed Reality headsets, you can create a UWP app or a Win32 app.

DirectX 11 全息 UWP 应用模板非常类似于 DirectX 11 UWP 应用模板。The DirectX 11 holographic UWP app template is much like the DirectX 11 UWP app template. 该模板包括一个程序循环、一个用于管理 Direct3D 设备和上下文的 DeviceResources 类和一个简化的内容呈现器类。The template includes a program loop, a DeviceResources class to manage the Direct3D device and context, and a simplified content renderer class. 它还有 IFrameworkView,就像其他任何 UWP 应用一样。It also has an IFrameworkView, just like any other UWP app.

然而,混合现实应用有一些其他功能,这些功能在典型的 Direct3D UWP 应用中不存在。The mixed reality app, however, has some additional capabilities that aren't present in a typical Direct3D UWP app. Windows Mixed Reality 应用模板可以:The Windows Mixed Reality app template can:

  • 处理与全息相机关联的 Direct3D 设备资源。Handle Direct3D device resources associated with holographic cameras.
  • 从系统检索相机后台缓冲区。Retrieve camera back buffers from the system. 对于 Direct3D12,创建全息后台缓冲区资源并管理资源生存期。In the case of Direct3D12, create holographic back buffer resources and manage resource lifetimes.
  • 处理 注视 的输入,并识别 手势Handle gaze input, and recognize a gesture.
  • 进入全屏立体声呈现模式。Go into full-screen stereo rendering mode.

如何入门?How do I get started?

按照下载 Visual Studio 2019 和 Windows Mixed Reality 应用模板中的说明,首先 安装这些工具First install the tools, following the instructions on downloading Visual Studio 2019 and the Windows Mixed Reality app templates. 混合现实应用模板在 Visual Studio marketplace 上可作为 web 下载,或通过 VISUAL studio UI 安装为扩展。The mixed reality app templates are available on the Visual Studio marketplace as a web download, or by installing them as an extension through the Visual Studio UI.

现在,你已准备好创建 DirectX 11 Windows Mixed Reality 应用!Now you're ready to create your DirectX 11 Windows Mixed Reality app! 请注意,若要删除示例内容,请在 pch 中注释掉 DRAW_SAMPLE_CONTENT 预处理器指令。Note, to remove the sample content, comment out the DRAW_SAMPLE_CONTENT preprocessor directive in pch.h.

创建 UWP 项目Creating a UWP project

安装工具后,] (。/install-the-tools.md) 你可以创建一个全息的 DirectX UWP 项目。Once the tools are installed,](../install-the-tools.md) you can then create a holographic DirectX UWP project.

在 Visual Studio 2019 中创建新项目:To create a new project in Visual Studio 2019:

  1. 启动 Visual StudioStart Visual Studio.
  2. 在右侧的 " 入门 " 部分中,选择 " 创建新项目"。In the Get Started section on the right, select Create a new project.
  3. 在 " 创建新项目 " 对话框的下拉菜单中,选择 " c + +"、" Windows Mixed Reality" 和 " UWP"。In the drop-down menus in the Create a new project dialog, select C++, Windows Mixed Reality, and UWP.
  4. (通用 Windows) (c + +/WinRT) 中选择 "全息 DirectX 11 应用程序"。Select Holographic DirectX 11 App (Universal Windows) (C++/WinRT). Visual Studio 2019 中全息版 DirectX 11 c + +/WinRT UWP 应用项目模板的屏幕截图Screenshot of the Holographic DirectX 11 C++/WinRT UWP app project template in Visual Studio 2019
    Visual Studio 2019 中的全息 DirectX 11 c + +/WinRT UWP 应用项目模板Holographic DirectX 11 C++/WinRT UWP app project template in Visual Studio 2019

    重要

    请确保项目模板的名称包含 " (c + +/WinRT) "。Be sure that the project template's name includes "(C++/WinRT)". 如果没有,则已安装全息版项目模板。If not, you have an older version of the holographic project templates installed. 若要获取最新的项目模板,请将 其安装 为 Visual Studio 2019 的扩展。To get the latest project templates, install them as an extension to Visual Studio 2019.

  5. 选择“下一步” 。Select Next.
  6. 填写 " 项目名称 " 和 " 位置 " 文本框,然后选择或点击 " 创建"。Fill in the Project name and Location text boxes, and select or tap Create. 创建全息应用项目。The holographic app project is created.
  7. 对于仅面向 HoloLens 2 的开发,请确保将 目标版本最低版本 设置为 Windows 10,版本 1903For development targeting only HoloLens 2, ensure that the Target version and Minimum version are set to Windows 10, version 1903. 如果你还面向 HoloLens (第一代) 或桌面 Windows Mixed Reality 耳机,则可以将 最低版本 设置为 Windows 10,版本 1809If you're also targeting HoloLens (1st gen) or desktop Windows Mixed Reality headsets, you can set Minimum version to Windows 10, version 1809. 使用 HoloLens 2 的新功能时,这将要求在代码中进行某种 版本自适应检查This will require some version adaptive checks in your code when using new features of HoloLens 2. 将 Windows 10 (版本1903)设置为目标和最小版本的屏幕截图Screenshot of setting Windows 10, version 1903 as the target and minimum versions
    Windows 10 (版本1903) 设置为目标和最低版本Setting Windows 10, version 1903 as the target and minimum versions

    重要

    如果看不到 windows 10 (版本 1903 )作为选项,则不会安装最新的 WINDOWS 10 SDK。If you do not see Windows 10, version 1903 as an option, you do not have the latest Windows 10 SDK installed. 若要使此选项显示,请 安装10.0.18362.0 或更高版本的 Windows 10 SDKTo get this option to appear, install version 10.0.18362.0 or later of the Windows 10 SDK.

在 Visual Studio 2017 中创建新项目:To create a new project in Visual Studio 2017:

  1. 启动 Visual StudioStart Visual Studio.
  2. 在 " 文件 " 菜单上,指向 " 新建 ",然后从上下文菜单中选择 " 项目 "。From the File menu, point to New and select Project from the context menu. 此时会打开“新建项目”对话框。 The New Project dialog opens.
  3. 展开左侧的 " 已安装 ",然后展开 " Visual C++ 语言" 节点。Expand Installed on the left and expand the Visual C++ language node.
  4. 导航到 " Windows 通用 > 全息 节点",然后选择 " ) (c + +/WinRT) (通用 Windows 的全息 DirectX 11 应用Navigate to the Windows Universal > Holographic node and select Holographic DirectX 11 App (Universal Windows) (C++/WinRT). Visual Studio 2017 中全息版 DirectX 11 c + +/WinRT UWP 应用项目模板的屏幕截图Screenshot of the Holographic DirectX 11 C++/WinRT UWP app project template in Visual Studio 2017
    Visual Studio 2017 中的全息 DirectX 11 c + +/WinRT UWP 应用项目模板Holographic DirectX 11 C++/WinRT UWP app project template in Visual Studio 2017

    重要

    请确保项目模板的名称包含 " (c + +/WinRT) "。Be sure that the project template's name includes "(C++/WinRT)". 如果没有,则已安装全息版项目模板。If not, you have an older version of the holographic project templates installed. 若要获取最新的项目模板,请将 其安装 为 Visual Studio 2017 的扩展。To get the latest project templates, install them as an extension to Visual Studio 2017.

  5. 填写 " 名称 " 和 " 位置 " 文本框,然后选择或点击 "确定"Fill in the Name and Location text boxes, and select or tap OK. 创建全息应用项目。The holographic app project is created.
  6. 对于仅面向 HoloLens 2 的开发,请确保将 目标版本最低版本 设置为 Windows 10,版本 1903For development targeting only HoloLens 2, ensure that the Target version and Minimum version are set to Windows 10, version 1903. 如果你还面向 HoloLens (第一代) 或桌面 Windows Mixed Reality 耳机,则可以将 最低版本 设置为 Windows 10,版本 1809If you're also targeting HoloLens (1st gen) or desktop Windows Mixed Reality headsets, you can set Minimum version to Windows 10, version 1809. 使用 HoloLens 2 的新功能时,这将要求在代码中进行某种 版本自适应检查This will require some version adaptive checks in your code when using new features of HoloLens 2. 将 Windows 10 (版本1903)设置为目标和最小版本的屏幕截图Screenshot of setting Windows 10, version 1903 as the target and minimum versions
    Windows 10 (版本1903) 设置为目标和最低版本Setting Windows 10, version 1903 as the target and minimum versions

    重要

    如果看不到 windows 10 (版本 1903 )作为选项,则不会安装最新的 WINDOWS 10 SDK。If you do not see Windows 10, version 1903 as an option, you do not have the latest Windows 10 SDK installed. 若要使此选项显示,请 安装10.0.18362.0 或更高版本的 Windows 10 SDKTo get this option to appear, install version 10.0.18362.0 or later of the Windows 10 SDK.

该模板将使用 c + +/WinRT(一种 c + + 17 语言 Windows 运行时 api)生成项目,该项目支持任何符合标准的 c + + 17 编译器。The template generates a project using C++/WinRT, a C++17 language projection of the Windows Runtime APIs that supports any standards-compliant C++17 compiler. 该项目演示了如何创建一个世界上锁定的多维数据集,该多维数据集是用户的2米。The project shows how to create a world-locked cube that's placed 2 meters from the user. 用户 可以按 下或按下控制器上的按钮,将多维数据集置于用户 注视指定的不同位置。The user can air-tap or press a button on the controller to place the cube in a different position specified by the user's gaze. 可以修改此项目来创建任何混合现实应用。You can modify this project to create any mixed reality app.

你还可以使用 Visual c # 全息项目模板创建一个新项目,该模板基于 SharpDX。You can also create a new project using the Visual C# holographic project template, which is based on SharpDX. 如果你的全息 c # 项目不是从 Windows 全息应用程序模板开始,则需要从 Windows Mixed Reality c # 模板项目复制 fxcompile 文件并将其导入到 .csproj 文件中,以便编译添加到项目中的 HLSL 文件。If your holographic C# project didn't start from the Windows Holographic app template, you'll need to copy the ms.fxcompile.targets file from a Windows Mixed Reality C# template project and import it in your.csproj file to compile HLSL files that you add to your project. 在 Visual Studio 的 Windows Mixed Reality 应用程序模板扩展中还提供了 Direct3D 12 模板。A Direct3D 12 template is also provided in the Windows Mixed Reality app templates extension to Visual Studio.

请参阅 使用 Visual Studio 进行部署和调试 ,获取有关如何生成和部署该示例并将其部署到 HoloLens、附加了沉浸式设备的 PC 或仿真程序的信息。Review Using Visual Studio to deploy and debug for information on how to build and deploy the sample to your HoloLens, PC with immersive device attached, or an emulator.

下面的说明将假设你使用 c + + 生成应用。The rest of the instructions below will assume that you're using C++ to build your app.

UWP 应用入口点UWP app entry point

全息 UWP 应用在 AppView 的 wWinMain 函数中启动。Your holographic UWP app starts in the wWinMain function in AppView.cpp. WWinMain 函数创建应用的 IFrameworkView ,并通过它启动 CoreApplicationThe wWinMain function creates the app's IFrameworkView and starts the CoreApplication with it.

AppViewFrom 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 事件和消息等的交互。From that point on, the AppView class handles interaction with Windows basic input events, CoreWindow events and messaging, and so on. 它还将创建应用使用的 HolographicSpace。It will also create the HolographicSpace used by your app.

创建 Win32 项目Creating a Win32 project

开始构建 Win32 全息项目的最简单方法是修改 BasicHologram Win32 示例The easiest way to get started building a Win32 holographic project is to adapt the BasicHologram Win32 sample.

此 Win32 示例使用 c + +/WinRT,它是支持任何符合标准的 c + + 17 编译器的 Windows 运行时 Api 的 c + + 17 语言投影。This Win32 sample uses C++/WinRT, a C++17 language projection of the Windows Runtime APIs that supports any standards-compliant C++17 compiler. 该项目演示了如何创建一个世界上锁定的多维数据集,该多维数据集是用户的2米。The project shows how to create a world-locked cube that's placed 2 meters from the user. 用户可以按控制器上的按钮,将多维数据集置于用户 注视指定的不同位置。The user can press a button on the controller to place the cube in a different position that's specified by the user's gaze. 可以修改此项目来创建任何混合现实应用。You can modify this project to create any mixed reality app.

Win32 应用程序入口点Win32 app entry point

全息 Win32 应用程序在 AppMain 的 wWinMain 函数中启动。Your holographic Win32 app starts in the wWinMain function in AppMain.cpp. WWinMain 函数创建应用的 HWND 并启动其消息循环。The wWinMain function creates the app's HWND and starts its message loop.

AppMainFrom 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 类处理与基本窗口消息的交互,等等。From that point on, the AppMain class handles interaction with basic window messages, and so on. 它还将创建应用使用的 HolographicSpace。It will also create the HolographicSpace used by your app.

呈现全息内容Render holographic content

项目的 " 内容 " 文件夹包含用于渲染 全息空间中全息影像的类。The project's Content folder contains classes for rendering holograms in the holographic space. 模板中的默认全息图是远离用户的旋转多维数据集。The default hologram in the template is a spinning cube that's placed 2 meters away from the user. 绘制此多维数据集是在 SpinningCubeRenderer 中实现的,该方法具有以下关键方法:Drawing this cube is implemented in SpinningCubeRenderer.cpp, which has these key methods:

方法Method 说明Explanation
CreateDeviceDependentResources 加载着色器并创建多维数据集网格。Loads shaders and creates the cube mesh.
PositionHologram 将全息图置于所提供的 SpatialPointerPose指定的位置。Places the hologram at the location specified by the provided SpatialPointerPose.
Update 旋转多维数据集,并设置模型矩阵。Rotates the cube, and sets the model matrix.
Render 使用顶点和像素着色器呈现一个帧。Renders a frame using the vertex and pixel shaders.

着色 子文件夹包含四个默认着色器实现:The Shaders subfolder contains four default shader implementations:

着色器Shader 说明Explanation
GeometryShader.hlsl 不修改几何图形的传递。A pass-through that leaves the geometry unmodified.
PixelShader.hlsl 通过颜色数据。Passes through the color data. 在光栅化步骤中,将颜色数据插值并分配给一个像素。The color data is interpolated and assigned to a pixel at the rasterization step.
VertexShader.hlsl 用于在 GPU 上执行顶点处理的简单着色器。Simple shader to do vertex processing on the GPU.
VPRTVertexShader.hlsl 用于在 GPU 上执行顶点处理的简单着色器,针对 Windows Mixed Reality 立体声渲染进行了优化。Simple shader to do vertex processing on the GPU, that is optimized for Windows Mixed Reality stereo rendering.

VertexShaderShared.hlsl 包含在和之间共享的通用代码 VertexShader.hlsl VPRTVertexShader.hlslVertexShaderShared.hlsl contains common code shared between VertexShader.hlsl and VPRTVertexShader.hlsl.

注意: Direct3D 12 应用模板还包括 ViewInstancingVertexShader.hlslNote: The Direct3D 12 app template also includes ViewInstancingVertexShader.hlsl. 此变体使用 D3D12 可选功能来更有效地呈现立体声图像。This variant uses D3D12 optional features to render stereo images more efficiently.

着色器将在项目生成时编译,并在 SpinningCubeRenderer:: CreateDeviceDependentResources 方法中加载。The shaders compile when the project is built, and loaded in the SpinningCubeRenderer::CreateDeviceDependentResources method.

与全息影像交互Interact with your holograms

用户输入在 SpatialInputHandler 类中处理,该类获取 SpatialInteractionManager 实例并订阅 SourcePressed 事件。User input is processed in the SpatialInputHandler class, which gets a SpatialInteractionManager instance and subscribes to the SourcePressed event. 这将允许检测分流手势和其他空间输入事件。This enables detecting the air-tap gesture and other spatial input events.

更新全息内容Update holographic content

混合现实应用在游戏循环中更新,默认情况下,该循环在的 Update 方法中实现 AppMain.cppYour mixed reality app updates in a game loop, which by default is implemented in the Update method in AppMain.cpp. Update 方法更新场景对象,如旋转立方体,并返回一个 HolographicFrame对象,该对象用于获取最新的视图和投影矩阵并显示交换链。The Update method updates scene objects, like the spinning cube, and returns a HolographicFrame object that is used to get up-to-date view and projection matrices and to present the swap chain.

中的 Render 方法 AppMain.cpp 采用 HolographicFrame ,并根据当前应用和空间定位状态将当前帧呈现到每个全息相机。The Render method in AppMain.cpp takes the HolographicFrame and renders the current frame to each holographic camera, according to the current app and spatial positioning state.

备注Notes

现在,Windows Mixed Reality 应用模板支持 (/Qspectre) 启用了 Spectre 缓解标志的编译。The Windows Mixed Reality app template now supports compilation with the Spectre mitigation flag enabled (/Qspectre). 在编译使用 Spectre 缓解功能的配置之前,请确保安装 Spectre (MSVC) 运行时库的 Microsoft Visual C++ 版本。Make sure to install the Spectre-mitigated version of the Microsoft Visual C++ (MSVC) runtime libraries before compiling a configuration with Spectre mitigation enabled. 若要安装 Spectre 缓解的 c + + 库,请启动 Visual Studio 安装程序并选择 " 修改"。To install the Spectre-mitigated C++ libraries, launch the Visual Studio Installer and select Modify. 导航到 各个组件 并搜索 "spectre"。Navigate to Individual components and search for "spectre". 选择与要为其编译 Spectre 的代码所需的目标平台和 MSVC 版本对应的框,然后单击 " 修改 " 开始安装。Select the boxes corresponding to the target platforms and MSVC version that you need to compile Spectre-mitigated code for, and click Modify to begin the install.

另请参阅See also