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_SYNCHRONIZED = 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, begin its session
and synchronize its frame loop with the runtime.
The application does this by successfully calling
xrBeginSession and then running its frame loop by calling
xrWaitFrame, xrBeginFrame and xrEndFrame in a loop.
If the runtime wishes to return the session to the
XR_SESSION_STATE_IDLE
state, it must wait until the application calls
xrBeginSession.
After returning from the xrBeginSession call, the runtime may then
immediately transition forward through the
XR_SESSION_STATE_SYNCHRONIZED
state to the
XR_SESSION_STATE_STOPPING
state, to request that the application end
this session.
If the system supports a user engagement sensor and runtime is in
XR_SESSION_STATE_IDLE
state, the runtime may wait until the user
starts engaging with the device before transitioning to the
XR_SESSION_STATE_READY
state.
Receiving the XR_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
xrWaitFrame, xrBeginFrame and xrEndFrame, 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 xrWaitFrame returns an
XrFrameState 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 XR_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 XR_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 XR_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 xrEndSession
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 may transition to the XR_SESSION_STATE_STOPPING
state
when the user stops engaging with the device.
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 if they
do not have a non-XR user experience.
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 application 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
This page is extracted from the OpenXR Specification. Fixes and changes should be made to the Specification, not directly.
Copyright
Copyright 2014-2024, The Khronos Group Inc.
This work is licensed under a Creative Commons Attribution 4.0 International License.