OpenXR Specification Documentation

This repository serves as the source for the formal OpenXR API documentation. It contains the OpenXR API Specification, the OpenXR header files (which are generated from the specification), and various related tools and scripts.

Note that the authoritative public repository for this project is located at https://github.com/KhronosGroup/OpenXR-Docs/, where you can track issues and submit patches via Pull Requests.

The XR_EXT_frame_synthesis extension allows applications to provide motion vector and depth images to the OpenXR runtime. The runtime uses this data to perform high-quality frame extrapolation and reprojection, synthesizing new frames to maintain a smooth experience even if the application's frame rate drops below the target.

This extension is independent of XR_KHR_composition_layer_depth and can be used alongside it. While XR_KHR_composition_layer_depth provides depth for composition, XR_EXT_frame_synthesis uses depth specifically for frame synthesis, and the resolution of the synthesis depth image may be lower than the composition depth image.

The OpenXR Style Guide defines the required procedures and conventions for writing specifications for new OpenXR APIs, extensions, layers, white papers, and tutorials. Following these rules ensures consistency across the API and all source/output documents.

Key Principles:

• Consistency: Mandatory for all changes or additions to the OpenXR specification.
• Precedence: If a contradiction is found between this style guide and the OpenXR specification itself, the specification takes precedence.
• Compliance: Changes to these procedures must be made through the normal OpenXR Working Group process.

Terminology: Key words such as must, required, should, recommend, may, and optional are interpreted according to RFC 2119.

The XR_KHR_opengl_enable extension allows OpenXR applications to use the OpenGL graphics API. This is necessary to use OpenGL swapchain images and to create an OpenGL-based XrSession.

To use this extension, you must define XR_USE_GRAPHICS_API_OPENGL and an appropriate window system define before including openxr_platform.h in all parts of your application that interact with this extension's types and functions.

Supported window system defines:

• XR_USE_PLATFORM_WIN32
• XR_USE_PLATFORM_XLIB
• XR_USE_PLATFORM_XCB
• XR_USE_PLATFORM_WAYLAND (deprecated)

The XR_EXT_debug_utils extension provides tools to obtain more detailed information about OpenXR usage, especially when combined with validation layers. It allows developers to:

• Create a debug messenger to pass debug messages to an application-supplied callback.
• Associate user-defined names with OpenXR handles to improve error message readability.
• Use session labels (regions and individual labels) to provide context (like a call-stack of labels) within debug messages.

The XR_FB_triangle_mesh extension allows OpenXR applications to create and manage triangle meshes to represent environment surfaces or real-world objects. It supports both immutable meshes (created once with fixed data) and mutable meshes (which can be updated over time).

Key Capabilities:

• Create a triangle mesh with vertex and index buffers.
• Specify triangle winding order (XrWindingOrderFB).
• Update mesh topology (vertices and indices) or just vertex positions for mutable meshes.

The XR_HTCX_vive_tracker_interaction extension provides an interaction profile for HTC VIVE Trackers. It allows applications to enumerate connected trackers, receive notifications when trackers are connected or change roles, and interact with specific trackers using role-based paths.

Key Capabilities:

• Enumerate all currently connected VIVE trackers.
• Receive notifications (XR_TYPE_EVENT_DATA_VIVE_TRACKER_CONNECTED_HTCX) when a tracker is connected or its role changes.
• Use role-based paths (e.g., /user/vive_tracker_htcx/role/chest) as subaction paths for actions or action spaces to target specific trackers.

The XR_ANDROID_geospatial_anchor extension provides two types of Earth-relative anchors:

1. Geospatial Anchors: Anchors positioned in space relative to the Earth using specific latitude, longitude, and altitude.
2. Surface Anchors: Anchors placed relative to a surface (like terrain or rooftops) using latitude, longitude, and altitude relative to that surface as identified by a Visual Positioning Service.

As the runtime's accuracy regarding its global position improves, the pose of these anchors will adjust automatically.

An XrInstance is an opaque handle that allows an OpenXR application to communicate with an OpenXR runtime. It serves as the primary container for OpenXR-related application state.

Key characteristics:

• Encapsulation: It stores and tracks application state without using the application's global address space, allowing for multiple instances within a single process.
• State Tracking: The OpenXR loader uses the instance to track the hierarchy of objects (e.g., an XrSession is a child of an XrInstance). This allows many API functions to infer the correct instance/runtime without requiring the developer to pass an XrInstance handle explicitly in every call.
• Lifecycle: An instance is created via xrCreateInstance and must be destroyed via xrDestroyInstance.

In OpenXR, mechanisms like runtime extensions or API layers may return lists of object handles. To distinguish between different types of handles (e.g., distinguishing an XrInstance from an XrSession), the XrObjectType enumeration is used. This allows developers to associate debug information or perform type-specific logic based on the returned handle type.

/* Relationship between XrObjectType and OpenXR Handle Types */
// XR_OBJECT_TYPE_INSTANCE -> XrInstance
// XR_OBJECT_TYPE_SESSION   -> XrSession
// XR_OBJECT_TYPE_SWAPCHAIN -> XrSwapchain
// XR_OBJECT_TYPE_SPACE     -> XrSpace
// XR_OBJECT_TYPE_ACTION_SET -> XrActionSet
// XR_OBJECT_TYPE_ACTION    -> XrAction