XrSessionState - Session lifecycle state

Enumerant Descriptions

The SESSION_STATE_UNKNOWN state must not be returned by the runtime, and is only defined to avoid 0 being a valid state.

Receiving the SESSION_STATE_IDLE state indicates that the runtime considers the session is idle. Applications in this state should minimize resource consumption but continue to call pollEvent at some reasonable cadence.

Receiving the SESSION_STATE_READY state indicates that the runtime desires the application to prepare rendering resources, begin its session and synchronize its frame loop with the runtime. The application does this by successfully calling beginSession and then running its frame loop by calling waitFrame, beginFrame and endFrame in a loop. If the runtime wishes to return the session to the SESSION_STATE_IDLE state, it must wait until the application calls beginSession. After returning from the beginSession call, the runtime may then immediately transition forward through the SESSION_STATE_SYNCHRONIZED state to the SESSION_STATE_STOPPING state, to request that the application end this session. If the system supports a user engagement sensor and runtime is in SESSION_STATE_IDLE state, the runtime should not transition to the SESSION_STATE_READY state until the user starts engaging with the device.

Receiving the SESSION_STATE_SYNCHRONIZED state indicates that the application has synchronized its frame loop with the runtime, but its frames are not visible to the user. The application should continue running its frame loop by calling waitFrame, beginFrame and endFrame, although it should avoid heavy GPU work so that other visible applications can take CPU and GPU precedence. The application can save resources here by skipping rendering and not submitting any composition layers until waitFrame returns an FrameState with shouldRender set to true. A runtime may use this frame synchronization to facilitate seamless switching from a previous XR application to this application on a frame boundary.

Receiving the SESSION_STATE_VISIBLE state indicates that the application has synchronized its frame loop with the runtime, and the session’s frames will be visible to the user, but the session is not eligible to receive XR input. An application may be visible but not have focus, for example when the runtime is composing a modal pop-up on top of the application’s rendered frames. The application should continue running its frame loop, rendering and submitting its composition layers, although it may wish to pause its experience, as users cannot interact with the application at this time. It is important for applications to continue rendering when visible, even when they do not have focus, so the user continues to see something reasonable underneath modal pop-ups. Runtimes should make input actions inactive while the application is unfocused, and applications should react to an inactive input action by skipping rendering of that action’s input avatar (depictions of hands or other tracked objects controlled by the user).

Receiving the SESSION_STATE_FOCUSED state indicates that the application has synchronized its frame loop with the runtime, the session’s frames will be visible to the user, and the session is eligible to receive XR input. The runtime should only give one session XR input focus at any given time. The application should be running its frame loop, rendering and submitting composition layers, including input avatars (depictions of hands or other tracked objects controlled by the user) for any input actions that are active. The runtime should avoid rendering its own input avatars when an application is focused, unless input from a given source is being captured by the runtime at the moment.

Receiving the SESSION_STATE_STOPPING state indicates that the runtime has determined that the application should halt its rendering loop. Applications should exit their rendering loop and call endSession when in this state. A possible reason for this would be to minimize contention between multiple applications. If the system supports a user engagement sensor and the session is running, the runtime should transition to the SESSION_STATE_STOPPING state when the user stops engaging with the device.

Receiving the SESSION_STATE_EXITING state indicates the runtime wishes the application to terminate its XR experience, typically due to a user request via a runtime user interface. Applications should gracefully end their process when in this state if they do not have a non-XR user experience.

Receiving the SESSION_STATE_LOSS_PENDING state indicates the runtime is no longer able to operate with the current session, for example due to the loss of a display hardware connection. An application should call destroySession and may end its process or decide to poll getSystem at some reasonable cadence to get a new https://www.khronos.org/registry/OpenXR/specs/1.0/html/xrspec.html#XrSystemId, and re-initialize all graphics resources related to the new system, and then create a new session using createSession. After the event is queued, subsequent calls to functions that accept Session parameters must no longer return any success code other than SESSION_LOSS_PENDING for the given Session handle. The SESSION_LOSS_PENDING success result is returned for an unspecified grace period of time, and the functions that return it simulate success in their behavior. If the runtime has no reasonable way to successfully complete a given function (e.g. createSwapchain) when a lost session is pending, or if the runtime is not able to provide the application a grace period, the runtime may return ERROR_SESSION_LOST. Thereafter, functions which accept Session parameters for the lost session may return ERROR_SESSION_LOST to indicate that the function failed and the given session was lost. The Session handle and child handles are henceforth unusable and should be destroyed by the application in order to immediately free up resources associated with those handles.

See Also

EventDataSessionStateChanged, pollEvent