Ghost: Ghost-XR API to abstract away and access OpenXR functionality

Extends Ghost to include an abstraction for OpenXR, which I refer to as
Ghost-XR. Such an API is the base for the following commit, which introduces VR
support to Blender.

Main features:
* Simple and high-level interface for Blender specific code to call.
* Extensible for muliple graphics backends, currently OpenGL and a DirectX
  compatibility layer are supported.
* Carefully designed error handling strategy allowing Blender to handle errors
  gracefully and with useful error messages.
* OpenXR extension and API-layer management.
* OpenXR session management.
* Basic OpenXR event management.
* Debug utilities for Ghost-XR and OpenXR

For more information on this API, check
https://wiki.blender.org/wiki/Source/Interface/XR.

Reviewed by: Brecht Van Lommel

Differential Revision: https://developer.blender.org/D6188

intern/ghost/GHOST_C-api.h

@@ -30,21 +30,6 @@
 extern "C" {
 #endif
 
-/**
- * Creates a "handle" for a C++ GHOST object.
- * A handle is just an opaque pointer to an empty struct.
- * In the API the pointer is cast to the actual C++ class.
- * The 'name' argument to the macro is the name of the handle to create.
- */
-
-GHOST_DECLARE_HANDLE(GHOST_SystemHandle);
-GHOST_DECLARE_HANDLE(GHOST_TimerTaskHandle);
-GHOST_DECLARE_HANDLE(GHOST_WindowHandle);
-GHOST_DECLARE_HANDLE(GHOST_EventHandle);
-GHOST_DECLARE_HANDLE(GHOST_RectangleHandle);
-GHOST_DECLARE_HANDLE(GHOST_EventConsumerHandle);
-GHOST_DECLARE_HANDLE(GHOST_ContextHandle);
-
 /**
  * Definition of a callback routine that receives events.
  * \param event The event received.
@@ -1006,6 +991,91 @@ extern void GHOST_BeginIME(GHOST_WindowHandle windowhandle,
  */
 extern void GHOST_EndIME(GHOST_WindowHandle windowhandle);
 
+#ifdef WITH_XR_OPENXR
+
+/* XR-context */
+
+/**
+ * Set a custom callback to be executed whenever an error occurs. Should be set before calling
+ * #GHOST_XrContextCreate() to get error handling during context creation too.
+ *
+ * \param customdata: Handle to some data that will get passed to \a handler_fn should an error be
+ *                    thrown.
+ */
+void GHOST_XrErrorHandler(GHOST_XrErrorHandlerFn handler_fn, void *customdata);
+
+/**
+ * \brief Initialize the Ghost XR-context.
+ *
+ * Includes setting up the OpenXR runtime link, querying available extensions and API layers,
+ * enabling extensions and API layers.
+ *
+ * \param create_info: Options for creating the XR-context, e.g. debug-flags and ordered array of
+ *                     graphics bindings to try enabling.
+ */
+GHOST_XrContextHandle GHOST_XrContextCreate(const GHOST_XrContextCreateInfo *create_info);
+/**
+ * Free a XR-context involving OpenXR runtime link destruction and freeing of all internal data.
+ */
+void GHOST_XrContextDestroy(GHOST_XrContextHandle xr_context);
+
+/**
+ * Set callbacks for binding and unbinding a graphics context for a session. The binding callback
+ * may create a new graphics context thereby. In fact that's the sole reason for this callback
+ * approach to binding. Just make sure to have an unbind function set that properly destructs.
+ *
+ * \param bind_fn: Function to retrieve (possibly create) a graphics context.
+ * \param unbind_fn: Function to release (possibly free) a graphics context.
+ */
+void GHOST_XrGraphicsContextBindFuncs(GHOST_XrContextHandle xr_context,
+                                      GHOST_XrGraphicsContextBindFn bind_fn,
+                                      GHOST_XrGraphicsContextUnbindFn unbind_fn);
+
+/**
+ * Set the drawing callback for views. A view would typically be either the left or the right eye,
+ * although other configurations are possible. When #GHOST_XrSessionDrawViews() is called to draw
+ * an XR frame, \a draw_view_fn is executed for each view.
+ *
+ * \param draw_view_fn: The callback to draw a single view for an XR frame.
+ */
+void GHOST_XrDrawViewFunc(GHOST_XrContextHandle xr_context, GHOST_XrDrawViewFn draw_view_fn);
+
+/* sessions */
+/**
+ * Create internal session data for \a xr_context and ask the OpenXR runtime to invoke a session.
+ *
+ * \param begin_info: Options for the session creation.
+ */
+void GHOST_XrSessionStart(GHOST_XrContextHandle xr_context,
+                          const GHOST_XrSessionBeginInfo *begin_info);
+/**
+ * Destruct internal session data for \a xr_context and ask the OpenXR runtime to stop a session.
+ */
+void GHOST_XrSessionEnd(GHOST_XrContextHandle xr_context);
+/**
+ * Draw a single frame by calling the view drawing callback defined by #GHOST_XrDrawViewFunc() for
+ * each view and submit it to the OpenXR runtime.
+ *
+ * \param customdata: Handle to some data that will get passed to the view drawing callback.
+ */
+void GHOST_XrSessionDrawViews(GHOST_XrContextHandle xr_context, void *customdata);
+/**
+ * Check if a \a xr_context has a session that, according to the OpenXR definition would be
+ * considered to be 'running'
+ * (https://www.khronos.org/registry/OpenXR/specs/1.0/html/xrspec.html#session_running).
+ */
+int GHOST_XrSessionIsRunning(const GHOST_XrContextHandle xr_context);
+
+/* events */
+/**
+ * Invoke handling of all OpenXR events for \a xr_context. Should be called on every main-loop
+ * iteration and will early-exit if \a xr_context is NULL (so caller doesn't have to check).
+ *
+ * \returns GHOST_kSuccess if any event was handled, otherwise GHOST_kFailure.
+ */
+GHOST_TSuccess GHOST_XrEventsHandle(GHOST_XrContextHandle xr_context);
+#endif
+
 #ifdef __cplusplus
 }
 #endif