xrGetInstanceProcAddr - Gets a function pointer for an OpenXR function

Parameter Descriptions

Description

getInstanceProcAddr itself is obtained in a platform- and loader- specific manner. Typically, the loader library will export this function as a function symbol, so applications can link against the loader library, or load it dynamically and look up the symbol using platform-specific APIs. Loaders must export function symbols for all core OpenXR functions. Because of this, applications that use only the core OpenXR functions have no need to use getInstanceProcAddr.

Because an application can call getInstanceProcAddr before creating an instance, getInstanceProcAddr returns a valid function pointer when the instance parameter is XR_NULL_HANDLE and the name parameter is one of the following strings:

No Instance Required

• enumerateInstanceExtensionProperties

• enumerateApiLayerProperties
• createInstance

getInstanceProcAddr must return ERROR_HANDLE_INVALID if name is not one of the above strings and instance is XR_NULL_HANDLE. getInstanceProcAddr may return ERROR_HANDLE_INVALID if name is not one of the above strings and instance is invalid but not XR_NULL_HANDLE.

getInstanceProcAddr must return ERROR_FUNCTION_UNSUPPORTED if instance is a valid instance and the string specified in name is not the name of an OpenXR core or enabled extension function.

If name is the name of an extension function, then the result returned by getInstanceProcAddr will depend upon how the instance was created. If instance was created with the related extension’s name appearing in the InstanceCreateInfo::enabledExtensionNames array, then getInstanceProcAddr returns a valid function pointer. If the related extension’s name did not appear in the InstanceCreateInfo::enabledExtensionNames array during the creation of instance, then getInstanceProcAddr returns ERROR_FUNCTION_UNSUPPORTED. Because of this, function pointers returned by getInstanceProcAddr using one Instance may not be valid when used with objects related to a different Instance.

The returned function pointer is of type PFN_xrVoidFunction, and must be cast to the type of the function being queried.

The table below defines the various use cases for getInstanceProcAddr and return value (“fp” is “function pointer”) for each case.

xrGetInstanceProcAddr behavior

1

The returned function pointer must only be called with a handle (the first parameter) that is instance or a child of instance.

Valid Usage (Implicit)

• If instance is not XR_NULL_HANDLE, instance must be a valid Instance handle

• name must be a null-terminated UTF-8 string
• function must be a pointer to a PFN_xrVoidFunction value

Return Codes

Success

• SUCCESS

Failure

• ERROR_HANDLE_INVALID
• ERROR_INSTANCE_LOST
• ERROR_RUNTIME_FAILURE
• ERROR_OUT_OF_MEMORY
• ERROR_FUNCTION_UNSUPPORTED
• ERROR_VALIDATION_FAILURE

See Also

PFN_xrVoidFunction, Instance

xrEnumerateApiLayerProperties - Returns up to requested number of global layer properties

Parameter Descriptions

• propertyCapacityInput is the capacity of the properties array, or 0 to indicate a request to retrieve the required capacity.

• propertyCountOutput is a pointer to the count of properties written, or a pointer to the required capacity in the case that propertyCapacityInput is 0.
• properties is a pointer to an array of ApiLayerProperties structures, but can be NULL if propertyCapacityInput is 0.
• See the Buffer Size Parameters section for a detailed description of retrieving the required properties size.

Description

The list of available layers may change at any time due to actions outside of the OpenXR runtime, so two calls to enumerateApiLayerProperties with the same parameters may return different results, or retrieve different propertyCountOutput values or properties contents.

Once an instance has been created, the layers enabled for that instance will continue to be enabled and valid for the lifetime of that instance, even if some of them become unavailable for future instances.

Valid Usage (Implicit)

• propertyCountOutput must be a pointer to a uint32_t value

• If propertyCapacityInput is not 0, properties must be a pointer to an array of propertyCapacityInput ApiLayerProperties structures

Return Codes

Success

• SUCCESS

Failure

• ERROR_OUT_OF_MEMORY
• ERROR_VALIDATION_FAILURE
• ERROR_RUNTIME_FAILURE
• ERROR_SIZE_INSUFFICIENT

See Also

ApiLayerProperties

xrEnumerateInstanceExtensionProperties - Returns properties of available instance extensions

Parameter Descriptions

• layerName is either NULL or a pointer to a string naming the API layer to retrieve extensions from, as returned by enumerateApiLayerProperties.

• propertyCapacityInput is the capacity of the properties array, or 0 to indicate a request to retrieve the required capacity.
• propertyCountOutput is a pointer to the count of properties written, or a pointer to the required capacity in the case that propertyCapacityInput is 0.
• properties is a pointer to an array of ExtensionProperties structures, but can be NULL if propertyCapacityInput is 0.
• See the Buffer Size Parameters section for a detailed description of retrieving the required properties size.

