xrt: Compositor doc improvement

This commit is contained in:
Ryan Pavlik 2022-07-15 16:30:06 -05:00
parent de4bf3be0a
commit 12fab0653c

View file

@ -1,9 +1,12 @@
// Copyright 2019-2021, Collabora, Ltd. // Copyright 2019-2022, Collabora, Ltd.
// SPDX-License-Identifier: BSL-1.0 // SPDX-License-Identifier: BSL-1.0
/*! /*!
* @file * @file
* @brief Header defining a XRT graphics provider. * @brief Header declaring XRT graphics interfaces.
* @author Jakob Bornecrantz <jakob@collabora.com> * @author Jakob Bornecrantz <jakob@collabora.com>
* @author Lubosz Sarnecki <lubosz.sarnecki@collabora.com>
* @author Ryan Pavlik <ryan.pavlik@collabora.com>
* @author Christoph Haag <christoph.haag@collabora.com>
* @ingroup xrt_iface * @ingroup xrt_iface
*/ */
@ -15,7 +18,7 @@
#if defined(XRT_OS_WINDOWS) #if defined(XRT_OS_WINDOWS)
#include "xrt/xrt_windows.h" #include "xrt/xrt_windows.h"
#include "d3d11.h" #include <d3d11.h>
#elif defined(XRT_DOXYGEN) #elif defined(XRT_DOXYGEN)
struct ID3D11Texture2D; struct ID3D11Texture2D;
#endif #endif
@ -758,6 +761,10 @@ struct xrt_compositor
const struct xrt_swapchain_create_info *info, const struct xrt_swapchain_create_info *info,
struct xrt_swapchain_create_properties *xsccp); struct xrt_swapchain_create_properties *xsccp);
/*!
* @name Function pointers for swapchain and sync creation and import
* @{
*/
/*! /*!
* Create a swapchain with a set of images. * Create a swapchain with a set of images.
* *
@ -795,6 +802,8 @@ struct xrt_compositor
xrt_result_t (*create_semaphore)(struct xrt_compositor *xc, xrt_result_t (*create_semaphore)(struct xrt_compositor *xc,
xrt_graphics_sync_handle_t *out_handle, xrt_graphics_sync_handle_t *out_handle,
struct xrt_compositor_semaphore **out_xcsem); struct xrt_compositor_semaphore **out_xcsem);
/*! @} */
/*! /*!
* Poll events from this compositor. * Poll events from this compositor.
@ -803,6 +812,10 @@ struct xrt_compositor
*/ */
xrt_result_t (*poll_events)(struct xrt_compositor *xc, union xrt_compositor_event *out_xce); xrt_result_t (*poll_events)(struct xrt_compositor *xc, union xrt_compositor_event *out_xce);
/*!
* @name Function pointers for session functions
* @{
*/
/*! /*!
* See xrBeginSession. * See xrBeginSession.
*/ */
@ -815,6 +828,13 @@ struct xrt_compositor
*/ */
xrt_result_t (*end_session)(struct xrt_compositor *xc); xrt_result_t (*end_session)(struct xrt_compositor *xc);
/*! @} */
/*!
* @name Function pointers for frame functions
* @{
*/
/*! /*!
* This function and @ref mark_frame function calls are a alternative to * This function and @ref mark_frame function calls are a alternative to
* @ref wait_frame. * @ref wait_frame.
@ -914,6 +934,13 @@ struct xrt_compositor
*/ */
xrt_result_t (*discard_frame)(struct xrt_compositor *xc, int64_t frame_id); xrt_result_t (*discard_frame)(struct xrt_compositor *xc, int64_t frame_id);
/*! @} */
/*!
* @name Function pointers for layer submission
* @{
*/
/*! /*!
* @brief Begins layer submission. * @brief Begins layer submission.
* *
@ -1077,6 +1104,8 @@ struct xrt_compositor
struct xrt_compositor_semaphore *xcsem, struct xrt_compositor_semaphore *xcsem,
uint64_t value); uint64_t value);
/*! @} */
/*! /*!
* Teardown the compositor. * Teardown the compositor.
* *
@ -1104,6 +1133,11 @@ xrt_comp_get_swapchain_create_properties(struct xrt_compositor *xc,
return xc->get_swapchain_create_properties(xc, info, xsccp); return xc->get_swapchain_create_properties(xc, info, xsccp);
} }
/*!
* @name Swapchain and sync creation and import methods
* @{
*/
/*! /*!
* @copydoc xrt_compositor::create_swapchain * @copydoc xrt_compositor::create_swapchain
* *
@ -1166,6 +1200,9 @@ xrt_comp_create_semaphore(struct xrt_compositor *xc,
return xc->create_semaphore(xc, out_handle, out_xcsem); return xc->create_semaphore(xc, out_handle, out_xcsem);
} }
/*! @} */
/*! /*!
* @copydoc xrt_compositor::poll_events * @copydoc xrt_compositor::poll_events
* *
@ -1179,6 +1216,11 @@ xrt_comp_poll_events(struct xrt_compositor *xc, union xrt_compositor_event *out_
return xc->poll_events(xc, out_xce); return xc->poll_events(xc, out_xce);
} }
/*!
* @name Session methods
* @{
*/
/*! /*!
* @copydoc xrt_compositor::begin_session * @copydoc xrt_compositor::begin_session
* *
@ -1205,6 +1247,15 @@ xrt_comp_end_session(struct xrt_compositor *xc)
return xc->end_session(xc); return xc->end_session(xc);
} }
/*! @} */
/*!
* @name Frame-related methods
* @brief Related to the OpenXR `xr*Frame` functions
* @{
*/
/*! /*!
* @copydoc xrt_compositor::predict_frame * @copydoc xrt_compositor::predict_frame
* *
@ -1287,6 +1338,15 @@ xrt_comp_discard_frame(struct xrt_compositor *xc, int64_t frame_id)
return xc->discard_frame(xc, frame_id); return xc->discard_frame(xc, frame_id);
} }
/*! @} */
/*!
* @name Layer submission methods
* @brief Equivalent to `xrEndFrame`, but split across multiple calls.
* @{
*/
/*! /*!
* @copydoc xrt_compositor::layer_begin * @copydoc xrt_compositor::layer_begin
* *
@ -1449,6 +1509,8 @@ xrt_comp_layer_commit_with_semaphore(struct xrt_compositor *xc,
return xc->layer_commit_with_semaphore(xc, frame_id, xcsem, value); return xc->layer_commit_with_semaphore(xc, frame_id, xcsem, value);
} }
/*! @} */
/*! /*!
* @copydoc xrt_compositor::destroy * @copydoc xrt_compositor::destroy
* *
@ -1649,7 +1711,7 @@ struct xrt_d3d_requirements
* A single image of a swapchain based on native buffer handles. * A single image of a swapchain based on native buffer handles.
* *
* @ingroup xrt_iface comp * @ingroup xrt_iface comp
* @see xrt_swapchain_native * @see xrt_swapchain_native, xrt_graphics_buffer_handle_t
*/ */
struct xrt_image_native struct xrt_image_native
{ {