Monado OpenXR Runtime
ipc_protocol.h
Go to the documentation of this file.
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_system.h"
20#include "xrt/xrt_session.h"
21#include "xrt/xrt_instance.h"
22#include "xrt/xrt_compositor.h"
23#include "xrt/xrt_device.h"
24#include "xrt/xrt_space.h"
25#include "xrt/xrt_tracking.h"
26#include "xrt/xrt_config_build.h"
27
28#include <assert.h>
29#include <sys/types.h>
30
31
32#define IPC_CRED_SIZE 1 // auth not implemented
33#define IPC_BUF_SIZE 512 // must be >= largest message length in bytes
34#define IPC_MAX_VIEWS 8 // max views we will return configs for
35#define IPC_MAX_FORMATS 32 // max formats our server-side compositor supports
36#define IPC_MAX_DEVICES 8 // max number of devices we will map using shared mem
37#define IPC_MAX_LAYERS XRT_MAX_LAYERS
38#define IPC_MAX_SLOTS 128
39#define IPC_MAX_CLIENTS 8
40#define IPC_MAX_RAW_VIEWS 32 // Max views that we can get, artificial limit.
41#define IPC_EVENT_QUEUE_SIZE 32
42
43#define IPC_SHARED_MAX_INPUTS 1024
44#define IPC_SHARED_MAX_OUTPUTS 128
45#define IPC_SHARED_MAX_BINDINGS 64
46
47// example: v21.0.0-560-g586d33b5
48#define IPC_VERSION_NAME_LEN 64
49
50#if defined(XRT_OS_WINDOWS) && !defined(XRT_ENV_MINGW)
51typedef int pid_t;
52#endif
53
54/*
55 *
56 * Shared memory structs.
57 *
58 */
59
60/*!
61 * A tracking in the shared memory area.
62 *
63 * @ingroup ipc
64 */
66{
67 //! For debugging.
68 char name[XRT_TRACKING_NAME_LEN];
69
70 //! What can the state tracker expect from this tracking system.
72
73 //! Initial offset of the tracking origin.
75};
76
77static_assert(sizeof(struct ipc_shared_tracking_origin) == 288,
78 "invalid structure size, maybe different 32/64 bits sizes or padding");
79
80/*!
81 * A binding in the shared memory area.
82 *
83 * @ingroup ipc
84 */
86{
87 enum xrt_device_name name;
88
89 //! Number of inputs.
90 uint32_t input_count;
91 //! Offset into the array of pairs where this input bindings starts.
93
94 //! Number of outputs.
95 uint32_t output_count;
96 //! Offset into the array of pairs where this output bindings starts.
98};
99
100static_assert(sizeof(struct ipc_shared_binding_profile) == 20,
101 "invalid structure size, maybe different 32/64 bits sizes or padding");
102
103/*!
104 * A device in the shared memory area.
105 *
106 * @ingroup ipc
107 */
109{
110 //! Enum identifier of the device.
112 enum xrt_device_type device_type;
113
114 //! Which tracking system origin is this device attached to.
116
117 //! A string describing the device.
118 char str[XRT_DEVICE_NAME_LEN];
119
120 //! A unique identifier. Persistent across configurations, if possible.
121 char serial[XRT_DEVICE_NAME_LEN];
122
123 //! Number of bindings.
125 //! 'Offset' into the array of bindings where the bindings starts.
127
128 //! Number of inputs.
129 uint32_t input_count;
130 //! 'Offset' into the array of inputs where the inputs starts.
132
133 //! Number of outputs.
134 uint32_t output_count;
135 //! 'Offset' into the array of outputs where the outputs starts.
137
138 bool orientation_tracking_supported;
139 bool position_tracking_supported;
140 bool hand_tracking_supported;
141 bool eye_gaze_supported;
142 bool face_tracking_supported;
143 bool body_tracking_supported;
144 bool force_feedback_supported;
145 bool form_factor_check_supported;
146 bool stage_supported;
147 bool battery_status_supported;
148 bool planes_supported;
149 enum xrt_plane_detection_capability_flags_ext plane_capability_flags;
150};
151
152static_assert(sizeof(struct ipc_shared_device) == 564,
153 "invalid structure size, maybe different 32/64 bits sizes or padding");
154
155/*!
156 * Data for a single composition layer.
157 *
158 * Similar in function to @ref comp_layer
159 *
160 * @ingroup ipc
161 */
163{
164 //! @todo what is this used for?
165 uint32_t xdev_id;
166
167 /*!
168 * Up to two indices of swapchains to use.
169 *
170 * How many are actually used depends on the value of @p data.type
171 */
172 uint32_t swapchain_ids[XRT_MAX_VIEWS * 2];
173
174 /*!
175 * All basic (trivially-serializable) data associated with a layer,
176 * aside from which swapchain(s) are used.
177 */
179};
180
181static_assert(sizeof(struct ipc_layer_entry) == 392,
182 "invalid structure size, maybe different 32/64 bits sizes or padding");
183
184/*!
185 * Render state for a single client, including all layers.
186 *
187 * @ingroup ipc
188 */
190{
191 struct xrt_layer_frame_data data;
192 uint32_t layer_count;
193 struct ipc_layer_entry layers[IPC_MAX_LAYERS];
194};
195
196static_assert(sizeof(struct ipc_layer_slot) == IPC_MAX_LAYERS * sizeof(struct ipc_layer_entry) + 32,
197 "invalid structure size, maybe different 32/64 bits sizes or padding");
198
199/*!
200 * A big struct that contains all data that is shared to a client, no pointers
201 * allowed in this. To get the inputs of a device you go:
202 *
203 * ```C++
204 * struct xrt_input *
205 * helper(struct ipc_shared_memory *ism, uint32_t device_id, uint32_t input)
206 * {
207 * uint32_t index = ism->isdevs[device_id]->first_input_index + input;
208 * return &ism->inputs[index];
209 * }
210 * ```
211 *
212 * @ingroup ipc
213 */
215{
216 /*!
217 * The git revision of the service, used by clients to detect version mismatches.
218 */
219 char u_git_tag[IPC_VERSION_NAME_LEN];
220
221 /*!
222 * Number of elements in @ref itracks that are populated/valid.
223 */
224 uint32_t itrack_count;
225
226 /*!
227 * @brief Array of shared tracking origin data.
228 *
229 * Only @ref itrack_count elements are populated/valid.
230 */
232
233 /*!
234 * Number of elements in @ref isdevs that are populated/valid.
235 */
236 uint32_t isdev_count;
237
238 /*!
239 * @brief Array of shared data per device.
240 *
241 * Only @ref isdev_count elements are populated/valid.
242 */
244
245 /*!
246 * Various roles for the devices.
247 */
248 struct
249 {
250 int32_t head;
251 int32_t eyes;
252 int32_t face;
253 int32_t body;
254
255 struct
256 {
257 int32_t left;
258 int32_t right;
259 } hand_tracking;
261
262 struct
263 {
264 struct
265 {
266 /*!
267 * Pixel properties of this display, not in absolute
268 * screen coordinates that the compositor sees. So
269 * before any rotation is applied by xrt_view::rot.
270 *
271 * The xrt_view::display::w_pixels &
272 * xrt_view::display::h_pixels become the recommended
273 * image size for this view.
274 *
275 * @todo doesn't account for overfill for timewarp or
276 * distortion?
277 */
278 struct
279 {
280 uint32_t w_pixels;
281 uint32_t h_pixels;
283 } views[2];
284 // view count
285 uint32_t view_count;
286 enum xrt_blend_mode blend_modes[XRT_MAX_DEVICE_BLEND_MODES];
287 uint32_t blend_mode_count;
288 } hmd;
289
290 struct xrt_input inputs[IPC_SHARED_MAX_INPUTS];
291
292 struct xrt_output outputs[IPC_SHARED_MAX_OUTPUTS];
293
294 struct ipc_shared_binding_profile binding_profiles[IPC_SHARED_MAX_BINDINGS];
295 struct xrt_binding_input_pair input_pairs[IPC_SHARED_MAX_INPUTS];
296 struct xrt_binding_output_pair output_pairs[IPC_SHARED_MAX_OUTPUTS];
297
298 struct ipc_layer_slot slots[IPC_MAX_SLOTS];
299
300 uint64_t startup_timestamp;
301 struct xrt_plane_detector_begin_info_ext plane_begin_info_ext;
302};
303
304static_assert(sizeof(struct ipc_shared_memory) == 6499920,
305 "invalid structure size, maybe different 32/64 bits sizes or padding");
306
307/*!
308 * Initial info from a client when it connects.
309 */
311{
312 pid_t pid;
313 struct xrt_application_info info;
314};
315
316static_assert(sizeof(struct ipc_client_description) == 140,
317 "invalid structure size, maybe different 32/64 bits sizes or padding");
318
320{
321 uint32_t ids[IPC_MAX_CLIENTS];
322 uint32_t id_count;
323};
324
325static_assert(sizeof(struct ipc_client_list) == 36,
326 "invalid structure size, maybe different 32/64 bits sizes or padding");
327
328/*!
329 * State for a connected application.
330 *
331 * @ingroup ipc
332 */
334{
335 // Stable and unique ID of the client, only unique within this instance.
336 uint32_t id;
337
338 bool primary_application;
339 bool session_active;
340 bool session_visible;
341 bool session_focused;
342 bool session_overlay;
343 bool io_active;
344 uint32_t z_order;
345 pid_t pid;
346 struct xrt_application_info info;
347};
348
349static_assert(sizeof(struct ipc_app_state) == 156,
350 "invalid structure size, maybe different 32/64 bits sizes or padding");
351
352
353/*!
354 * Arguments for creating swapchains from native images.
355 */
357{
358 uint32_t sizes[XRT_MAX_SWAPCHAIN_IMAGES];
359};
360
361static_assert(sizeof(struct ipc_arg_swapchain_from_native) == 32,
362 "invalid structure size, maybe different 32/64 bits sizes or padding");
363
364/*!
365 * Arguments for xrt_device::get_view_poses with two views.
366 */
368{
369 struct xrt_fov fovs[XRT_MAX_VIEWS];
370 struct xrt_pose poses[XRT_MAX_VIEWS];
371 struct xrt_space_relation head_relation;
372};
373
374static_assert(sizeof(struct ipc_info_get_view_poses_2) == 144,
375 "invalid structure size, maybe different 32/64 bits sizes or padding");
xrt_plane_detection_capability_flags_ext
Caps for a plane detector, see xrt_device.
Definition: xrt_plane_detector.h:30
xrt_blend_mode
Blend mode that the device supports, exact mirror of XrEnvironmentBlendMode.
Definition: xrt_defines.h:109
#define XRT_SYSTEM_MAX_DEVICES
Maximum number of devices simultaneously usable by an implementation of xrt_system_devices.
Definition: xrt_system.h:142
#define XRT_MAX_SWAPCHAIN_IMAGES
Max swapchain images, artificial limit.
Definition: xrt_limits.h:34
xrt_tracking_type
What kind of tracking system is this.
Definition: xrt_tracking.h:45
xrt_device_type
How an xrt_device can be used.
Definition: xrt_defines.h:788
State for a connected application.
Definition: ipc_protocol.h:334
Arguments for creating swapchains from native images.
Definition: ipc_protocol.h:357
Initial info from a client when it connects.
Definition: ipc_protocol.h:311
Definition: ipc_protocol.h:320
Arguments for xrt_device::get_view_poses with two views.
Definition: ipc_protocol.h:368
Data for a single composition layer.
Definition: ipc_protocol.h:163
struct xrt_layer_data data
All basic (trivially-serializable) data associated with a layer, aside from which swapchain(s) are us...
Definition: ipc_protocol.h:178
uint32_t swapchain_ids[XRT_MAX_VIEWS *2]
Up to two indices of swapchains to use.
Definition: ipc_protocol.h:172
uint32_t xdev_id
Definition: ipc_protocol.h:165
Render state for a single client, including all layers.
Definition: ipc_protocol.h:190
A binding in the shared memory area.
Definition: ipc_protocol.h:86
uint32_t output_count
Number of outputs.
Definition: ipc_protocol.h:95
uint32_t input_count
Number of inputs.
Definition: ipc_protocol.h:90
uint32_t first_input_index
Offset into the array of pairs where this input bindings starts.
Definition: ipc_protocol.h:92
uint32_t first_output_index
Offset into the array of pairs where this output bindings starts.
Definition: ipc_protocol.h:97
A device in the shared memory area.
Definition: ipc_protocol.h:109
uint32_t first_input_index
'Offset' into the array of inputs where the inputs starts.
Definition: ipc_protocol.h:131
uint32_t binding_profile_count
Number of bindings.
Definition: ipc_protocol.h:124
uint32_t first_binding_profile_index
'Offset' into the array of bindings where the bindings starts.
Definition: ipc_protocol.h:126
uint32_t input_count
Number of inputs.
Definition: ipc_protocol.h:129
uint32_t output_count
Number of outputs.
Definition: ipc_protocol.h:134
uint32_t first_output_index
'Offset' into the array of outputs where the outputs starts.
Definition: ipc_protocol.h:136
char str[XRT_DEVICE_NAME_LEN]
A string describing the device.
Definition: ipc_protocol.h:118
uint32_t tracking_origin_index
Which tracking system origin is this device attached to.
Definition: ipc_protocol.h:115
char serial[XRT_DEVICE_NAME_LEN]
A unique identifier. Persistent across configurations, if possible.
Definition: ipc_protocol.h:121
enum xrt_device_name name
Enum identifier of the device.
Definition: ipc_protocol.h:111
A big struct that contains all data that is shared to a client, no pointers allowed in this.
Definition: ipc_protocol.h:215
struct ipc_shared_memory::@245::@247::@248 display
Pixel properties of this display, not in absolute screen coordinates that the compositor sees.
uint32_t itrack_count
Number of elements in itracks that are populated/valid.
Definition: ipc_protocol.h:224
char u_git_tag[64]
The git revision of the service, used by clients to detect version mismatches.
Definition: ipc_protocol.h:219
struct ipc_shared_memory::@244 roles
Various roles for the devices.
struct ipc_shared_tracking_origin itracks[XRT_SYSTEM_MAX_DEVICES]
Array of shared tracking origin data.
Definition: ipc_protocol.h:231
struct ipc_shared_device isdevs[XRT_SYSTEM_MAX_DEVICES]
Array of shared data per device.
Definition: ipc_protocol.h:243
uint32_t isdev_count
Number of elements in isdevs that are populated/valid.
Definition: ipc_protocol.h:236
A tracking in the shared memory area.
Definition: ipc_protocol.h:66
char name[XRT_TRACKING_NAME_LEN]
For debugging.
Definition: ipc_protocol.h:68
enum xrt_tracking_type type
What can the state tracker expect from this tracking system.
Definition: ipc_protocol.h:71
struct xrt_pose offset
Initial offset of the tracking origin.
Definition: ipc_protocol.h:74
Non-process-specific information provided by the application at instance create time.
Definition: xrt_instance.h:72
A binding pair, going from a binding point to a device input.
Definition: xrt_device.h:193
A binding pair, going from a binding point to a device output.
Definition: xrt_device.h:204
Describes a projection matrix fov.
Definition: xrt_defines.h:488
A single named input, that sits on a xrt_device.
Definition: xrt_device.h:164
All the pure data values associated with a composition layer.
Definition: xrt_compositor.h:396
Per frame data for the layer submission calls, used in xrt_compositor::layer_begin.
Definition: xrt_compositor.h:482
A single named output, that sits on a xrt_device.
Definition: xrt_device.h:182
A query for a plane.
Definition: xrt_plane_detector.h:97
A pose composed of a position and orientation.
Definition: xrt_defines.h:467
A relation with two spaces, includes velocity and acceleration.
Definition: xrt_defines.h:659
Header holding common defines.
Header declaring XRT graphics interfaces.
Common defines and enums for XRT.
xrt_device_name
A enum that is used to name devices so that the state trackers can reason about the devices easier.
Definition: xrt_defines.h:714
Header defining an xrt display or controller device.
Header for xrt_instance object.
Header for limits of the XRT interfaces.
Internal result type for XRT.
Header for session object.
Header defining xrt space and space overseer.
Header for system objects.
Header defining the tracking system integration in Monado.