OpenXR is an open, royalty-free standard developed by Khronos that aims to simplify AR/VR development by allowing developers to seamlessly target a wide range of AR/VR devices.
Unity works closely with strategic partners to make sure that creators have all the support they need when developing content for Unity's supported platforms. This involves deep platform integration, Unity engine improvements, and XR tech stack optimizations for each platform. As of 2019.3, Unity officially supports these platforms for XR: ARKit. OpenXR is an open, royalty-free standard for access to virtual reality and augmented reality platforms and devices. It is developed by a working group managed by the Khronos Group consortium. Varjo has been an active contributing member in OpenXR standardization. Varjo headsets have preliminary support for OpenXR, so that you can use your OpenXR applications with Varjo headsets.
Requirements
This version of OpenXR is compatible with the following versions of the Unity Editor:
- OpenXR Hand Tracking in Unity. Pete Nancollis, Senior Software Engineer. In December 2020 Unity announced that support for OpenXR would be added to Unity 2020.2 as a preview feature. This really opens up the space for developers and consumers as hand tracked applications can be made without being tied to one platform.
- The Mixed Reality OpenXR Plugin supplies basic anchor functionality through an implementation of Unity's ARFoundation ARAnchorManager. To learn the basics on ARAnchors in ARFoundation, visit the ARFoundation Manual for AR Anchor Manager.
- 2020.2+
Supported platforms
Unity's OpenXR plug-in should work with any device that supports conformant PC-based OpenXR runtimes. The following platforms have been fully tested and are officially supported:
| Platform | Build target | Graphics API | Rendering mode |
|---|---|---|---|
| Windows Mixed Reality | Windows | DX11 | Single Pass Instanced |
| HoloLens 2 | UWP | DX11 | Single Pass Instanced |
At this time, deploying directly to Oculus Quest/Quest 2 is not supported.
Unity plans to expand the number of supported platforms in the future as more of our platform partners adopt the OpenXR standard. However, given the unbounded combinations of possible hardware/software configurations, Unity is unable to test or guarantee that all configurations will work optimally. To help the community as a whole, Unity will continue to submit any runtime issues, and contribute conformance tests and specification changes to the Khronos working group.
Getting started
To enable OpenXR in your project, follow the steps below:
- Install the OpenXR Plugin package from Package Manager.
- Open the Project Settings window (menu: Edit > Project Settings), and select XR Plug-in Management.
- Enable the OpenXR option and any Feature Sets for the runtimes you intend to target.
- In the OpenXR > Features tab, select the interaction profile of the device you are testing with.
- In the OpenXR tab, make sure the current active runtime is set to the hardware you are testing with. See the Per-platform setttings section on this page for more information.
Project validation
Unity raises errors and warnings at build time if your project is not compatible with OpenXR. Make sure that your project conforms to the following rules and standards:
The Color Space must be set to Linear in the Player settings (menu: Edit > Project Settings > Player, then select your platform and change this setting under Other Settings > Rendering). OpenXR does not support Gamma color space rendering in Unity.
You must select at least one interaction profile in the OpenXR tab. Unity's OpenXR plug-in includes several interaction profiles, and you can add more from the Features tab. For more information on interaction profiles, see the OpenXR input page.
Features might introduce new validation steps. For more information, refer to specific feature documentation. Unity does not write or maintain documentation for third-party features, nor does Unity guarantee that any third-party documentation is correct or complete.
Unity reports validation issues in the following locations:
- XR Plug-in Management window: Icon next to the OpenXR loader.
- Features pane: Icon next to the feature set containing the feature that is reporting a validation issue.
- Features pane: Icon next to each feature that is reporting a validation issue.
- Console window, as the result of a build: Validation errors cause the build to terminate. Validation warnings do not terminate the build.
Validation issues reported in XR Plug-in Management
Clicking on either the validation warning or the error icon brings up the Validation window.
Validation issues reported in features pane
Clicking on either the validation warning or the error icon brings up the Validation window.
Validation issues reported in build
Double-clicking on build warnings or errors from validation brings up the Validation window.
Troubleshooting
If you experience an issue, please file a bug. When you do, please also check the log file to see if Unity supports the combination of OpenXR runtimes and features you are using. The log file will provide additional guidance.
Unity generates a diagnostic log in either the Player or Editor log, depending on where you run the application. The diagnostic log starts with Start Unity OpenXR Diagnostic Report and ends with End Unity OpenXR Diagnostic Report log entries. It contains information about your application, Unity version, OpenXR runtime, OpenXR Extensions, and other aspects that can help diagnose issues.
The most important part of the diagnostic log is the section marked OpenXR Support Details . This section provides some simple information on what parts of your application Unity supports, what it might not support, and what to do before submitting an issue or requesting assistance.
Examples
Diagnostic log OpenXR Support Details section when running with Unity supported items
Diagnostic log OpenXR Support Details section when running with items not supported by Unity
Known issues
- Deploying directly to Oculus Quest/Quest 2 will be released at a later date.
- A black box appears in upper-right quadrant when running in Oculus desktop. An updated Oculus runtime will be released which fixes this. In the meantime, you can turn off occlusion mesh for the built-in renderer.
- Eye Tracking Interaction device layout does not appear in the Unity Input System menus.
- Haptics is currently not supported. It will be added in a later version of the OpenXR plug-in.
- An issue with an invalid stage space during startup may cause problems with the XR Rig component from the
com.unity.xr.interaction.toolkitpackage, or the camera offset component in thecom.unity.xr.legacyinputhelperspackage. These packages will be updated shortly to contain fixes for this issue. Until then the workaround is to use theFloorDevice Tracking Option setting.
Upgrading a project to use OpenXR
OpenXR is a plug-in in Unity's XR plug-in architecture. Unity recommends using the XR Interaction Toolkit for input and interactions. If you are using any platform-vendor specific toolkits, please see the platform-vendor specific documentation on how to integrate those toolkits with OpenXR. Vendors are still in the process of adding OpenXR support to their toolkits; please make sure you check supported status before enabling OpenXR in your project.
The core steps to upgrade a project to use OpenXR are the setup instructions at the top. In addition, you might need to do some of the following:
- Update to the latest supported version of Unity before implementing OpenXR. Some APIs that your project relies on might have been changed or removed, and this will let you easily distinguish which changes are a result of the new Unity version and which come from OpenXR.
- Disable XR SDK plug-ins that are also supported by OpenXR. There is a good chance that OpenXR supports your target device, so enabling a competing XR SDK plug-in may cause unexpected behavior. In Project Settings > XR Plug-in Management, uncheck the plug-in provider(s) for your target device(s).
- Update your input code if your project doesn't use the new Input System. For more information, see the Quick start guide in the Input System package documentation.
- Change quality settings. It is possible that switching over to the OpenXR provider will affect your application's visual quality. You can adjust the quality settings of your project (menu: Edit > Project Settings > Player, then select the Quality tab) to try getting your old visuals back.
OpenXR concepts
Understanding OpenXR's action-based input
See OpenXR Input Documentation.
Generic OpenXR Settings
Settings supported on all platforms
The following settings are general across all platforms in OpenXR:
Render Mode - Sets the requested render mode for a given platform. You can choose from the following:
| Option | Description |
|---|---|
| Multi Pass | When rendering, the engine will do a complete render pass (culling and rendering) for each eye. |
| Single Pass Instanced | When rendering, the engine will do simultaneous renders to each eye using shared culling and a single render pass. |
Depth Submission Mode - Sets the requested depth submission mode for a given platform. You can choose from the following:
| Option | Description |
|---|---|
| None | No depth submission support. No depth based stability or re-projection support that the platform my provide will be available. |
| Depth 16 bit | A shared depth buffer using 16 bits per pixel will be used. |
| Depth 24 bit | A shared depth buffer using 24 bits per pixel will be used. |
Per-platform settings
Standalone:
Active OpenXR Runtime - Sets the OpenXR runtime to be used when running your app in Play mode. This setting is only active for the current running instance of the Editor that you are using. You can choose from the following:
| Option | Description |
|---|---|
| System Default | The currently set OpenXR runtime. |
| Windows Mixed Reality | If available, sets the current OpenXR runtime to the Microsoft OpenXR runtime for Windows Mixed Reality. |
| SteamVR | If available, sets the current OpenXR runtime to the SteamVR OpenXR runtime. |
| Oculus | If available, sets the current OpenXR runtime to the Oculus OpenXR runtime. |
| Other | Allows you to navigate to and select the json file for a specific runtime. Useful when you want to use an OpenXR runtime that Unity might not directly support or detect automatically. |
OpenXR features
Features allow third parties to extend Unity's base support for OpenXR. They bring the functionality of OpenXR spec extensions to the Unity ecosystem, but Unity is not involved in their development.
Features might integrate into the Unity XR Plug-in framework to provide data to other XR subsystems (for example, providing meshing or plane data for AR use cases which are not yet standardized in OpenXR 1.0).
Features are a collection of Unity Assets that can be distributed through the Package Manager, Asset Store, or any other mechanism.
Feature selection and configuration
You can enable, disable, and configure features from the Features tab in the XR Plug-in Management > OpenXR window. The window has two main sections: Feature Sets in the left pane, and Features that a feature set supports in the right pane. Microsoft editor for word.
Feature sets are a grouping of features that a provider defines. Use them to easily select and group a number of features. Selecting a feature set in the left pane filters the set of features on the right to only the features that the set contains. You can then enable or disable these features individually.
The right pane provides the following information for each feature:
- Name
- Category, which can be one of the following:
- Feature - Category for general features.
- Interaction - Category for features that provide specific support for input or other interaction devices.
- Author, which can be a person, team, or company
- Version
- Settings - If the feature has any custom settings, you can configure these here.
OpenXR core features
General features
- Mock Runtime (Note: Enabling this will take over whatever current OpenXR runtime you might be using.)
- Eye Tracking Support
Interaction profile features
- Microsoft Hand Interaction Support
- HTC Vive Controller Support
- Khronos Simple Controller Support
- Microsoft Motion Controller Support
- Oculus Touch Controller Support
- Valve Index Controller Support
Unity plans to expand the number of supported platforms in the future as more of our platform partners adopt the OpenXR standard. However, given the unbounded combinations of possible hardware/software configurations, Unity is unable to test or guarantee that all configurations will work optimally. To help the community as a whole, Unity will continue to submit any runtime issues, and contribute conformance tests and specification changes to the Khronos working group.
Getting started
To enable OpenXR in your project, follow the steps below:
- Install the OpenXR Plugin package from Package Manager.
- Open the Project Settings window (menu: Edit > Project Settings), and select XR Plug-in Management.
- Enable the OpenXR option and any Feature Sets for the runtimes you intend to target.
- In the OpenXR > Features tab, select the interaction profile of the device you are testing with.
- In the OpenXR tab, make sure the current active runtime is set to the hardware you are testing with. See the Per-platform setttings section on this page for more information.
Project validation
Unity raises errors and warnings at build time if your project is not compatible with OpenXR. Make sure that your project conforms to the following rules and standards:
The Color Space must be set to Linear in the Player settings (menu: Edit > Project Settings > Player, then select your platform and change this setting under Other Settings > Rendering). OpenXR does not support Gamma color space rendering in Unity.
You must select at least one interaction profile in the OpenXR tab. Unity's OpenXR plug-in includes several interaction profiles, and you can add more from the Features tab. For more information on interaction profiles, see the OpenXR input page.
Features might introduce new validation steps. For more information, refer to specific feature documentation. Unity does not write or maintain documentation for third-party features, nor does Unity guarantee that any third-party documentation is correct or complete.
Unity reports validation issues in the following locations:
- XR Plug-in Management window: Icon next to the OpenXR loader.
- Features pane: Icon next to the feature set containing the feature that is reporting a validation issue.
- Features pane: Icon next to each feature that is reporting a validation issue.
- Console window, as the result of a build: Validation errors cause the build to terminate. Validation warnings do not terminate the build.
Validation issues reported in XR Plug-in Management
Clicking on either the validation warning or the error icon brings up the Validation window.
Validation issues reported in features pane
Clicking on either the validation warning or the error icon brings up the Validation window.
Validation issues reported in build
Double-clicking on build warnings or errors from validation brings up the Validation window.
Troubleshooting
If you experience an issue, please file a bug. When you do, please also check the log file to see if Unity supports the combination of OpenXR runtimes and features you are using. The log file will provide additional guidance.
Unity generates a diagnostic log in either the Player or Editor log, depending on where you run the application. The diagnostic log starts with Start Unity OpenXR Diagnostic Report and ends with End Unity OpenXR Diagnostic Report log entries. It contains information about your application, Unity version, OpenXR runtime, OpenXR Extensions, and other aspects that can help diagnose issues.
The most important part of the diagnostic log is the section marked OpenXR Support Details . This section provides some simple information on what parts of your application Unity supports, what it might not support, and what to do before submitting an issue or requesting assistance.
Examples
Diagnostic log OpenXR Support Details section when running with Unity supported items
Diagnostic log OpenXR Support Details section when running with items not supported by Unity
Known issues
- Deploying directly to Oculus Quest/Quest 2 will be released at a later date.
- A black box appears in upper-right quadrant when running in Oculus desktop. An updated Oculus runtime will be released which fixes this. In the meantime, you can turn off occlusion mesh for the built-in renderer.
- Eye Tracking Interaction device layout does not appear in the Unity Input System menus.
- Haptics is currently not supported. It will be added in a later version of the OpenXR plug-in.
- An issue with an invalid stage space during startup may cause problems with the XR Rig component from the
com.unity.xr.interaction.toolkitpackage, or the camera offset component in thecom.unity.xr.legacyinputhelperspackage. These packages will be updated shortly to contain fixes for this issue. Until then the workaround is to use theFloorDevice Tracking Option setting.
Upgrading a project to use OpenXR
OpenXR is a plug-in in Unity's XR plug-in architecture. Unity recommends using the XR Interaction Toolkit for input and interactions. If you are using any platform-vendor specific toolkits, please see the platform-vendor specific documentation on how to integrate those toolkits with OpenXR. Vendors are still in the process of adding OpenXR support to their toolkits; please make sure you check supported status before enabling OpenXR in your project.
The core steps to upgrade a project to use OpenXR are the setup instructions at the top. In addition, you might need to do some of the following:
- Update to the latest supported version of Unity before implementing OpenXR. Some APIs that your project relies on might have been changed or removed, and this will let you easily distinguish which changes are a result of the new Unity version and which come from OpenXR.
- Disable XR SDK plug-ins that are also supported by OpenXR. There is a good chance that OpenXR supports your target device, so enabling a competing XR SDK plug-in may cause unexpected behavior. In Project Settings > XR Plug-in Management, uncheck the plug-in provider(s) for your target device(s).
- Update your input code if your project doesn't use the new Input System. For more information, see the Quick start guide in the Input System package documentation.
- Change quality settings. It is possible that switching over to the OpenXR provider will affect your application's visual quality. You can adjust the quality settings of your project (menu: Edit > Project Settings > Player, then select the Quality tab) to try getting your old visuals back.
OpenXR concepts
Understanding OpenXR's action-based input
See OpenXR Input Documentation.
Generic OpenXR Settings
Settings supported on all platforms
The following settings are general across all platforms in OpenXR:
Render Mode - Sets the requested render mode for a given platform. You can choose from the following:
| Option | Description |
|---|---|
| Multi Pass | When rendering, the engine will do a complete render pass (culling and rendering) for each eye. |
| Single Pass Instanced | When rendering, the engine will do simultaneous renders to each eye using shared culling and a single render pass. |
Depth Submission Mode - Sets the requested depth submission mode for a given platform. You can choose from the following:
| Option | Description |
|---|---|
| None | No depth submission support. No depth based stability or re-projection support that the platform my provide will be available. |
| Depth 16 bit | A shared depth buffer using 16 bits per pixel will be used. |
| Depth 24 bit | A shared depth buffer using 24 bits per pixel will be used. |
Per-platform settings
Standalone:
Active OpenXR Runtime - Sets the OpenXR runtime to be used when running your app in Play mode. This setting is only active for the current running instance of the Editor that you are using. You can choose from the following:
| Option | Description |
|---|---|
| System Default | The currently set OpenXR runtime. |
| Windows Mixed Reality | If available, sets the current OpenXR runtime to the Microsoft OpenXR runtime for Windows Mixed Reality. |
| SteamVR | If available, sets the current OpenXR runtime to the SteamVR OpenXR runtime. |
| Oculus | If available, sets the current OpenXR runtime to the Oculus OpenXR runtime. |
| Other | Allows you to navigate to and select the json file for a specific runtime. Useful when you want to use an OpenXR runtime that Unity might not directly support or detect automatically. |
OpenXR features
Features allow third parties to extend Unity's base support for OpenXR. They bring the functionality of OpenXR spec extensions to the Unity ecosystem, but Unity is not involved in their development.
Features might integrate into the Unity XR Plug-in framework to provide data to other XR subsystems (for example, providing meshing or plane data for AR use cases which are not yet standardized in OpenXR 1.0).
Features are a collection of Unity Assets that can be distributed through the Package Manager, Asset Store, or any other mechanism.
Feature selection and configuration
You can enable, disable, and configure features from the Features tab in the XR Plug-in Management > OpenXR window. The window has two main sections: Feature Sets in the left pane, and Features that a feature set supports in the right pane. Microsoft editor for word.
Feature sets are a grouping of features that a provider defines. Use them to easily select and group a number of features. Selecting a feature set in the left pane filters the set of features on the right to only the features that the set contains. You can then enable or disable these features individually.
The right pane provides the following information for each feature:
- Name
- Category, which can be one of the following:
- Feature - Category for general features.
- Interaction - Category for features that provide specific support for input or other interaction devices.
- Author, which can be a person, team, or company
- Version
- Settings - If the feature has any custom settings, you can configure these here.
OpenXR core features
General features
- Mock Runtime (Note: Enabling this will take over whatever current OpenXR runtime you might be using.)
- Eye Tracking Support
Interaction profile features
- Microsoft Hand Interaction Support
- HTC Vive Controller Support
- Khronos Simple Controller Support
- Microsoft Motion Controller Support
- Oculus Touch Controller Support
- Valve Index Controller Support
Accessing features at runtime via script
You can also access all the settings in the Features window through script. The scripting API documentation in this package provides information on all APIs you can use for feature support. The code samples below illustrate some of the common tasks.
Iterating over all features
Getting a specific feature by type
Iterating over all feature sets
Openxr Unity
Feature sets are an Editor-only concept and as such can only be accessed in the Unity Editor.
Iterating over features in a feature set
Feature sets are an Editor-only concept and as such can only be accessed in the Unity Editor.
Openxr Input Unity
Implementing a feature
Openxr Oculus Quest 2
Anyone can add new features. To learn more, see documentation on how to add a feature to Unity's OpenXR support.
Openxr Unity Tutorial
References
