[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