Description

If properties is NULL, then the number of extensions properties available is returned in propertyCountOutput. Otherwise, propertyCountInput must point to a variable set by the user to the number of elements in the properties array. If propertyCountInput is less than the number of extension properties available, the contents of properties will be undefined. If propertyCountInput is smaller than the number of extensions available, the runtime must return the failure code ERROR_SIZE_INSUFFICIENT and the contents of properties are undefined.

Because the list of available layers may change externally between calls to enumerateInstanceExtensionProperties, two calls may retrieve different results if a layerName is available in one call but not in another. The extensions supported by a layer may also change between two calls, e.g. if the layer implementation is replaced by a different version between those calls.

Valid Usage (Implicit)

• If layerName is not NULL, layerName must be a null-terminated UTF-8 string

• propertyCountOutput must be a pointer to a uint32_t value
• If propertyCapacityInput is not 0, properties must be a pointer to an array of propertyCapacityInput ExtensionProperties structures

Return Codes

Success

• SUCCESS

Failure

• ERROR_OUT_OF_MEMORY
• ERROR_API_LAYER_NOT_PRESENT
• ERROR_RUNTIME_FAILURE
• ERROR_VALIDATION_FAILURE
• ERROR_SIZE_INSUFFICIENT

See Also

ExtensionProperties

xrCreateInstance - Creates an OpenXR Instance

Parameter Descriptions

Description

createInstance creates the Instance, then enables and initializes global API layers and extensions requested by the application. If an extension is provided by an API layer, both the API layer and extension must be specified at createInstance time. If a specified API layer cannot be found, no Instance will be created and the function will return ERROR_API_LAYER_NOT_PRESENT. Likewise, if a specified extension cannot be found, the call must return ERROR_EXTENSION_NOT_PRESENT and no Instance will be created. Additionally, some runtimes may limit the number of concurrent instances that may be in use. If the application attempts to create more instances than a runtime can simultaneously support, createInstance may return ERROR_LIMIT_REACHED.

If the ApplicationInfo::applicationName is the empty string the runtime must return ERROR_NAME_INVALID.

If the InstanceCreateInfo structure contains a platform-specific extension for a platform other than the target platform, ERROR_INITIALIZATION_FAILED may be returned. If a mandatory platform-specific extension is defined for the target platform but no matching extension struct is provided in InstanceCreateInfo the runtime must return ERROR_INITIALIZATION_FAILED.

Return Codes

Success

• SUCCESS

Failure

• ERROR_OUT_OF_MEMORY
• ERROR_LIMIT_REACHED
• ERROR_INSTANCE_LOST
• ERROR_RUNTIME_FAILURE
• ERROR_INITIALIZATION_FAILED
• ERROR_API_VERSION_UNSUPPORTED
• ERROR_API_LAYER_NOT_PRESENT
• ERROR_EXTENSION_NOT_PRESENT
• ERROR_VALIDATION_FAILURE
• ERROR_NAME_INVALID

See Also

Instance, InstanceCreateInfo

A convenience wrapper to make a compatible pair of calls to createInstance and destroyInstance

To ensure that destroyInstance is always called: pass bracket (or the allocate function from your favourite resource management library) as the last argument. To just extract the pair pass (,) as the last argument.

xrDestroyInstance - Destroy an instance of OpenXR

Parameters

The destroyInstance function is used to destroy an Instance.

Parameter Descriptions

• instance is the handle to the instance to destroy.

Instance handles are destroyed using destroyInstance. When an Instance is destroyed, all handles that are children of that Instance are also destroyed.

Valid Usage (Implicit)

• instance must be a valid Instance handle

Thread Safety

• Access to instance, and any child handles, must be externally synchronized

Return Codes

Success

• SUCCESS

Failure

• ERROR_HANDLE_INVALID

See Also

Instance

xrResultToString - Converts an XrResult to a UTF-8 string

Parameter Descriptions

Description

Returns the text version of the provided Result value as a UTF-8 string.

In all cases the returned string must be one of:

Result String Return Values

• The literal string defined for the provide numeric value in the core spec or extension. (e.g. the value 0 results in the string SUCCESS)

• XR_UNKNOWN_SUCCESS_ concatenated with the positive result number expressed as a decimal number.
• XR_UNKNOWN_FAILURE_ concatenated with the negative result number expressed as a decimal number.

Valid Usage (Implicit)

• instance must be a valid Instance handle

• value must be a valid Result value
• buffer must be a character array of length MAX_RESULT_STRING_SIZE

Return Codes

Success

• SUCCESS

Failure

• ERROR_HANDLE_INVALID
• ERROR_INSTANCE_LOST
• ERROR_RUNTIME_FAILURE
• ERROR_VALIDATION_FAILURE

See Also

