diff options
author | Julian Eisel <julian@blender.org> | 2020-03-17 22:10:57 +0300 |
---|---|---|
committer | Julian Eisel <julian@blender.org> | 2020-03-17 23:39:59 +0300 |
commit | 406bfd43040a5526702b51f88f1491cb61aecedb (patch) | |
tree | 980c77919f9930d51c5f4f411d2e658f66a263e5 /intern/ghost/GHOST_C-api.h | |
parent | c9a8de1d704b807460a7a6838db28f7ae2472200 (diff) |
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
Diffstat (limited to 'intern/ghost/GHOST_C-api.h')
-rw-r--r-- | intern/ghost/GHOST_C-api.h | 100 |
1 files changed, 85 insertions, 15 deletions
diff --git a/intern/ghost/GHOST_C-api.h b/intern/ghost/GHOST_C-api.h index a3cc9aa1df5..aafe374a93b 100644 --- a/intern/ghost/GHOST_C-api.h +++ b/intern/ghost/GHOST_C-api.h @@ -31,21 +31,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. * \param userdata The callback's user data, supplied to GHOST_CreateSystem. @@ -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 |