Khronos OpenXR Registry - The Khronos Group Inc (original) (raw)

The OpenXR™ registry contains formatted specifications of the OpenXR API, header files, API reference pages, the reference card, and related documentation. The registry also links to the GitHub repository where the sources for these documents can be found.

For general information on OpenXR, including information on implementations, developer resources, and more, see the OpenXR homepage.

Index to the OpenXR Registry page content:

• OpenXR 1.1 API Specifications (also applies to 1.0 development)
• OpenXR 1.0 Reference Guide
• OpenXR API Reference Pages
• OpenXR Loader Design Document
• OpenXR™ Documentation and Extensions: Procedures and Conventions
• OpenXR™ Working Group Extension Processes
• OpenXR™ Conformance Test Suite Usage Instructions and Developer Guide
• Changelogs for the OpenXR API Specifications, SDK, and CTS
• OpenXR GitHub Repositories
  • API and Extension Specification Repository
    * Header Files
    * API Registry
  • Loader and Validation Layers Repositories
    * KhronosGroup/OpenXR-SDK
    * KhronosGroup/OpenXR-SDK-Source
  • KhronosGroup/OpenXR-CTS Conformance Test Suite Repository
  • Other Repositories
• Obsolete: OpenXR 1.0.34 API Specifications
• Obsolete: OpenXR 0.90 Provisional Specification
• Providing Feedback on the Registry

OpenXR 1.1 API Specifications

We currently publish the OpenXR API Specification in PDF and HTML forms. There are several versions of the OpenXR 1.1 Specification, as well as related Specifications and collateral material:

• OpenXR 1.1 API + all published Extensions (Single-file HTML) (PDF)
  This Specification includes Khronos-defined KHR extensions such as the graphics API interfaces used on different platforms and window systems, as well as all vendor-specific and multi-vendorEXT non-Khronos extensions that have been incorporated into the Specification Repository.
• OpenXR 1.1 API + Ratified Extensions (Single-file HTML) (PDF)
  This Specification includes ratified Khronos-defined KHR extensions such as the graphics API interfaces used on different platforms and window systems, as well as ratified multi-vendorEXT extensions.

OpenXR 1.0 Reference Guide

The OpenXR 1.0 Reference Guide (PDF) is a compact document summarizing the OpenXR 1.0 functions, structures, and enumerants, as well as providing an overview of the input system and a typical OpenXR application's flow. It remains applicable to OpenXR 1.1.

API Reference Pages

The OpenXR API Reference Pages describe how to use individual API and extension commands. The goal is to define all commands and structures in the core API and extensions, although there may be some omissions in non-KHR extensions.

• OpenXR 1.1 Reference Pages (Single-file HTML) (HTML, one file per reference page)

The reference pages are generated by automatic extraction from the Specification source, and are not separately checked into GitHub. The set of pages linked above are generated from the 1.1 API specification including all extensions.

OpenXR™ Loader Design Document

The OpenXR™ Loader Design Document describes the underlying design of the standard cross-platform loader, along with some platform-specific details. It also describes how runtimes interact with the loader and other software that may wish to enumerate or interact with OpenXR runtimes outside of or prior to the ratified specification.

OpenXR™ Documentation and Extensions: Procedures and Conventions

The OpenXR™ Documentation and Extensions: Procedures and Conventions document (colloquially, the “Style Guide”) defines mandatory and recommended conventions and best practices used in creating and modifying the API Specification and extensions. Authors wishing to write OpenXR extension specifications, or contribute to existing specifications, should familiarize themselves with and adhere to this document.

OpenXR™ Working Group Extension Processes

The OpenXR™ Working Group Extension Processes document is a concise definition of the processes followed to add or promote an extension within the OpenXR specification. It is meant to be read in conjunction with the Style Guide. Authors wishing to write OpenXR extension specifications must follow both this document as well as the Style Guide.

OpenXR™ Conformance Test Suite Usage Instructions and Developer Guide

• OpenXR-CTS Usage Guide in PDF format
• OpenXR-CTS Usage Guide in HTML format

The OpenXR-CTS Usage Guide provides instructions on the usage of the CTS as part of a conformance submission, as well as additional information on the design and usage of the test suite. For more information on conformance and the Adopter program, see the information on the OpenXR-CTS repo.

Note that this is updated at a different cadence than the other documents here: it is updated upon release of a new approved revision of the OpenXR-CTS, rather than upon release of a new version of the OpenXR spec.

Changelogs for the OpenXR API Specifications, SDK, and CTS

Changelogs are maintained for the Specification, SDK, and Conformance Test Suite (CTS). Some changelog items are shared between the Specification and SDK changelog documents, where applicable. Each repository contains the relevant changelog file. The links below go to a formatted view of each changelog where it is found on GitHub.

• Changelog for OpenXR Specifications - in OpenXR-Docs and OpenXR-Registry repos
• Changelog for OpenXR SDK - in OpenXR-SDK and OpenXR-SDK-Source repos
• Changelog for OpenXR CTS - in the OpenXR-CTS repo

OpenXR GitHub Repositories

API and Extension Specification Repository

The OpenXR-Docs repository contains the AsciiDoc source for the OpenXR API specification, and for registered OpenXR API extensions.

OpenXR-Docs also contains the generated header files, API Registryxr.xml, and scripts for spec building and verification.

