OpenXR 1.0 Reference Guide Page 1
OpenXR™ is a cross-platform API that enables a continuum of real-and-virtual combined environments generated by computers through human-machine interaction and is inclusive of the technologies associated with virtual reality, augmented reality, and mixed reality. It is the interface between an application and an in-process or out-of-process XR runtime that may handle frame composition, peripheral management, and more. Color-coded names as follows: function names and structure names. [n.n.n] Indicates sections and text in the OpenXR 1.0 specification. Specification and additional resources at khronos.org/openxr £ Indicates content that pertains to an extension.
OpenXR API Overview A high level overview of a typical OpenXR application including the order of function calls, creation of objects, session state changes, and the rendering loop.
OpenXR Action System Concepts [11.1]
Create action and action spaces Set up interaction profile bindings Sync and get action states xrCreateActionSet xrSetInteractionProfileSuggestedBindings xrSyncActions name = "gameplay" /interaction_profiles/oculus/touch_controller session activeActionSets = { "gameplay", ...} xrCreateAction "teleport": /user/hand/right/input/a/click actionSet="gameplay" "teleport_ray": /user/hand/right/input/aim/pose xrGetActionStateBoolean("teleport_ray") name = “teleport” if (state.currentState) // button is pressed /interaction_profiles/htc/vive_controller type = XR_INPUT_ACTION_TYPE_BOOLEAN { actionSet="gameplay" "teleport": /user/hand/right/input/trackpad/click "teleport_ray": /user/hand/right/input/aim/pose xrLocateSpace (teleport_ray_space, name = "teleport_ray" stage_reference_space); type = XR_INPUT_ACTION_TYPE_POSE } xrCreateActionSpace xrAttachSessionActionSets action = "teleport_ray" session actionSets = { "gameplay", ... }
OpenXR separates application actions such as Interaction profiles identify a collection of buttons and Syncing actions selects the active action Move, Jump, and Teleport from the input Trigger, other input sources in a physical arrangement to allow set(s) to receive input, and updates the action Thumbstick, Button, etc. Actions are grouped into applications and runtimes to coordinate action-to-input states. Most input data is accessible with application-defined action sets that correspond mapping. Runtimes bind actions to input devices based on xrGetActionState* functions. Pose actions to usage context (menu, gameplay, etc.). This application-supplied suggested bindings and other runtime- for tracked objects use "action spaces" and simplifies support for different or future input specific sources. This permits developers to customize to xrLocateSpace instead, for use like reference devices and maximizes user accessibility. hardware they have tested, while making it possible to run spaces. on other hardware as supported by runtimes.
©2019 Khronos Group - Rev. 0719 www.khronos.org/openxr OpenXR 1.0 Reference Guide Page 2
OpenXR Fundamentals Buffer size parameters [2.11] XrResult return codes [2.8] Some functions refer to input/output buffers with parameters API commands return values of type XrResult. Negative values Traversing pointer chains [2.7.7] of the following form: are error codes, while non-negative (≥0) are success codes. typedef struct XrBaseInStructure { XrResult xrFunction(uint32_t elementCapacityInput, XrStructureType type; uint32_t* elementCountOutput, float* elements); Success codes const struct XrBaseInStructure* next; XR_SUCCESS XR_TIMEOUT_EXPIRED } XrBaseInStructure; Two-call idiom for buffer size parameters XR_SESSION_LOSS_PENDING XR_EVENT_UNAVAILABLE First call xrFunction() with a valid elementCountOutput pointer typedef struct XrBaseOutStructure { XR_SESSION_NOT_FOCUSED XR_FRAME_DISCARDED XrStructureType type; (always required), elements = NULL, and elementCapacityInput struct XrBaseOutStructure* next; = 0 to get the number of elements in the buffer; allocate XR_SPACE_BOUNDS_UNAVAILABLE } XrBaseOutStructure; sufficient space, then call xrFunction() again with the allocated buffer's parameters. Error codes XR_ERROR_X where X may be: Macros for version and header control Graphics API header control [Appendix] ACTION_TYPE_MISMATCH Compile Time Symbol API ACTIONSET_NOT_ATTACHED Version numbers [2.1, Appendix] XR_USE_GRAPHICS_API_OPENGL OpenGL ACTIONSETS_ALREADY_ATTACHED typedef uint64_t XrVersion; XR_USE_GRAPHICS_API_OPENGL_ES OpenGL ES ANDROID_THREAD_SETTINGS_FAILURE_KHR Version numbers are encoded in 64 bits as follows: ANDROID_THREAD_SETTINGS_ID_INVALID_KHR XR_USE_GRAPHICS_API_VULKAN Vulkan bits 63-48: bits 47-32: bits 31-0: API_LAYER_NOT_PRESENT Major version Minor version Patch version XR_USE_GRAPHICS_API_D3D11 Direct3D 11 API_VERSION_UNSUPPORTED XR_USE_GRAPHICS_API_D3D12 Direct3D 12 Version macros CALL_ORDER_INVALID #define XR_CURRENT_API_VERSION ENVIRONMENT_BLEND_MODE_UNSUPPORTED Window system header control [Appendix] XR_MAKE_VERSION(1, 0, 0) EXTENSION_NOT_PRESENT Compile Time Symbol Window System #define XR_MAKE_VERSION(major, minor, patch) FEATURE_UNSUPPORTED ((((major) & 0xffffULL) << 48) | XR_USE_PLATFORM_WIN32 Microsoft Windows FILE_ACCESS_ERROR (((minor) & 0xffffULL) << 32) | ((patch) & 0xffffffffULL)) XR_USE_PLATFORM_XLIB X Window System Xlib FILE_CONTENTS_INVALID #define XR_VERSION_MAJOR(version) XR_USE_PLATFORM_XCB X Window System Xcb FORM_FACTOR_UNAVAILABLE (uint16_t) (((uint64_t)(version) >> 48) & 0xffffULL) XR_USE_PLATFORM_WAYLAND Wayland FORM_FACTOR_UNSUPPORTED #define XR_VERSION_MINOR(version) XR_USE_PLATFORM_ANDROID Android Native FUNCTION_UNSUPPORTED (uint16_t) (((uint64_t)(version) >> 32) & 0xffffULL) GRAPHICS_DEVICE_INVALID #define XR_VERSION_PATCH(version) HANDLE_INVALID (uint32_t) ((uint64_t)(version) & 0xffffffffULL) Data types INDEX_OUT_OF_RANGE Color [2.14] INITIALIZATION_FAILED Color components are linear (e.g., not sRGB), not alpha- INSTANCE_LOST premultiplied, in the range 0.0..1.0. LAYER_INVALID Threading behavior [2.3] typedef struct XrColor4f { OpenXR functions generally support being called from multiple float r; float g; float b; float a; LAYER_LIMIT_EXCEEDED threads with a few exceptions: } XrColor4f; LIMIT_REACHED • The handle parameter and any child handles that will LOCALIZED_NAME_DUPLICATED be destroyed by a destroy function must be externally Coordinate system [2.15] synchronized. LOCALIZED_NAME_INVALID OpenXR uses a Cartesian right- • The instance parameter and any child handles in handed coordinate system with an NAME_DUPLICATED xrDestroyInstance x, y, and z axis. NAME_INVALID • The session parameter and any child handles in xrDestroySession Points and directions can be OUT_OF_MEMORY • The space parameter and any child handles in represented using the following PATH_COUNT_EXCEEDED xrDestroySpace struct types with the following PATH_FORMAT_INVALID members: • The swapchain parameter and any child handles in PATH_INVALID xrDestroySwapchain Members x, y for distance in meters or PATH_UNSUPPORTED • The actionSet parameter and any child handles in XrVector2f 2D direction xrDestroyActionSet Members x, y, z for distance in meters, POSE_INVALID • The action parameter and any child handles in XrVector3f or velocity or angular velocity REFERENCE_SPACE_UNSUPPORTED xrDestroyAction RUNTIME_FAILURE • Calls to xrWaitFrame for a given XrSession must be XrVector4f Members x, y, z, w for a 4D vector externally synchronized. construct SESSION_LOST Members x, y, z, w representing 3D SESSION_NOT_READY XrQuaternionf orientation as a unit quaternion XR_KHR_android_thread_settings[12.3] SESSION_NOT_RUNNING Members orientation as a unit £ If enabled, this extension allows the application to specify XrPosef SESSION_NOT_STOPPING the Android thread type. quaternion and position in meters SESSION_RUNNING XrResult xrSetAndroidApplicationThreadKHR( typedef struct XrVector2f { SIZE_INSUFFICIENT XrSession session, float x; XrAndroidThreadTypeKHR threadType, float y; SWAPCHAIN_FORMAT_UNSUPPORTED uint32_t threadId); } XrVector2f; SWAPCHAIN_RECT_INVALID threadType: XR_ANDROID_THREAD_TYPE_X_KHR typedef struct XrVector3f { SYSTEM_INVALID where X may be: float x; TIME_INVALID APPLICATION_MAIN, APPLICATION_WORKER, float y; VALIDATION_FAILURE RENDERER_MAIN, RENDERER_WORKER float z; } XrVector3f; VIEW_CONFIGURATION_TYPE_UNSUPPORTED typedef struct XrVector4f { £ XR_KHR_android_thread_settings Time float x; This extension enables the following additional error codes: float y; XR_ERROR_ANDROID_THREAD_SETTINGS_ID_INVALID_KHR float z; XrTime [2.12.1] XR_ERROR_ANDROID_THREAD_SETTINGS_FAILURE_KHR A 64-bit integer representing a time relative to a runtime- float w; dependent epoch. All simultaneous applications use the same } XrVector4f; epoch. typedef struct XrPosef { Convenience macros [2.8.3] XrQuaternionf orientation;; XrDuration [2.13] XrVector3f position; #define XR_SUCCEEDED(result) ((result) >= 0) A 64-bit signed integer representing a duration; the difference } XrPosef; XR_SUCCEEDED is true for non-negative codes. between two XrTime values. typedef struct XrQuaternionf { #define XR_FAILED(result) ((result) < 0) Special values: float x; XR_FAILED is true for negative codes. #define XR_NO_DURATION 0 float y; float z; #define XR_UNQUALIFIED_SUCCESS(result) ((result) == 0) #define XR_INFINITE_DURATION 0x7fffffffffffffffLL float w; XR_UNQUALIFIED_SUCCESS is true for 0 (XR_SUCCESS) only. } XrQuaternionf;
©2019 Khronos Group - Rev. 0719 www.khronos.org/openxr OpenXR 1.0 Reference Guide Page 3 Instance lifecycle Command function pointers [3.2] £ XR_KHR_android_create_instance [12.1] XrResult xrGetInstanceProcAddr(XrInstance instance, This extension enables the following: API layers and extensions [2.7, 4.1] const char* name, PFN_xrVoidFunction* function); typedef struct XrInstanceCreateInfoAndroidKHR { API layers are inserted between the application and the XrStructureType type; runtime to hook API calls for logging, debugging, validation, etc. Instance lifecycle [4.2] const void* next; Extensions can expose new features or modify the behavior of Call xrCreateInstance to get an XrInstance handle. The Instance void* applicationVM; existing functions. Both extensions and API layers are selected manages the interface between the application and the OpenXR void* applicationActivity; at XrInstance creation. To enable a layer, add its name to the runtime. } XrInstanceCreateInfoAndroidKHR; enabledApiLayerNames member of XrInstanceCreateInfo. To XrResult xrCreateInstance( enable an extension, add its name to the enabledExtensions Instance information [4.3] member of XrInstanceCreateInfo. const XrInstanceCreateInfo* createInfo, XrInstance* instance); XrResult xrGetInstanceProperties(XrInstance instance, XrResult xrEnumerateApiLayerProperties( XrInstanceProperties*instanceProperties ); uint32_t propertyCapacityInput, typedef struct XrInstanceCreateInfo { XrStructureType type; typedef struct XrInstanceProperties { uint32_t* propertyCountOutput, XrStructureType type; XrApiLayerProperties*properties ); const void* next; XrInstanceCreateFlags createFlags; void* next; typedef struct XrApiLayerProperties { XrApplicationInfo applicationInfo; XrVersion runtimeVersion; XrStructureType type; uint32_t enabledApiLayerCount; char runtimeName[XR_MAX_RUNTIME_NAME_SIZE]; void* next; const char* const* enabledApiLayerNames; } XrInstanceProperties; char layerName[XR_MAX_API_LAYER_NAME_SIZE]; uint32_t enabledExtensionCount; XrVersion specVersion; const char* const* enabledExtensionNames; XrEventDataInstanceLossPending [4.4.2] uint32_t layerVersion; } XrInstanceCreateInfo; Receiving this structure predicts a session loss at lossTime. The char description[ createFlags must be 0 application should call xrDestroyInstance and release instance XR_MAX_API_LAYER_DESCRIPTION_SIZE]; resources. } XrApiLayerProperties; typedef struct XrApplicationInfo { char applicationName[ typedef struct XrEventDataInstanceLossPending { XrResult xrEnumerateInstanceExtensionProperties( XR_MAX_APPLICATION_NAME_SIZE]; XrStructureType type; const char* layerName, uint32_t applicationVersion; const void* next; uint32_t propertyCapacityInput, char engineName[XR_MAX_ENGINE_NAME_SIZE]; XrTime lossTime; uint32_t* propertyCountOutput, uint32_t engineVersion; } XrEventDataInstanceLossPending; XrExtensionProperties* properties); XrVersion apiVersion; } XrApplicationInfo; typedef struct XrExtensionProperties { XrResult xrPollEvent(XrInstance instance, XrStructureType type; XrResult xrDestroyInstance(XrInstance instance); XrEventDataBuffer*eventData); void* next; char extensionName[ typedef struct XrEventDataBaseHeader { XR_MAX_EXTENSION_NAME_SIZE]; XrStructureType type; uint32_t extensionVersion; const void* next; } XrExtensionProperties; } XrEventDataBaseHeader; typedef struct XrEventDataEventsLost { XrStructureType type; Common types typedef struct XrRect2Di { const void* next; XrOffset2Di offset; uint32_t lostEventCount; Offsets, extents, and areas [2.16] XrExtent2Di extent; } XrEventDataEventsLost; Members indicate offset in meters if physical. } XrRect2Df; Type to string conversions [4.5] typedef struct XrOffset2Df { FOV angles [2.17] float x; XrResult xrResultToString(XrInstance instance, float y; Angles are in radians from -π/2 to π/2. XrResult value, } XrOffset2Df; typedef struct XrFovf { char buffer[XR_MAX_RESULT_STRING_SIZE]); float angleLeft; typedef struct XrOffset2Di { float angleRight; XrResult xrStructureTypeToString(XrInstance instance, int32_t x; float angleUp; XrStructureType value, int32_t y; float angleDown; char buffer[XR_MAX_STRUCTURE_NAME_SIZE]); } XrOffset2Di; } XrFovf;
Members specify a rectangular area in meters if physical. Boolean type [2.19] typedef struct XrExtent2Df { The only valid values are XR_TRUE or XR_FALSE. Semantic Paths and Path Tree float width; typedef uint32_t XrBool32; float height; Path names and XrPath [6.1, 6.2] } XrExtent2Df; Event polling [2.20.1] Path name strings must contain only lower case a-z, digits 0-9, hyphen, underscore, period, or forward slash. typedef struct XrExtent2Di { The application is expected to allocate an event queue of int32_t width; type XrEventDataBuffer and periodically call xrPollEvent. The XrPath is an atom that connects an application with a int32_t height; If the event queue overflows,xrPollEvent will return the single path, within the context of a single instance. As an } XrExtent2Di; XrEventDataEventsLost event XrPath is only shorthand for a well-formed path string, they have no explicit life cycle. Members specify a rectangular area in meters if physical. typedef struct XrEventDataBuffer { typedef struct XrRect2Df { XrStructureType type; Path to string conversion [6.2.1] XrOffset2Df offset; const void* next; XrExtent2Df extent; uint8_t varying[4000]; XrResult xrStringToPath(XrInstance instance, } XrRect2Df; } XrEventDataBuffer; const char* pathString, XrPath* path); XrResult xrPathToString(XrInstance instance, XrPath path, uint32_t bufferCapacityInput, uint32_t* bufferCountOutput, char* buffer); System typedef struct XrSystemProperties { XrStructureType type; Reserved paths [6.3.1] Getting the XrSystemID [5.1-2] void* next; XrSystemId systemId; /user/hand/left XrResult xrGetSystem(XrInstance instance, uint32_t vendorId; /user/hand/right const XrSystemGetInfo* getInfo, XrSystemId* systemId); char systemName[XR_MAX_SYSTEM_NAME_SIZE]; /user/head A return of XR_ERROR_FORM_FACTOR_UNAVAILABLE indicates XrSystemGraphicsProperties graphicsProperties; /user/gamepad the form factor is supported but temporarily unavailable; the XrSystemTrackingPropertiestrackingProperties ; application may retryxrGetSystem . } XrSystemProperties; /user/treadmill typedef struct XrSystemGetInfo { typedef struct XrSystemGraphicsProperties { Input/output subpaths [6.3.2-3] XrStructureType type; uint32_t maxSwapchainImageHeight; Input source paths are of the form: const void* next; uint32_t maxSwapchainImageWidth; XrFormFactor formFactor; uint32_t maxLayerCount; .../input/
©2019 Khronos Group - Rev. 0719 www.khronos.org/openxr OpenXR 1.0 Reference Guide Page 4 Spaces XrResult xrGetReferenceSpaceBoundsRect( Semantic Paths / Path Tree (continued) XrSession session, Standard values for identifier Working with spaces [7.3] XrReferenceSpaceType referenceSpaceType, XrExtent2Df* bounds); trackpad thumbstick joystick XrResult xrDestroySpace(XrSpace space); referenceSpaceType: trigger pedal throttle XrResult xrLocateSpace(XrSpace space, XR_REFERENCE_SPACE_TYPE_VIEW, XrSpace baseSpace, XrTime time, XR_REFERENCE_SPACE_TYPE_LOCAL, trackball thumbrest system XrSpaceLocation* location); XR_REFERENCE_SPACE_TYPE_STAGE shoulder squeeze wheel typedef struct XrSpaceLocation { An XrEventDataReferenceSpaceChangePending event is sent XrStructureType type; to the application when the origin (and possibly bounds) of a dpad_X where X may be: up, down, left, right void* next; reference space is changing: XrSpaceLocationFlags locationFlags; diamond_X where X may be: up, down, left, right XrPosef pose; typedef } XrSpaceLocation; struct XrEventDataReferenceSpaceChangePending { a, b, x, y, start, home, end, select XrStructureType type; locationFlags: A bitwise OR of zero or more of const void* next; volume_up, volume_down, mute_mic, play_pause, menu XR_SPACE_LOCATION_ORIENTATION_VALID_BIT, XrSession session; XR_SPACE_LOCATION_POSITION_VALID_BIT, XrReferenceSpaceType referenceSpaceType; Standard pose identifiers XR_SPACE_LOCATION_ORIENTATION_TRACKED_BIT, XrTime changeTime; XR_SPACE_LOCATION_POSITION_TRACKED_BIT grip aim XrBool32 poseValid; XrSpaceVelocity may be passed in using the next chain of XrPosef poseInPreviousSpace; Standard locations XrSpaceLocation to determine the velocity. } XrEventDataReferenceSpaceChangePending; left left_upper left_lower upper typedef struct XrSpaceVelocity { Action spaces [7.2] right right_upper right_lower lower XrStructureType type; An XrSpace handle for a pose action is created using void* next; xrCreateActionSpace, by specifying the chosen pose action XrSpaceVelocityFlags velocityFlags; Standard components and an optional transform from its natural origin. Examples of XrVector3f linearVelocity; well-known pose action paths: click force twist x, y XrVector3f angularVelocity; } XrSpaceVelocity; /user/hand/left/input/grip touch value pose velocityFlags: A bitwise OR of zero or more of /user/hand/left/input/aim XR_SPACE_VELOCITY_LINEAR_VALID_BIT, /user/hand/right/input/grip Standard output identifier XR_SPACE_VELOCITY_ANGULAR_VALID_BIT /user/hand/right/input/aim haptic Reference spaces [7.1] XrResult xrCreateActionSpace(XrSession session, Interaction profile paths[6.4] XrResult xrEnumerateReferenceSpaces( const XrActionSpaceCreateInfo* createInfo, XrSpace* space); An interaction profile identifies a collection of buttons and XrSession session, uint32_t spaceCapacityInput, other input sources, and is of the form: uint32_t* spaceCountOutput, typedef struct XrActionSpaceCreateInfo { /interaction_profiles/
©2019 Khronos Group - Rev. 0719 www.khronos.org/openxr OpenXR 1.0 Reference Guide Page 5 Rendering (continued) typedef struct XrViewState { XrResult xrEndFrame(XrSession session, XrStructureType type; const XrFrameEndInfo* frameEndInfo); void* next; £ [12.2] XR_KHR_android_surface_swapchain typedef struct XrFrameEndInfo { This extension enables the Android swapchain function: XrViewStateFlags viewStateFlags; } XrViewState; XrStructureType type; XrResult xrCreateSwapchainAndroidSurfaceKHR( const void* next; viewStateFlags: A bitwise OR of zero or more of XrTime displayTime; XrSession session, const XrSwapchainCreateInfo* info, XR_VIEW_STATE_X_BIT where X may be: XrSwapchain* swapchain, jobject* surface); XrEnvironmentBlendMode environmentBlendMode; ORIENTATION_VALID, uint32_t layerCount; POSITION_VALID, ORIENTATION_TRACKED, [12.18] XR_KHR_vulkan_swapchain_format_list const XrCompositionLayerBaseHeader* const* layers; £ POSITION_TRACKED Enables the Vulkan VK_KHR_image_format_list extension. } XrFrameEndInfo; layers: A pointer to an array of Projection and/or Quad Frame Waiting [10.4] £ typedef struct XrVulkanSwapchainFormatListCreateInfoKHR { types, or optionally: XrStructureType type; XrResult xrWaitFrame(XrSession session, const void* next; [12.5] If XR_KHR_composition_layer_cube is enabled, then const XrFrameWaitInfo* frameWaitInfo, struct XrCompositionLayerCubeKHR can be used. uint32_t viewFormatCount; XrFrameState* frameState); const VkFormat* viewFormats; [12.6] If XR_KHR_composition_layer_cylinder is enabled, } XrVulkanSwapchainFormatListCreateInfoKHR; typedef struct XrFrameWaitInfo { then struct XrCompositionLayerCylinderKHR can be used. XrStructureType type; [12.8] If XR_KHR_composition_layer_equirect is enabled, View and Projection State [10.2] const void* next; then struct XrCompositionLayerEquirectKHR can be used. XrResult xrLocateViews(XrSession session, } XrFrameWaitInfo; const XrViewLocateInfo* viewLocateInfo, Environment Blend Mode [10.5.7] XrViewState* viewState, uint32_t viewCapacityInput, typedef struct XrFrameState { XrResult xrEnumerateEnvironmentBlendModes( uint32_t* viewCountOutput, XrView* views); XrStructureType type; void* next; XrInstance instance, XrSystemId systemId, typedef struct XrViewLocateInfo { XrTime predictedDisplayTime; XrViewConfigurationType viewConfigurationType, XrStructureType type; XrDuration predictedDisplayPeriod; uint32_t environmentBlendModeCapacityInput, const void* next; XrBool32 shouldRender; uint32_t* environmentBlendModeCountOutput, XrViewConfigurationType viewConfigurationType; } XrFrameState; XrEnvironmentBlendMode* environmentBlendModes); XrTime displayTime; Populates an array of XrEnvironmentBlendMode values: XrSpace space Frame Submission [10.5] XR_ENVIRONMENT_BLEND_MODE_X where X may be: } XrViewLocateInfo; XrResult xrBeginFrame(XrSession session, OPAQUE, ADDITIVE, ALPHA_BLEND typedef struct XrView { const XrFrameBeginInfo* frameBeginInfo); XrStructureType type; void* next; typedef struct XrFrameBeginInfo { XrPosef pose; XrStructureType type; XrFovf fov; const void* next; } XrView; } XrFrameBeginInfo;
OpenXR session life cycle [9.3] An XrSession proceeds through a number of states based on application requests, runtime operations, and user actions. The following diagram shows the session state machine. The state boxes are labeled with a name that is associated with an XrSessionState value.
Notes
©2019 Khronos Group - Rev. 0719 www.khronos.org/openxr OpenXR 1.0 Reference Guide Page 6
Session [9] £ [12.13] Enabled with XR_KHR_vulkan_enable Session Control [9.2] XrResult xrGetVulkanGraphicsRequirementsKHR( XrResult xrBeginSession(XrSession session, Session lifecycle [9.1] XrInstance instance, XrSystemId systemId, const XrSessionBeginInfo* beginInfo); XrResult xrCreateSession(XrInstance instance, XrGraphicsRequirementsVulkanKHR* graphicsRequirements); typedef struct XrSessionBeginInfo { const XrSessionCreateInfo* createInfo, XrStructureType type; XrSession* session); typedef struct XrGraphicsRequirementsVulkanKHR { const void* next; typedef struct XrSessionCreateInfo { XrStructureType type; XrViewConfigurationType primaryViewConfigurationType; XrStructureType type; void* next; } XrSessionBeginInfo; XrVersion minApiVersionSupported; const void* next; XrResult xrEndSession(XrSession session); XrSessionCreateFlags createFlags; XrVersion maxApiVersionSupported; XrSystemId systemId; } XrGraphicsRequirementsVulkanKHR; XrResult xrRequestExitSession(XrSession session); } XrSessionCreateInfo; typedef struct XrSwapchainImageVulkanKHR { createFlags must be 0 XrStructureType type; Session States [9.3] void* next; typedef struct XrEventDataSessionStateChanged { £ next: A pointer to an instance of XrGraphicsBindingX XrStructureType type; where may be: D3D12KHR, D3D11KHR, VkImage image; X } XrSwapchainImageVulkanKHR; const void* next; OpenGLESAndroidKHR, OpenGLWaylandKHR, XrSession session; XrSessionState state; OpenGLXcbKHR, OpenGLXlibKHR, typedef struct XrGraphicsBindingVulkanKHR { XrTime time; OpenGLWin32KHR, VulkanKHR XrStructureType type; } XrEventDataSessionStateChanged; const void* next; Using Graphics APIs in runtimes VkInstance instance; state: XR_SESSION_STATE_X where X may be: UNKNOWN, IDLE, READY, SYNCHRONIZED, VISIBLE, FOCUSED, Use extensions to enable access to OpenGL, OpenGL ES, Vulkan, VkPhysicalDevice physicalDevice; and Direct3D 11 and 12 graphics APIs. The extended functions VkDevice device; STOPPING, LOSS_PENDING, EXITING for using Vulkan are shown below. For others, see Extensions on uint32_t queueFamilyIndex; page 7 of this reference guide. uint32_t queueIndex; } XrGraphicsBindingVulkanKHR;
Compositing £ XR_KHR_composition_layer_cylinder[12.6] Input and Haptics: Actions This extension adds an additional layer type where the XR Actions are created at initialization time and later used to Compositing [10.5] runtime must map a texture stemming from a swapchain onto request input device state, create action spaces, or control Composition layers are submitted by the application via the the inside of a cylinder section. It can be imagined much the haptic events. xrEndFrame call. All composition layers to be drawn must be same way a curved television display looks to a viewer. submitted with everyxrEndFrame call. Composition layers typedef struct XrCompositionLayerCylinderKHR { Action sets [11.2] are drawn in the same order as they are specified in via XrStructureType type; XrResult xrCreateActionSet(XrInstance instance, XrFrameEndInfo, with the 0th layer drawn first. const void* next; const XrActionSetCreateInfo* createInfo, typedef struct XrCompositionLayerBaseHeader { XrCompositionLayerFlags layerFlags; XrActionSet* actionSet); XrStructureType type; XrSpace space; XrEyeVisibility eyeVisibility; typedef struct XrActionSetCreateInfo { const void* next; XrStructureType type; XrCompositionLayerFlags layerFlags; XrSwapchainSubImage subImage; XrPosef pose; const void* next; XrSpace space; char actionSetName[XR_MAX_ACTION_SET_NAME_SIZE]; } XrCompositionLayerBaseHeader; float radius; float centralAngle; char localizedActionSetName[ layerFlags: A bitwise OR of float aspectRatio; XR_MAX_LOCALIZED_ACTION_SET_NAME_SIZE]; XR_COMPOSITION_LAYER_X_BIT where X may be: } XrCompositionLayerCylinderKHR; uint32_t priority; CORRECT_CHROMATIC_ABERRATION, } XrActionSetCreateInfo; BLEND_TEXTURE_SOURCE_ALPHA £ XR_KHR_composition_layer_equirect[13.6] XrResult xrDestroyActionSet(XrActionSet actionSet); type: This extension adds an additional layer type where the XR XR_TYPE_COMPOSITION_LAYER_X where X may be: runtime must map an equirectangular coded image stemming Actions [11.3] PROJECTION, QUAD, CUBE_KHR, CYLINDER_KHR, from a swapchain onto the inside of a sphere. XrResult xrCreateAction(XrActionSet actionSet, EQUIRECT_KHR typedef struct XrCompositionLayerEquirectKHR { const XrActionCreateInfo* createInfo, next: NULL or a pointer to an extension-specific structure: £ XrStructureType type; XrAction* action); XrCompositionLayerColorModulationInfoKHR if the const void* next; typedef struct XrActionCreateInfo { XR_KHR_composition_layer_color_modulation extension XrCompositionLayerFlags layerFlags; XrStructureType type; is enabled; or XrSpace space; const void* next; £ XrCompositionLayerDepthInfoKHR if XrEyeVisibility eyeVisibility; char actionName[XR_MAX_ACTION_NAME_SIZE]; XR_KHR_composition_layer_depth is enabled XrSwapchainSubImage subImage; XrActionTypeactionType ; XrPosef pose; uint32_t countSubactionPaths; typedef struct XrSwapchainSubImage { float radius; const XrPath* subactionPaths; XrSwapchain swapchain; XrVector2f scale; char localizedActionName[ XrRect2Di imageRect; XrVector2f bias; XR_MAX_LOCALIZED_ACTION_NAME_SIZE]; uint32_t imageArrayIndex; } XrCompositionLayerEquirectKHR; } XrSwapchainSubImage; } XrActionCreateInfo; typedef actionType: XR_ACTION_TYPE_X where X may be: typedef struct XrCompositionLayerProjection { struct XrCompositionLayerColorModulationInfoKHR { BOOLEAN_INPUT, FLOAT_INPUT, VECTOR2F_INPUT, XrStructureType type; const void* next; XrStructureType type; POSE_INPUT, VIBRATION_OUTPUT XrCompositionLayerFlags layerFlags; const void* next; XrSpace space; XrColor4f colorScale; XrResult xrDestroyAction(XrAction action); uint32_t viewCount; XrColor4f colorOffset; const XrCompositionLayerProjectionView* views; } XrCompositionLayerColorModulationInfoKHR; Suggested Bindings [11.4] } XrCompositionLayerProjection; Applications need to provide default bindings for their actions typedef struct XrCompositionLayerDepthInfoKHR { to runtimes so that input data can be mapped appropriately typedef struct XrCompositionLayerProjectionView { XrStructureType type; to the application’s actions. The bindings suggested by this XrStructureType type; const void* next; system are only a hint to the runtime. const void* next; XrSwapchainSubImage subImage; XrPosef pose; float minDepth; XrResult xrSuggestInteractionProfileBindings( XrFovf fov; float maxDepth; XrInstance instance, XrSwapchainSubImage subImage; float nearZ; const XrInteractionProfileSuggestedBinding* } XrCompositionLayerProjectionView; float farZ; suggestedBindings); } XrCompositionLayerDepthInfoKHR; £ XR_KHR_composition_layer_cube[12.25] typedef struct XrInteractionProfileSuggestedBinding { This extension adds an additional layer type that enables direct typedef struct XrCompositionLayerQuad { XrStructureType type; sampling from cubemaps. XrStructureType type; const void* next; const void* next; XrPath interactionProfile; typedef struct XrCompositionLayerCubeKHR { XrCompositionLayerFlags layerFlags; uint32_t countSuggestedBindings; XrStructureType type; const void* next; XrSpace space; const XrActionSuggestedBinding* suggestedBindings; XrCompositionLayerFlags layerFlags; XrEyeVisibility eyeVisibility; } XrInteractionProfileSuggestedBinding; XrSpace space; XrSwapchainSubImage subImage; XrEyeVisibility eyeVisibility; XrPosef pose; typedef struct XrActionSuggestedBinding { XrSwapchain swapchain; XrExtent2Df size; XrAction action; uint32_t imageArrayIndex; } XrCompositionLayerQuad; XrPath binding; } XrActionSuggestedBinding; XrQuaternionf orientation; eyeVisibility: XR_EYE_VISIBILITY_X where X may be: BOTH, } XrCompositionLayerCubeKHR; LEFT, RIGHT Continued on next page > ©2019 Khronos Group - Rev. 0719 www.khronos.org/openxr OpenXR 1.0 Reference Guide Page 7 Inputs and Haptics: Actions (continued) XrResult xrGetActionStateFloat(XrSession session, Input Action State Synchronization [11.7] const XrActionStateGetInfo* getInfo, XrResult xrSyncActions(XrSession session, XrActionStateFloat* state); const XrActionsSyncInfo* syncInfo); typedef struct XrEventDataInteractionProfileChanged { XrStructureType type; typedef struct XrActionStateFloat { typedef struct XrActionsSyncInfo { const void* next; XrStructureType type; XrStructureType type; XrSession session; void* next; const void* next; } XrEventDataInteractionProfileChanged; float currentState; uint32_t countActiveActionSets; XrBool32 changedSinceLastSync; const XrActiveActionSet* activeActionSets; An action set becomes immutable when attathed to a XrTime lastChangeTime; } XrActionsSyncInfo; session. XrBool32 isActive; } XrActionStateFloat; typedef struct XrActiveActionSet { XrResult xrAttachSessionActionSets(XrSession session, XrActionSet actionSet; const XrSessionActionSetsAttachInfo* attachInfo); XrResult xrGetActionStateVector2f(XrSession session, XrPath subactionPath; const XrActionStateGetInfo* getInfo, } XrActiveActionSet; typedef struct XrSessionActionSetsAttachInfo { XrActionStateVector2f* state); XrStructureType type; Action Sources [11.8] const void* next; typedef struct XrActionStateVector2f { XrStructureType type; XrResult xrEnumerateBoundSourcesForAction( uint32_t countActionSets; XrSession session, const XrActionSet* actionSets; void* next; } XrSessionActionSetsAttachInfo; XrVector2f currentState; const XrBoundSourcesForActionEnumerateInfo* XrBool32 changedSinceLastSync; enumerateInfo, XrResult xrGetCurrentInteractionProfile(XrSession session, XrTime lastChangeTime; uint32_t sourceCapacityInput, XrPath topLevelUserPath, XrBool32 isActive; uint32_t* sourceCountOutput, XrInteractionProfileInfo* interactionProfile); } XrActionStateVector2f; XrPath* sources); typedef struct XrInteractionProfileInfo { XrResult xrGetActionStatePose(XrSession session, typedef struct XrBoundSourcesForActionEnumerateInfo { XrStructureType type; const XrActionStateGetInfo* getInfo, XrStructureType type; const void* next; XrActionStatePose* state); const void* next; XrPath interactionProfile; XrAction action; } XrInteractionProfileInfo; typedef struct XrActionStatePose { } XrBoundSourcesForActionEnumerateInfo; XrStructureType type; Reading Input Action State [11.5] XrResult xrGetInputSourceLocalizedName( void* next; XrSession session, typedef struct XrActionStateGetInfo { XrBool32 isActive; const XrInputSourceLocalizedNameGetInfo* getInfo, XrStructureType type; } XrActionStatePose; const void* next; uint32_t bufferCapacityInput, XrAction action; uint32_t* bufferCountOutput, Output Actions and Haptics [11.6] char* buffer); XrPath subactionPath; XrResult xrApplyHapticFeedback(XrSession session, } XrActionStateGetInfo; const XrHapticActionInfo* hapticActionInfo, typedef struct XrInputSourceLocalizedNameGetInfo { typedef struct XrHapticActionInfo { const XrHapticBaseHeader* hapticFeedback); XrStructureType type; XrStructureType type; const void* next; typedef struct XrHapticBaseHeader { XrPath sourcePath; const void* next; XrStructureType type; XrAction action; XrInputSourceLocalizedNameFlags whichComponents; const void* next; } XrInputSourceLocalizedNameGetInfo; XrPath subactionPath; } XrHapticBaseHeader; } XrHapticActionInfo; whichComponents: A bitwise OR of typedef struct XrHapticVibration { XR_INPUT_SOURCE_LOCALIZED_NAME_X_BIT where XrResult xrGetActionStateBoolean(XrSession session, XrStructureType type; X may be: USER_PATH, INTERACTION_PROFILE, const XrActionStateGetInfo* getInfo, const void* next; COMPONENT XrActionStateBoolean* state); XrDuration duration; typedef struct XrActionStateBoolean { float frequency; XrStructureType type; float amplitude; void* next; } XrHapticVibration; XrBool32 currentState; duration: nanoseconds or XR_MIN_HAPTIC_DURATION XrBool32 changedSinceLastSync; frequency: Hz or XR_FREQUENCY_UNSPECIFIED XrTime lastChangeTime; typedef struct XrGraphicsRequirementsD3D12KHR { XrBool32 isActive; XrResult xrStopHapticFeedback(XrSession session, XrStructureType type; const XrHapticActionInfo* hapticActionInfo); void* next; } XrActionStateBoolean; LUID adapterLuid; D3D_FEATURE_LEVEL minFeatureLevel; } XrGraphicsRequirementsD3D12KHR; £ Extensions [12] typedef struct XrSwapchainImageD3D11KHR { XrStructureType type; XR_KHR opengl_enable [12.14] Support theOpenGL graphics API in an OpenXR runtime. Extension naming convention [2.6] void* next; ID3D11Texture2D* texture; typedef struct XrGraphicsBindingOpenGLWin32KHR { Khronos-created extensions supported by } XrSwapchainImageD3D11KHR; XR_KHR_* multiple vendors XrStructureType type; const void* next; XR_EXT_* extensions supported by multiple vendors, typedef struct XrGraphicsRequirementsD3D11KHR { HDC hDC; HGLRC hGLRC; possibly IP-restricted XrStructureType type; } XrGraphicsBindingOpenGLWin32KHR; void* next; XR_KHR_convert_timespec_time [12.9] LUID adapterLuid; typedef struct XrGraphicsBindingOpenGLXlibKHR { Enabling this extension makes the following available. D3D_FEATURE_LEVEL minFeatureLevel; XrStructureType type; } XrGraphicsRequirementsD3D11KHR; const void* XR_MAY_ALIAS next; XrResult xrConvertTimespecTimeToTimeKHR( Display* xDisplay; XrInstance instance, XrResult xrDestroySession(XrSession session); uint32_t visualid; const struct timespec* timespecTime, XrTime* time); GLXFBConfig glxFBConfig; XR_KHR_D3D12_enable [12.12] GLXDrawable glxDrawable; XrResult xrConvertTimeToTimespecTimeKHR( Support the D3D 12 graphics API in an OpenXR runtime. GLXContext glxContext; XrInstance instance, XrTime time, } XrGraphicsBindingOpenGLXlibKHR; struct timespec*timespecTime ); XrResult xrGetD3D12GraphicsRequirementsKHR( XrInstance instance, XrSystemId systemId, typedef struct XrGraphicsBindingOpenGLXcbKHR { XR_KHR_D3D11_enable [12.11] XrGraphicsRequirementsD3D12KHR* XrStructureType type; Support the D3D 11 graphics API in an OpenXR runtime. graphicsRequirements); const void* next; xcb_connection_t* connection; XrResult xrGetD3D11GraphicsRequirementsKHR( typedef struct XrGraphicsBindingD3D12KHR { uint32_t screenNumber; XrInstance instance, XrSystemId systemId, XrStructureType type; xcb_glx_fbconfig_t fbconfigid; XrGraphicsRequirementsD3D11KHR* const void* next; xcb_visualid_t visualid; graphicsRequirements); ID3D12Device* device; xcb_glx_drawable_t glxDrawable; ID3D12CommandQueue* queue; xcb_glx_context_t glxContext; typedef struct XrGraphicsBindingD3D11KHR { } XrGraphicsBindingD3D12KHR; } XrGraphicsBindingOpenGLXcbKHR; XrStructureType type; const void* next; typedef struct XrSwapchainImageD3D12KHR { typedef struct XrGraphicsBindingOpenGLWaylandKHR { ID3D11Device* device; XrStructureType type; XrStructureType type; } XrGraphicsBindingD3D11KHR; void* next; const void* next; ID3D12Resource* texture; struct wl_display* display; } XrSwapchainImageD3D12KHR; } XrGraphicsBindingOpenGLWaylandKHR; Continued on next page > ©2019 Khronos Group - Rev. 0719 www.khronos.org/openxr OpenXR 1.0 Reference Guide Page 8 Extensions (continued) XR_KHR_visibility_mask [12.16] XrResult xrGetVulkanDeviceExtensionsKHR( This extension enables the following: XrInstance instance, XrSystemId systemId, uint32_t bufferCapacityInput, typedef struct XrSwapchainImageOpenGLKHR { XrResult xrGetVisibilityMaskKHR(XrSession session, uint32_t* bufferCountOutput, char* buffer); XrStructureType type; XrViewConfigurationType viewConfigurationType, void* next; uint32_t viewIndex, XR_KHR_vulkan_swapchain_format_list [12.18] uint32_t image; XrVisibilityMaskTypeKHR visibilityMaskType, This extension enables the following: } XrSwapchainImageOpenGLKHR; XrVisibilityMaskKHR* visibilityMask); visibilityMask: typedef XrResult xrGetOpenGLGraphicsRequirementsKHR( struct XrVulkanSwapchainFormatListCreateInfoKHR { XrInstance instance, XrSystemId systemId, XR_VISIBILITY_MASK_TYPE_X_KHR where X may be: HIDDEN_TRIANGLE_MESH, VISIBLE_TRIANGLE_MESH, XrStructureType type; XrGraphicsRequirementsOpenGLKHR* const void* next; graphicsRequirements); LINE_LOOP uint32_t viewFormatCount; typedef struct XrGraphicsRequirementsOpenGLKHR { typedef struct XrVisibilityMaskKHR { const VkFormat* viewFormats; XrStructureType type; XrStructureType type; void* next; } XrVulkanSwapchainFormatListCreateInfoKHR; void* next; uint32_t vertexCapacityInput; XrVersion minApiVersionSupported; uint32_t vertexCountOutput; XR_KHR_win32_convert_performance_counter_time XrVersion maxApiVersionSupported; XrVector2f* vertices; [12.19] } XrGraphicsRequirementsOpenGLKHR; uint32_t indexCapacityInput; This extension enables the following: uint32_t indexCountOutput; XR_KHR_opengl_es_enable [12.15] uint32_t* indices; XrResult xrConvertWin32PerformanceCounterToTimeKHR( Support the OpenGL ES graphics API in an OpenXR runtime. } XrVisibilityMaskKHR; XrInstance instance, typedef struct XrEventDataVisibilityMaskChangedKHR { const LARGE_INTEGER* performanceCounter, typedef struct XrGraphicsBindingOpenGLESAndroidKHR { XrTime* time); XrStructureType type; XrStructureType type; const void* next; const void* next; XrResult xrConvertTimeToWin32PerformanceCounterKHR( EGLDisplay display; XrSession session; XrInstance instance, XrTime time, EGLConfig config; EGLContext context; XrViewConfigurationType viewConfigurationType; LARGE_INTEGER* performanceCounter); } XrGraphicsBindingOpenGLESAndroidKHR; uint32_t viewIndex; } XrEventDataVisibilityMaskChangedKHR; typedef struct XrSwapchainImageOpenGLESKHR { XrStructureType type; XR_KHR_vulkan_enable [12.17] void* next; Support the Vulkan graphics API in an OpenXR runtime in uint32_t image; addition to those functions and structs shown under Sessions Learn more about OpenXR } XrSwapchainImageOpenGLESKHR; on page 6 of this reference guide. OpenXR is maintained by the Khronos Group, a worldwide XrResult xrGetOpenGLESGraphicsRequirementsKHR( XrResult xrGetVulkanGraphicsDeviceKHR( consortium of organizations that work to create and maintain XrInstance instance, XrSystemId systemId, XrInstance instance, XrSystemId systemId, key standards used across many industries. Visit Khronos XrGraphicsRequirementsOpenGLESKHR* VkInstance vkInstance, online for resources to help you use and master OpenXR: graphicsRequirements); VkPhysicalDevice* vkPhysicalDevice); Main OpenXR Resource Page: khronos.org/openxr/ typedef struct XrGraphicsRequirementsOpenGLESKHR { XrStructureType type; XrResult xrGetVulkanInstanceExtensionsKHR( OpenXR Registry: khronos.org/registry/openxr/ XrInstance instance, XrSystemId systemId, void* next; Forums: forums.khronos.org/ XrVersion minApiVersionSupported; uint32_t bufferCapacityInput, XrVersion maxApiVersionSupported; uint32_t* bufferCountOutput, char* buffer); Slack: khr.io/slack } XrGraphicsRequirementsOpenGLESKHR; Courses: khronos.org/developers/training/ Videos & Presentations: khr.io/library/ Notes Khronos Events: khronos.org/news/events/ Khronos Blog: khronos.org/blog/ Reference Guides: khr.io/refguides/ Khronos Books: khronos.org/developers/books/ Khronos Merchandise: khronos.org/store/
@thekhronosgroup khronos.org
OpenXR is a trademark of the Khronos Group. The Khronos Group is an industry consortium creating open standards for the authoring and acceleration of parallel computing, graphics, and dynamic media on a wide variety of platforms and devices. See www.khronos.org to learn more about the Khronos Group. See www.khronos.org/openxr to learn more about OpenXR.
Reference guide production by Miller Mattson www.millermattson.com ©2019 Khronos Group - Rev. 0719 & www.khronos.org/openxr