OpenXR Tutorial

Jump to Platform/Graphics API Selection

This tutorial will teach you how to use the OpenXR API. OpenXR is an API managed by the Khronos Group which provides a cross-platform way for applications to interact with immersive devices. This includes virtual reality (VR) headsets, augmented reality (AR) devices, motion controllers and more.

An API is an application programming interface, a set of rules for how a software system can be interfaced-with by other systems. There is no specific library or code that is OpenXR, but rather there are multiple implementations (or runtimes), which might be provided by hardware manufacturers or by software companies; there are even open source runtimes for OpenXR. Whichever runtime you use, if it’s compliant with the OpenXR specification, your OpenXR-compliant code will work with it.

This tutorial introduces programming with OpenXR. If you use a game engine such as Unreal Engine, Unity or Godot, you may not need to interact directly with OpenXR: the engine abstracts this away. However, it may be beneficial to learn the underlying concepts.

OpenXR is designed to work with various different graphics APIs: Vulkan, Direct3D 11, Direct3D 12, OpenGL and OpenGL ES are all supported at present. You will need some familiarity with your graphics API of choice to get the most out of this tutorial.

Other prerequisites are:

• A Windows or Linux PC to compile the code.

• An IDE (integrated development environment) that supports your target device: either Visual Studio 2017 or later; or Android Studio.

• Some XR hardware to run on: either an XR device that connects to your PC, or an Android-based device like a Meta Quest or Pico Neo. It is also possible to use Monado to emulate XR hardware.

• CMake 3.22.1 is required.

• Python 3.6+ is required to build the OpenXR-SDK-Source repository. See OpenXR-SDK-Source/BUILDING.md.

Tutorial Structure

The tutorial is divided into several main chapters. Each chapter walks you through a part of the process of creating an XR application and assumes that the previous chapters have been completed.

Explanations of key concepts are given throughout the chapters to provide deeper insight into the workings of OpenXR. The code snippets can be copied directly into your project as you follow the tutorial, and explanations for the code are generally given after the code snippets.

At the end of each chapter there is a link to download the full example source code up to that point.

The full source code for this tutorial can also be downloaded from:

https://github.com/KhronosGroup/OpenXR-Tutorials.

• In the Introduction, we describe the basic concepts underpinning OpenXR, and show you how to set up a PC or Android development environment to build the code.

• In Setup, we show how to initialize OpenXR and connect your program to your XR device.

• In Graphics, we setup the swapchains and render graphics to the views.

• In Actions, we use OpenXR’s action system to bind input to application specific actions allowing the user to interact with the XR device.

• In Extensions, we demonstrate various extensions that you may find helpful.

To begin the tutorial, select the platform and graphics API you want to use:

	D3D11	D3D12	OpenGL or OpenGL ES	Vulkan
Android			Android, OpenGL ES	Android, Vulkan
Linux			Linux, OpenGL	Linux, Vulkan
Windows	Windows, D3D11	Windows, D3D12	Windows, OpenGL	Windows, Vulkan

• Android

  • Android, OpenGL ES

  • Android, Vulkan

• Linux

  • Linux, OpenGL

  • Linux, Vulkan

• Windows

  • Windows, D3D11

  • Windows, D3D12

  • Windows, OpenGL

  • Windows, Vulkan

At any time you can change platform/API by clicking the link at the top-right of the page.

Contents:

• 1 Introduction
  • 1.1 Goal of OpenXR
  • 1.2 Overview
  • 1.3 Environment Setup
  • 1.4 Project Setup
    • 1.4.1 CMake and Project Files
    • 1.4.2 Common Files
    • 1.4.3 Main.cpp and the OpenXRTutorial Class
    • 1.4.4 Build and Run
  • 1.5 Summary
• 2 OpenXR Setup
  • 2.1 Creating an Instance
    • 2.1.1 The OpenXR Instance
    • 2.1.2 XR_EXT_debug_utils
    • 2.1.3 Obtaining the System Id
  • 2.2 Creating a Session
    • 2.2.1 XrSession
  • 2.3 Polling the Event Loop
    • 2.3.1 xrPollEvent
    • 2.3.2 XrSessionState
    • 2.3.3 xrBeginSession and xrEndSession
  • 2.4 Summary
• 3 Graphics
  • 3.1 Creating Swapchains
    • 3.1.1 View Configurations
    • 3.1.2 Enumerate the Swapchain Formats
    • 3.1.3 Create the Swapchains
    • 3.1.4 Enumerate Swapchain Images
    • 3.1.5 Create the Swapchain Image Views
    • 3.1.6 Destroy the Swapchain
  • 3.2 Building a RenderLoop
    • 3.2.1 Environment Blend Modes
    • 3.2.2 Reference Spaces
    • 3.2.3 Rendering a Frame
    • 3.2.4 Rendering Layers
  • 3.3 Rendering Cuboids
  • 3.4 Summary
• 4 Interactions
  • 4.1 The OpenXR Interaction System
  • 4.2 Creating Actions and Action Sets
  • 4.3 Interaction Profiles and Bindings
    • 4.3.1 Bindings and Profiles
    • 4.3.2 Binding Interactions
    • Theory and Best Practices for Interaction Profiles
  • 4.4 Using Actions in the Application
  • 4.5 Rendering the Controller Position
  • 4.6 Checking for Connected Controllers
  • 4.7 Summary
• 5 Extensions
  • 5.1 Hand Tracking
  • 5.2 Composition Layer Depth
  • 5.3 Summary
• 6 Next Steps
  • 6.1 Multiview rendering
    • 6.1.1 CMake and Downloads
    • 6.1.2 Update Main.cpp
    • 6.1.3 GraphicsAPI and Multiview
  • 6.2 Graphics API
  • 6.3 OpenXR API Layers
  • 6.4 Color Science
  • 6.5 Multithreaded Rendering
  • 6.6 Conclusion

Version: v1.0.8