開始使用 OpenXRGetting started with OpenXR

您可以在 HoloLens 2 上使用 OpenXR 或在電腦上使用 Windows Mixed Reality 沉浸式頭戴裝置進行開發。You can develop using OpenXR on a HoloLens 2 or Windows Mixed Reality immersive headset on the desktop. 如果您沒有耳機的存取權,您可以改用 HoloLens 2 模擬器或 Windows Mixed Reality 模擬器。If you don't have access to a headset, you can use the HoloLens 2 Emulator or the Windows Mixed Reality Simulator instead.

開始使用 OpenXR 進行 HoloLens 2Getting started with OpenXR for HoloLens 2

若要開始開發 HoloLens 2 的 OpenXR 應用程式:To start developing OpenXR applications for HoloLens 2:

  1. 設定 HoloLens 2 或遵循指示來 安裝最新版本的 HoloLens 2 模擬器Set up a HoloLens 2 or follow the instructions to install a recent version of the HoloLens 2 emulator. 如果您使用的是最新的模擬器映射,或裝置已更新其 OS,您應該已有 OpenXR 1.0 準備就緒可供使用。You should already have OpenXR 1.0 ready to go if you're using a recent emulator image or the device has updated its OS.
  2. 從裝置或模擬器啟動 Store 應用程式,以確定您已取得最新的 OpenXR 執行時間,並提供所有 延伸模組。Make sure you've got the latest OpenXR runtime with all extensions present by launching the Store app from the device or emulator.
    • 開啟右上方的功能表,選取 [ 下載和更新],然後選擇 [ 取得更新]。Open the menu in the upper-right, select Downloads and updates, and choose Get updates.

注意

如果您使用模擬器,模擬器映射會在您每次啟動時重設,因此最好是確定您有 最新版的 HoloLens 2 模擬器映射If you're using the emulator, the emulator image will reset each time you start it, and so your best bet is to just make sure that you have the latest version of the HoloLens 2 emulator image.

開始使用適用于 Windows Mixed Reality 耳機的 OpenXRGetting started with OpenXR for Windows Mixed Reality headsets

若要開始開發適用于沉浸式 Windows Mixed Reality 耳機的 OpenXR 應用程式:To start developing OpenXR applications for immersive Windows Mixed Reality headsets:

  1. 請確定您至少執行 (1903) 的 Windows 10 2019 年5月更新,這是 Windows Mixed Reality 終端使用者執行 OpenXR 應用程式的最低需求。Be sure you're running at least the Windows 10 May 2019 Update (1903), which is the minimum requirement for Windows Mixed Reality end users to run OpenXR applications. 如果您使用的是舊版的 Windows 10,您可以使用 Windows 10 更新助理進行升級。If you're on an earlier version of Windows 10, you can upgrade by using the Windows 10 Update Assistant.
  2. 設定 Windows Mixed Reality 耳機或遵循指示來 啟用 Windows Mixed Reality模擬器。Set up a Windows Mixed Reality headset or follow the instructions to enable the Windows Mixed Reality simulator.

這樣就完成了!That's it! 系統會為所有 Windows Mixed Reality 使用者安裝 Windows Mixed Reality OpenXR 執行時間,並自動使其成為作用中狀態。The Windows Mixed Reality OpenXR runtime is installed and made active automatically for all Windows Mixed Reality users. Microsoft Store 接著會讓執行時間保持在最新狀態。The Microsoft Store then keeps the runtime up to date.

若要再次啟用 Windows Mixed Reality OpenXR 執行時間,請從 [開始] 功能表啟動混合實境入口,然後選取視窗頂端的 [修正]。To activate the Windows Mixed Reality OpenXR Runtime again, launch Mixed Reality Portal from the Start menu, and select "Fix it" at the top of the window. 如果該按鈕遺失,表示 OpenXR 執行時間已在使用中。If that button is missing, the OpenXR runtime is already active.

取得 Windows Mixed Reality 的 OpenXR 開發人員工具Getting the OpenXR Developer Tools for Windows Mixed Reality

若要試用 Windows Mixed Reality OpenXR 執行時間,您可以安裝 OpenXR Developer Tools for Windows Mixed Reality 應用程式To try out the Windows Mixed Reality OpenXR Runtime, you can install the OpenXR Developer Tools for Windows Mixed Reality app. 此應用程式提供各種 OpenXR 功能的示範,以及具有使用中執行時間和目前耳機相關重要資訊的系統狀態頁面。This app provides a demo of various OpenXR features, along with a System Status page with key information about the active runtime and current headset.

使用 HoloLens 2 模擬器時,安裝適用于 Windows Mixed Reality 的 OpenXR 開發人員工具最簡單的方式是透過 Windows 裝置入口網站When using the HoloLens 2 emulator, the easiest way to install the OpenXR Developer Tools for Windows Mixed Reality is through the Windows Device Portal. 流覽至 [OpenXR] 頁面,然後按一下 [開發人員功能] 下的 [安裝] 按鈕,該按鈕也可在實體 HoloLens 2 裝置上運作。Navigating to the "OpenXR" page and then clicking the "Install" button under "Developer Features", which also works on physical HoloLens 2 devices.

