OpenXR 入门Getting started with OpenXR

你可在桌面上的 HoloLens 2 或 Windows Mixed Reality 沉浸式头戴显示设备上使用 OpenXR 进行开发。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.

针对 HoloLens 2 的 OpenXR 入门Getting 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. 请确保已获得最新的 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.

OpenXR for Windows Mixed Reality 耳机入门Getting started with OpenXR for Windows Mixed Reality headsets

开始为沉浸式 Windows Mixed Reality 耳机开发 OpenXR 应用程序:To start developing OpenXR applications for immersive Windows Mixed Reality headsets:

  1. 请确保至少运行 Windows 10 2019 更新 (1903) ,这是 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 OpenXR 运行时已安装,并为所有 Windows Mixed Reality 用户自动激活。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 运行时,可以安装 适用于 Windows Mixed reality 应用的 OpenXR 开发人员工具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项目在 Visual Studio 中显示一个简单的 OpenXR 示例,其中包含 WIN32 和 UWP HoloLens 2 项目文件。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 桌面后。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 中的 BasicXrApp 示例的60分钟视频。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 + + 解决方案中。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. 切换到 " 浏览 " 选项卡并搜索 OpenXRSwitch 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 上混合现实 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 运行时并提供所有 扩展 ,请从目标设备或模拟器中启动 应用商店 应用,打开右上方的菜单,选择 " 下载和更新 ",然后选择 " 获取更新"。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. Windows Mixed Reality 应用的 OpenXR 开发人员工具 从 Microsoft Store 安装到目标设备上并运行它。Install the OpenXR Developer Tools for Windows Mixed Reality app from the Microsoft Store onto the target device and run it.
  3. 导航到 " 开发人员设置 " 选项卡,并启用 " 使用最新预览版 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. Windows Mixed Reality 应用开发人员设置选项卡的 OpenXR 开发人员工具OpenXR Developer Tools for Windows Mixed Reality app Developer Settings tab
  4. 确认 Windows Mixed Reality 的 OpenXR 开发人员工具的 "系统状态" 选项卡上显示的 运行时版本 与计划尝试的预览扩展所需的版本相匹配。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.
    "Windows Mixed Reality 应用系统状态" 选项卡的 OpenXR 开发人员工具OpenXR Developer Tools for Windows Mixed Reality app System Status tab

请参阅 混合现实 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.