For most developers, the header files provided with the generated loader source in the OpenXR-SDK GitHub repository is all that's needed.

However, all OpenXR headers provided by Khronos are ultimately obtained from the OpenXR-Docs repository. If you need to generate a customized version of the headers and/or loader, use the API Registry xr.xml inOpenXR-SDK-Source orOpenXR-Docs as required, together with the scripts in specification/scripts and/or src/scripts.

API Registry

OpenXR defines an API Registry for the API and extensions, formally defining function prototypes, structures, enumerants, and many other aspects of the API and extension mechanisms. The OpenXR Registry is the basis for generating the header files; AsciiDoc include files used in the Specification, and reference pages for interface definitions, parameter and member validity language, and synchronization language; and more.

The canonical location for the registry is the OpenXR-Docs repository in specification/registry/xr.xml, and that is where any changes should be submitted. "Read-only" copies, regularly synchronized, exist in the same relative path in:

• the OpenXR-SDK repository, for optional, custom code generation by an application. None of the associated scripts are included in this repository, and all generated files are pre-generated, so changes to the XML here do not have any effect except on any custom scripts that might be written explicitly to consume the XML.
• the OpenXR-SDK-Source repository, for header generation, loader and API layer source generation, and loader documentation generation. Changes to the XML here affect all these generated files and libraries.
• the OpenXR-CTS repository, for header generation, loader (for CTS use) and API layer source generation, and conformance source generation. Changes to the XML here affect all these generated files and libraries.

Loader and Validation Layers Repositories

There are additional Khronos Github repositories containing OpenXR source code, libraries, and tools.

KhronosGroup/OpenXR-SDK

The OpenXR-SDK repository contains:

• all OpenXR header files (generated and static)
• source code and CMake build system for the OpenXR loader that is used for Linux, Windows, macOS, and Android
• all generated source files required to build the loader
• rendered HTML of the loader design doc (in doc/loader/)
• a copy of the XML registry, for optional custom code generation usage

Most application developers can use this repository, as it provides the header and loader with minimum dependencies, with no requirement for code generation at build time. It is designed for inclusion in your application's source tree, as the loader model for OpenXR on Windows is to bundle the loader (whether statically or dynamically linked) with your application, rather than installing system-wide.

This repository contains a subset of the OpenXR-SDK-Source repository (only the loader source), with the generated source code files pre-generated for easier usage. If you're looking for API layers, sample code, etc. see that repo.

KhronosGroup/OpenXR-SDK-Source

The OpenXR-SDK-Source repository contains:

• the static OpenXR header file openxr_platform_defines.h
• source code and CMake build system for
  • the OpenXR loader that is used for Linux, Windows, macOS, and Android
  • two "beta" API layers, XR_LUNARG_core_validation and XR_LUNARG_api_dump
  • the hello_xr sample application
  • tests for the loader
• a copy of the XML registry, for required code generation usage
• code generation scripts (in Python 3) required for the loader, API layers, and tests
• the loader design document source (in AsciiDoc) and the scripts required to build it

OpenXR-SDK-Source is where development of the loader takes place: changes are migrated toOpenXR-SDK regularly. Unlike that repo, it does not contain the generated headers or source: you need Python 3.6 or newer on your system to compile this repository.

Note: This repository was formerly known as OpenXR-SDK during the 0.90 time frame, and has been renamed to make room for the new, simpler OpenXR-SDK that contains only the loader and headers, and does not require any code generation.

KhronosGroup/OpenXR-CTS Conformance Test Suite Repository

The OpenXR-CTS repository contains the source code for the OpenXR Conformance Tests. See the OpenXR-CTS Usage Guide for instructions on using the test suite. Note that while the CTS source code is freely available, you must be a Khronos Adopter and pay the Adopter Fee in order to use the OpenXR trademark for your implementation. See theKhronos API Adopter Program page, as well as the formal Conformance Process Document, for more information.

Other Repositories

Other Khronos repositories containing OpenXR material include:

• The OpenXR-Hpp repository contains code used to generate openxr.hpp and its included headers, which form a layered C++ binding for OpenXR.

Obsolete: OpenXR 1.0.34 API Specifications

These are retained for your convenience, as the last pre-1.1 release, but are no longer updated. The OpenXR 1.1 specification includes all 1.0 content, and portions exclusive to 1.1 are noted in the text.

• OpenXR 1.0.34 API + all published Extensions (Single-file HTML) (PDF)
• OpenXR 1.0.34 API + Khronos-defined Extensions (Single-file HTML) (PDF)

Obsolete: OpenXR 0.90 Provisional API Specification Resources

These are provided for your convenience in porting to 1.0 only.All users of 0.90 should port to the final 1.0 as soon as possible.

• OpenXR 0.90 Provisional API + all published Extensions (Single-file HTML) (PDF)
• OpenXR 0.90 Reference Pages including all published Extensions(Single-file HTML) (HTML, one file per reference page)
• The OpenXR 0.90 API Overview (PDF) is a compact document providing an overview of the OpenXR 0.90 API, Input, and Haptics, and a typical OpenXR app's flow.

Providing Feedback on the Registry

Khronos welcomes comments and bug reports. To provide feedback on the OpenXR registry itself (such as reporting missing content, bad links, etc.), file an issue in the OpenXR-Registry GitHub project.

For the OpenXR Specification or other documentation and tools, file an Issue on the appropriate GitHub Repository.