www.khronos.org/openxr
©2019–2021 Khronos Group - Rev. 0421
OpenXR 1.0 Reference Guide Page 2
XrResult return codes [2.8]
API commands return values of type XrResult. Negave values
are error codes, while non-negave (≥0) are success codes.
Success codes
XR_SUCCESS XR_TIMEOUT_EXPIRED
XR_SESSION_LOSS_PENDING XR_EVENT_UNAVAILABLE
XR_SESSION_NOT_FOCUSED XR_FRAME_DISCARDED
XR_SPACE_BOUNDS_UNAVAILABLE
Error codes
XR_ERROR_X where X may be:
ACTION_TYPE_MISMATCH
ACTIONSET_NOT_ATTACHED
ACTIONSETS_ALREADY_ATTACHED
ANDROID_THREAD_SETTINGS_FAILURE_KHR
ANDROID_THREAD_SETTINGS_ID_INVALID_KHR
API_LAYER_NOT_PRESENT
API_VERSION_UNSUPPORTED
CALL_ORDER_INVALID
ENVIRONMENT_BLEND_MODE_UNSUPPORTED
EXTENSION_NOT_PRESENT
FEATURE_UNSUPPORTED
FILE_ACCESS_ERROR
FILE_CONTENTS_INVALID
FORM_FACTOR_UNAVAILABLE
FORM_FACTOR_UNSUPPORTED
FUNCTION_UNSUPPORTED
GRAPHICS_DEVICE_INVALID
HANDLE_INVALID
INDEX_OUT_OF_RANGE
INITIALIZATION_FAILED
INSTANCE_LOST
LAYER_INVALID
LAYER_LIMIT_EXCEEDED
LIMIT_REACHED
LOCALIZED_NAME_DUPLICATED
LOCALIZED_NAME_INVALID
NAME_DUPLICATED
NAME_INVALID
OUT_OF_MEMORY
PATH_COUNT_EXCEEDED
PATH_FORMAT_INVALID
PATH_INVALID
PATH_UNSUPPORTED
POSE_INVALID
REFERENCE_SPACE_UNSUPPORTED
RUNTIME_FAILURE
SESSION_LOST
SESSION_NOT_READY
SESSION_NOT_RUNNING
SESSION_NOT_STOPPING
SESSION_RUNNING
SIZE_INSUFFICIENT
SWAPCHAIN_FORMAT_UNSUPPORTED
SWAPCHAIN_RECT_INVALID
SYSTEM_INVALID
TIME_INVALID
VALIDATION_FAILURE
VIEW_CONFIGURATION_TYPE_UNSUPPORTED
£
XR_KHR_android_thread_sengs
This extension enables the following addional error codes:
XR_ERROR_ANDROID_THREAD_SETTINGS_ID_INVALID_KHR
XR_ERROR_ANDROID_THREAD_SETTINGS_FAILURE_KHR
Convenience macros [2.8.3]
#dene XR_SUCCEEDED(result) ((result) >= 0)
XR_SUCCEEDED is true for non-negave codes.
#dene XR_FAILED(result) ((result) < 0)
XR_FAILED is true for negave codes.
#dene XR_UNQUALIFIED_SUCCESS(result) ((result) == 0)
XR_UNQUALIFIED_SUCCESS is true for 0 (XR_SUCCESS) only.
Time
XrTime
[2.12.1]
A 64-bit integer represenng a me relave to a runme-
dependent epoch. All simultaneous applicaons use the same
epoch.
XrDuraon
[2.13]
A 64-bit signed integer represenng a duraon; the dierence
between two XrTime values.
Special values:
#dene XR_NO_DURATION 0
#dene XR_INFINITE_DURATION 0x7fLL
Data types
Color [2.14]
Color components are linear (e.g., not sRGB), not alpha-
premulplied, in the range 0.0..1.0.
typedef struct XrColor4f {
oat r; oat g; oat b; oat a;
} XrColor4f;
Coordinate system [2.15]
OpenXR uses a Cartesian right-
handed coordinate system with an
x, y, and z axis.
Points and direcons can be
represented using the following
struct types with the following
members:
XrVector2f
Members x, y for distance in meters or
2D direcon
XrVector3f
Members x, y, z for distance in meters,
or velocity or angular velocity
XrVector4f
Members x, y, z, w for a 4D vector
construct
XrQuaternionf
Members x, y, z, w represenng 3D
orientaon as a unit quaternion
XrPosef
Members orientaon as a unit
quaternion and posion in meters
typedef struct XrVector2f {
oat x;
oat y;
} XrVector2f;
typedef struct XrVector3f {
oat x;
oat y;
oat z;
} XrVector3f;
typedef struct XrVector4f {
oat x;
oat y;
oat z;
oat w;
} XrVector4f;
typedef struct XrPosef {
XrQuaternionf orientaon;;
XrVector3f posion;
} XrPosef;
typedef struct XrQuaternionf {
oat x;
oat y;
oat z;
oat w;
} XrQuaternionf;
Threading behavior [2.3]
OpenXR funcons generally support being called from mulple
threads with a few excepons:
• The handle parameter and any child handles that will
be destroyed by a destroy funcon must be externally
synchronized.
• The instance parameter and any child handles in
xrDestroyInstance
• The session parameter and any child handles in
xrDestroySession
• The space parameter and any child handles in
xrDestroySpace
• The swapchain parameter and any child handles in
xrDestroySwapchain
• The aconSet parameter and any child handles in
xrDestroyAconSet
• The acon parameter and any child handles in
xrDestroyAcon
• Calls to xrWaitFrame for a given XrSession must be
externally synchronized.
XR_KHR_android_thread_sengs [12.3]
£
If enabled, this extension allows the applicaon to specify
the Android thread type.
XrResult xrSetAndroidApplicaonThreadKHR(
XrSession session,
XrAndroidThreadTypeKHR threadType,
uint32_t threadId);
threadType:
XR_ANDROID_THREAD_TYPE_X_KHR
where X may be:
APPLICATION_MAIN,
APPLICATION_WORKER,
RENDERER_MAIN, RENDERER_WORKER
Macros for version and header control
Version numbers [2.1, Appendix]
typedef uint64_t XrVersion;
Version numbers are encoded in 64 bits as follows:
bits 63-48:
Major version
bits 47-32:
Minor version
bits 31-0:
Patch version
Version macros
#dene XR_CURRENT_API_VERSION
XR_MAKE_VERSION(1, 0, 0)
#dene XR_MAKE_VERSION(major, minor, patch)
((((major) & 0xULL) << 48) |
(((minor) & 0xULL) << 32) | ((patch) & 0xULL))
#dene XR_VERSION_MAJOR(version)
(uint16_t) (((uint64_t)(version) >> 48) & 0xULL)
#dene XR_VERSION_MINOR(version)
(uint16_t) (((uint64_t)(version) >> 32) & 0xULL)
#dene XR_VERSION_PATCH(version)
(uint32_t) ((uint64_t)(version) & 0xULL)
Graphics API header control [Appendix]
Compile Time Symbol API
XR_USE_GRAPHICS_API_OPENGL
OpenGL
XR_USE_GRAPHICS_API_OPENGL_ES
OpenGL ES
XR_USE_GRAPHICS_API_VULKAN
Vulkan
XR_USE_GRAPHICS_API_D3D11
Direct3D 11
XR_USE_GRAPHICS_API_D3D12
Direct3D 12
Window system header control [Appendix]
Compile Time Symbol Window System
XR_USE_PLATFORM_WIN32
Microso Windows
XR_USE_PLATFORM_XLIB
X Window System Xlib
XR_USE_PLATFORM_XCB
X Window System Xcb
XR_USE_PLATFORM_WAYLAND
Wayland
XR_USE_PLATFORM_ANDROID
Android Nave
OpenXR Fundamentals
Traversing pointer chains [2.7.7]
typedef struct XrBaseInStructure {
XrStructureType type;
const struct XrBaseInStructure* next;
} XrBaseInStructure;
typedef struct XrBaseOutStructure {
XrStructureType type;
struct XrBaseOutStructure* next;
} XrBaseOutStructure;
Buer size parameters [2.11]
Some funcons refer to input/output buers with parameters
of the following form:
XrResult xrFuncon(uint32_t elementCapacityInput,
uint32_t* elementCountOutput, oat* elements);
Two-call idiom for buer size parameters
First call xrFuncon() with a valid elementCountOutput pointer
(always required), elements = NULL, and elementCapacityInput
= 0 to get the number of elements in the buer; allocate
sucient space, then call xrFuncon() again with the allocated
buer's parameters.