適用于 Windows Mixed Reality 應用程式的 OpenXR 開發人員工具

建立範例 OpenXR 應用程式Building a sample OpenXR app

如果尚未安裝 OpenXR 開發所需的工具,請務必 安裝這些工具Be sure to install the tools you'll need for OpenXR development if you haven't already.

BasicXrApp專案會顯示一個簡單的 OpenXR 範例,其中包含 WIN32 和 UWP HoloLens 2 專案檔 Visual Studio。The BasicXrApp project shows a simple OpenXR sample with Win32 and UWP HoloLens 2 project files in Visual Studio. 因為解決方案包含 HoloLens UWP 專案,所以您需要在 Visual Studio 中安裝 通用 Windows 平臺開發工作負載 ,才能完全開啟。Because the solution contains a HoloLens UWP project, you'll need the Universal Windows Platform development workload installed in Visual Studio to fully open it.

由於封裝和部署的差異,Win32 和 UWP 專案檔是分開的,因此每個專案內的應用程式程式碼幾乎完全相同!While the Win32 and UWP project files are separate because of differences in packaging and deployment, the app code inside each project is almost exactly the same!

建立 OpenXR Win32 desktop 之後。EXE,您可以在任何支援 OpenXR 的 desktop VR 平臺上搭配 VR 耳機使用它,無論耳機類型為何。After building an OpenXR Win32 desktop .EXE, you can use it with a VR headset on any desktop VR platform that supports OpenXR, whatever the headset type.

建立 OpenXR UWP 應用程式套件之後,您可以將 該套件部署 到 HoloLens 2 裝置或 HoloLens 2 模擬器。After building an OpenXR UWP app package, you can deploy that package to either a HoloLens 2 device or the HoloLens 2 Emulator.

學習 OpenXR APILearning the OpenXR API

如需 OpenXR API 的導覽,請參閱 Visual Studio 中的這段60分鐘影片 BasicXrApp 範例。For a tour of the OpenXR API, check out this 60-minute video of the BasicXrApp sample in Visual Studio. 影片會示範如何在您自己的引擎中使用 OpenXR API 的每個主要元件,也會示範現今建置於 OpenXR 上的一些應用程式:The video shows how each of the major components of the OpenXR API can be used in your own engine, and also demonstrates some of the applications built on OpenXR today:

將 OpenXR 載入器整合至專案Integrate the OpenXR loader into a project

若要在現有專案中開始使用 OpenXR,您將包含 OpenXR 載入器。To get started with OpenXR in an existing project, you'll include the OpenXR loader. 載入器會探索裝置上的作用中 OpenXR 執行時間,並提供其所執行之核心函式和擴充功能的存取權。The loader discovers the active OpenXR runtime on the device and provides access to the core functions and extension functions that it implements.

您可以從 Visual Studio 專案 參考官方的 OpenXR NuGet 套件 ,或從 Khronos GitHub 存放庫 包含官方 OpenXR 載入器來源You can reference the official OpenXR NuGet package from your Visual Studio project or include the official OpenXR loader source from the Khronos GitHub repo. 這兩種方法都可讓您存取 OpenXR 1.0 核心功能,以及已發佈 KHR EXTMSFT 延伸模組。Either approach will give you access to OpenXR 1.0 core features, plus published KHR, EXT and MSFT extensions.

如果您有興趣使用延伸模組進行實驗 MSFT_preview ,您可以從混合現實的 GitHub 存放庫 中複製預覽 OpenXR 標頭If you're interested to experiment with MSFT_preview extensions as well, you can copy in preview OpenXR headers from the Mixed Reality GitHub repo.

參考官方 OpenXR NuGet 套件Reference official OpenXR NuGet package

OpenXR 載入 器 NuGet 套件是參考預建 OpenXR 載入器的最簡單方式。Visual Studio c + + 方案中的 DLL。The OpenXR.Loader NuGet package is the easiest way to reference a prebuilt OpenXR loader .DLL in your Visual Studio C++ solution. 這可讓您存取 OpenXR 1.0 核心功能,以及已發佈 KHR EXTMSFT 延伸模組。This will give you access to OpenXR 1.0 core features, plus published KHR, EXT and MSFT extensions.

若要將 OpenXR 載入器 NuGet 套件參考新增至您的 Visual Studio c + + 方案:To add an OpenXR.Loader NuGet package reference to your Visual Studio C++ solution:

  1. 方案總管 中,以滑鼠右鍵按一下要使用 OpenXR 的專案,然後選取 [ 管理 NuGet 套件 ...]。In Solution Explorer, right-click the project that will use OpenXR and select Manage NuGet Packages....
  2. 切換至 [ 流覽 ] 索引標籤,然後搜尋 OpenXR 載入 器。Switch to the Browse tab and search for OpenXR.Loader.
  3. 選取 OpenXR 載入 器套件,然後在右邊的詳細資料窗格中選取 [安裝]。Select the OpenXR.Loader package and select Install in the details pane to the right.
  4. 選取 [確定] 以接受專案的變更。Select OK to accept the changes to your project.
  5. 新增 #include <openxr/openxr.h> 至原始檔,以開始使用 OPENXR API。Add #include <openxr/openxr.h> to a source file to start using the OpenXR API.

