mirrors/monado
1
0
Fork 0
mirror of https://gitlab.freedesktop.org/monado/monado.git synced 2025-01-01 04:36:07 +00:00
Code Issues Actions Packages Projects Releases Wiki Activity

xrt: Improve docs, fixing doxygen warnings

Browse source
This commit is contained in:
Ryan Pavlik 2022-05-17 13:19:17 -05:00 committed by Jakob Bornecrantz
parent 6bd18ecb38
commit 507be96326
5 changed files with 107 additions and 13 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

8
src/xrt/include/xrt/xrt_compositor.h
View file

@ -389,10 +389,12 @@ struct xrt_swapchain
* See xrAcquireSwapchainImage.
*
* Caller must make sure that no image is acquired before calling
* acquire_image.
* @ref xrt_swapchain_acquire_image.
*
* @param xsc Self pointer
* @param[out] out_index Image index to use next
*
* Call @ref xrt_swapchain_wait_image before writing to the image index output from this function.
*/
xrt_result_t (*acquire_image)(struct xrt_swapchain *xsc, uint32_t *out_index);
@ -461,9 +463,9 @@ xrt_swapchain_acquire_image(struct xrt_swapchain *xsc, uint32_t *out_index)
* @public @memberof xrt_swapchain
*/
static inline xrt_result_t
xrt_swapchain_wait_image(struct xrt_swapchain *xsc, uint64_t timeout, uint32_t index)
xrt_swapchain_wait_image(struct xrt_swapchain *xsc, uint64_t timeout_ns, uint32_t index)
{
return xsc->wait_image(xsc, timeout, index);
return xsc->wait_image(xsc, timeout_ns, index);
}
/*!

1
src/xrt/include/xrt/xrt_defines.h
View file

@ -715,6 +715,7 @@ enum xrt_input_type
enum xrt_input_name
{
// clang-format off
//! Standard pose used for rendering
XRT_INPUT_GENERIC_HEAD_POSE = XRT_INPUT_NAME(0x0000, POSE),
XRT_INPUT_GENERIC_HEAD_DETECT = XRT_INPUT_NAME(0x0001, BOOLEAN),
XRT_INPUT_GENERIC_HAND_TRACKING_LEFT = XRT_INPUT_NAME(0x0002, HAND_TRACKING),

4
src/xrt/include/xrt/xrt_instance.h
View file

@ -132,9 +132,9 @@ struct xrt_instance
static inline xrt_result_t
xrt_instance_create_system(struct xrt_instance *xinst,
struct xrt_system_devices **out_xsysd,
struct xrt_system_compositor **out_xsc)
struct xrt_system_compositor **out_xsysc)
{
return xinst->create_system(xinst, out_xsysd, out_xsc);
return xinst->create_system(xinst, out_xsysd, out_xsysc);
}
/*!

61
src/xrt/include/xrt/xrt_prober.h
View file

@ -47,6 +47,11 @@ struct os_hid_device;
*/
#define XRT_MAX_DEVICES_PER_PROBE 16
/*!
* The maximum number of @ref xrt_auto_prober instances that can be handled.
*
* @ingroup xrt_iface
*/
#define XRT_MAX_AUTO_PROBERS 16
/*!
@ -101,6 +106,12 @@ struct xrt_prober_device
/*!
* Callback for listing video devices.
*
* @param xp Prober
* @param pdev Prober device being iterated
* @param product Product string, if available
* @param manufacturer Manufacturer string, if available
* @param serial Serial number string, if available
* @param ptr Your opaque userdata pointer as provided to @ref xrt_prober_list_video_devices
* @ingroup xrt_iface
*/
typedef void (*xrt_prober_list_video_func_t)(struct xrt_prober *xp,
@ -133,17 +144,16 @@ struct xrt_prober
* to detect any additional devices that may show up once the first
* device has been been started.
*
* @note Code consuming this interface should use xrt_prober_probe()
* @see xrt_prober::lock_list, xrt_prober::unlock_list
*/
xrt_result_t (*probe)(struct xrt_prober *xp);
/*!
* Locks the prober list of probed devices and returns it, while locked
* calling @ref xrt_prober::probe is forbidden. Not thread safe.
* Locks the prober list of probed devices and returns it.
* While locked, calling @ref xrt_prober::probe is forbidden. Not thread safe.
*
* See @ref xrt_prober::probe for more detailed expected usage.
*
* @note Code consuming this interface should use xrt_prober_lock_list()
* @see xrt_prober::probe, xrt_prober::unlock_list
*/
xrt_result_t (*lock_list)(struct xrt_prober *xp,
@ -155,7 +165,6 @@ struct xrt_prober
* Takes a pointer to the list pointer and clears it. Not thread safe.
* See @ref xrt_prober::probe for more detailed expected usage.
*
* @note Code consuming this interface should use xrt_prober_unlock_list()
* @see xrt_prober::probe, xrt_prober::lock_list
*/
xrt_result_t (*unlock_list)(struct xrt_prober *xp, struct xrt_prober_device ***devices);
@ -206,6 +215,16 @@ struct xrt_prober
*/
int (*select)(struct xrt_prober *xp, struct xrt_device **xdevs, size_t xdev_capacity);
/*!
* Open a HID (Human Interface Device) interface using native HID support.
*
* @param xp Pointer to self
* @param xpdev prober device
* @param iface HID interface number
* @param[out] out_hid_dev instance of @ref os_hid_device for the given interface
*
* @return 0 on success, <0 on error.
*/
int (*open_hid_interface)(struct xrt_prober *xp,
struct xrt_prober_device *xpdev,
int iface,
@ -220,8 +239,28 @@ struct xrt_prober
struct xrt_frame_context *xfctx,
struct xrt_fs **out_xfs);
/*!
* Iterate through available video devices, calling your callback @p cb with your userdata @p ptr.
*
* @param xp Pointer to self
* @param cb Callback function
* @param ptr Opaque pointer for your userdata, passed through to the callback.
*
* @see xrt_prober_list_video_func_t
* @return 0 on success, <0 on error.
*/
int (*list_video_devices)(struct xrt_prober *xp, xrt_prober_list_video_func_t cb, void *ptr);
/*!
* Retrieve the raw @ref xrt_prober_entry and @ref xrt_auto_prober arrays.
*
* @param xp Pointer to self
* @param[out] out_entry_count The size of @p out_entries
* @param[out] out_entries An array of prober entries
* @param[out] out_auto_probers An array of up to @ref XRT_MAX_AUTO_PROBERS auto-probers
*
* @return 0 on success, <0 on error.
*/
int (*get_entries)(struct xrt_prober *xp,
size_t *out_entry_count,
struct xrt_prober_entry ***out_entries,
@ -246,6 +285,14 @@ struct xrt_prober
unsigned char *out_buffer,
size_t max_length);
/*!
* Determine whether a prober device can be opened.
*
* @param xp Pointer to self
* @param xpdev prober device
*
* @return true if @p xpdev can be opened.
*/
bool (*can_open)(struct xrt_prober *xp, struct xrt_prober_device *xpdev);
/*!
@ -558,9 +605,9 @@ static inline xrt_result_t
xrt_builder_estimate_system(struct xrt_builder *xb,
cJSON *config,
struct xrt_prober *xp,
struct xrt_builder_estimate *estimate)
struct xrt_builder_estimate *out_estimate)
{
return xb->estimate_system(xb, config, xp, estimate);
return xb->estimate_system(xb, config, xp, out_estimate);
}
/*!

46
src/xrt/include/xrt/xrt_results.h
View file

@ -1,4 +1,4 @@
// Copyright 2020, Collabora, Ltd.
// Copyright 2020-2022, Collabora, Ltd.
// SPDX-License-Identifier: BSL-1.0
/*!
* @file
@ -9,8 +9,20 @@
#pragma once
/*!
* Result type used across Monado.
*
* 0 is @ref XRT_SUCCESS, positive values are "special" non-error return codes (like timeout), negative values are
* errors.
*
* @see u_pp_xrt_result
* @ingroup xrt_iface
*/
typedef enum xrt_result
{
/*!
* The operation succeeded
*/
XRT_SUCCESS = 0,
/*!
@ -20,11 +32,33 @@ typedef enum xrt_result
*/
XRT_TIMEOUT = 2,
/*!
* A problem occurred either with the IPC transport itself, with invalid commands from the client, or with
* invalid responses from the server.
*/
XRT_ERROR_IPC_FAILURE = -1,
/*!
* Returned when trying to acquire or release an image and there is no image left to acquire/no space in the
* queue left to release to
*/
XRT_ERROR_NO_IMAGE_AVAILABLE = -2,
/*!
* Other unspecified error related to Vulkan
*/
XRT_ERROR_VULKAN = -3,
/*!
* Other unspecified error related to OpenGL
*/
XRT_ERROR_OPENGL = -4,
/*!
* The function tried to submit Vulkan commands but received an error.
*/
XRT_ERROR_FAILED_TO_SUBMIT_VULKAN_COMMANDS = -5,
/*!
*
* Returned when a swapchain create flag is passed that is valid, but
@ -35,45 +69,55 @@ typedef enum xrt_result
* isn't supported.
*/
XRT_ERROR_SWAPCHAIN_FLAG_VALID_BUT_UNSUPPORTED = -6,
/*!
* Could not allocate native image buffer(s).
*/
XRT_ERROR_ALLOCATION = -7,
/*!
* The pose is no longer active, this happens when the application
* tries to access a pose that is no longer active.
*/
XRT_ERROR_POSE_NOT_ACTIVE = -8,
/*!
* Creating a fence failed.
*/
XRT_ERROR_FENCE_CREATE_FAILED = -9,
/*!
* Getting or giving the native fence handle caused a error.
*/
XRT_ERROR_NATIVE_HANDLE_FENCE_ERROR = -10,
/*!
* Multiple not supported on this layer level (IPC, compositor).
*/
XRT_ERROR_MULTI_SESSION_NOT_IMPLEMENTED = -11,
/*!
* The requested format is not supported by Monado.
*/
XRT_ERROR_SWAPCHAIN_FORMAT_UNSUPPORTED = -12,
/*!
* The given config was EGL_NO_CONFIG_KHR and EGL_KHR_no_config_context
* is not supported by the display.
*/
XRT_ERROR_EGL_CONFIG_MISSING = -13,
/*!
* Failed to initialize threading components.
*/
XRT_ERROR_THREADING_INIT_FAILURE = -14,
/*!
* The client has not created a session on this IPC connection,
* which is needed for the given command.
*/
XRT_ERROR_IPC_SESSION_NOT_CREATED = -15,
/*!
* The client has already created a session on this IPC connection.
*/