[Bf-blender-cvs] [cd35a7b7d51] vr_scene_inspection: Add comments to C-API function declarations
Julian Eisel
noreply at git.blender.org
Tue Mar 10 16:44:41 CET 2020
Commit: cd35a7b7d511dd52351c7b84bcfa3530883bf3d9
Author: Julian Eisel
Date: Mon Mar 9 15:27:01 2020 +0100
Branches: vr_scene_inspection
https://developer.blender.org/rBcd35a7b7d511dd52351c7b84bcfa3530883bf3d9
Add comments to C-API function declarations
===================================================================
M intern/ghost/GHOST_C-api.h
M intern/ghost/intern/GHOST_C-api.cpp
M intern/ghost/intern/GHOST_Xr.cpp
M intern/ghost/intern/GHOST_XrContext.cpp
===================================================================
diff --git a/intern/ghost/GHOST_C-api.h b/intern/ghost/GHOST_C-api.h
index 5919606098c..9b5a549f489 100644
--- a/intern/ghost/GHOST_C-api.h
+++ b/intern/ghost/GHOST_C-api.h
@@ -1012,27 +1012,82 @@ extern void GHOST_EndIME(GHOST_WindowHandle windowhandle);
/**
* Set a custom callback to be executed whenever an error occurs. Should be set before calling
- * #GHOST_XrContextCreate().
+ * #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 */
-int GHOST_XrSessionIsRunning(const GHOST_XrContextHandle xr_context);
+/**
+ * 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
diff --git a/intern/ghost/intern/GHOST_C-api.cpp b/intern/ghost/intern/GHOST_C-api.cpp
index 95e138347ee..0dd32f3a1a8 100644
--- a/intern/ghost/intern/GHOST_C-api.cpp
+++ b/intern/ghost/intern/GHOST_C-api.cpp
@@ -971,6 +971,12 @@ void GHOST_XrSessionEnd(GHOST_XrContextHandle xr_contexthandle)
GHOST_XR_CAPI_CALL(xr_context->endSession(), xr_context);
}
+void GHOST_XrSessionDrawViews(GHOST_XrContextHandle xr_contexthandle, void *draw_customdata)
+{
+ GHOST_IXrContext *xr_context = (GHOST_IXrContext *)xr_contexthandle;
+ GHOST_XR_CAPI_CALL(xr_context->drawSessionViews(draw_customdata), xr_context);
+}
+
int GHOST_XrSessionIsRunning(const GHOST_XrContextHandle xr_contexthandle)
{
const GHOST_IXrContext *xr_context = (const GHOST_IXrContext *)xr_contexthandle;
@@ -978,12 +984,6 @@ int GHOST_XrSessionIsRunning(const GHOST_XrContextHandle xr_contexthandle)
return 0; /* Only reached if exception is thrown. */
}
-void GHOST_XrSessionDrawViews(GHOST_XrContextHandle xr_contexthandle, void *draw_customdata)
-{
- GHOST_IXrContext *xr_context = (GHOST_IXrContext *)xr_contexthandle;
- GHOST_XR_CAPI_CALL(xr_context->drawSessionViews(draw_customdata), xr_context);
-}
-
void GHOST_XrGraphicsContextBindFuncs(GHOST_XrContextHandle xr_contexthandle,
GHOST_XrGraphicsContextBindFn bind_fn,
GHOST_XrGraphicsContextUnbindFn unbind_fn)
diff --git a/intern/ghost/intern/GHOST_Xr.cpp b/intern/ghost/intern/GHOST_Xr.cpp
index 726d068552b..2f122ca8e13 100644
--- a/intern/ghost/intern/GHOST_Xr.cpp
+++ b/intern/ghost/intern/GHOST_Xr.cpp
@@ -29,11 +29,6 @@
#include "GHOST_XrContext.h"
#include "GHOST_XrException.h"
-/**
- * \brief Initialize the window manager XR-Context.
- * Includes setting up the OpenXR instance, querying available extensions and API layers,
- * enabling extensions (currently graphics binding extension only) and API layers.
- */
GHOST_XrContextHandle GHOST_XrContextCreate(const GHOST_XrContextCreateInfo *create_info)
{
GHOST_XrContext *xr_context = new GHOST_XrContext(create_info);
diff --git a/intern/ghost/intern/GHOST_XrContext.cpp b/intern/ghost/intern/GHOST_XrContext.cpp
index 6b00979630c..0c533939b8c 100644
--- a/intern/ghost/intern/GHOST_XrContext.cpp
+++ b/intern/ghost/intern/GHOST_XrContext.cpp
@@ -487,14 +487,6 @@ void GHOST_XrContext::handleSessionStateChange(const XrEventDataSessionStateChan
* Public as in, exposed in the Ghost API.
* \{ */
-/**
- * Set context for binding and unbinding a graphics context for a session. The binding callback
- * may create a new 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_XrContext::setGraphicsContextBindFuncs(GHOST_XrGraphicsContextBindFn bind_fn,
GHOST_XrGraphicsContextUnbindFn unbind_fn)
{
More information about the Bf-blender-cvs
mailing list