Ocean
Session.h
Go to the documentation of this file.
1 /*
2  * Copyright (c) Meta Platforms, Inc. and affiliates.
3  *
4  * This source code is licensed under the MIT license found in the
5  * LICENSE file in the root directory of this source tree.
6  */
7 
8 #ifndef META_OCEAN_PLATFORM_OPENXR_SESSION_H
9 #define META_OCEAN_PLATFORM_OPENXR_SESSION_H
10 
14 
15 #include "ocean/base/Lock.h"
16 
17 namespace Ocean
18 {
19 
20 namespace Platform
21 {
22 
23 namespace OpenXR
24 {
25 
26 /**
27  * This class wraps an OpenXR session.
28  * A session represents an application’s intention to display XR content to the user.
29  * @ingroup platformopenxr
30  */
31 class OCEAN_PLATFORM_OPENXR_EXPORT Session final
32 {
33  public:
34 
35  /**
36  * Definition of a vector holding color spaces.
37  */
38  typedef std::vector<XrColorSpaceFB> XrColorSpacesFB;
39 
40  public:
41 
42  /**
43  * Default constructor creating an invalid session.
44  */
45  Session() = default;
46 
47  /**
48  * Move constructor.
49  * @param session The session to be moved
50  */
51  inline Session(Session&& session);
52 
53  /**
54  * Destructs the session and releases all associated resources.
55  */
57 
58  /**
59  * Initializes the session.
60  * @param instance The instance for which the session will be created, must be valid
61  * @param xrGraphicsBinding The pointer to the graphics binding struct, must be valid
62  * @param width The recommended width of the view configuration used for this session, in pixel, with range [1, infinity)
63  * @param height The recommended height of the view configuration used for this session, in pixel, with range [1, infinity)
64  * @return True, if succeeded
65  */
66  inline bool initialize(const Instance& instance, const void* xrGraphicsBinding, const unsigned int width, const unsigned int height);
67 
68  /**
69  * Initializes the session.
70  * @param xrInstance The instance for which the session will be created, must be valid
71  * @param xrSystemId The runtime's identifier, must be valid
72  * @param xrGraphicsBinding The pointer to the graphics binding struct, must be valid
73  * @param width The recommended width of the view configuration used for this session, in pixel, with range [1, infinity)
74  * @param height The recommended height of the view configuration used for this session, in pixel, with range [1, infinity)
75  * @return True, if succeeded
76  */
77  bool initialize(const XrInstance& xrInstance, const XrSystemId& xrSystemId, const void* xrGraphicsBinding, const unsigned int width, const unsigned int height);
78 
79  /**
80  * Explicitly releases the session and all associated resources.
81  * @see initialize().
82  */
83  void release();
84 
85  /**
86  * Begins this session.
87  * After this function successfully returns, the session is considered to be running.
88  * The session should be stopped with end().
89  * @param xrViewConfigurationType The view configuration to be used, must be valid
90  * @return True, if succeeded
91  * @see isRunning(), end().
92  */
93  bool begin(const XrViewConfigurationType xrViewConfigurationType);
94 
95  /**
96  * Ends this session.
97  * @return True, if succeeded
98  * @see isRunning(), begin().
99  */
100  bool end();
101 
102  /**
103  * Returns whether this session is currently running.
104  * @return True, if so
105  * @see begin().
106  */
107  inline bool isRunning() const;
108 
109  /**
110  * Returns the recommended width of the view configuration used for this session.
111  * @return The session's view configuration width, in pixel, with range [1, infinity)
112  */
113  inline unsigned int width() const;
114 
115  /**
116  * Returns the recommended height of the view configuration used for this session.
117  * @return The session's view configuration height, in pixel, with range [1, infinity)
118  */
119  inline unsigned int height() const;
120 
121  /**
122  * Creates a space associated with this session.
123  * @param xrReferenceSpaceType The type of the space to create, must be valid
124  * @return The resulting space object
125  */
126  inline ScopedXrSpace createSpace(const XrReferenceSpaceType xrReferenceSpaceType) const;
127 
128  /**
129  * Creates an action space for a pose action.
130  * @param xrAction The action for which the space will be created, must be a pose action, must be valid
131  * @param xrSubactionPath Optional subaction path for the action space, XR_NULL_PATH otherwise
132  * @return The resulting space object
133  */
134  inline ScopedXrSpace createActionSpace(const XrAction& xrAction, const XrPath& xrSubactionPath = XR_NULL_PATH) const;
135 
136  /**
137  * Creates an action space for a pose action.
138  * @param xrAction The action for which the space will be created, must be a pose action, must be valid
139  * @param subactionPath Optional subaction path for the action space, empty otherwise
140  * @return The resulting space object
141  */
142  inline ScopedXrSpace createActionSpace(const XrAction& xrAction, const std::string& subactionPath) const;
143 
144  /**
145  * Waits for the next frame that needs to be rendered.
146  * @param predictedDisplayTime The resulting predicted display time of the next frame
147  * @param predictedDisplayPeriod Optional resulting predicted display preriod of the next frame, nullptr if not of interest
148  * @return True, if the next frame needs to be rendered; False, to skip the next frame
149  */
150  bool nextFrame(XrTime& predictedDisplayTime, XrDuration* predictedDisplayPeriod = nullptr);
151 
152  /**
153  * Sets the color space of this session.
154  * Needs extension: XR_FB_COLOR_SPACE_EXTENSION_NAME.
155  * @param xrColorSpaceFB The color space to set
156  * @return True, if succeeded
157  */
158  inline bool setColorSpace(const XrColorSpaceFB xrColorSpaceFB);
159 
160  /**
161  * Translates an OpenXR result associated with this instance into a readable string.
162  * @param xrResult The OpenXR result to translate
163  * @return The translated result
164  */
165  std::string translateResult(const XrResult xrResult) const;
166 
167  /**
168  * Returns the OpenXR instance associated with this session.
169  * @return The associated OpenXR instance, XR_NULL_HANDLE if unknown
170  */
171  inline XrInstance xrInstance() const;
172 
173  /**
174  * Returns the OpenXR runtime's identifier.
175  * @return The runtime's identifier, XR_NULL_SYSTEM_ID if unknown
176  */
177  inline XrSystemId xrSystemId() const;
178 
179  /**
180  * Returns whether this object holds a valid OpenXR instance.
181  * @return True, if so
182  * @see initialize().
183  */
184  bool isValid() const;
185 
186  /**
187  * Move operator.
188  * @param session The session to be moved
189  * @return Reference to this object
190  */
191  Session& operator=(Session&& session);
192 
193  /**
194  * Returns the wrapped OpenXR session.
195  * @return The actual session, nullptr if not initialized
196  * @see isValid().
197  */
198  operator XrSession() const;
199 
200  /**
201  * Returns whether this object holds a valid OpenXR session.
202  * @return True, if so
203  * @see isValid().
204  */
205  explicit inline operator bool() const;
206 
207  /**
208  * Creates a space associated with this session.
209  * @param xrInstance The OpenXR instance which created the session, must be valid
210  * @param xrSession The OpenXR session to which the space will be associated, must be valid
211  * @param xrReferenceSpaceType The type of the space to create, must be valid
212  * @return The resulting space object
213  */
214  static ScopedXrSpace createSpace(const XrInstance& xrInstance, const XrSession& xrSession, const XrReferenceSpaceType xrReferenceSpaceType);
215 
216  /**
217  * Creates an action space for a pose action.
218  * @param xrInstance The OpenXR instance which created the session, must be valid
219  * @param xrSession The OpenXR session to which the space will be associated, must be valid
220  * @param xrAction The action for which the space will be created, must be a pose action, must be valid
221  * @param xrSubactionPath Optional subaction path for the action space, XR_NULL_PATH otherwise
222  * @return The resulting space object
223  */
224  static ScopedXrSpace createActionSpace(const XrInstance& xrInstance, const XrSession& xrSession, const XrAction& xrAction, const XrPath& xrSubactionPath = XR_NULL_PATH);
225 
226  /**
227  * Creates an action space for a pose action.
228  * @param xrInstance The OpenXR instance which created the session, must be valid
229  * @param xrSession The OpenXR session to which the space will be associated, must be valid
230  * @param xrAction The action for which the space will be created, must be a pose action, must be valid
231  * @param subactionPath Optional subaction path for the action space, empty otherwise
232  * @return The resulting space object
233  */
234  static inline ScopedXrSpace createActionSpace(const XrInstance& xrInstance, const XrSession& xrSession, const XrAction& xrAction, const std::string& subactionPath);
235 
236  /**
237  * Determines the available color spaces.
238  * Needs extension: XR_FB_COLOR_SPACE_EXTENSION_NAME.
239  * @param xrInstance The OpenXR instance for which the color spaces will be determined, must be valid
240  * @param xrSession The OpenXR session for which the color spaces will be determined, must be valid
241  * @param xrColorSpacesFB The resulting color spaces
242  * @return True, if succeeded
243  */
244  static bool determineExistingColorSpaces(const XrInstance& xrInstance, const XrSession& xrSession, XrColorSpacesFB& xrColorSpacesFB);
245 
246  /**
247  * Sets the color space of a session.
248  * Needs extension: XR_FB_COLOR_SPACE_EXTENSION_NAME.
249  * @param xrInstance The OpenXR instance for which the color space will be set, must be valid
250  * @param xrSession The OpenXR session for which the color space will be set, must be valid
251  * @param xrColorSpaceFB The color space to set
252  * @return True, if succeeded
253  */
254  static bool setColorSpace(const XrInstance& xrInstance, const XrSession& xrSession, const XrColorSpaceFB xrColorSpaceFB);
255 
256  protected:
257 
258  /**
259  * Disabled copy constructor.
260  */
261  Session(const Session&) = delete;
262 
263  /**
264  * Disabled assign operator.
265  * @return Reference to this object
266  */
267  Session& operator=(const Session&) = delete;
268 
269  protected:
270 
271  /// The OpenXR instance for which the session is created.
272  XrInstance xrInstance_ = XR_NULL_HANDLE;
273 
274  /// The actual OpenXR session.
275  XrSession xrSession_ = XR_NULL_HANDLE;
276 
277  /// The identifier for the runtime.
278  XrSystemId xrSystemId_ = XR_NULL_SYSTEM_ID;
279 
280  /// True, if the session is running.
281  bool isRunning_ = false;
282 
283  /// The recommended width of the view configuration used for this session, in pixel, with range [1, infinity).
284  unsigned int width_ = 0u;
285 
286  /// The recommended height of the view configuration used for this session, in pixel, with range [1, infinity)
287  unsigned int height_ = 0u;
288 
289  /// The session's lock.
290  mutable Lock lock_;
291 };
292 
293 inline Session::Session(Session&& session)
294 {
295  *this = std::move(session);
296 }
297 
298 inline bool Session::initialize(const Instance& instance, const void* xrGraphicsBinding, const unsigned int width, const unsigned int height)
299 {
300  ocean_assert(instance.isValid());
301  ocean_assert(xrGraphicsBinding != nullptr);
302 
303  return initialize(instance, instance.xrSystemId(), xrGraphicsBinding, width, height);
304 }
305 
306 inline bool Session::isRunning() const
307 {
308  const ScopedLock scopedLock(lock_);
309 
310  return isRunning_;
311 }
312 
313 inline unsigned int Session::width() const
314 {
315  const ScopedLock scopedLock(lock_);
316 
317  return width_;
318 }
319 
320 inline unsigned int Session::height() const
321 {
322  const ScopedLock scopedLock(lock_);
323 
324  return height_;
325 }
326 
327 inline ScopedXrSpace Session::createSpace(const XrReferenceSpaceType xrReferenceSpaceType) const
328 {
329  const ScopedLock scopedLock(lock_);
330 
331  ocean_assert(isValid());
332 
333  return createSpace(xrInstance_, xrSession_, xrReferenceSpaceType);
334 }
335 
336 inline ScopedXrSpace Session::createActionSpace(const XrAction& xrAction, const XrPath& xrSubactionPath) const
337 {
338  const ScopedLock scopedLock(lock_);
339 
340  ocean_assert(isValid());
341 
342  return createActionSpace(xrInstance_, xrSession_, xrAction, xrSubactionPath);
343 }
344 
345 inline ScopedXrSpace Session::createActionSpace(const XrAction& xrAction, const std::string& subactionPath) const
346 {
348 }
349 
350 inline bool Session::setColorSpace(const XrColorSpaceFB xrColorSpaceFB)
351 {
352  const ScopedLock scopedLock(lock_);
353 
354  ocean_assert(isValid());
355 
356  return setColorSpace(xrInstance_, xrSession_, xrColorSpaceFB);
357 }
358 
359 inline XrInstance Session::xrInstance() const
360 {
361  const ScopedLock scopedLock(lock_);
362 
363  return xrInstance_;
364 }
365 
366 inline XrSystemId Session::xrSystemId() const
367 {
368  const ScopedLock scopedLock(lock_);
369 
370  return xrSystemId_;
371 }
372 
373 inline Session::operator bool() const
374 {
375  return isValid();
376 }
377 
378 ScopedXrSpace Session::createActionSpace(const XrInstance& xrInstance, const XrSession& xrSession, const XrAction& xrAction, const std::string& subactionPath)
379 {
380  return createActionSpace(xrInstance, xrSession, xrAction, Utilities::translatePath(xrInstance, subactionPath));
381 }
382 
383 }
384 
385 }
386 
387 }
388 
389 #endif // META_OCEAN_PLATFORM_OPENXR_SESSION_H
This class implements a recursive lock object.
Definition: Lock.h:31
This class wraps an OpenXR instance.
Definition: Instance.h:30
bool isValid() const
Returns whether this object holds a valid OpenXR instance.
XrSystemId xrSystemId() const
Returns the identifier for the runtime.
This class wraps an OpenXR session.
Definition: Session.h:32
XrSession xrSession_
The actual OpenXR session.
Definition: Session.h:275
unsigned int height() const
Returns the recommended height of the view configuration used for this session.
Definition: Session.h:320
XrSystemId xrSystemId_
The identifier for the runtime.
Definition: Session.h:278
unsigned int width() const
Returns the recommended width of the view configuration used for this session.
Definition: Session.h:313
bool nextFrame(XrTime &predictedDisplayTime, XrDuration *predictedDisplayPeriod=nullptr)
Waits for the next frame that needs to be rendered.
unsigned int height_
The recommended height of the view configuration used for this session, in pixel, with range [1,...
Definition: Session.h:287
std::string translateResult(const XrResult xrResult) const
Translates an OpenXR result associated with this instance into a readable string.
~Session()
Destructs the session and releases all associated resources.
bool end()
Ends this session.
static ScopedXrSpace createSpace(const XrInstance &xrInstance, const XrSession &xrSession, const XrReferenceSpaceType xrReferenceSpaceType)
Creates a space associated with this session.
bool isRunning() const
Returns whether this session is currently running.
Definition: Session.h:306
static ScopedXrSpace createActionSpace(const XrInstance &xrInstance, const XrSession &xrSession, const XrAction &xrAction, const XrPath &xrSubactionPath=XR_NULL_PATH)
Creates an action space for a pose action.
bool setColorSpace(const XrColorSpaceFB xrColorSpaceFB)
Sets the color space of this session.
Definition: Session.h:350
bool begin(const XrViewConfigurationType xrViewConfigurationType)
Begins this session.
XrInstance xrInstance() const
Returns the OpenXR instance associated with this session.
Definition: Session.h:359
bool initialize(const Instance &instance, const void *xrGraphicsBinding, const unsigned int width, const unsigned int height)
Initializes the session.
Definition: Session.h:298
XrInstance xrInstance_
The OpenXR instance for which the session is created.
Definition: Session.h:272
Session & operator=(const Session &)=delete
Disabled assign operator.
Session(const Session &)=delete
Disabled copy constructor.
XrSystemId xrSystemId() const
Returns the OpenXR runtime's identifier.
Definition: Session.h:366
Session & operator=(Session &&session)
Move operator.
Lock lock_
The session's lock.
Definition: Session.h:290
unsigned int width_
The recommended width of the view configuration used for this session, in pixel, with range [1,...
Definition: Session.h:284
ScopedXrSpace createActionSpace(const XrAction &xrAction, const XrPath &xrSubactionPath=XR_NULL_PATH) const
Creates an action space for a pose action.
Definition: Session.h:336
std::vector< XrColorSpaceFB > XrColorSpacesFB
Definition of a vector holding color spaces.
Definition: Session.h:38
void release()
Explicitly releases the session and all associated resources.
Session()=default
Default constructor creating an invalid session.
bool isRunning_
True, if the session is running.
Definition: Session.h:281
ScopedXrSpace createSpace(const XrReferenceSpaceType xrReferenceSpaceType) const
Creates a space associated with this session.
Definition: Session.h:327
bool initialize(const XrInstance &xrInstance, const XrSystemId &xrSystemId, const void *xrGraphicsBinding, const unsigned int width, const unsigned int height)
Initializes the session.
bool isValid() const
Returns whether this object holds a valid OpenXR instance.
static bool setColorSpace(const XrInstance &xrInstance, const XrSession &xrSession, const XrColorSpaceFB xrColorSpaceFB)
Sets the color space of a session.
static bool determineExistingColorSpaces(const XrInstance &xrInstance, const XrSession &xrSession, XrColorSpacesFB &xrColorSpacesFB)
Determines the available color spaces.
static std::string translatePath(const XrInstance &xrInstance, const XrPath &xrPath)
Converts an OpenXR path to a string.
This class implements a scoped lock object for recursive lock objects.
Definition: Lock.h:135
The namespace covering the entire Ocean framework.
Definition: Accessor.h:15