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 //! The supported fields.
140};
141
142static_assert(sizeof(struct ipc_shared_device) == 568,
143 "invalid structure size, maybe different 32/64 bits sizes or padding");
144
145/*!
146 * Data for a single composition layer.
147 *
148 * Similar in function to @ref comp_layer
149 *
150 * @ingroup ipc
151 */
153{
154 //! @todo what is this used for?
155 uint32_t xdev_id;
156
157 /*!
158 * Up to two indices of swapchains to use.
159 *
160 * How many are actually used depends on the value of @p data.type
161 */
162 uint32_t swapchain_ids[XRT_MAX_VIEWS * 2];
163
164 /*!
165 * All basic (trivially-serializable) data associated with a layer,
166 * aside from which swapchain(s) are used.
167 */
169};
170
171static_assert(sizeof(struct ipc_layer_entry) == 392,
172 "invalid structure size, maybe different 32/64 bits sizes or padding");
173
174/*!
175 * Render state for a single client, including all layers.
176 *
177 * @ingroup ipc
178 */
180{
181 struct xrt_layer_frame_data data;
182 uint32_t layer_count;
183 struct ipc_layer_entry layers[IPC_MAX_LAYERS];
184};
185
186static_assert(sizeof(struct ipc_layer_slot) == IPC_MAX_LAYERS * sizeof(struct ipc_layer_entry) + 32,
187 "invalid structure size, maybe different 32/64 bits sizes or padding");
188
189/*!
190 * A big struct that contains all data that is shared to a client, no pointers
191 * allowed in this. To get the inputs of a device you go:
192 *
193 * ```C++
194 * struct xrt_input *
195 * helper(struct ipc_shared_memory *ism, uint32_t device_id, uint32_t input)
196 * {
197 * uint32_t index = ism->isdevs[device_id]->first_input_index + input;
198 * return &ism->inputs[index];
199 * }
200 * ```
201 *
202 * @ingroup ipc
203 */
205{
206 /*!
207 * The git revision of the service, used by clients to detect version mismatches.
208 */
209 char u_git_tag[IPC_VERSION_NAME_LEN];
210
211 /*!
212 * Number of elements in @ref itracks that are populated/valid.
213 */
214 uint32_t itrack_count;
215
216 /*!
217 * @brief Array of shared tracking origin data.
218 *
219 * Only @ref itrack_count elements are populated/valid.
220 */
222
223 /*!
224 * Number of elements in @ref isdevs that are populated/valid.
225 */
226 uint32_t isdev_count;
227
228 /*!
229 * @brief Array of shared data per device.
230 *
231 * Only @ref isdev_count elements are populated/valid.
232 */
234
235 /*!
236 * Various roles for the devices.
237 */
238 struct
239 {
240 int32_t head;
241 int32_t eyes;
242 int32_t face;
243 int32_t body;
244
245 struct
246 {
247 struct
248 {
249 int32_t left;
250 int32_t right;
251 } unobstructed;
252
253 struct
254 {
255 int32_t left;
256 int32_t right;
257 } conforming;
258 } hand_tracking;
260
261 struct
262 {
263 struct
264 {
265 /*!
266 * Pixel properties of this display, not in absolute
267 * screen coordinates that the compositor sees. So
268 * before any rotation is applied by xrt_view::rot.
269 *
270 * The xrt_view::display::w_pixels &
271 * xrt_view::display::h_pixels become the recommended
272 * image size for this view.
273 *
274 * @todo doesn't account for overfill for timewarp or
275 * distortion?
276 */
277 struct
278 {
279 uint32_t w_pixels;
280 uint32_t h_pixels;
282 } views[2];
283 // view count
284 uint32_t view_count;
285 enum xrt_blend_mode blend_modes[XRT_MAX_DEVICE_BLEND_MODES];
286 uint32_t blend_mode_count;
287 } hmd;
288
289 struct xrt_input inputs[IPC_SHARED_MAX_INPUTS];
290
291 struct xrt_output outputs[IPC_SHARED_MAX_OUTPUTS];
292
293 struct ipc_shared_binding_profile binding_profiles[IPC_SHARED_MAX_BINDINGS];
294 struct xrt_binding_input_pair input_pairs[IPC_SHARED_MAX_INPUTS];
295 struct xrt_binding_output_pair output_pairs[IPC_SHARED_MAX_OUTPUTS];
296
297 struct ipc_layer_slot slots[IPC_MAX_SLOTS];
298
299 uint64_t startup_timestamp;
300 struct xrt_plane_detector_begin_info_ext plane_begin_info_ext;
301};
302
303static_assert(sizeof(struct ipc_shared_memory) == 6500056,
304 "invalid structure size, maybe different 32/64 bits sizes or padding");
305
306/*!
307 * Initial info from a client when it connects.
308 */
310{
311 pid_t pid;
312 struct xrt_application_info info;
313};
314
315static_assert(sizeof(struct ipc_client_description) == 140,
316 "invalid structure size, maybe different 32/64 bits sizes or padding");
317
319{
320 uint32_t ids[IPC_MAX_CLIENTS];
321 uint32_t id_count;
322};
323
324static_assert(sizeof(struct ipc_client_list) == 36,
325 "invalid structure size, maybe different 32/64 bits sizes or padding");
326
327/*!
328 * State for a connected application.
329 *
330 * @ingroup ipc
331 */
333{
334 // Stable and unique ID of the client, only unique within this instance.
335 uint32_t id;
336
337 bool primary_application;
338 bool session_active;
339 bool session_visible;
340 bool session_focused;
341 bool session_overlay;
342 bool io_active;
343 uint32_t z_order;
344 pid_t pid;
345 struct xrt_application_info info;
346};
347
348static_assert(sizeof(struct ipc_app_state) == 156,
349 "invalid structure size, maybe different 32/64 bits sizes or padding");
350
351
352/*!
353 * Arguments for creating swapchains from native images.
354 */
356{
357 uint32_t sizes[XRT_MAX_SWAPCHAIN_IMAGES];
358};
359
360static_assert(sizeof(struct ipc_arg_swapchain_from_native) == 32,
361 "invalid structure size, maybe different 32/64 bits sizes or padding");
362
363/*!
364 * Arguments for xrt_device::get_view_poses with two views.
365 */
367{
368 struct xrt_fov fovs[XRT_MAX_VIEWS];
369 struct xrt_pose poses[XRT_MAX_VIEWS];
370 struct xrt_space_relation head_relation;
371};
372
373static_assert(sizeof(struct ipc_info_get_view_poses_2) == 144,
374 "invalid structure size, maybe different 32/64 bits sizes or padding");
375
377{
378 uint32_t num_samples;
379 float sample_rate;
380 bool append;
381};
xrt_blend_mode
Blend mode that the device supports, exact mirror of XrEnvironmentBlendMode.
Definition: xrt_defines.h:110
#define XRT_SYSTEM_MAX_DEVICES
Maximum number of devices simultaneously usable by an implementation of xrt_system_devices.
Definition: xrt_system.h:141
#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:783
State for a connected application.
Definition: ipc_protocol.h:333
Arguments for creating swapchains from native images.
Definition: ipc_protocol.h:356
Initial info from a client when it connects.
Definition: ipc_protocol.h:310
Definition: ipc_protocol.h:319
Arguments for xrt_device::get_view_poses with two views.
Definition: ipc_protocol.h:367
Data for a single composition layer.
Definition: ipc_protocol.h:153
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:168
uint32_t swapchain_ids[XRT_MAX_VIEWS *2]
Up to two indices of swapchains to use.
Definition: ipc_protocol.h:162
uint32_t xdev_id
Definition: ipc_protocol.h:155
Render state for a single client, including all layers.
Definition: ipc_protocol.h:180
Definition: ipc_protocol.h:377
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
struct xrt_device_supported supported
The supported fields.
Definition: ipc_protocol.h:139
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:205
struct ipc_shared_memory::@255::@259::@260 display
Pixel properties of this display, not in absolute screen coordinates that the compositor sees.
struct ipc_shared_memory::@254 roles
Various roles for the devices.
uint32_t itrack_count
Number of elements in itracks that are populated/valid.
Definition: ipc_protocol.h:214
char u_git_tag[64]
The git revision of the service, used by clients to detect version mismatches.
Definition: ipc_protocol.h:209
struct ipc_shared_tracking_origin itracks[XRT_SYSTEM_MAX_DEVICES]
Array of shared tracking origin data.
Definition: ipc_protocol.h:221
struct ipc_shared_device isdevs[XRT_SYSTEM_MAX_DEVICES]
Array of shared data per device.
Definition: ipc_protocol.h:233
uint32_t isdev_count
Number of elements in isdevs that are populated/valid.
Definition: ipc_protocol.h:226
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:192
A binding pair, going from a binding point to a device output.
Definition: xrt_device.h:203
Static data of supported features of the xrt_device this struct sits on.
Definition: xrt_device.h:254
Describes a projection matrix fov.
Definition: xrt_defines.h:483
A single named input, that sits on a xrt_device.
Definition: xrt_device.h:163
All the pure data values associated with a composition layer.
Definition: xrt_compositor.h:394
Per frame data for the layer submission calls, used in xrt_compositor::layer_begin.
Definition: xrt_compositor.h:480
A single named output, that sits on a xrt_device.
Definition: xrt_device.h:181
A query for a plane.
Definition: xrt_plane_detector.h:97
A pose composed of a position and orientation.
Definition: xrt_defines.h:463
A relation with two spaces, includes velocity and acceleration.
Definition: xrt_defines.h:654
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:708
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.