若要查看作用中 OpenXR API 的範例,請參閱 BasicXrApp 範例應用程式。To see an example of the OpenXR API in action, check out the BasicXrApp sample app.

包含官方 OpenXR 載入器來源Include official OpenXR loader source

如果您想要自行建立載入器,例如避免額外的載入器。DLL,您可以將官方的 Khronos OpenXR 載入器來源提取至您的專案。If you want to build the loader yourself, for example to avoid the extra loader .DLL, you can pull the official Khronos OpenXR loader sources into your project. 這可讓您存取 OpenXR 1.0 核心功能,以及已發佈 KHR EXTMSFT 延伸模組。This will give you access to OpenXR 1.0 core features, plus published KHR, EXT and MSFT extensions.

若要開始使用,請遵循 GitHub 上 Khronos OpenXR-SDK存放庫中的指示。To get started here, follow the instructions in the Khronos OpenXR-SDK repo on GitHub. 專案設定為使用 CMake 建立-如果您使用 MSBuild,則必須將程式碼複製到您自己的專案中。The project is set up to build with CMake - if you're using MSBuild, you'll need to copy the code into your own project.

使用預覽延伸模組Using preview extensions

MSFT_preview延伸模組藍圖中所列的延伸模組是為了收集意見反應而預覽的實驗廠商擴充功能。The MSFT_preview extensions listed in the extension roadmap are experimental vendor extensions being previewed to gather feedback. 這些延伸模組僅適用于開發人員裝置,並會在真正的延伸模組發行時移除。These extensions are for developer devices only and will be removed when the real extension ships.

如果您想要試用可用的擴充功能 MSFT_preview ,請執行下列步驟來更新您的專案:If you're interested to try out the available MSFT_preview extensions, go through the following steps to update your project:

  1. 遵循上述其中一種方法,將 OpenXR 載入器整合到您的專案中。Follow either of the approaches above to integrate an OpenXR loader into your project.
  2. 將您專案中的標準 OpenXR 標頭取代為 GitHub 上 Mixed Reality OpenXR存放庫中的預覽標頭。Replace the standard OpenXR headers in your project with the preview headers from the Mixed Reality OpenXR repo on GitHub.

若要在目標 HoloLens 2 或桌上型電腦上啟用預覽延伸模組支援:To then activate preview extension support on your target HoloLens 2 or desktop PC:

  1. 若要確定您有最新的 OpenXR 執行時間,並顯示所有 延伸 模組,請從目標裝置或模擬器內啟動 Store 應用程式,開啟右上方的功能表,選取 [ 下載和更新 ],然後選擇 [ 取得更新]。To make sure you've got the latest OpenXR runtime with all extensions present, launch the Store app from within the target device or emulator, open the menu in the upper-right, select Downloads and updates and choose Get updates.
  2. 從 Microsoft Store 將 Windows Mixed Reality 應用程式的 OpenXR 開發人員工具 安裝到目標裝置,然後執行它。Install the OpenXR Developer Tools for Windows Mixed Reality app from the Microsoft Store onto the target device and run it.
  3. 流覽至 [ 開發人員設定 ] 索引標籤,然後啟用 [ 使用最新 preview OpenXR 運行 時間]Navigate to the Developer Settings tab and enable Use latest preview OpenXR runtime. 這會啟用您裝置上已啟用預覽延伸模組的預覽執行時間。This enables the preview runtime on your device, which has preview extensions activated. ![OpenXR Developer Tools for Windows Mixed Reality app Developer Settings] 索引標籤](images/mixed-reality-openxr-developer-tools-settings.png)OpenXR Developer Tools for Windows Mixed Reality app Developer Settings tab
  4. 確認 OpenXR Developer Tools for Windows Mixed Reality的 [系統狀態] 索引標籤上所顯示的 執行階段版本,符合您打算嘗試的預覽擴充功能所需的版本。Confirm the Runtime version shown on the System Status tab of the OpenXR Developer Tools for Windows Mixed Reality matches the required version of the preview extensions you plan to try. 若是如此,您應該會在 [ 擴充 功能] 清單中看到延伸模組。If so, you should see the extension in the Extensions list. 一旦穩定的擴充功能可供使用,將會移除其預覽延伸模組。Once a stable extension is available, its preview extension will be removed.
    ![OpenXR 開發人員工具以 Windows Mixed Reality 應用程式系統狀態] 索引標籤](images/mixed-reality-openxr-developer-tools-status.png)OpenXR Developer Tools for Windows Mixed Reality app System Status tab

如需這些預覽延伸模組的檔和使用方式的範例,請參閱 Mixed Reality OpenXR 存放庫。See the Mixed Reality OpenXR repo for documentation of these preview extensions and samples of how to use them.

疑難排解Troubleshooting

如果您在進行 OpenXR 開發時遇到問題,請參閱我們的 疑難排解秘訣If you have trouble getting up and running with OpenXR development, check out our troubleshooting tips.