OpenXR-MixedReality/README.md

OpenXR Samples for Mixed Reality Developers

This repository contains OpenXR code samples tailored for developers who are familiar with and using the Visual Studio toolchain, e.g. HoloLens 2 developers.

These OpenXR samples use C++17 and D3D11. The same source code works across UWP applications running on HoloLens 2 and Win32 applications running on Windows Desktop with Windows Mixed Reality immersive headsets.

Prepare, build and run the samples

• Understand what is OpenXR and why OpenXR. Read the latest OpenXR 1.0 spec (HTML) and the latest openxr.h header file (Khronos GitHub).

• Update to Windows 10 May 2019 Update (1903) or later and Visual Studio 2017 or 2019. If you will be deploying to a HoloLens 2, you should install Visual Studio 2019 16.2 or later.

• Prepare a HoloLens 2 device or Windows Mixed Reality device.

• Clone the samples repo: git clone https://github.com/microsoft/OpenXR-MixedReality.git

• Open the BasicXrApp.sln or Samples.sln file in Visual Studio. F5 to build and run the sample. You typically choose ARM64 platform when running on HoloLens 2 devices, or choose x64 platform when running on a Windows Desktop PC with the HoloLens 2 Emulator or a Windows Mixed Reality immersive headset (or simulator).

OpenXR preview extensions

The openxr_preview folder contains an additional openxr_msft_preview.h header to offer the following OpenXR extensions that are only available in preview runtime.

1. XR_EXT_user_presence
2. XR_MSFT_scene_marker

Please send feedback on preview extensions and samples at GitHub issues. We are planning to incorporate your feedback and finalize these extensions as vendor extensions (MSFT) or cross-vendor extensions (EXT) in the central Khronos OpenXR headers and spec over the coming months.

OpenXR samples and extension usages

• The core OpenXR API usage patterns
  can be found in the BasicXrApp/OpenXRProgram.cpp file. The Run() function captures a typical OpenXR app code flow for session initialization, event handling, the frame loop and input actions.

• Hand tracking
  The Scene_HandTracking.cpp demos the usage of XR_EXT_hand_tracking and XR_MSFT_hand_tracking_mesh extensions.

• Eye tracking
  The Scene_EyeGazeInteraction.cpp file demos the usage of XR_EXT_eye_gaze_interaction extension.

• Mixed reality capture support
  Search "secondary" in XrApp.cpp file to understand the usage of XR_MSFT_secondary_view_configuration and XR_MSFT_first_person_observer extensions.

• Render the motion controller model
  The ControllerObject.cpp and Scene_ControllerModel.cpp files demos the usage of XR_MSFT_controller_model extension.

• Holographic window attachment
  The SampleSceneUwp/Main.cpp file demos protocol activation for XR apps, and using XR_MSFT_holographic_window_attachment extension to interop with CoreWindow in order to support keyboard inputs and TextEditingContext.

• Understand the local, unbounded and anchor spaces
  The ThreeSpacesUwp project demos the usage and differences of LOCAL, UNBOUNDED reference spaces and spatial anchors.

• The sample code for XR_MSFT_spatial_graph_bridge is coming soon ...

OpenXR app best practices for HoloLens 2

The BasicXrApp demonstrates the best practices for an OpenXR app to achieve full frame rate and low latency.

For more detailed information on getting the best visual quality and performance on HoloLens 2, see the best practices for HoloLens 2.

Contributing

This project welcomes contributions and suggestions. Most contributions require you to agree to a Contributor License Agreement (CLA) declaring that you have the right to, and actually do, grant us the rights to use your contribution. For details, visit https://cla.microsoft.com.

When you submit a pull request, a CLA-bot will automatically determine whether you need to provide a CLA and decorate the PR appropriately (e.g., label, comment). Simply follow the instructions provided by the bot. You will only need to do this once across all repos using our CLA.

This project has adopted the Microsoft Open Source Code of Conduct. For more information see the Code of Conduct FAQ or contact opencode@microsoft.com with any additional questions or comments.