建立全像攝影 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 上以 網路下載的形式提供,或透過 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 1903 版For development targeting only HoloLens 2, ensure that the Target version and Minimum version are set to Windows 10, version 1903. 如果您也將目標設為 HoloLens (第1代) 或桌面 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. 若要讓此選項出現,請 安裝 WINDOWS 10 SDK 的版本10.0.18362.0 或更新版本To 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 通用 > 全像] 節點,然後選取 [全像] DirectX 11 應用程式 (通用 Windows) (c + +/WinRT])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 1903 版For development targeting only HoloLens 2, ensure that the Target version and Minimum version are set to Windows 10, version 1903. 如果您也將目標設為 HoloLens (第1代) 或桌面 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. 若要讓此選項出現,請 安裝 WINDOWS 10 SDK 的版本10.0.18362.0 或更新版本To 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個計量的全球鎖定 cube。The project shows how to create a world-locked cube that's placed 2 meters from the user. 使用者可以 按一下 或按下控制器上的按鈕,將 cube 放在使用者的 注視所指定的不同位置。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.

您也可以使用以 SharpDX 為基礎的 Visual c # 全像投影專案範本來建立新專案。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. 您也可以在 Windows Mixed Reality 應用程式範本延伸模組中提供 Direct3D 12 範本,以 Visual Studio。A Direct3D 12 template is also provided in the Windows Mixed Reality app templates extension to Visual Studio.

請參閱 使用 Visual Studio 部署和調試 程式,以取得如何建立範例,並將其部署至您的 HoloLens、具有沉浸式裝置連接的電腦或模擬器的資訊。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.

AppView .cppFrom 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個計量的全球鎖定 cube。The project shows how to create a world-locked cube that's placed 2 meters from the user. 使用者可以按下控制器上的按鈕,將 cube 放在使用者的 注視所指定的不同位置。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.

AppMain .cppFrom 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

專案的 Content 資料夾包含用來轉譯全像攝影 空間中之全息的類別。The project's Content folder contains classes for rendering holograms in the holographic space. 範本中的預設全息圖是放置2個計量離開使用者的旋轉 cube。The default hologram in the template is a spinning cube that's placed 2 meters away from the user. 繪圖這個 cube 是在 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 旋轉 cube,並設定模型矩陣。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 方法會更新場景物件(例如旋轉 cube),並傳回用來取得最新的視圖和投射矩陣,以及呈現交換鏈的 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.

中的轉譯方法 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 應用程式範本現在支援使用已啟用 Spectre 防護旗標的編譯 (/Qspectre) 。The Windows Mixed Reality app template now supports compilation with the Spectre mitigation flag enabled (/Qspectre). 在編譯設定 Spectre 緩和功能的設定之前,請務必先安裝 Spectre 緩和版的 Microsoft Visual C++ (MSVC) 執行時間程式庫。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