matrixfurry.com
The open source OpenXR runtime
1// Copyright 2020-2024 Collabora, Ltd.
2// SPDX-License-Identifier: BSL-1.0
3/*!
4 * @file
5 * @brief Common protocol definition.
6 * @author Pete Black <pblack@collabora.com>
7 * @author Jakob Bornecrantz <jakob@collabora.com>
8 * @author Korcan Hussein <korcan.hussein@collabora.com>
9 * @ingroup ipc_shared
10 */
11
12#pragma once
13
14#include "xrt/xrt_limits.h"
15#include "xrt/xrt_compiler.h"
16#include "xrt/xrt_compositor.h"
17#include "xrt/xrt_results.h"
18#include "xrt/xrt_defines.h"
19#include "xrt/xrt_future.h"
20#include "xrt/xrt_system.h"
21#include "xrt/xrt_session.h"
22#include "xrt/xrt_instance.h"
23#include "xrt/xrt_compositor.h"
24#include "xrt/xrt_device.h"
25#include "xrt/xrt_space.h"
26#include "xrt/xrt_tracking.h"
27#include "xrt/xrt_config_build.h"
28
29#include <assert.h>
30#include <sys/types.h>
31
32
33#define IPC_CRED_SIZE 1 // auth not implemented
34#define IPC_BUF_SIZE 512 // must be >= largest message length in bytes
35#define IPC_MAX_VIEWS 8 // max views we will return configs for
36#define IPC_MAX_FORMATS 32 // max formats our server-side compositor supports
37#define IPC_MAX_DEVICES 8 // max number of devices we will map using shared mem
38#define IPC_MAX_LAYERS XRT_MAX_LAYERS
39#define IPC_MAX_SLOTS 128
40#define IPC_MAX_CLIENTS 8
41#define IPC_MAX_RAW_VIEWS 32 // Max views that we can get, artificial limit.
42#define IPC_EVENT_QUEUE_SIZE 32
43
44#define IPC_SHARED_MAX_INPUTS 1024
45#define IPC_SHARED_MAX_OUTPUTS 128
46#define IPC_SHARED_MAX_BINDINGS 64
47
48// example: v21.0.0-560-g586d33b5
49#define IPC_VERSION_NAME_LEN 64
50
51#if defined(XRT_OS_WINDOWS) && !defined(XRT_ENV_MINGW)
52typedef int pid_t;
53#endif
54
55/*
56 *
57 * Shared memory structs.
58 *
59 */
60
61/*!
62 * A tracking in the shared memory area.
63 *
64 * @ingroup ipc
65 */
66struct ipc_shared_tracking_origin
67{
68 //! For debugging.
69 char name[XRT_TRACKING_NAME_LEN];
70
71 //! What can the state tracker expect from this tracking system.
72 enum xrt_tracking_type type;
73
74 //! Initial offset of the tracking origin.
75 struct xrt_pose offset;
76};
77
78/*!
79 * A binding in the shared memory area.
80 *
81 * @ingroup ipc
82 */
83struct ipc_shared_binding_profile
84{
85 enum xrt_device_name name;
86
87 //! Number of inputs.
88 uint32_t input_count;
89 //! Offset into the array of pairs where this input bindings starts.
90 uint32_t first_input_index;
91
92 //! Number of outputs.
93 uint32_t output_count;
94 //! Offset into the array of pairs where this output bindings starts.
95 uint32_t first_output_index;
96};
97
98/*!
99 * A device in the shared memory area.
100 *
101 * @ingroup ipc
102 */
103struct ipc_shared_device
104{
105 //! Enum identifier of the device.
106 enum xrt_device_name name;
107 enum xrt_device_type device_type;
108
109 //! Which tracking system origin is this device attached to.
110 uint32_t tracking_origin_index;
111
112 //! A string describing the device.
113 char str[XRT_DEVICE_NAME_LEN];
114
115 //! A unique identifier. Persistent across configurations, if possible.
116 char serial[XRT_DEVICE_NAME_LEN];
117
118 //! Number of bindings.
119 uint32_t binding_profile_count;
120 //! 'Offset' into the array of bindings where the bindings starts.
121 uint32_t first_binding_profile_index;
122
123 //! Number of inputs.
124 uint32_t input_count;
125 //! 'Offset' into the array of inputs where the inputs starts.
126 uint32_t first_input_index;
127
128 //! Number of outputs.
129 uint32_t output_count;
130 //! 'Offset' into the array of outputs where the outputs starts.
131 uint32_t first_output_index;
132
133 //! The supported fields.
134 struct xrt_device_supported supported;
135};
136
137/*!
138 * Data for a single composition layer.
139 *
140 * Similar in function to @ref comp_layer
141 *
142 * @ingroup ipc
143 */
144struct ipc_layer_entry
145{
146 //! @todo what is this used for?
147 uint32_t xdev_id;
148
149 /*!
150 * Up to two indices of swapchains to use.
151 *
152 * How many are actually used depends on the value of @p data.type
153 */
154 uint32_t swapchain_ids[XRT_MAX_VIEWS * 2];
155
156 /*!
157 * All basic (trivially-serializable) data associated with a layer,
158 * aside from which swapchain(s) are used.
159 */
160 struct xrt_layer_data data;
161};
162
163/*!
164 * Render state for a single client, including all layers.
165 *
166 * @ingroup ipc
167 */
168struct ipc_layer_slot
169{
170 struct xrt_layer_frame_data data;
171 uint32_t layer_count;
172 struct ipc_layer_entry layers[IPC_MAX_LAYERS];
173};
174
175/*!
176 * A big struct that contains all data that is shared to a client, no pointers
177 * allowed in this. To get the inputs of a device you go:
178 *
179 * ```C++
180 * struct xrt_input *
181 * helper(struct ipc_shared_memory *ism, uint32_t device_id, uint32_t input)
182 * {
183 * uint32_t index = ism->isdevs[device_id]->first_input_index + input;
184 * return &ism->inputs[index];
185 * }
186 * ```
187 *
188 * @ingroup ipc
189 */
190struct ipc_shared_memory
191{
192 /*!
193 * The git revision of the service, used by clients to detect version mismatches.
194 */
195 char u_git_tag[IPC_VERSION_NAME_LEN];
196
197 /*!
198 * Number of elements in @ref itracks that are populated/valid.
199 */
200 uint32_t itrack_count;
201
202 /*!
203 * @brief Array of shared tracking origin data.
204 *
205 * Only @ref itrack_count elements are populated/valid.
206 */
207 struct ipc_shared_tracking_origin itracks[XRT_SYSTEM_MAX_DEVICES];
208
209 /*!
210 * Number of elements in @ref isdevs that are populated/valid.
211 */
212 uint32_t isdev_count;
213
214 /*!
215 * @brief Array of shared data per device.
216 *
217 * Only @ref isdev_count elements are populated/valid.
218 */
219 struct ipc_shared_device isdevs[XRT_SYSTEM_MAX_DEVICES];
220
221 /*!
222 * Various roles for the devices.
223 */
224 struct
225 {
226 int32_t head;
227 int32_t eyes;
228 int32_t face;
229 int32_t body;
230
231 struct
232 {
233 struct
234 {
235 int32_t left;
236 int32_t right;
237 } unobstructed;
238
239 struct
240 {
241 int32_t left;
242 int32_t right;
243 } conforming;
244 } hand_tracking;
245 } roles;
246
247 struct
248 {
249 struct
250 {
251 /*!
252 * Pixel properties of this display, not in absolute
253 * screen coordinates that the compositor sees. So
254 * before any rotation is applied by xrt_view::rot.
255 *
256 * The xrt_view::display::w_pixels &
257 * xrt_view::display::h_pixels become the recommended
258 * image size for this view.
259 *
260 * @todo doesn't account for overfill for timewarp or
261 * distortion?
262 */
263 struct
264 {
265 uint32_t w_pixels;
266 uint32_t h_pixels;
267 } display;
268 } views[2];
269 // view count
270 uint32_t view_count;
271 enum xrt_blend_mode blend_modes[XRT_MAX_DEVICE_BLEND_MODES];
272 uint32_t blend_mode_count;
273 } hmd;
274
275 struct xrt_input inputs[IPC_SHARED_MAX_INPUTS];
276
277 struct xrt_output outputs[IPC_SHARED_MAX_OUTPUTS];
278
279 struct ipc_shared_binding_profile binding_profiles[IPC_SHARED_MAX_BINDINGS];
280 struct xrt_binding_input_pair input_pairs[IPC_SHARED_MAX_INPUTS];
281 struct xrt_binding_output_pair output_pairs[IPC_SHARED_MAX_OUTPUTS];
282
283 struct ipc_layer_slot slots[IPC_MAX_SLOTS];
284
285 uint64_t startup_timestamp;
286 struct xrt_plane_detector_begin_info_ext plane_begin_info_ext;
287};
288
289/*!
290 * Initial info from a client when it connects.
291 */
292struct ipc_client_description
293{
294 pid_t pid;
295 struct xrt_application_info info;
296};
297
298struct ipc_client_list
299{
300 uint32_t ids[IPC_MAX_CLIENTS];
301 uint32_t id_count;
302};
303
304/*!
305 * State for a connected application.
306 *
307 * @ingroup ipc
308 */
309struct ipc_app_state
310{
311 // Stable and unique ID of the client, only unique within this instance.
312 uint32_t id;
313
314 bool primary_application;
315 bool session_active;
316 bool session_visible;
317 bool session_focused;
318 bool session_overlay;
319 bool io_active;
320 uint32_t z_order;
321 pid_t pid;
322 struct xrt_application_info info;
323};
324
325
326/*!
327 * Arguments for creating swapchains from native images.
328 */
329struct ipc_arg_swapchain_from_native
330{
331 uint32_t sizes[XRT_MAX_SWAPCHAIN_IMAGES];
332};
333
334/*!
335 * Arguments for xrt_device::get_view_poses with two views.
336 */
337struct ipc_info_get_view_poses_2
338{
339 struct xrt_fov fovs[XRT_MAX_VIEWS];
340 struct xrt_pose poses[XRT_MAX_VIEWS];
341 struct xrt_space_relation head_relation;
342};
343
344struct ipc_pcm_haptic_buffer
345{
346 uint32_t num_samples;
347 float sample_rate;
348 bool append;
349};