C Specification

The xrPollEvent function is defined as:

// Provided by XR_VERSION_1_0
XrResult xrPollEvent(
    XrInstance                                  instance,
    XrEventDataBuffer*                          eventData);

Parameters

Parameter Descriptions

Description

xrPollEvent polls for the next event and returns an event if one is available. xrPollEvent returns immediately regardless of whether an event was available. The event (if present) is unilaterally removed from the queue if a valid XrInstance 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 XrEventDataBuffer pointed to by eventData.

The runtime must discard queued events which contain destroyed or otherwise invalid handles. The runtime must not return events containing handles that have been destroyed or are otherwise invalid at the time of the call to xrPollEvent.

Valid Usage (Implicit)
Return Codes
On success, this command returns

  • XR_SUCCESS

  • XR_EVENT_UNAVAILABLE

On failure, this command returns

  • XR_ERROR_VALIDATION_FAILURE

  • XR_ERROR_RUNTIME_FAILURE

  • XR_ERROR_HANDLE_INVALID

  • XR_ERROR_INSTANCE_LOST

Table 1. Event Descriptions
Event Description

XrEventDataEventsLost

event queue has overflowed and some events were lost

XrEventDataInstanceLossPending

application is about to lose the instance

XrEventDataInteractionProfileChanged

current interaction profile for one or more top level user paths has changed

XrEventDataReferenceSpaceChangePending

runtime will begin operating with updated definitions or bounds for a reference space

XrEventDataSessionStateChanged

the application’s session has changed lifecycle state

See Also

XR_VERSION_1_0, XrEventDataBuffer, XrInstance

Document Notes

For more information, see the OpenXR Specification

This page is extracted from the OpenXR Specification. Fixes and changes should be made to the Specification, not directly.

Copyright

Copyright 2014-2025 The Khronos Group Inc.

This work is licensed under a Creative Commons Attribution 4.0 International License.