C Specification
The XrSessionState enumerates the possible session lifecycle states:
typedef enum XrSessionState {
XR_SESSION_STATE_UNKNOWN = 0,
XR_SESSION_STATE_IDLE = 1,
XR_SESSION_STATE_READY = 2,
XR_SESSION_STATE_RUNNING = 3,
XR_SESSION_STATE_VISIBLE = 4,
XR_SESSION_STATE_FOCUSED = 5,
XR_SESSION_STATE_STOPPING = 6,
XR_SESSION_STATE_LOSS_PENDING = 7,
XR_SESSION_STATE_EXITING = 8,
XR_SESSION_STATE_MAX_ENUM = 0x7FFFFFFF
} XrSessionState;Description
The XR_SESSION_STATE_UNKNOWN state must not be returned by the runtime,
and is only defined to avoid 0 being a valid state.
Receiving the XR_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 xrPollEvent
at some reasonable cadence.
Receiving the XR_SESSION_STATE_READY state
indicates that the runtime desires the application to prepare rendering resources,
call xrBeginSession, and start its rendering loop.
The rendering loop should consist of some sequence of
xrWaitFrame/xrBeginFrame/xrEndFrame calls. An application
should avoid heavy GPU work until reaching the XR_SESSION_STATE_VISIBLE state
to avoid contention with other applications which may still possibly be running.
Receiving the XR_SESSION_STATE_RUNNING state
indicates that the runtime has detected the applications rendering loop and properly
synchronized it with the display’s refresh cycle. Achieving synchronization prior
to entering the XR_SESSION_STATE_VISIBLE state facilitates switching between
applications on a display frame boundary.
Receiving the XR_SESSION_STATE_VISIBLE state
indicates that the session is visible.
This can occur in many cases, one typical example is when a user switches
from one OpenXR application to the current one.
Applications that become visible should respond by simulating and
submitting frames.
Applications that lose visibility should stop submitting frames in
order to give CPU and GPU precedence to any other applications that need it.
This is a temporary event and usually indicates that either the user or
the runtime process has determine the session should be placed on the
back burner but may be brought back into visibility shortly.
Receiving the XR_SESSION_STATE_FOCUSED state
indicates the application is able to receive user input.
If a session is focused it receives all input from a user.
On the other hand, if a session does not have focus, it may receive no user
input.
The runtime must guarantee that at most one application has input
focus at any given time.
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.
It is important for apps to continue rendering when visible even when they
do not have focus.
Applications should only render input avatars (depictions of hands or other
tracked objects controlled by the user) when in the XR_SESSION_STATE_FOCUSED state.
The runtime must not render input avatars when an application is focused.
Receiving the XR_SESSION_STATE_STOPPING state
indicates that the runtime has determined that the application should halt
its rendering loop. A possible reason for this would be to minimize contention
between multiple applications.
Applications should exit their rendering loop and
call xrEndSession when in this state.
Receiving the XR_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.
Receiving the XR_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 xrDestroySession and may end its process
or decide to poll xrGetSystem at some reasonable cadence to
get a new XrSystemId, and re-initialize all graphics resources related to the new system,
and then create a new session using xrCreateSession.
After the event is queued, subsequent calls to functions that accept XrSession parameters
must no longer return any success code other than XR_SESSION_LOSS_PENDING for the given XrSession handle.
The XR_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. xrCreateSwapchain) when a lost session is pending, or if the runtime is not able to
provide the app a grace period, the runtime may return XR_ERROR_SESSION_LOST.
Thereafter, functions which accept XrSession parameters for the lost session may return
XR_ERROR_SESSION_LOST to indicate that the function failed and the given session was lost.
The XrSession 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
Document Notes
For more information, see the OpenXR Specification at URL
This page is extracted from the OpenXR Specification. Fixes and changes should be made to the Specification, not directly.
Copyright
Copyright (c) 2014-2019 Khronos Group. This work is licensed under a Creative Commons Attribution 4.0 International License.