Monado OpenXR Runtime
xrt_session.h
Go to the documentation of this file.
1// Copyright 2020-2023, Collabora, Ltd.
2// SPDX-License-Identifier: BSL-1.0
3/*!
4 * @file
5 * @brief Header for session object.
6 * @author Jakob Bornecrantz <jakob@collabora.com>
7 * @ingroup xrt_iface
8 */
9
10#pragma once
11
12#include "xrt/xrt_compiler.h"
13#include "xrt/xrt_defines.h"
14#include "xrt/xrt_space.h"
15
16
17#ifdef __cplusplus
18extern "C" {
19#endif
20
22
23
24/*
25 *
26 * Session events.
27 *
28 */
29
30/*!
31 * Type of a @ref xrt_session event.
32 *
33 * @see xrt_session_event
34 * @ingroup xrt_iface
35 */
37{
38 //! This session has no pending events.
40
41 //! The state of the session has changed.
43
44 //! The state of the primary session has changed.
46
47 //! The session is about to be lost.
49
50 //! The session has been lost.
52
53 //! The refresh rate of session (compositor) has changed.
55
56 //! A reference space for this session has a pending change.
58
59 //! The performance of the session has changed
61
62 //! The passthrough state of the session has changed
64
65 // ! The visibility mask of given view has changed
66 XRT_SESSION_EVENT_VISIBILITY_MASK_CHANGE = 9,
67
68 //! User presence has changed (hmd may have been put on or removed)
70};
71
72/*!
73 * Session state changes event, type @ref XRT_SESSION_EVENT_STATE_CHANGE.
74 *
75 * @see xrt_session_event
76 * @ingroup xrt_iface
77 */
79{
80 enum xrt_session_event_type type;
81 bool visible;
82 bool focused;
83};
84
85/*!
86 * Primary session state changes event,
87 * type @ref XRT_SESSION_EVENT_OVERLAY_CHANGE.
88 *
89 * @see xrt_session_event
90 * @ingroup xrt_iface
91 */
93{
94 enum xrt_session_event_type type;
95 bool primary_focused;
96};
97
98/*!
99 * Loss pending event, @ref XRT_SESSION_EVENT_LOSS_PENDING.
100 *
101 * @see xrt_session_event
102 * @ingroup xrt_iface
103 */
105{
106 enum xrt_session_event_type type;
107 int64_t loss_time_ns;
108};
109
110/*!
111 * Session lost event, type @ref XRT_SESSION_EVENT_LOST.
112 *
113 * @see xrt_session_event
114 * @ingroup xrt_iface
115 */
117{
118 enum xrt_session_event_type type;
119};
120
121/*!
122 * Display refresh rate of compositor changed event,
123 * type @ref XRT_SESSION_EVENT_DISPLAY_REFRESH_RATE_CHANGE.
124 *
125 * @see xrt_session_event
126 * @ingroup xrt_iface
127 */
129{
130 enum xrt_session_event_type type;
131 float from_display_refresh_rate_hz;
132 float to_display_refresh_rate_hz;
133};
134
135/*!
136 * Event that tells the application that the reference space has a pending
137 * change to it, maps to @p XrEventDataReferenceSpaceChangePending,
138 * type @ref XRT_SESSION_EVENT_REFERENCE_SPACE_CHANGE_PENDING.
139 *
140 * @see xrt_session_event
141 * @ingroup xrt_iface
142 */
144{
145 enum xrt_session_event_type event_type;
146 enum xrt_reference_space_type ref_type;
147 int64_t timestamp_ns;
148 struct xrt_pose pose_in_previous_space;
149 bool pose_valid;
150};
151
152/*!
153 * Performance metrics change event.
154 */
156{
157 enum xrt_session_event_type type;
158 enum xrt_perf_domain domain;
159 enum xrt_perf_sub_domain sub_domain;
160 enum xrt_perf_notify_level from_level;
161 enum xrt_perf_notify_level to_level;
162};
163
164/*!
165 * Passthrough state change event.
166 */
168{
169 enum xrt_session_event_type type;
170 enum xrt_passthrough_state state;
171};
172
173/*!
174 * Visibility mask changed event
175 */
177{
178 enum xrt_session_event_type type;
179 uint32_t view_index;
180};
181
182/*!
183 * User presence changed event
184 */
186{
187 enum xrt_session_event_type type;
188 bool is_user_present;
189};
190
191/*!
192 * Union of all session events, used to return multiple events through one call.
193 * Each event struct must start with a @ref xrt_session_event_type field.
194 *
195 * @see xrt_session_event
196 * @ingroup xrt_iface
197 */
199 enum xrt_session_event_type type;
201 struct xrt_session_event_state_change overlay;
202 struct xrt_session_event_loss_pending loss_pending;
203 struct xrt_session_event_lost lost;
206 struct xrt_session_event_perf_change performance;
209 struct xrt_session_event_user_presence_change presence_change;
210};
211
212/*!
213 * Used internally from producers of events to push events into session, some
214 * sinks might multiplex events to multiple sessions.
215 *
216 * @ingroup xrt_iface
217 */
219{
220 /*!
221 * Push one event to this sink, data is copied so pointer only needs to
222 * be valid for the duration of the call.
223 *
224 * @param xses Self-pointer to event sink.
225 * @param xse A pre-filled out event.
226 */
228};
229
230/*!
231 * @copydoc xrt_session_event_sink::push_event
232 *
233 * Helper for calling through the function pointer.
234 *
235 * @public @memberof xrt_session_event_sink
236 */
237XRT_CHECK_RESULT static inline xrt_result_t
239{
240 return xses->push_event(xses, xse);
241}
242
243
244/*
245 *
246 * Session.
247 *
248 */
249
250/*!
251 * The XRT representation of `XrSession`, this object does not have all of the
252 * functionality of a session, most are partitioned to the session level
253 * compositor object. Often this is @ref xrt_compositor_native, note that
254 * interface may also be a system level object depending in implementer.
255 *
256 * @ingroup xrt_iface
257 */
259{
260 /*!
261 * Poll a single event from this session, if no event is available then
262 * the type of the event will be @ref XRT_SESSION_EVENT_NONE.
263 *
264 * @param xs Pointer to self
265 * @param[out] out_xse Event to be returned.
266 */
268
269 /*!
270 * Destroy the session, must be destroyed after the native compositor.
271 *
272 * Code consuming this interface should use @ref xrt_session_destroy.
273 *
274 * @param xs Pointer to self
275 */
276 void (*destroy)(struct xrt_session *xs);
277};
278
279/*!
280 * @copydoc xrt_session::poll_events
281 *
282 * Helper for calling through the function pointer.
283 *
284 * @public @memberof xrt_session
285 */
286XRT_CHECK_RESULT static inline xrt_result_t
288{
289 return xs->poll_events(xs, out_xse);
290}
291
292/*!
293 * Destroy an xrt_session - helper function.
294 *
295 * @param[in,out] xs_ptr A pointer to the xrt_session struct pointer.
296 *
297 * Will destroy the system if `*xs_ptr` is not NULL. Will then set `*xs_ptr` to
298 * NULL.
299 *
300 * @public @memberof xrt_session
301 */
302static inline void
304{
305 struct xrt_session *xs = *xs_ptr;
306 if (xs == NULL) {
307 return;
308 }
309
310 *xs_ptr = NULL;
311 xs->destroy(xs);
312}
313
314
315#ifdef __cplusplus
316}
317#endif
xrt_session_event_type
Type of a xrt_session event.
Definition: xrt_session.h:37
enum xrt_result xrt_result_t
Result type used across Monado.
xrt_reference_space_type
Type of a OpenXR mapped reference space, maps to the semantic spaces on the xrt_space_overseer struct...
Definition: xrt_defines.h:596
@ XRT_SESSION_EVENT_PASSTHRU_STATE_CHANGE
The passthrough state of the session has changed.
Definition: xrt_session.h:63
@ XRT_SESSION_EVENT_REFERENCE_SPACE_CHANGE_PENDING
A reference space for this session has a pending change.
Definition: xrt_session.h:57
@ XRT_SESSION_EVENT_LOSS_PENDING
The session is about to be lost.
Definition: xrt_session.h:48
@ XRT_SESSION_EVENT_LOST
The session has been lost.
Definition: xrt_session.h:51
@ XRT_SESSION_EVENT_DISPLAY_REFRESH_RATE_CHANGE
The refresh rate of session (compositor) has changed.
Definition: xrt_session.h:54
@ XRT_SESSION_EVENT_USER_PRESENCE_CHANGE
User presence has changed (hmd may have been put on or removed)
Definition: xrt_session.h:69
@ XRT_SESSION_EVENT_STATE_CHANGE
The state of the session has changed.
Definition: xrt_session.h:42
@ XRT_SESSION_EVENT_OVERLAY_CHANGE
The state of the primary session has changed.
Definition: xrt_session.h:45
@ XRT_SESSION_EVENT_NONE
This session has no pending events.
Definition: xrt_session.h:39
@ XRT_SESSION_EVENT_PERFORMANCE_CHANGE
The performance of the session has changed.
Definition: xrt_session.h:60
Main compositor server interface.
Definition: xrt_compositor.h:2233
A pose composed of a position and orientation.
Definition: xrt_defines.h:463
Display refresh rate of compositor changed event, type XRT_SESSION_EVENT_DISPLAY_REFRESH_RATE_CHANGE.
Definition: xrt_session.h:129
Loss pending event, XRT_SESSION_EVENT_LOSS_PENDING.
Definition: xrt_session.h:105
Session lost event, type XRT_SESSION_EVENT_LOST.
Definition: xrt_session.h:117
Primary session state changes event, type XRT_SESSION_EVENT_OVERLAY_CHANGE.
Definition: xrt_session.h:93
Passthrough state change event.
Definition: xrt_session.h:168
Performance metrics change event.
Definition: xrt_session.h:156
Event that tells the application that the reference space has a pending change to it,...
Definition: xrt_session.h:144
Used internally from producers of events to push events into session, some sinks might multiplex even...
Definition: xrt_session.h:219
static XRT_CHECK_RESULT xrt_result_t xrt_session_event_sink_push(struct xrt_session_event_sink *xses, const union xrt_session_event *xse)
Push one event to this sink, data is copied so pointer only needs to be valid for the duration of the...
Definition: xrt_session.h:238
xrt_result_t(* push_event)(struct xrt_session_event_sink *xses, const union xrt_session_event *xse)
Push one event to this sink, data is copied so pointer only needs to be valid for the duration of the...
Definition: xrt_session.h:227
Session state changes event, type XRT_SESSION_EVENT_STATE_CHANGE.
Definition: xrt_session.h:79
User presence changed event.
Definition: xrt_session.h:186
Visibility mask changed event.
Definition: xrt_session.h:177
The XRT representation of XrSession, this object does not have all of the functionality of a session,...
Definition: xrt_session.h:259
static void xrt_session_destroy(struct xrt_session **xs_ptr)
Destroy an xrt_session - helper function.
Definition: xrt_session.h:303
xrt_result_t(* poll_events)(struct xrt_session *xs, union xrt_session_event *out_xse)
Poll a single event from this session, if no event is available then the type of the event will be XR...
Definition: xrt_session.h:267
static XRT_CHECK_RESULT xrt_result_t xrt_session_poll_events(struct xrt_session *xs, union xrt_session_event *out_xse)
Poll a single event from this session, if no event is available then the type of the event will be XR...
Definition: xrt_session.h:287
void(* destroy)(struct xrt_session *xs)
Destroy the session, must be destroyed after the native compositor.
Definition: xrt_session.h:276
Union of all session events, used to return multiple events through one call.
Definition: xrt_session.h:198
Header holding common defines.
Common defines and enums for XRT.
xrt_perf_notify_level
Performance level.
Definition: xrt_defines.h:2103
xrt_perf_domain
Domain type.
Definition: xrt_defines.h:2076
xrt_passthrough_state
Specify additional state change behavior.
Definition: xrt_defines.h:134
Header defining xrt space and space overseer.