matrixfurry.com
The open source OpenXR runtime
1// Copyright 2023, Collabora, Ltd.
2// Copyright 2024-2025, NVIDIA CORPORATION.
3// SPDX-License-Identifier: BSL-1.0
4/*!
5 * @file
6 * @brief Helper to implement @ref xrt_system.
7 * @author Jakob Bornecrantz <jakob@collabora.com>
8 * @ingroup aux_util
9 */
10
11#pragma once
12
13#include "xrt/xrt_system.h"
14#include "xrt/xrt_session.h"
15#include "os/os_threading.h"
16
17
18#ifdef __cplusplus
19extern "C" {
20#endif
21
22struct xrt_session;
23struct xrt_session_event_sink;
24union xrt_session_event;
25
26/*!
27 * A pair of @ref xrt_session and @ref xrt_session_event_sink that has been
28 * registered to this system, used to multiplex events to all sessions.
29 *
30 * @ingroup aux_util
31 */
32struct u_system_session_pair
33{
34 struct xrt_session *xs;
35 struct xrt_session_event_sink *xses;
36};
37
38/*!
39 * A helper to implement a @ref xrt_system, takes care of multiplexing events
40 * to sessions.
41 *
42 * @ingroup aux_util
43 * @implements xrt_system
44 */
45struct u_system
46{
47 struct xrt_system base;
48
49 //! Pushes events to all sessions created from this system.
50 struct xrt_session_event_sink broadcast;
51
52 struct
53 {
54 struct os_mutex mutex;
55
56 //! Number of session and event sink pairs.
57 uint32_t count;
58 //! Capacity of the session array.
59 uint32_t capacity;
60 //! Array of session and event sink pairs.
61 struct u_system_session_pair *pairs;
62 } sessions;
63
64 /*!
65 * Used to implement @ref xrt_system::create_session, can be NULL. This
66 * field should be set with @ref u_system_set_system_compositor.
67 */
68 struct xrt_system_compositor *xsysc;
69};
70
71/*!
72 * Create a @ref u_system, creates a fully working system. Objects wishing to
73 * use @ref u_system as a parent class should use @ref u_system_init.
74 *
75 * @public @memberof u_system
76 * @ingroup aux_util
77 * @see u_system_init
78 */
79struct u_system *
80u_system_create(void);
81
82/*!
83 * Inits a @ref u_system struct when used as a parent class, only to be used
84 * by base class. Not needed to be called if created by @ref u_system_create.
85 *
86 * @protected @memberof u_system
87 * @ingroup aux_util
88 */
89bool
90u_system_init(struct u_system *usys, void (*destroy_fn)(struct xrt_system *));
91
92/*!
93 * Finalizes a @ref u_system struct when used as a parent class, only to be used
94 * by base class. This will not free the @ref u_system pointer itself but will
95 * free any resources created by the default implementation functions. Not
96 * needed to be called if created by @ref u_system_create, instead use
97 * xrt_system::destroy.
98 *
99 * @protected @memberof u_system
100 * @ingroup aux_util
101 */
102void
103u_system_fini(struct u_system *usys);
104
105/*!
106 * Add a @ref xrt_session to be tracked and to receive multiplexed events.
107 *
108 * @public @memberof u_system
109 * @ingroup aux_util
110 */
111void
112u_system_add_session(struct u_system *usys, struct xrt_session *xs, struct xrt_session_event_sink *xses);
113
114/*!
115 * Remove a @ref xrt_session from tracking, it will no longer receive events,
116 * the given @p xses needs to match when it was added.
117 *
118 * @public @memberof u_system
119 * @ingroup aux_util
120 */
121void
122u_system_remove_session(struct u_system *usys, struct xrt_session *xs, struct xrt_session_event_sink *xses);
123
124/*!
125 * Broadcast event to all sessions under this system.
126 *
127 * @public @memberof u_system
128 * @ingroup aux_util
129 */
130void
131u_system_broadcast_event(struct u_system *usys, const union xrt_session_event *xse);
132
133/*!
134 * Set the system compositor, used in the @ref xrt_system_create_session call.
135 *
136 * @public @memberof u_system
137 * @ingroup aux_util
138 */
139void
140u_system_set_system_compositor(struct u_system *usys, struct xrt_system_compositor *xsysc);
141
142/*!
143 * Fill system properties.
144 *
145 * @public @memberof u_system
146 * @ingroup aux_util
147 */
148void
149u_system_fill_properties(struct u_system *usys, const char *name);
150
151/*!
152 * Destroy an @ref u_system_create allocated @ref u_system - helper function.
153 *
154 * @param[in,out] usys_ptr A pointer to the @ref u_system_create allocated
155 * struct pointer.
156 *
157 * Will destroy the system devices if @p *usys_ptr is not NULL. Will then set
158 * @p *usys_ptr to NULL.
159 *
160 * @public @memberof u_system
161 */
162static inline void
163u_system_destroy(struct u_system **usys_ptr)
164{
165 struct u_system *usys = *usys_ptr;
166 if (usys == NULL) {
167 return;
168 }
169
170 *usys_ptr = NULL;
171 usys->base.destroy(&usys->base);
172}
173
174
175#ifdef __cplusplus
176}
177#endif