Monado OpenXR Runtime
xrt_instance.h
Go to the documentation of this file.
1 // Copyright 2020-2022, Collabora, Ltd.
2 // SPDX-License-Identifier: BSL-1.0
3 /*!
4  * @file
5  * @brief Header for @ref xrt_instance 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 
15 
16 #ifdef __cplusplus
17 extern "C" {
18 #endif
19 
20 
21 struct xrt_prober;
22 struct xrt_device;
23 struct xrt_system_devices;
25 
26 
27 /*!
28  * @addtogroup xrt_iface
29  * @{
30  */
31 
32 #define XRT_MAX_APPLICATION_NAME_SIZE 128
33 
34 /*!
35  * Information provided by the application at instance create time.
36  */
38 {
39  char application_name[XRT_MAX_APPLICATION_NAME_SIZE];
40 };
41 
42 /*!
43  * @interface xrt_instance
44  *
45  * This interface acts as a root object for Monado.
46  * It typically either wraps an @ref xrt_prober or forms a connection to an
47  * out-of-process XR service.
48  *
49  * This is as close to a singleton object as there is in Monado: you should not
50  * create more than one xrt_instance implementation per process.
51  *
52  * Each "target" will provide its own (private) implementation of this
53  * interface, which is exposed by implementing xrt_instance_create().
54  *
55  * Additional information can be found in @ref understanding-targets.
56  *
57  * @sa ipc_instance_create
58  */
60 {
61  /*!
62  * @name Interface Methods
63  *
64  * All implementations of the xrt_instance implementation must
65  * populate all these function pointers with their implementation
66  * methods. To use this interface, see the helper functions.
67  * @{
68  */
69 
70  /*!
71  * Creates all of the system resources like the devices and system
72  * compositor. The system compositor is optional.
73  *
74  * Should only be called once.
75  *
76  * @note Code consuming this interface should use xrt_instance_create_system()
77  *
78  * @param xinst Pointer to self
79  * @param[out] out_xsysd Return of devices, required.
80  * @param[out] out_xsysc Return of system compositor, optional.
81  *
82  * @see xrt_prober::probe, xrt_prober::select, xrt_gfx_provider_create_native
83  */
85  struct xrt_system_devices **out_xsysd,
86  struct xrt_system_compositor **out_xsysc);
87 
88  /*!
89  * Get the instance @ref xrt_prober, if any.
90  *
91  * If the instance is not using an @ref xrt_prober, it may return null.
92  *
93  * The instance retains ownership of the prober and is responsible for
94  * destroying it.
95  *
96  * Can be called multiple times. (The prober is usually created at
97  * instance construction time.)
98  *
99  * @note Code consuming this interface should use
100  * xrt_instance_get_prober().
101  *
102  * @param xinst Pointer to self
103  * @param[out] out_xp Pointer to xrt_prober pointer, will be populated
104  * or set to NULL.
105  *
106  * @return XRT_SUCCESS on success, other error code on error.
107  */
108  xrt_result_t (*get_prober)(struct xrt_instance *xinst, struct xrt_prober **out_xp);
109 
110  /*!
111  * Destroy the instance and its owned objects, including the prober (if
112  * any).
113  *
114  * Code consuming this interface should use xrt_instance_destroy().
115  *
116  * @param xinst Pointer to self
117  */
118  void (*destroy)(struct xrt_instance *xinst);
119  /*!
120  * @}
121  */
122  struct xrt_instance_info instance_info;
123 
124  uint64_t startup_timestamp;
125 };
126 
127 /*!
128  * @copydoc xrt_instance::create_system
129  *
130  * Helper for calling through the function pointer.
131  *
132  * @public @memberof xrt_instance
133  */
134 static inline xrt_result_t
136  struct xrt_system_devices **out_xsysd,
137  struct xrt_system_compositor **out_xsysc)
138 {
139  return xinst->create_system(xinst, out_xsysd, out_xsysc);
140 }
141 
142 /*!
143  * @copydoc xrt_instance::get_prober
144  *
145  * Helper for calling through the function pointer.
146  *
147  * @public @memberof xrt_instance
148  */
149 static inline xrt_result_t
150 xrt_instance_get_prober(struct xrt_instance *xinst, struct xrt_prober **out_xp)
151 {
152  return xinst->get_prober(xinst, out_xp);
153 }
154 
155 /*!
156  * Destroy an xrt_instance - helper function.
157  *
158  * @param[in,out] xinst_ptr A pointer to your instance implementation pointer.
159  *
160  * Will destroy the instance if *xinst_ptr is not NULL. Will then set *xinst_ptr
161  * to NULL.
162  *
163  * @public @memberof xrt_instance
164  */
165 static inline void
167 {
168  struct xrt_instance *xinst = *xinst_ptr;
169  if (xinst == NULL) {
170  return;
171  }
172 
173  xinst->destroy(xinst);
174  *xinst_ptr = NULL;
175 }
176 
177 /*!
178  * @name Factory
179  * Implemented in each target.
180  * @{
181  */
182 /*!
183  * Create an implementation of the xrt_instance interface.
184  *
185  * Creating more then one @ref xrt_instance is probably never the right thing
186  * to do, so avoid it.
187  *
188  * Each target must implement this function.
189  *
190  * @param[in] ii A pointer to a info struct containing information about the
191  * application.
192  * @param[out] out_xinst A pointer to an xrt_instance pointer. Will be
193  * populated.
194  *
195  * @return 0 on success
196  *
197  * @relates xrt_instance
198  */
200 xrt_instance_create(struct xrt_instance_info *ii, struct xrt_instance **out_xinst);
201 
202 /*!
203  * @}
204  */
205 
206 /*!
207  * @}
208  */
209 
210 
211 #ifdef __cplusplus
212 }
213 #endif
static void xrt_instance_destroy(struct xrt_instance **xinst_ptr)
Destroy an xrt_instance - helper function.
Definition: xrt_instance.h:166
xrt_result_t xrt_instance_create(struct xrt_instance_info *ii, struct xrt_instance **out_xinst)
Create an implementation of the xrt_instance interface.
Definition: target_instance.c:112
static xrt_result_t xrt_instance_create_system(struct xrt_instance *xinst, struct xrt_system_devices **out_xsysd, struct xrt_system_compositor **out_xsysc)
Creates all of the system resources like the devices and system compositor.
Definition: xrt_instance.h:135
enum xrt_result xrt_result_t
Result type used across Monado.
static xrt_result_t xrt_instance_get_prober(struct xrt_instance *xinst, struct xrt_prober **out_xp)
Get the instance xrt_prober, if any.
Definition: xrt_instance.h:150
A single HMD or input device.
Definition: xrt_device.h:227
Information provided by the application at instance create time.
Definition: xrt_instance.h:38
This interface acts as a root object for Monado.
Definition: xrt_instance.h:60
xrt_result_t(* get_prober)(struct xrt_instance *xinst, struct xrt_prober **out_xp)
Get the instance xrt_prober, if any.
Definition: xrt_instance.h:108
void(* destroy)(struct xrt_instance *xinst)
Destroy the instance and its owned objects, including the prober (if any).
Definition: xrt_instance.h:118
xrt_result_t(* create_system)(struct xrt_instance *xinst, struct xrt_system_devices **out_xsysd, struct xrt_system_compositor **out_xsysc)
Creates all of the system resources like the devices and system compositor.
Definition: xrt_instance.h:84
The main prober that probes and manages found but not opened HMD devices that are connected to the sy...
Definition: xrt_prober.h:131
The system compositor is a long lived object, it has the same life time as a XrSystemID.
Definition: xrt_compositor.h:1974
A collection of xrt_device, and the roles they have been assigned.
Definition: xrt_system.h:24
Header holding common defines.
Common defines and enums for XRT.