Instance, Result, structureTypeToString

xrStructureTypeToString - Converts an XrStructureType to a UTF-8 string

Parameter Descriptions

Description

Returns the text version of the provided StructureType value as a UTF-8 string.

In all cases the returned string must be one of:

Structure Type String Return Values

• The literal string defined for the provide numeric value in the core spec or extension. (e.g. the value of TYPE_INSTANCE_CREATE_INFO results in the string TYPE_INSTANCE_CREATE_INFO)

• XR_UNKNOWN_STRUCTURE_TYPE_ concatenated with the structure type number expressed as a decimal number.

Valid Usage (Implicit)

• instance must be a valid Instance handle

• value must be a valid StructureType value
• buffer must be a character array of length MAX_STRUCTURE_NAME_SIZE

Return Codes

Success

• SUCCESS

Failure

• ERROR_HANDLE_INVALID
• ERROR_INSTANCE_LOST
• ERROR_RUNTIME_FAILURE
• ERROR_VALIDATION_FAILURE

See Also

Instance, StructureType, resultToString

xrGetInstanceProperties - Gets information about the instance

Parameter Descriptions

Description

The instanceProperties parameter must be filled out by the runtime in response to this call, with information as defined in InstanceProperties.

Return Codes

Success

• SUCCESS

Failure

• ERROR_HANDLE_INVALID
• ERROR_INSTANCE_LOST
• ERROR_RUNTIME_FAILURE
• ERROR_VALIDATION_FAILURE

See Also

Instance, InstanceProperties

xrPollEvent - Polls for events

Parameters

pollEvent polls for the next event and returns an event if one is available. pollEvent returns immediately regardless of whether an event was available. The event (if present) is unilaterally removed from the queue if a valid Instance is provided. On return the eventData parameter is filled with the event’s data and the type field is changed to the event’s type. Runtimes may create valid next chains depending on enabled extensions, but they must guarantee that any such chains point only to objects which fit completely within the original EventDataBuffer pointed to by eventData.

Return Codes

Success

• SUCCESS
• EVENT_UNAVAILABLE

Failure

• ERROR_INSTANCE_LOST
• ERROR_RUNTIME_FAILURE
• ERROR_HANDLE_INVALID
• ERROR_VALIDATION_FAILURE

The runtime must discard queued events which contain destroyed or otherwise invalid handles.

Event Descriptions

See Also

EventDataBuffer, Instance

XrApiLayerProperties - Structure specifying layer properties

Valid Usage (Implicit)

See Also

StructureType, https://www.khronos.org/registry/OpenXR/specs/1.0/html/xrspec.html#XrVersion, enumerateApiLayerProperties

XrExtensionProperties - Returns properties of available instance extensions

Valid Usage (Implicit)

See Also

StructureType, enumerateInstanceExtensionProperties

XrApplicationInfo - Structure specifying application info

Valid Usage (Implicit)

Note

When using the OpenXR API to implement a reusable engine that will be used by many applications, engineName should be set to a unique string that identifies the engine, and engineVersion should encode a representation of the engine’s version. This way, all applications that share this engine version will provide the same engineName and engineVersion to the runtime. The engine should then enable individual applications to choose their specific applicationName and applicationVersion, enabling one application to be distinguished from another application.

When using the OpenXR API to implement an individual application without a shared engine, the input engineName should be left empty and engineVersion should be set to 0. The applicationName should then be filled in with a unique string that identifies the app and the applicationVersion should encode a representation of the application’s version.

See Also

InstanceCreateInfo, https://www.khronos.org/registry/OpenXR/specs/1.0/html/xrspec.html#XrVersion

XrInstanceCreateInfo - Structure specifying params of a newly created instance

Valid Usage (Implicit)

• type must be TYPE_INSTANCE_CREATE_INFO

• next must be NULL or a valid pointer to the next structure in a structure chain. See also: DebugUtilsMessengerCreateInfoEXT, InstanceCreateInfoAndroidKHR
• createFlags must be 0
• applicationInfo must be a valid ApplicationInfo structure
• If enabledApiLayerCount is not 0, enabledApiLayerNames must be a pointer to an array of enabledApiLayerCount null-terminated UTF-8 strings
• If enabledExtensionCount is not 0, enabledExtensionNames must be a pointer to an array of enabledExtensionCount null-terminated UTF-8 strings

See Also

ApplicationInfo, InstanceCreateFlags, StructureType, createInstance

XrInstanceProperties - Contains information about the instance

Valid Usage (Implicit)

See Also

StructureType, https://www.khronos.org/registry/OpenXR/specs/1.0/html/xrspec.html#XrVersion, getInstanceProperties

XrEventDataBuffer - Event buffer

Valid Usage (Implicit)

See Also

EventDataBaseHeader, StructureType, pollEvent