From bc6cc85e7d516ec270d2dba1194cfabe40afe1b3 Mon Sep 17 00:00:00 2001 From: Ryan Pavlik Date: Wed, 3 Jun 2020 11:43:30 -0500 Subject: [PATCH] xrt: Improve doxygen documentation. --- doc/Doxyfile.in | 3 +- doc/changes/xrt/mr.365.md | 1 + src/xrt/auxiliary/os/os_ble.h | 1 + src/xrt/auxiliary/os/os_ble_dbus.c | 4 + src/xrt/auxiliary/os/os_hid.h | 17 ++ src/xrt/auxiliary/os/os_hid_hidraw.c | 3 + .../auxiliary/tracking/t_debug_hsv_filter.cpp | 6 + .../auxiliary/tracking/t_debug_hsv_picker.cpp | 6 + .../auxiliary/tracking/t_debug_hsv_viewer.cpp | 5 + src/xrt/auxiliary/tracking/t_hsv_filter.c | 5 + src/xrt/auxiliary/tracking/t_tracker_psmv.cpp | 9 + src/xrt/auxiliary/tracking/t_tracking.h | 43 +++++ src/xrt/auxiliary/util/u_distortion_mesh.c | 4 +- src/xrt/auxiliary/util/u_distortion_mesh.h | 9 +- src/xrt/auxiliary/util/u_sink.h | 40 +++- src/xrt/auxiliary/util/u_sink_converter.c | 5 + src/xrt/auxiliary/util/u_sink_deinterleaver.c | 7 +- src/xrt/auxiliary/util/u_sink_queue.c | 7 +- src/xrt/auxiliary/util/u_sink_quirk.c | 8 +- src/xrt/auxiliary/util/u_sink_split.c | 7 +- src/xrt/compositor/client/comp_gl_client.h | 18 +- .../compositor/client/comp_gl_xlib_client.h | 10 +- src/xrt/compositor/client/comp_vk_client.h | 20 +- src/xrt/compositor/main/comp_compositor.h | 34 ++-- src/xrt/compositor/main/comp_window.h | 9 +- .../main/comp_window_direct_nvidia.c | 4 +- .../main/comp_window_direct_randr.c | 4 +- src/xrt/compositor/main/comp_window_wayland.c | 2 + src/xrt/compositor/main/comp_window_xcb.c | 2 + src/xrt/drivers/arduino/arduino_device.c | 3 + src/xrt/drivers/arduino/arduino_prober.c | 4 + src/xrt/drivers/daydream/daydream_device.h | 3 + src/xrt/drivers/daydream/daydream_prober.c | 6 +- src/xrt/drivers/dummy/dummy_hmd.c | 3 + src/xrt/drivers/dummy/dummy_prober.c | 7 +- src/xrt/drivers/hdk/hdk_device.h | 3 + src/xrt/drivers/hydra/hydra_driver.c | 2 + src/xrt/drivers/north_star/ns_hmd.h | 2 + src/xrt/drivers/north_star/ns_prober.c | 6 + src/xrt/drivers/ohmd/oh_device.h | 3 + src/xrt/drivers/ohmd/oh_prober.c | 6 + src/xrt/drivers/psmv/psmv_driver.c | 2 + src/xrt/drivers/psvr/psvr_device.c | 1 + src/xrt/drivers/psvr/psvr_interface.h | 1 + src/xrt/drivers/psvr/psvr_prober.c | 4 + src/xrt/drivers/realsense/rs_6dof.c | 3 + src/xrt/drivers/survive/survive_driver.c | 7 + src/xrt/drivers/v4l2/v4l2_driver.c | 34 +++- src/xrt/drivers/v4l2/v4l2_interface.h | 1 + src/xrt/drivers/vive/vive_controller_driver.c | 1 + src/xrt/drivers/vive/vive_device.h | 3 + src/xrt/include/xrt/xrt_compositor.h | 180 ++++++++++++++---- src/xrt/include/xrt/xrt_device.h | 12 ++ src/xrt/include/xrt/xrt_frame.h | 15 +- src/xrt/include/xrt/xrt_frameserver.h | 40 ++-- src/xrt/include/xrt/xrt_gfx_egl.h | 3 + src/xrt/include/xrt/xrt_gfx_fd.h | 1 + src/xrt/include/xrt/xrt_gfx_vk.h | 3 + src/xrt/include/xrt/xrt_gfx_xlib.h | 3 + src/xrt/include/xrt/xrt_instance.h | 36 ++-- src/xrt/include/xrt/xrt_prober.h | 39 ++-- src/xrt/include/xrt/xrt_tracking.h | 13 ++ src/xrt/ipc/ipc_client.h | 10 +- src/xrt/ipc/ipc_client_compositor.c | 9 +- src/xrt/ipc/ipc_client_device.c | 7 + src/xrt/ipc/ipc_client_hmd.c | 7 + src/xrt/ipc/ipc_client_instance.c | 9 + src/xrt/state_trackers/gui/gui_common.h | 3 + src/xrt/state_trackers/gui/gui_ogl.c | 5 + .../state_trackers/gui/gui_scene_calibrate.c | 5 +- src/xrt/state_trackers/gui/gui_scene_debug.c | 4 + .../state_trackers/gui/gui_scene_main_menu.c | 4 + src/xrt/state_trackers/gui/gui_scene_video.c | 4 + src/xrt/state_trackers/prober/p_prober.h | 82 +++++++- src/xrt/state_trackers/prober/p_tracking.c | 4 + .../targets/common/target_instance_parts.h | 7 + src/xrt/targets/gui/gui_sdl2.h | 11 +- src/xrt/targets/openxr/oxr_sdl2_hack.c | 1 + 78 files changed, 767 insertions(+), 148 deletions(-) create mode 100644 doc/changes/xrt/mr.365.md diff --git a/doc/Doxyfile.in b/doc/Doxyfile.in index 6bc1c951b..a118a592b 100644 --- a/doc/Doxyfile.in +++ b/doc/Doxyfile.in @@ -48,6 +48,7 @@ ALWAYS_DETAILED_SEC = YES WARN_IF_UNDOCUMENTED = @DOXYGEN_WARN_UNDOCUMENTED@ EXTRACT_ALL = @DOXYGEN_EXTRACT_ALL@ +HIDE_UNDOC_RELATIONS = NO # The STRIP_FROM_INC_PATH tag can be used to strip a user-defined part of the # path mentioned in the documentation of a class, which tells the reader which @@ -2243,7 +2244,7 @@ DIA_PATH = # and usage relations if the target is undocumented or is not a class. # The default value is: YES. -HIDE_UNDOC_RELATIONS = YES +# HIDE_UNDOC_RELATIONS = YES # If you set the HAVE_DOT tag to YES then doxygen will assume the dot tool is # available from the path. This tool is part of Graphviz (see: diff --git a/doc/changes/xrt/mr.365.md b/doc/changes/xrt/mr.365.md new file mode 100644 index 000000000..1a4ec8b38 --- /dev/null +++ b/doc/changes/xrt/mr.365.md @@ -0,0 +1 @@ +Improve Doxygen documentation of interfaces. Now the inheritance structure and implementation of interfaces is shown in the docs, and helper functions that call through function pointers are listed as "member functions", to help developers understand the internal structure of Monado better. diff --git a/src/xrt/auxiliary/os/os_ble.h b/src/xrt/auxiliary/os/os_ble.h index 2c9d8ab73..fc880f6fb 100644 --- a/src/xrt/auxiliary/os/os_ble.h +++ b/src/xrt/auxiliary/os/os_ble.h @@ -20,6 +20,7 @@ extern "C" { /*! + * @interface os_ble_device * Representing a single ble notify attribute on a device. * * @ingroup aux_os diff --git a/src/xrt/auxiliary/os/os_ble_dbus.c b/src/xrt/auxiliary/os/os_ble_dbus.c index b00b6f37a..606dcd01b 100644 --- a/src/xrt/auxiliary/os/os_ble_dbus.c +++ b/src/xrt/auxiliary/os/os_ble_dbus.c @@ -28,6 +28,10 @@ * */ +/*! + * An implementation of @ref os_ble_device using a DBus connection to BlueZ. + * @implements os_ble_device + */ struct ble_notify { struct os_ble_device base; diff --git a/src/xrt/auxiliary/os/os_hid.h b/src/xrt/auxiliary/os/os_hid.h index b6a7509bf..bd5fbc9c8 100644 --- a/src/xrt/auxiliary/os/os_hid.h +++ b/src/xrt/auxiliary/os/os_hid.h @@ -21,6 +21,8 @@ extern "C" { /*! + * @interface os_hid_device + * * Representing a single hid interface on a device. */ struct os_hid_device @@ -56,6 +58,8 @@ struct os_hid_device * * If milliseconds are negative, this call blocks indefinitely, 0 polls, * and positive will block for that amount of milliseconds. + * + * @public @memberof os_hid_device */ static inline int os_hid_read(struct os_hid_device *hid_dev, @@ -68,6 +72,8 @@ os_hid_read(struct os_hid_device *hid_dev, /*! * Write an output report to the given device. + * + * @public @memberof os_hid_device */ static inline int os_hid_write(struct os_hid_device *hid_dev, const uint8_t *data, size_t size) @@ -80,6 +86,8 @@ os_hid_write(struct os_hid_device *hid_dev, const uint8_t *data, size_t size) * * If the device doesn't have more than one feature report, just request * report 0. + * + * @public @memberof os_hid_device */ static inline int os_hid_get_feature(struct os_hid_device *hid_dev, @@ -92,6 +100,8 @@ os_hid_get_feature(struct os_hid_device *hid_dev, /*! * Get a feature report with a timeout. + * + * @public @memberof os_hid_device */ static inline int os_hid_get_feature_timeout(struct os_hid_device *hid_dev, @@ -107,6 +117,8 @@ os_hid_get_feature_timeout(struct os_hid_device *hid_dev, * * The first byte of the buffer is the report number, to be followed by * the data of the report. + * + * @public @memberof os_hid_device */ static inline int os_hid_set_feature(struct os_hid_device *hid_dev, @@ -118,6 +130,8 @@ os_hid_set_feature(struct os_hid_device *hid_dev, /*! * Close and free the given device. + * + * @public @memberof os_hid_device */ static inline void os_hid_destroy(struct os_hid_device *hid_dev) @@ -128,6 +142,9 @@ os_hid_destroy(struct os_hid_device *hid_dev) #ifdef XRT_OS_LINUX /*! * Open the given path as a hidraw device. + * + * @public @memberof hid_hidraw + * @relatesalso os_hid_device */ int os_hid_open_hidraw(const char *path, struct os_hid_device **out_hid); diff --git a/src/xrt/auxiliary/os/os_hid_hidraw.c b/src/xrt/auxiliary/os/os_hid_hidraw.c index bf938f276..5b5b03847 100644 --- a/src/xrt/auxiliary/os/os_hid_hidraw.c +++ b/src/xrt/auxiliary/os/os_hid_hidraw.c @@ -28,6 +28,9 @@ #include +/*! + * @implements os_hid_device + */ struct hid_hidraw { struct os_hid_device base; diff --git a/src/xrt/auxiliary/tracking/t_debug_hsv_filter.cpp b/src/xrt/auxiliary/tracking/t_debug_hsv_filter.cpp index ebe3f1219..371fcc06c 100644 --- a/src/xrt/auxiliary/tracking/t_debug_hsv_filter.cpp +++ b/src/xrt/auxiliary/tracking/t_debug_hsv_filter.cpp @@ -27,6 +27,12 @@ #define HSV2_WIN "HSV Channel #3 (Blue)" #define HSV3_WIN "HSV Channel #4 (White)" +/*! + * An @ref xrt_frame_sink that can be used to debug the behavior of + * @ref t_hsv_filter. + * @implements xrt_frame_sink + * @implements xrt_frame_node + */ class DebugHSVFilter { public: diff --git a/src/xrt/auxiliary/tracking/t_debug_hsv_picker.cpp b/src/xrt/auxiliary/tracking/t_debug_hsv_picker.cpp index 432050468..bedf59ba7 100644 --- a/src/xrt/auxiliary/tracking/t_debug_hsv_picker.cpp +++ b/src/xrt/auxiliary/tracking/t_debug_hsv_picker.cpp @@ -28,6 +28,12 @@ #define max(a, b) (a > b ? a : b) #define min(a, b) (a < b ? a : b) +/*! + * An @ref xrt_frame_sink that can be used to select HSV thresholds + * interactively. + * @implements xrt_frame_sink + * @implements xrt_frame_node + */ class DebugHSVPicker { public: diff --git a/src/xrt/auxiliary/tracking/t_debug_hsv_viewer.cpp b/src/xrt/auxiliary/tracking/t_debug_hsv_viewer.cpp index a18b27ed0..450d89f53 100644 --- a/src/xrt/auxiliary/tracking/t_debug_hsv_viewer.cpp +++ b/src/xrt/auxiliary/tracking/t_debug_hsv_viewer.cpp @@ -23,6 +23,11 @@ #define HSV_WIN "HSV Filter Tester" +/*! + * An @ref xrt_frame_sink related to debug viewing of HSV. + * @implements xrt_frame_sink + * @implements xrt_frame_node + */ class DebugHSVViewer { public: diff --git a/src/xrt/auxiliary/tracking/t_hsv_filter.c b/src/xrt/auxiliary/tracking/t_hsv_filter.c index 2175091e8..4ca93d607 100644 --- a/src/xrt/auxiliary/tracking/t_hsv_filter.c +++ b/src/xrt/auxiliary/tracking/t_hsv_filter.c @@ -132,6 +132,11 @@ t_hsv_build_optimized_table(struct t_hsv_filter_params *params, #define NUM_CHANNELS 4 +/*! + * An @ref xrt_frame_sink that splits the input based on hue. + * @implements xrt_frame_sink + * @implements xrt_frame_node + */ struct t_hsv_filter { struct xrt_frame_sink base; diff --git a/src/xrt/auxiliary/tracking/t_tracker_psmv.cpp b/src/xrt/auxiliary/tracking/t_tracker_psmv.cpp index 417f4b1a1..796805872 100644 --- a/src/xrt/auxiliary/tracking/t_tracker_psmv.cpp +++ b/src/xrt/auxiliary/tracking/t_tracker_psmv.cpp @@ -33,6 +33,8 @@ /*! * Single camera. + * + * @see TrackerPSMV */ struct View { @@ -63,6 +65,13 @@ struct View } }; +/*! + * The core object of the PS Move tracking setup. + * + * @implements xrt_tracked_psmv + * @implements xrt_frame_sink + * @implements xrt_frame_node + */ struct TrackerPSMV { struct xrt_tracked_psmv base = {}; diff --git a/src/xrt/auxiliary/tracking/t_tracking.h b/src/xrt/auxiliary/tracking/t_tracking.h index 81c3a77b4..82bc545e5 100644 --- a/src/xrt/auxiliary/tracking/t_tracking.h +++ b/src/xrt/auxiliary/tracking/t_tracking.h @@ -129,12 +129,16 @@ struct t_stereo_camera_calibration /*! * Allocates a new stereo calibration data, unreferences the old @p calib. + * + * @public @memberof t_stereo_camera_calibration */ void t_stereo_camera_calibration_alloc(struct t_stereo_camera_calibration **calib); /*! * Only to be called by @p t_stereo_camera_calibration_reference. + * + * @private @memberof t_stereo_camera_calibration */ void t_stereo_camera_calibration_destroy(struct t_stereo_camera_calibration *c); @@ -147,6 +151,8 @@ t_stereo_camera_calibration_destroy(struct t_stereo_camera_calibration *c); * @p dst points to will be set to @p src. * @param[in] src Object to be have it's refcount increased @p dst is set to * this. + * + * @relates t_stereo_camera_calibration */ static inline void t_stereo_camera_calibration_reference(struct t_stereo_camera_calibration **dst, @@ -257,6 +263,10 @@ struct t_hsv_filter_color uint8_t v_min; }; +/*! + * Parameters for constructing an HSV filter. + * @relates t_hsv_filter + */ struct t_hsv_filter_params { struct t_hsv_filter_color color[3]; @@ -299,6 +309,12 @@ t_hsv_filter_sample(struct t_hsv_filter_optimized_table *t, return t->v[y / T_HSV_STEP][u / T_HSV_STEP][v / T_HSV_STEP]; } +/*! + * Construct an HSV filter sink. + * @public @memberof t_hsv_filter + * + * @relates xrt_frame_context + */ int t_hsv_filter_create(struct xrt_frame_context *xfctx, struct t_hsv_filter_params *params, @@ -312,9 +328,15 @@ t_hsv_filter_create(struct xrt_frame_context *xfctx, * */ +/*! + * @public @memberof xrt_tracked_psmv + */ int t_psmv_start(struct xrt_tracked_psmv *xtmv); +/*! + * @public @memberof xrt_tracked_psmv + */ int t_psmv_create(struct xrt_frame_context *xfctx, struct xrt_colour_rgb_f32 *rgb, @@ -322,9 +344,15 @@ t_psmv_create(struct xrt_frame_context *xfctx, struct xrt_tracked_psmv **out_xtmv, struct xrt_frame_sink **out_sink); +/*! + * @public @memberof xrt_tracked_psvr + */ int t_psvr_start(struct xrt_tracked_psvr *xtvr); +/*! + * @public @memberof xrt_tracked_psvr + */ int t_psvr_create(struct xrt_frame_context *xfctx, struct t_stereo_camera_calibration *data, @@ -420,6 +448,7 @@ struct t_calibration_params /*! * Sets the calibration parameters to the their default values. + * @public @memberof t_calibration_params */ static inline void t_calibration_params_default(struct t_calibration_params *p) @@ -473,6 +502,8 @@ t_calibration_params_default(struct t_calibration_params *p) * retained, and pointed-to struct modified. * @param gui Frame sink * @param out_sink Output: created frame sink. + * + * @relates xrt_frame_context */ int t_calibration_stereo_create(struct xrt_frame_context *xfctx, @@ -488,22 +519,34 @@ t_calibration_stereo_create(struct xrt_frame_context *xfctx, * */ +/*! + * @relates xrt_frame_context + */ int t_convert_yuv_or_yuyv_create(struct xrt_frame_sink *next, struct xrt_frame_sink **out_sink); +/*! + * @relates xrt_frame_context + */ int t_debug_hsv_picker_create(struct xrt_frame_context *xfctx, struct xrt_frame_sink *passthrough, struct xrt_frame_sink **out_sink); +/*! + * @relates xrt_frame_context + */ int t_debug_hsv_viewer_create(struct xrt_frame_context *xfctx, struct xrt_frame_sink *passthrough, struct xrt_frame_sink **out_sink); +/*! + * @relates xrt_frame_context + */ int t_debug_hsv_filter_create(struct xrt_frame_context *xfctx, struct xrt_frame_sink *passthrough, diff --git a/src/xrt/auxiliary/util/u_distortion_mesh.c b/src/xrt/auxiliary/util/u_distortion_mesh.c index 89c4aaa31..aebed7a15 100644 --- a/src/xrt/auxiliary/util/u_distortion_mesh.c +++ b/src/xrt/auxiliary/util/u_distortion_mesh.c @@ -158,7 +158,9 @@ u_distortion_mesh_from_gen(struct u_uv_generator *gen, #define div_scalar m_vec2_div_scalar #define len m_vec2_len - +/*! + * @implements u_uv_generator + */ struct panotools_state { struct u_uv_generator base; diff --git a/src/xrt/auxiliary/util/u_distortion_mesh.h b/src/xrt/auxiliary/util/u_distortion_mesh.h index 203f28c0e..b91a1b623 100644 --- a/src/xrt/auxiliary/util/u_distortion_mesh.h +++ b/src/xrt/auxiliary/util/u_distortion_mesh.h @@ -47,7 +47,9 @@ struct u_uv_triplet }; /*! - * Generator struct for building meshes, can be implemented by drivers for + * @interface u_uv_generator + * + * Generator interface for building meshes, can be implemented by drivers for * special meshes. * * @ingroup aux_util @@ -67,6 +69,8 @@ struct u_uv_generator * Given a @ref u_uv_generator generates num_views meshes, populates target. * * @ingroup aux_util + * @public @memberof u_uv_generator + * @relatesalso xrt_hmd_parts */ void u_distortion_mesh_from_gen(struct u_uv_generator *, @@ -78,6 +82,7 @@ u_distortion_mesh_from_gen(struct u_uv_generator *, * values into it. This probably isn't the function you want. * * @ingroup aux_util + * @see u_distortion_mesh_from_panotools */ void u_distortion_mesh_generator_from_panotools( @@ -90,6 +95,7 @@ u_distortion_mesh_generator_from_panotools( * This is probably the function you want. * * @ingroup aux_util + * @relates xrt_hmd_parts */ void u_distortion_mesh_from_panotools(const struct u_panotools_values *left, @@ -100,6 +106,7 @@ u_distortion_mesh_from_panotools(const struct u_panotools_values *left, * Create two distortion meshes with no distortion. * * @ingroup aux_util + * @relates xrt_hmd_parts */ void u_distortion_mesh_none(struct xrt_hmd_parts *target); diff --git a/src/xrt/auxiliary/util/u_sink.h b/src/xrt/auxiliary/util/u_sink.h index d22eb2284..46d56a4fb 100644 --- a/src/xrt/auxiliary/util/u_sink.h +++ b/src/xrt/auxiliary/util/u_sink.h @@ -15,7 +15,9 @@ extern "C" { #endif - +/*! + * @see u_sink_quirk_create + */ struct u_sink_quirk_params { bool stereo_sbs; @@ -23,43 +25,77 @@ struct u_sink_quirk_params bool leap_motion; }; +/*! + * @relatesalso xrt_frame_sink + * @relates xrt_frame_context + */ void u_sink_create_format_converter(struct xrt_frame_context *xfctx, enum xrt_format f, struct xrt_frame_sink *downstream, struct xrt_frame_sink **out_xfs); +/*! + * @relatesalso xrt_frame_sink + * @relates xrt_frame_context + */ void u_sink_create_to_r8g8b8_or_l8(struct xrt_frame_context *xfctx, struct xrt_frame_sink *downstream, struct xrt_frame_sink **out_xfs); +/*! + * @relatesalso xrt_frame_sink + * @relates xrt_frame_context + */ void u_sink_create_to_yuv_yuyv_uyvy_or_l8(struct xrt_frame_context *xfctx, struct xrt_frame_sink *downstream, struct xrt_frame_sink **out_xfs); +/*! + * @relatesalso xrt_frame_sink + * @relates xrt_frame_context + */ void u_sink_create_to_yuv_or_yuyv(struct xrt_frame_context *xfctx, struct xrt_frame_sink *downstream, struct xrt_frame_sink **out_xfs); - +/*! + * @public @memberof u_sink_deinterleaver + * @relatesalso xrt_frame_sink + * @relates xrt_frame_context + */ void u_sink_deinterleaver_create(struct xrt_frame_context *xfctx, struct xrt_frame_sink *downstream, struct xrt_frame_sink **out_xfs); +/*! + * @public @memberof u_sink_queue + * @relatesalso xrt_frame_sink + * @relates xrt_frame_context + */ bool u_sink_queue_create(struct xrt_frame_context *xfctx, struct xrt_frame_sink *downstream, struct xrt_frame_sink **out_xfs); +/*! + * @public @memberof u_sink_quirk + * @relatesalso xrt_frame_sink + * @relates xrt_frame_context + */ void u_sink_quirk_create(struct xrt_frame_context *xfctx, struct xrt_frame_sink *downstream, struct u_sink_quirk_params *params, struct xrt_frame_sink **out_xfs); +/*! + * @public @memberof u_sink_split + * @relatesalso xrt_frame_sink + */ void u_sink_split_create(struct xrt_frame_context *xfctx, struct xrt_frame_sink *left, diff --git a/src/xrt/auxiliary/util/u_sink_converter.c b/src/xrt/auxiliary/util/u_sink_converter.c index a53898b35..548e6c5f2 100644 --- a/src/xrt/auxiliary/util/u_sink_converter.c +++ b/src/xrt/auxiliary/util/u_sink_converter.c @@ -26,6 +26,11 @@ * */ +/*! + * An @ref xrt_frame_sink that converts frames. + * @implements xrt_frame_sink + * @implements xrt_frame_node + */ struct u_sink_converter { struct xrt_frame_sink base; diff --git a/src/xrt/auxiliary/util/u_sink_deinterleaver.c b/src/xrt/auxiliary/util/u_sink_deinterleaver.c index d488297d8..fea39507d 100644 --- a/src/xrt/auxiliary/util/u_sink_deinterleaver.c +++ b/src/xrt/auxiliary/util/u_sink_deinterleaver.c @@ -2,7 +2,7 @@ // SPDX-License-Identifier: BSL-1.0 /*! * @file - * @brief A @ref xrt_frame_sink that deinterleaves stereo frames. + * @brief An @ref xrt_frame_sink that deinterleaves stereo frames. * @author Pete Black * @author Jakob Bornecrantz * @ingroup aux_util @@ -13,6 +13,11 @@ #include "util/u_frame.h" +/*! + * An @ref xrt_frame_sink that deinterleaves stereo frames. + * @implements xrt_frame_sink + * @implements xrt_frame_node + */ struct u_sink_deinterleaver { struct xrt_frame_sink base; diff --git a/src/xrt/auxiliary/util/u_sink_queue.c b/src/xrt/auxiliary/util/u_sink_queue.c index 663750c78..8e68c1dd1 100644 --- a/src/xrt/auxiliary/util/u_sink_queue.c +++ b/src/xrt/auxiliary/util/u_sink_queue.c @@ -2,7 +2,7 @@ // SPDX-License-Identifier: BSL-1.0 /*! * @file - * @brief A @ref xrt_frame_sink queue. + * @brief An @ref xrt_frame_sink queue. * @author Jakob Bornecrantz * @ingroup aux_util */ @@ -14,6 +14,11 @@ #include +/*! + * An @ref xrt_frame_sink queue. + * @implements xrt_frame_sink + * @implements xrt_frame_node + */ struct u_sink_queue { struct xrt_frame_sink base; diff --git a/src/xrt/auxiliary/util/u_sink_quirk.c b/src/xrt/auxiliary/util/u_sink_quirk.c index a9ee746d9..2644f1f99 100644 --- a/src/xrt/auxiliary/util/u_sink_quirk.c +++ b/src/xrt/auxiliary/util/u_sink_quirk.c @@ -2,7 +2,7 @@ // SPDX-License-Identifier: BSL-1.0 /*! * @file - * @brief A @ref xrt_frame_sink that quirks frames. + * @brief An @ref xrt_frame_sink that quirks frames. * @author Jakob Bornecrantz * @ingroup aux_util */ @@ -10,7 +10,11 @@ #include "util/u_misc.h" #include "util/u_sink.h" - +/*! + * An @ref xrt_frame_sink that quirks frames. + * @implements xrt_frame_sink + * @implements xrt_frame_node + */ struct u_sink_quirk { struct xrt_frame_sink base; diff --git a/src/xrt/auxiliary/util/u_sink_split.c b/src/xrt/auxiliary/util/u_sink_split.c index b0f94c7ae..fa8b00506 100644 --- a/src/xrt/auxiliary/util/u_sink_split.c +++ b/src/xrt/auxiliary/util/u_sink_split.c @@ -2,7 +2,7 @@ // SPDX-License-Identifier: BSL-1.0 /*! * @file - * @brief A @ref xrt_frame_sink splitter. + * @brief An @ref xrt_frame_sink splitter. * @author Jakob Bornecrantz * @ingroup aux_util */ @@ -11,6 +11,11 @@ #include "util/u_sink.h" +/*! + * An @ref xrt_frame_sink splitter. + * @implements xrt_frame_sink + * @implements xrt_frame_node + */ struct u_sink_split { struct xrt_frame_sink base; diff --git a/src/xrt/compositor/client/comp_gl_client.h b/src/xrt/compositor/client/comp_gl_client.h index 5a5bd72ca..50615d1e0 100644 --- a/src/xrt/compositor/client/comp_gl_client.h +++ b/src/xrt/compositor/client/comp_gl_client.h @@ -23,11 +23,14 @@ extern "C" { */ /*! + * @class client_gl_swapchain + * * Wraps the real compositor swapchain providing a OpenGL based interface. * * Almost a one to one mapping to a OpenXR swapchain. * * @ingroup comp_client + * @implements xrt_swapchain_gl */ struct client_gl_swapchain { @@ -37,9 +40,12 @@ struct client_gl_swapchain }; /*! + * @class client_gl_compositor + * * Wraps the real compositor providing a OpenGL based interface. * * @ingroup comp_client + * @implements xrt_compositor_gl */ struct client_gl_compositor { @@ -56,7 +62,8 @@ struct client_gl_compositor */ /*! - * Convenience function to convert a xrt_swapchain to a client_gl_swapchain. + * Down-cast helper. + * @private @memberof client_gl_swapchain */ static inline struct client_gl_swapchain * client_gl_swapchain(struct xrt_swapchain *xsc) @@ -65,7 +72,8 @@ client_gl_swapchain(struct xrt_swapchain *xsc) } /*! - * Convenience function to convert a xrt_compositor to a client_gl_compositor. + * Down-cast helper. + * @private @memberof client_gl_compositor */ static inline struct client_gl_compositor * client_gl_compositor(struct xrt_compositor *xc) @@ -79,6 +87,12 @@ typedef client_gl_void_ptr_func (*client_gl_get_procaddr)(const char *name); /*! * Fill in a client_gl_compositor and do common OpenGL sanity checking. + * + * OpenGL can have multiple backing window systems we have to interact with, so + * there isn't just one unified OpenGL client constructor. + * + * @public @memberof client_gl_compositor + * @relatesalso xrt_compositor_fd */ bool client_gl_compositor_init(struct client_gl_compositor *c, diff --git a/src/xrt/compositor/client/comp_gl_xlib_client.h b/src/xrt/compositor/client/comp_gl_xlib_client.h index 45e530ea7..2b5521fa6 100644 --- a/src/xrt/compositor/client/comp_gl_xlib_client.h +++ b/src/xrt/compositor/client/comp_gl_xlib_client.h @@ -18,9 +18,11 @@ extern "C" { /*! + * @class client_gl_xlib_compositor * A client facing xlib OpenGL base compositor. * * @ingroup comp_client + * @extends client_gl_compositor */ struct client_gl_xlib_compositor { @@ -29,10 +31,9 @@ struct client_gl_xlib_compositor }; /*! - * Convenience function to convert a xrt_compositor to a - * client_gl_xlib_compositor. + * Down-cast helper. * - * @ingroup comp_client + * @private @memberof client_gl_xlib_compositor */ static inline struct client_gl_xlib_compositor * client_gl_xlib_compositor(struct xrt_compositor *xc) @@ -43,7 +44,8 @@ client_gl_xlib_compositor(struct xrt_compositor *xc) /*! * Create a new client_gl_xlib_compositor. * - * @ingroup comp_client + * @public @memberof client_gl_xlib_compositor + * @relatesalso xrt_compositor_fd */ struct client_gl_xlib_compositor * client_gl_xlib_compositor_create(struct xrt_compositor_fd *xcfd, diff --git a/src/xrt/compositor/client/comp_vk_client.h b/src/xrt/compositor/client/comp_vk_client.h index f1f896c6f..851edb698 100644 --- a/src/xrt/compositor/client/comp_vk_client.h +++ b/src/xrt/compositor/client/comp_vk_client.h @@ -32,23 +32,32 @@ struct client_vk_compositor; * Almost a one to one mapping to a OpenXR swapchain. * * @ingroup comp_client + * @implements xrt_swapchain_vk */ struct client_vk_swapchain { struct xrt_swapchain_vk base; + + //! Owning reference to the backing fd swapchain. struct xrt_swapchain_fd *xscfd; + + //! Non-owning reference to our parent compositor. struct client_vk_compositor *c; }; /*! + * @class client_vk_compositor + * * Wraps the real compositor providing a Vulkan based interface. * * @ingroup comp_client + * @implements xrt_compositor_vk */ struct client_vk_compositor { struct xrt_compositor_vk base; + //! Owning reference to the backing fd compositor struct xrt_compositor_fd *xcfd; struct vk_bundle vk; @@ -62,9 +71,9 @@ struct client_vk_compositor */ /*! - * Convenience function to convert a xrt_swapchain to a client_vk_swapchain. + * Down-cast helper. * - * @ingroup comp_client + * @private @memberof client_vk_swapchain */ static inline struct client_vk_swapchain * client_vk_swapchain(struct xrt_swapchain *xsc) @@ -73,9 +82,9 @@ client_vk_swapchain(struct xrt_swapchain *xsc) } /*! - * Convenience function to convert a xrt_compositor to a client_vk_compositor. + * Down-cast helper. * - * @ingroup comp_client + * @private @memberof client_vk_compositor */ static inline struct client_vk_compositor * client_vk_compositor(struct xrt_compositor *xc) @@ -86,7 +95,8 @@ client_vk_compositor(struct xrt_compositor *xc) /*! * Create a new client_vk_compositor. * - * @ingroup comp_client + * @public @memberof client_vk_compositor + * @relatesalso xrt_compositor_fd */ struct client_vk_compositor * client_vk_compositor_create(struct xrt_compositor_fd *xcfd, diff --git a/src/xrt/compositor/main/comp_compositor.h b/src/xrt/compositor/main/comp_compositor.h index fa5337869..e9142241a 100644 --- a/src/xrt/compositor/main/comp_compositor.h +++ b/src/xrt/compositor/main/comp_compositor.h @@ -37,6 +37,7 @@ extern "C" { * A single swapchain image, holds the needed state for tracking image usage. * * @ingroup comp_main + * @see comp_swapchain */ struct comp_swapchain_image { @@ -59,6 +60,8 @@ struct comp_swapchain_image * Not used by the window backend that uses the vk_swapchain to render to. * * @ingroup comp_main + * @implements xrt_swapchain_fd + * @see comp_compositor */ struct comp_swapchain { @@ -74,10 +77,14 @@ struct comp_swapchain */ struct u_index_fifo fifo; }; - +/*! + * Tag for distinguishing the union contents of @ref comp_layer. + */ enum comp_layer_type { + //! comp_layer::stereo is initialized COMP_LAYER_STEREO_PROJECTION, + //! comp_layer::quad is initialized COMP_LAYER_QUAD, }; @@ -85,6 +92,7 @@ enum comp_layer_type * A quad layer. * * @ingroup comp_main + * @see comp_layer */ struct comp_layer_quad { @@ -101,6 +109,7 @@ struct comp_layer_quad * A stereo projection layer. * * @ingroup comp_main + * @see comp_layer */ struct comp_layer_stereo { @@ -116,6 +125,7 @@ struct comp_layer_stereo * A single layer. * * @ingroup comp_main + * @see comp_layer_slot */ struct comp_layer { @@ -133,6 +143,7 @@ struct comp_layer * A stack of layers. * * @ingroup comp_main + * @see comp_compositor */ struct comp_layer_slot { @@ -147,6 +158,7 @@ struct comp_layer_slot * Main compositor struct tying everything in the compositor together. * * @ingroup comp_main + * @implements xrt_compositor_fd */ struct comp_compositor { @@ -245,7 +257,7 @@ struct comp_compositor /*! * Convenience function to convert a xrt_swapchain to a comp_swapchain. * - * @ingroup comp_main + * @private @memberof comp_swapchain */ static inline struct comp_swapchain * comp_swapchain(struct xrt_swapchain *xsc) @@ -256,7 +268,7 @@ comp_swapchain(struct xrt_swapchain *xsc) /*! * Convenience function to convert a xrt_compositor to a comp_compositor. * - * @ingroup comp_main + * @private @memberof comp_compositor */ static inline struct comp_compositor * comp_compositor(struct xrt_compositor *xc) @@ -268,7 +280,7 @@ comp_compositor(struct xrt_compositor *xc) * Do garbage collection, destroying any resources that has been scheduled for * destruction from other threads. * - * @ingroup comp_main + * @public @memberof comp_compositor */ void comp_compositor_garbage_collect(struct comp_compositor *c); @@ -276,7 +288,7 @@ comp_compositor_garbage_collect(struct comp_compositor *c); /*! * A compositor function that is implemented in the swapchain code. * - * @ingroup comp_main + * @public @memberof comp_compositor */ struct xrt_swapchain * comp_swapchain_create(struct xrt_compositor *xc, @@ -295,7 +307,7 @@ comp_swapchain_create(struct xrt_compositor *xc, * does the actual destruction and is called from @ref * comp_compositor_garbage_collect. * - * @ingroup comp_main + * @private @memberof comp_swapchain */ void comp_swapchain_really_destroy(struct comp_swapchain *sc); @@ -303,7 +315,7 @@ comp_swapchain_really_destroy(struct comp_swapchain *sc); /*! * Printer helper. * - * @ingroup comp_main + * @public @memberof comp_compositor */ void comp_compositor_print(struct comp_compositor *c, @@ -314,7 +326,7 @@ comp_compositor_print(struct comp_compositor *c, /*! * Spew level logging. * - * @ingroup comp_main + * @relates comp_compositor */ #define COMP_SPEW(c, ...) \ do { \ @@ -326,7 +338,7 @@ comp_compositor_print(struct comp_compositor *c, /*! * Debug level logging. * - * @ingroup comp_main + * @relates comp_compositor */ #define COMP_DEBUG(c, ...) \ do { \ @@ -338,7 +350,7 @@ comp_compositor_print(struct comp_compositor *c, /*! * Mode printing. * - * @ingroup comp_main + * @relates comp_compositor */ #define COMP_PRINT_MODE(c, ...) \ do { \ @@ -350,7 +362,7 @@ comp_compositor_print(struct comp_compositor *c, /*! * Error level logging. * - * @ingroup comp_main + * @relates comp_compositor */ #define COMP_ERROR(c, ...) \ do { \ diff --git a/src/xrt/compositor/main/comp_window.h b/src/xrt/compositor/main/comp_window.h index 10551b103..550917cfd 100644 --- a/src/xrt/compositor/main/comp_window.h +++ b/src/xrt/compositor/main/comp_window.h @@ -25,6 +25,7 @@ extern "C" { */ /*! + * @interface comp_window * A output device or a window, often directly connected to the device. * * @ingroup comp_main @@ -61,6 +62,7 @@ struct comp_window * Create a xcb window. * * @ingroup comp_main + * @public @memberof comp_window_xcb */ struct comp_window * comp_window_xcb_create(struct comp_compositor *c); @@ -71,6 +73,7 @@ comp_window_xcb_create(struct comp_compositor *c); * Create a wayland window. * * @ingroup comp_main + * @public @memberof comp_window_wayland */ struct comp_window * comp_window_wayland_create(struct comp_compositor *c); @@ -78,17 +81,19 @@ comp_window_wayland_create(struct comp_compositor *c); #ifdef VK_USE_PLATFORM_XLIB_XRANDR_EXT /*! - * Create a direct surface to a HMD over RandR. + * Create a direct surface to an HMD over RandR. * * @ingroup comp_main + * @public @memberof comp_window_direct_randr */ struct comp_window * comp_window_direct_randr_create(struct comp_compositor *c); /*! - * Create a direct surface to a HMD on NVIDIA. + * Create a direct surface to an HMD on NVIDIA. * * @ingroup comp_main + * @public @memberof comp_window_direct_nvidia */ struct comp_window * comp_window_direct_nvidia_create(struct comp_compositor *c); diff --git a/src/xrt/compositor/main/comp_window_direct_nvidia.c b/src/xrt/compositor/main/comp_window_direct_nvidia.c index 779b8960c..4462fad94 100644 --- a/src/xrt/compositor/main/comp_window_direct_nvidia.c +++ b/src/xrt/compositor/main/comp_window_direct_nvidia.c @@ -31,6 +31,8 @@ struct comp_window_direct_nvidia_display /*! * Direct mode "window" into a device, using Vulkan direct mode extension * and xcb. + * + * @implements comp_window */ struct comp_window_direct_nvidia { @@ -43,7 +45,7 @@ struct comp_window_direct_nvidia /* * - * Pre decalre functions + * Forward declare functions * */ diff --git a/src/xrt/compositor/main/comp_window_direct_randr.c b/src/xrt/compositor/main/comp_window_direct_randr.c index fc1a7dd9a..0ec21e6d7 100644 --- a/src/xrt/compositor/main/comp_window_direct_randr.c +++ b/src/xrt/compositor/main/comp_window_direct_randr.c @@ -39,6 +39,8 @@ struct comp_window_direct_randr_display /*! * Direct mode "window" into a device, using Vulkan direct mode extension * and xcb. + * + * @implements comp_window */ struct comp_window_direct_randr { @@ -56,7 +58,7 @@ struct comp_window_direct_randr /* * - * Pre decalre functions + * Forward declare functions * */ diff --git a/src/xrt/compositor/main/comp_window_wayland.c b/src/xrt/compositor/main/comp_window_wayland.c index 1a3c6d3bb..c26d6cdc0 100644 --- a/src/xrt/compositor/main/comp_window_wayland.c +++ b/src/xrt/compositor/main/comp_window_wayland.c @@ -29,6 +29,8 @@ /*! * A Wayland connection and window. + * + * @implements comp_window */ struct comp_window_wayland { diff --git a/src/xrt/compositor/main/comp_window_xcb.c b/src/xrt/compositor/main/comp_window_xcb.c index e2c29bffa..da0687c92 100644 --- a/src/xrt/compositor/main/comp_window_xcb.c +++ b/src/xrt/compositor/main/comp_window_xcb.c @@ -43,6 +43,8 @@ struct comp_window_xcb_display /*! * A xcb connection and window. + * + * @implements comp_window */ struct comp_window_xcb { diff --git a/src/xrt/drivers/arduino/arduino_device.c b/src/xrt/drivers/arduino/arduino_device.c index 6eb012b76..be2350b47 100644 --- a/src/xrt/drivers/arduino/arduino_device.c +++ b/src/xrt/drivers/arduino/arduino_device.c @@ -57,6 +57,9 @@ struct arduino_parsed_input struct arduino_parsed_sample sample; }; +/*! + * @implements xrt_device + */ struct arduino_device { struct xrt_device base; diff --git a/src/xrt/drivers/arduino/arduino_prober.c b/src/xrt/drivers/arduino/arduino_prober.c index e8058993c..55c4c1f89 100644 --- a/src/xrt/drivers/arduino/arduino_prober.c +++ b/src/xrt/drivers/arduino/arduino_prober.c @@ -35,6 +35,7 @@ DEBUG_GET_ONCE_BOOL_OPTION(arduino_debug, "ARDUINO_PRINT_DEBUG", false) * Arduino prober struct. * * @ingroup drv_arduino + * @implements xrt_auto_prober */ struct arduino_prober { @@ -52,12 +53,14 @@ struct arduino_prober * */ +//! @private @memberof arduino_prober static inline struct arduino_prober * arduino_prober(struct xrt_auto_prober *p) { return (struct arduino_prober *)p; } +//! @public @memberof arduino_prober static void arduino_prober_destroy(struct xrt_auto_prober *p) { @@ -66,6 +69,7 @@ arduino_prober_destroy(struct xrt_auto_prober *p) free(ap); } +//! @public @memberof arduino_prober static struct xrt_device * arduino_prober_autoprobe(struct xrt_auto_prober *xap, cJSON *attached_data, diff --git a/src/xrt/drivers/daydream/daydream_device.h b/src/xrt/drivers/daydream/daydream_device.h index d6c63cadf..dca6a3211 100644 --- a/src/xrt/drivers/daydream/daydream_device.h +++ b/src/xrt/drivers/daydream/daydream_device.h @@ -61,6 +61,9 @@ struct daydream_parsed_input struct daydream_parsed_sample sample; }; +/*! + * @implements xrt_device + */ struct daydream_device { struct xrt_device base; diff --git a/src/xrt/drivers/daydream/daydream_prober.c b/src/xrt/drivers/daydream/daydream_prober.c index f50e3d908..10015d52d 100644 --- a/src/xrt/drivers/daydream/daydream_prober.c +++ b/src/xrt/drivers/daydream/daydream_prober.c @@ -27,7 +27,7 @@ * */ -// Should the experimental PSVR driver be enabled. +// Should the experimental Daydream driver be enabled. DEBUG_GET_ONCE_BOOL_OPTION(daydream_enable, "DAYDREAM_ENABLE", true) DEBUG_GET_ONCE_BOOL_OPTION(daydream_spew, "DAYDREAM_PRINT_SPEW", false) DEBUG_GET_ONCE_BOOL_OPTION(daydream_debug, "DAYDREAM_PRINT_DEBUG", false) @@ -36,6 +36,7 @@ DEBUG_GET_ONCE_BOOL_OPTION(daydream_debug, "DAYDREAM_PRINT_DEBUG", false) * Daydream prober struct. * * @ingroup drv_daydream + * @implements xrt_auto_prober */ struct daydream_prober { @@ -53,12 +54,14 @@ struct daydream_prober * */ +//! @private @memberof daydream_prober static inline struct daydream_prober * daydream_prober(struct xrt_auto_prober *p) { return (struct daydream_prober *)p; } +//! @public @memberof daydream_prober static void daydream_prober_destroy(struct xrt_auto_prober *p) { @@ -67,6 +70,7 @@ daydream_prober_destroy(struct xrt_auto_prober *p) free(pdaydream); } +//! @public @memberof daydream_prober static struct xrt_device * daydream_prober_autoprobe(struct xrt_auto_prober *xap, cJSON *attached_data, diff --git a/src/xrt/drivers/dummy/dummy_hmd.c b/src/xrt/drivers/dummy/dummy_hmd.c index 63ca09eff..01b516321 100644 --- a/src/xrt/drivers/dummy/dummy_hmd.c +++ b/src/xrt/drivers/dummy/dummy_hmd.c @@ -32,6 +32,9 @@ * */ +/*! + * @implements xrt_device + */ struct dummy_hmd { struct xrt_device base; diff --git a/src/xrt/drivers/dummy/dummy_prober.c b/src/xrt/drivers/dummy/dummy_prober.c index d5cd9acdb..14bc2211a 100644 --- a/src/xrt/drivers/dummy/dummy_prober.c +++ b/src/xrt/drivers/dummy/dummy_prober.c @@ -17,18 +17,22 @@ #include "dummy_interface.h" - +/*! + * @implements xrt_auto_prober + */ struct dummy_prober { struct xrt_auto_prober base; }; +//! @private @memberof dummy_prober static inline struct dummy_prober * dummy_prober(struct xrt_auto_prober *p) { return (struct dummy_prober *)p; } +//! @public @memberof dummy_prober static void dummy_prober_destroy(struct xrt_auto_prober *p) { @@ -37,6 +41,7 @@ dummy_prober_destroy(struct xrt_auto_prober *p) free(dp); } +//! @public @memberof dummy_prober static struct xrt_device * dummy_prober_autoprobe(struct xrt_auto_prober *xap, cJSON *attached_data, diff --git a/src/xrt/drivers/hdk/hdk_device.h b/src/xrt/drivers/hdk/hdk_device.h index dc317ac14..41941301f 100644 --- a/src/xrt/drivers/hdk/hdk_device.h +++ b/src/xrt/drivers/hdk/hdk_device.h @@ -24,6 +24,9 @@ enum HDK_VARIANT HDK_VARIANT_2 }; +/*! + * @implements xrt_device + */ struct hdk_device { struct xrt_device base; diff --git a/src/xrt/drivers/hydra/hydra_driver.c b/src/xrt/drivers/hydra/hydra_driver.c index 475ac346b..7d6691d7f 100644 --- a/src/xrt/drivers/hydra/hydra_driver.c +++ b/src/xrt/drivers/hydra/hydra_driver.c @@ -154,6 +154,7 @@ struct hydra_device; * A Razer Hydra system containing two controllers. * * @ingroup drv_hydra + * @extends xrt_tracking_origin */ struct hydra_system { @@ -191,6 +192,7 @@ struct hydra_system * A Razer Hydra device, representing just a single controller. * * @ingroup drv_hydra + * @implements xrt_device */ struct hydra_device { diff --git a/src/xrt/drivers/north_star/ns_hmd.h b/src/xrt/drivers/north_star/ns_hmd.h index b75ce430c..64f456252 100644 --- a/src/xrt/drivers/north_star/ns_hmd.h +++ b/src/xrt/drivers/north_star/ns_hmd.h @@ -118,6 +118,7 @@ struct ns_eye * Information about the whole North Star headset. * * @ingroup drv_ns + * @implements xrt_device */ struct ns_hmd { @@ -139,6 +140,7 @@ struct ns_hmd * The mesh generator for the North Star distortion. * * @ingroup drv_ns + * @implements u_uv_generator */ struct ns_mesh { diff --git a/src/xrt/drivers/north_star/ns_prober.c b/src/xrt/drivers/north_star/ns_prober.c index b2fc8aeab..a6c7627b8 100644 --- a/src/xrt/drivers/north_star/ns_prober.c +++ b/src/xrt/drivers/north_star/ns_prober.c @@ -24,6 +24,9 @@ DEBUG_GET_ONCE_OPTION(ns_config_path, "NS_CONFIG_PATH", NULL) DEBUG_GET_ONCE_BOOL_OPTION(ns_spew, "NS_PRINT_SPEW", false) DEBUG_GET_ONCE_BOOL_OPTION(ns_debug, "NS_PRINT_DEBUG", false) +/*! + * @implements xrt_auto_prober + */ struct ns_prober { struct xrt_auto_prober base; @@ -32,12 +35,14 @@ struct ns_prober bool print_debug; }; +//! @private @memberof ns_prober static inline struct ns_prober * ns_prober(struct xrt_auto_prober *p) { return (struct ns_prober *)p; } +//! @public @memberof ns_prober static void ns_prober_destroy(struct xrt_auto_prober *p) { @@ -46,6 +51,7 @@ ns_prober_destroy(struct xrt_auto_prober *p) free(nsp); } +//! @public @memberof ns_prober static struct xrt_device * ns_prober_autoprobe(struct xrt_auto_prober *xap, cJSON *attached_data, diff --git a/src/xrt/drivers/ohmd/oh_device.h b/src/xrt/drivers/ohmd/oh_device.h index 711ef9867..6d4553be8 100644 --- a/src/xrt/drivers/ohmd/oh_device.h +++ b/src/xrt/drivers/ohmd/oh_device.h @@ -19,6 +19,9 @@ extern "C" { typedef struct ohmd_context ohmd_context; typedef struct ohmd_device ohmd_device; +/*! + * @implements xrt_device + */ struct oh_device { struct xrt_device base; diff --git a/src/xrt/drivers/ohmd/oh_prober.c b/src/xrt/drivers/ohmd/oh_prober.c index 275911522..d3e66e9c8 100644 --- a/src/xrt/drivers/ohmd/oh_prober.c +++ b/src/xrt/drivers/ohmd/oh_prober.c @@ -24,6 +24,9 @@ DEBUG_GET_ONCE_BOOL_OPTION(oh_spew, "OH_PRINT_SPEW", false) DEBUG_GET_ONCE_BOOL_OPTION(oh_debug, "OH_PRINT_DEBUG", false) DEBUG_GET_ONCE_BOOL_OPTION(oh_external, "OH_EXTERNAL_DRIVER", false) +/*! + * @implements xrt_auto_prober + */ struct oh_prober { struct xrt_auto_prober base; @@ -32,12 +35,14 @@ struct oh_prober bool print_debug; }; +//! @private @memberof oh_prober static inline struct oh_prober * oh_prober(struct xrt_auto_prober *p) { return (struct oh_prober *)p; } +//! @public @memberof oh_prober static void oh_prober_destroy(struct xrt_auto_prober *p) { @@ -51,6 +56,7 @@ oh_prober_destroy(struct xrt_auto_prober *p) free(ohp); } +//! @public @memberof oh_prober static struct xrt_device * oh_prober_autoprobe(struct xrt_auto_prober *xap, cJSON *attached_data, diff --git a/src/xrt/drivers/psmv/psmv_driver.c b/src/xrt/drivers/psmv/psmv_driver.c index 4220d0067..12924951e 100644 --- a/src/xrt/drivers/psmv/psmv_driver.c +++ b/src/xrt/drivers/psmv/psmv_driver.c @@ -440,6 +440,8 @@ struct psmv_parsed_input * Translated to axis that means the ball is on the Y+ axis, the buttons on the * Z+ axis, the trigger on the Z- axis, the USB port on the Y- axis, the start * button on the X+ axis, select button on the X- axis. + * + * @implements xrt_device */ struct psmv_device { diff --git a/src/xrt/drivers/psvr/psvr_device.c b/src/xrt/drivers/psvr/psvr_device.c index 02e94200d..a9c68b67a 100644 --- a/src/xrt/drivers/psvr/psvr_device.c +++ b/src/xrt/drivers/psvr/psvr_device.c @@ -49,6 +49,7 @@ DEBUG_GET_ONCE_BOOL_OPTION(psvr_disco, "PSVR_DISCO", false) * Private struct for the @ref drv_psvr device. * * @ingroup drv_psvr + * @implements xrt_device */ struct psvr_device { diff --git a/src/xrt/drivers/psvr/psvr_interface.h b/src/xrt/drivers/psvr/psvr_interface.h index f9a380946..16780fc7b 100644 --- a/src/xrt/drivers/psvr/psvr_interface.h +++ b/src/xrt/drivers/psvr/psvr_interface.h @@ -24,6 +24,7 @@ extern "C" { * Create a probe for PSVR devices. * * @ingroup drv_psvr + * @relates xrt_auto_prober */ struct xrt_auto_prober * psvr_create_auto_prober(void); diff --git a/src/xrt/drivers/psvr/psvr_prober.c b/src/xrt/drivers/psvr/psvr_prober.c index 5c2260176..d892803ce 100644 --- a/src/xrt/drivers/psvr/psvr_prober.c +++ b/src/xrt/drivers/psvr/psvr_prober.c @@ -37,6 +37,7 @@ DEBUG_GET_ONCE_BOOL_OPTION(psvr_debug, "PSVR_PRINT_DEBUG", false) * PSVR prober struct. * * @ingroup drv_psvr + * @implements xrt_auto_prober */ struct psvr_prober { @@ -54,12 +55,14 @@ struct psvr_prober * */ +//! @private @memberof psvr_prober static inline struct psvr_prober * psvr_prober(struct xrt_auto_prober *p) { return (struct psvr_prober *)p; } +//! @public @memberof psvr_prober static void psvr_prober_destroy(struct xrt_auto_prober *p) { @@ -68,6 +71,7 @@ psvr_prober_destroy(struct xrt_auto_prober *p) free(ppsvr); } +//! @public @memberof psvr_prober static struct xrt_device * psvr_prober_autoprobe(struct xrt_auto_prober *xap, cJSON *attached_data, diff --git a/src/xrt/drivers/realsense/rs_6dof.c b/src/xrt/drivers/realsense/rs_6dof.c index 214da2f05..daa5eaa42 100644 --- a/src/xrt/drivers/realsense/rs_6dof.c +++ b/src/xrt/drivers/realsense/rs_6dof.c @@ -28,6 +28,9 @@ +/*! + * @implements xrt_device + */ struct rs_6dof { struct xrt_device base; diff --git a/src/xrt/drivers/survive/survive_driver.c b/src/xrt/drivers/survive/survive_driver.c index 333ac3735..13552fec3 100644 --- a/src/xrt/drivers/survive/survive_driver.c +++ b/src/xrt/drivers/survive/survive_driver.c @@ -106,6 +106,10 @@ typedef enum static bool survive_already_initialized = false; #define MAX_PENDING_EVENTS 30 + +/*! + * @implements xrt_device + */ struct survive_device { struct xrt_device base; @@ -128,6 +132,9 @@ enum VIVE_VARIANT VIVE_VARIANT_INDEX }; +/*! + * @extends xrt_tracking_origin + */ struct survive_system { struct xrt_tracking_origin base; diff --git a/src/xrt/drivers/v4l2/v4l2_driver.c b/src/xrt/drivers/v4l2/v4l2_driver.c index 974b6b110..f5cc406ab 100644 --- a/src/xrt/drivers/v4l2/v4l2_driver.c +++ b/src/xrt/drivers/v4l2/v4l2_driver.c @@ -35,6 +35,13 @@ * */ +/*! + * Spew level logging. + * + * Outputs a line, from the given format string and arguments, only if + * v4l2_fs::print_spew is true. + * @relates v4l2_fs + */ #define V_SPEW(p, ...) \ do { \ if (p->print_spew) { \ @@ -44,6 +51,14 @@ } \ } while (false) +/*! + * Debug level logging. + * + * Outputs a line, from the given format string and arguments, only if + * v4l2_fs::print_debug is true. + * + * @relates v4l2_fs + */ #define V_DEBUG(p, ...) \ do { \ if (p->print_debug) { \ @@ -53,6 +68,13 @@ } \ } while (false) +/*! + * Error level logging. + * + * Outputs a line, from the given format string and arguments. + * + * @relates v4l2_fs + */ #define V_ERROR(p, ...) \ do { \ fprintf(stderr, "%s - ", __func__); \ @@ -91,6 +113,10 @@ DEBUG_GET_ONCE_NUM_OPTION(v4l2_exposure_absolute, "V4L2_EXPOSURE_ABSOLUTE", 10) * */ +/*! + * @extends xrt_frame + * @ingroup drv_v4l2 + */ struct v4l2_frame { struct xrt_frame base; @@ -100,6 +126,9 @@ struct v4l2_frame struct v4l2_buffer v_buf; }; +/*! + * @ingroup drv_v4l2 + */ struct v4l2_control_state { int force; @@ -110,7 +139,10 @@ struct v4l2_control_state }; /*! - * A single open v4l2 capture device, starts it's own thread and waits on it. + * A single open v4l2 capture device, starts its own thread and waits on it. + * + * @implements xrt_frame_node + * @implements xrt_fs */ struct v4l2_fs { diff --git a/src/xrt/drivers/v4l2/v4l2_interface.h b/src/xrt/drivers/v4l2/v4l2_interface.h index e39da96c4..f2cdf2be9 100644 --- a/src/xrt/drivers/v4l2/v4l2_interface.h +++ b/src/xrt/drivers/v4l2/v4l2_interface.h @@ -28,6 +28,7 @@ extern "C" { * Descriptor of a v4l2 source. * * @ingroup drv_v4l2 + * @extends xrt_fs_mode */ struct v4l2_source_descriptor { diff --git a/src/xrt/drivers/vive/vive_controller_driver.c b/src/xrt/drivers/vive/vive_controller_driver.c index 9924e32b7..828e90bb7 100644 --- a/src/xrt/drivers/vive/vive_controller_driver.c +++ b/src/xrt/drivers/vive/vive_controller_driver.c @@ -127,6 +127,7 @@ enum controller_variant * A Vive Controller device, representing just a single controller. * * @ingroup drv_vive + * @implements xrt_device */ struct vive_controller_device { diff --git a/src/xrt/drivers/vive/vive_device.h b/src/xrt/drivers/vive/vive_device.h index 0923eae87..dedf9096f 100644 --- a/src/xrt/drivers/vive/vive_device.h +++ b/src/xrt/drivers/vive/vive_device.h @@ -48,6 +48,9 @@ enum VIVE_VARIANT VIVE_VARIANT_INDEX }; +/*! + * @implements xrt_device + */ struct vive_device { struct xrt_device base; diff --git a/src/xrt/include/xrt/xrt_compositor.h b/src/xrt/include/xrt/xrt_compositor.h index 0cd478c04..76f2a5038 100644 --- a/src/xrt/include/xrt/xrt_compositor.h +++ b/src/xrt/include/xrt/xrt_compositor.h @@ -70,7 +70,8 @@ enum xrt_view_type }; /*! - * Common swapchain base. + * @interface xrt_swapchain + * Common swapchain interface/base. * * @ingroup xrt_iface */ @@ -106,9 +107,11 @@ struct xrt_swapchain }; /*! - * Helper for xrt_swapchain::acquire_image. + * @copydoc xrt_swapchain::acquire_image * - * @ingroup xrt_iface + * Helper for calling through the function pointer. + * + * @public @memberof xrt_swapchain */ static inline bool xrt_swapchain_acquire_image(struct xrt_swapchain *xsc, uint32_t *index) @@ -117,9 +120,11 @@ xrt_swapchain_acquire_image(struct xrt_swapchain *xsc, uint32_t *index) } /*! - * Helper for xrt_swapchain::wait_image. + * @copydoc xrt_swapchain::wait_image * - * @ingroup xrt_iface + * Helper for calling through the function pointer. + * + * @public @memberof xrt_swapchain */ static inline bool xrt_swapchain_wait_image(struct xrt_swapchain *xsc, @@ -130,9 +135,11 @@ xrt_swapchain_wait_image(struct xrt_swapchain *xsc, } /*! - * Helper for xrt_swapchain::release_image. + * @copydoc xrt_swapchain::release_image * - * @ingroup xrt_iface + * Helper for calling through the function pointer. + * + * @public @memberof xrt_swapchain */ static inline bool xrt_swapchain_release_image(struct xrt_swapchain *xsc, uint32_t index) @@ -141,10 +148,12 @@ xrt_swapchain_release_image(struct xrt_swapchain *xsc, uint32_t index) } /*! - * Helper for xrt_swapchain::destroy, does a null check and sets xc_ptr to - * null if freed. + * @copydoc xrt_swapchain::destroy * - * @ingroup xrt_iface + * Helper for calling through the function pointer: does a null check and sets + * xsc_ptr to null if freed. + * + * @public @memberof xrt_swapchain */ static inline void xrt_swapchain_destroy(struct xrt_swapchain **xsc_ptr) @@ -159,7 +168,9 @@ xrt_swapchain_destroy(struct xrt_swapchain **xsc_ptr) } /*! - * Common compositor base. + * @interface xrt_compositor + * + * Common compositor client interface/base. * * @ingroup xrt_iface */ @@ -241,8 +252,8 @@ struct xrt_compositor void (*discard_frame)(struct xrt_compositor *xc); /*! - * Begins layer submission, this and the other layer_* calls equivalent - * to xrEndFrame, except over multiple class. It's only after + * Begins layer submission, this and the other layer_* calls are + * equivalent to xrEndFrame, except over multiple calls. It's only after * @p layer_commit that layers will be displayed. From the point of view * of the swapchain the image is used as soon as it's given in a call. */ @@ -252,6 +263,7 @@ struct xrt_compositor /*! * Adds a stereo projection layer for submissions. * + * @param xc Self pointer * @param timestamp When should this layer be shown. * @param xdev The device the layer is relative to. * @param name Which pose this layer is relative to. @@ -294,6 +306,7 @@ struct xrt_compositor * Adds a quad layer for submission, the center of the quad is specified * by the pose and extends outwards from it. * + * @param xc Self pointer * @param timestamp When should this layer be shown. * @param xdev The device the layer is relative to. * @param name Which pose this layer is relative to. @@ -337,9 +350,11 @@ struct xrt_compositor }; /*! - * Helper for xrt_compositor::create_swapchain + * @copydoc xrt_compositor::create_swapchain * - * @ingroup xrt_iface + * Helper for calling through the function pointer. + * + * @public @memberof xrt_compositor */ static inline struct xrt_swapchain * xrt_comp_create_swapchain(struct xrt_compositor *xc, @@ -359,9 +374,11 @@ xrt_comp_create_swapchain(struct xrt_compositor *xc, } /*! - * Helper for xrt_compositor::poll_events + * @copydoc xrt_compositor::poll_events * - * @ingroup xrt_iface + * Helper for calling through the function pointer. + * + * @public @memberof xrt_compositor */ static inline void xrt_comp_poll_events(struct xrt_compositor *xc, uint64_t *WIP) @@ -370,9 +387,11 @@ xrt_comp_poll_events(struct xrt_compositor *xc, uint64_t *WIP) } /*! - * Helper for xrt_compositor::prepare_session + * @copydoc xrt_compositor::prepare_session * - * @ingroup xrt_iface + * Helper for calling through the function pointer. + * + * @public @memberof xrt_compositor */ static inline void xrt_comp_prepare_session(struct xrt_compositor *xc) @@ -381,9 +400,11 @@ xrt_comp_prepare_session(struct xrt_compositor *xc) } /*! - * Helper for xrt_compositor::begin_session + * @copydoc xrt_compositor::begin_session * - * @ingroup xrt_iface + * Helper for calling through the function pointer. + * + * @public @memberof xrt_compositor */ static inline void xrt_comp_begin_session(struct xrt_compositor *xc, enum xrt_view_type view_type) @@ -392,9 +413,11 @@ xrt_comp_begin_session(struct xrt_compositor *xc, enum xrt_view_type view_type) } /*! - * Helper for xrt_compositor::end_session + * @copydoc xrt_compositor::end_session * - * @ingroup xrt_iface + * Helper for calling through the function pointer. + * + * @public @memberof xrt_compositor */ static inline void xrt_comp_end_session(struct xrt_compositor *xc) @@ -403,9 +426,11 @@ xrt_comp_end_session(struct xrt_compositor *xc) } /*! - * Helper for xrt_compositor::wait_frame + * @copydoc xrt_compositor::wait_frame * - * @ingroup xrt_iface + * Helper for calling through the function pointer. + * + * @public @memberof xrt_compositor */ static inline void xrt_comp_wait_frame(struct xrt_compositor *xc, @@ -416,9 +441,11 @@ xrt_comp_wait_frame(struct xrt_compositor *xc, } /*! - * Helper for xrt_compositor::begin_frame + * @copydoc xrt_compositor::begin_frame * - * @ingroup xrt_iface + * Helper for calling through the function pointer. + * + * @public @memberof xrt_compositor */ static inline void xrt_comp_begin_frame(struct xrt_compositor *xc) @@ -427,9 +454,11 @@ xrt_comp_begin_frame(struct xrt_compositor *xc) } /*! - * Helper for xrt_compositor::discard_frame + * @copydoc xrt_compositor::discard_frame * - * @ingroup xrt_iface + * Helper for calling through the function pointer. + * + * @public @memberof xrt_compositor */ static inline void xrt_comp_discard_frame(struct xrt_compositor *xc) @@ -438,9 +467,11 @@ xrt_comp_discard_frame(struct xrt_compositor *xc) } /*! - * Helper for xrt_compositor::layer_begin + * @copydoc xrt_compositor::layer_begin * - * @ingroup xrt_iface + * Helper for calling through the function pointer. + * + * @public @memberof xrt_compositor */ static inline void xrt_comp_layer_begin(struct xrt_compositor *xc, @@ -450,9 +481,11 @@ xrt_comp_layer_begin(struct xrt_compositor *xc, } /*! - * Helper for xrt_compositor::layer_stereo_projection + * @copydoc xrt_compositor::layer_stereo_projection * - * @ingroup xrt_iface + * Helper for calling through the function pointer. + * + * @public @memberof xrt_compositor */ static inline void xrt_comp_layer_stereo_projection(struct xrt_compositor *xc, @@ -481,9 +514,11 @@ xrt_comp_layer_stereo_projection(struct xrt_compositor *xc, } /*! - * Helper for xrt_compositor::layer_quad + * @copydoc xrt_compositor::layer_quad * - * @ingroup xrt_iface + * Helper for calling through the function pointer. + * + * @public @memberof xrt_compositor */ static inline void xrt_comp_layer_quad(struct xrt_compositor *xc, @@ -505,9 +540,11 @@ xrt_comp_layer_quad(struct xrt_compositor *xc, } /*! - * Helper for xrt_compositor::layer_commit + * @copydoc xrt_compositor::layer_commit * - * @ingroup xrt_iface + * Helper for calling through the function pointer. + * + * @public @memberof xrt_compositor */ static inline void xrt_comp_layer_commit(struct xrt_compositor *xc) @@ -516,10 +553,12 @@ xrt_comp_layer_commit(struct xrt_compositor *xc) } /*! - * Helper for xrt_compositor::destroy, does a null check and sets xc_ptr to - * null if freed. + * @copydoc xrt_compositor::destroy * - * @ingroup xrt_iface + * Helper for calling through the function pointer: does a null check and sets + * xc_ptr to null if freed. + * + * @public @memberof xrt_compositor */ static inline void xrt_comp_destroy(struct xrt_compositor **xc_ptr) @@ -541,10 +580,13 @@ xrt_comp_destroy(struct xrt_compositor **xc_ptr) */ /*! + * Base class for an OpenGL (ES) client swapchain. * @ingroup xrt_iface comp_client + * @extends xrt_swapchain */ struct xrt_swapchain_gl { + //! @public Base struct xrt_swapchain base; // GLuint @@ -554,19 +596,35 @@ struct xrt_swapchain_gl }; /*! + * Base class for an OpenGL (ES) client compositor. * @ingroup xrt_iface comp_client + * @extends xrt_compositor */ struct xrt_compositor_gl { struct xrt_compositor base; }; +/*! + * Down-cast helper. + * + * @private @memberof xrt_swapchain_gl + * + * @todo unused - remove? + */ static inline struct xrt_swapchain_gl * xrt_swapchain_gl(struct xrt_swapchain *xsc) { return (struct xrt_swapchain_gl *)xsc; } +/*! + * Down-cast helper. + * + * @private @memberof xrt_compositor_gl + * + * @todo unused - remove? + */ static inline struct xrt_compositor_gl * xrt_compositor_gl(struct xrt_compositor *xc) { @@ -592,9 +650,11 @@ typedef uint64_t VkDeviceMemory; * Base class for a Vulkan client swapchain. * * @ingroup xrt_iface comp_client + * @extends xrt_swapchain */ struct xrt_swapchain_vk { + //! @public Base struct xrt_swapchain base; VkImage images[XRT_MAX_SWAPCHAIN_IMAGES]; @@ -605,18 +665,34 @@ struct xrt_swapchain_vk * Base class for a Vulkan client compositor. * * @ingroup xrt_iface comp_client + * @extends xrt_compositor */ struct xrt_compositor_vk { + //! @public Base struct xrt_compositor base; }; +/*! + * Down-cast helper. + * + * @private @memberof xrt_swapchain_vk + * + * @todo unused - remove? + */ static inline struct xrt_swapchain_vk * xrt_swapchain_vk(struct xrt_swapchain *xsc) { return (struct xrt_swapchain_vk *)xsc; } +/*! + * Down-cast helper. + * + * @private @memberof xrt_compositor_vk + * + * @todo unused - remove? + */ static inline struct xrt_compositor_vk * xrt_compositor_vk(struct xrt_compositor *xc) { @@ -634,6 +710,7 @@ xrt_compositor_vk(struct xrt_compositor *xc) * A single image of a fd based swapchain. * * @ingroup xrt_iface comp + * @see xrt_swapchain_fd */ struct xrt_image_fd { @@ -643,33 +720,52 @@ struct xrt_image_fd }; /*! - * A swapchain that exposes fd to be imported into a client API. + * @interface xrt_swapchain_fd + * Base class for a swapchain that exposes fd to be imported into a client API. * * @ingroup xrt_iface comp + * @extends xrt_swapchain */ struct xrt_swapchain_fd { + //! @public Base struct xrt_swapchain base; struct xrt_image_fd images[XRT_MAX_SWAPCHAIN_IMAGES]; }; /*! - * Main compositor. + * @interface xrt_compositor_fd + * + * Main compositor server interface. * * @ingroup xrt_iface comp + * @extends xrt_compositor */ struct xrt_compositor_fd { + //! @public Base struct xrt_compositor base; }; +/*! + * Down-cast helper. + * + * @public @memberof xrt_swapchain_fd + */ static inline struct xrt_swapchain_fd * xrt_swapchain_fd(struct xrt_swapchain *xsc) { return (struct xrt_swapchain_fd *)xsc; } +/*! + * Down-cast helper. + * + * @public @memberof xrt_compositor_fd + * + * @todo unused - remove? + */ static inline struct xrt_compositor_fd * xrt_compositor_fd(struct xrt_compositor *xc) { diff --git a/src/xrt/include/xrt/xrt_device.h b/src/xrt/include/xrt/xrt_device.h index 036e42b80..71ff32624 100644 --- a/src/xrt/include/xrt/xrt_device.h +++ b/src/xrt/include/xrt/xrt_device.h @@ -202,6 +202,8 @@ struct xrt_output }; /*! + * @interface xrt_device + * * A single HMD or input device. * * @ingroup xrt_iface @@ -311,6 +313,8 @@ struct xrt_device /*! * Helper function for @ref xrt_device::update_inputs. + * + * @public @memberof xrt_device */ static inline void xrt_device_update_inputs(struct xrt_device *xdev) @@ -320,6 +324,8 @@ xrt_device_update_inputs(struct xrt_device *xdev) /*! * Helper function for @ref xrt_device::get_tracked_pose. + * + * @public @memberof xrt_device */ static inline void xrt_device_get_tracked_pose(struct xrt_device *xdev, @@ -334,6 +340,8 @@ xrt_device_get_tracked_pose(struct xrt_device *xdev, /*! * Helper function for @ref xrt_device::set_output. + * + * @public @memberof xrt_device */ static inline void xrt_device_set_output(struct xrt_device *xdev, @@ -345,6 +353,8 @@ xrt_device_set_output(struct xrt_device *xdev, /*! * Helper function for @ref xrt_device::get_view_pose. + * + * @public @memberof xrt_device */ static inline void xrt_device_get_view_pose(struct xrt_device *xdev, @@ -357,6 +367,8 @@ xrt_device_get_view_pose(struct xrt_device *xdev, /*! * Helper function for @ref xrt_device::destroy. + * + * @public @memberof xrt_device */ static inline void xrt_device_destroy(struct xrt_device **xdev_ptr) diff --git a/src/xrt/include/xrt/xrt_frame.h b/src/xrt/include/xrt/xrt_frame.h index fe1c23195..f01823eda 100644 --- a/src/xrt/include/xrt/xrt_frame.h +++ b/src/xrt/include/xrt/xrt_frame.h @@ -44,8 +44,14 @@ struct xrt_frame /*! + * @interface xrt_frame_sink + * * A object that is sent frames. * + * All objects that implement @ref xrt_frame_sink **must** also implement @ref + * xrt_frame_node, and should take an @ref xrt_frame_context to register + * themselves with in their constructor. + * * @ingroup xrt_iface */ struct xrt_frame_sink @@ -58,6 +64,8 @@ struct xrt_frame_sink }; /*! + * @interface xrt_frame_node + * * A interface object used for destroying a frame graph. * * @see container_of @@ -105,6 +113,7 @@ struct xrt_frame_context * @param[in] src Object to be have it's refcount increased @p dst is set to * this. * @ingroup xrt_iface + * @relates xrt_frame */ static inline void xrt_frame_reference(struct xrt_frame **dst, struct xrt_frame *src) @@ -131,7 +140,7 @@ xrt_frame_reference(struct xrt_frame **dst, struct xrt_frame *src) /*! * Add a node to a context. * - * @ingroup xrt_iface + * @public @memberof xrt_frame_context */ static inline void xrt_frame_context_add(struct xrt_frame_context *xfctx, @@ -142,9 +151,9 @@ xrt_frame_context_add(struct xrt_frame_context *xfctx, } /*! - * Destroy all child nodes, but free the context itself. + * Destroy all child nodes, but do not free the context itself. * - * @ingroup xrt_iface + * @public @memberof xrt_frame_context */ static inline void xrt_frame_context_destroy_nodes(struct xrt_frame_context *xfctx) diff --git a/src/xrt/include/xrt/xrt_frameserver.h b/src/xrt/include/xrt/xrt_frameserver.h index 3d07eb6ff..4e69d9f15 100644 --- a/src/xrt/include/xrt/xrt_frameserver.h +++ b/src/xrt/include/xrt/xrt_frameserver.h @@ -27,6 +27,7 @@ extern "C" { * floats for broad applicability. * * @ingroup xrt_iface + * @see xrt_fs */ struct xrt_fs_capture_parameters { @@ -34,6 +35,10 @@ struct xrt_fs_capture_parameters float exposure; }; +/*! + * @see xrt_fs + * @ingroup xrt_iface + */ struct xrt_fs_mode { uint32_t width; @@ -43,7 +48,8 @@ struct xrt_fs_mode }; /*! - * Frameserver that generates frame, multiple subframes (like stereo and + * @interface xrt_fs + * Frameserver that generates frames. Multiple subframes (like stereo and * mipmaps) can be generate in one frame. * * @ingroup xrt_iface @@ -56,7 +62,7 @@ struct xrt_fs char name[512]; /*! - * All frames produced by this frameserver is tagged with this id. + * All frames produced by this frameserver are tagged with this id. */ uint64_t source_id; @@ -100,9 +106,11 @@ struct xrt_fs */ /*! - * Helper for xrt_fs::enumerate_modes. + * @copydoc xrt_fs::enumerate_modes * - * @ingroup xrt_iface + * Helper for calling through the function pointer. + * + * @public @memberof xrt_fs */ static inline bool xrt_fs_enumerate_modes(struct xrt_fs *xfs, @@ -113,9 +121,11 @@ xrt_fs_enumerate_modes(struct xrt_fs *xfs, } /*! - * Helper for xrt_fs::configure_capture. + * @copydoc xrt_fs::configure_capture * - * @ingroup xrt_iface + * Helper for calling through the function pointer. + * + * @public @memberof xrt_fs */ static inline bool xrt_fs_configure_capture(struct xrt_fs *xfs, @@ -125,9 +135,11 @@ xrt_fs_configure_capture(struct xrt_fs *xfs, } /*! - * Helper for xrt_fs::stream_start. + * @copydoc xrt_fs::stream_start * - * @ingroup xrt_iface + * Helper for calling through the function pointer. + * + * @public @memberof xrt_fs */ static inline bool xrt_fs_stream_start(struct xrt_fs *xfs, @@ -138,9 +150,11 @@ xrt_fs_stream_start(struct xrt_fs *xfs, } /*! - * Helper for xrt_fs::stream_stop. + * @copydoc xrt_fs::stream_stop * - * @ingroup xrt_iface + * Helper for calling through the function pointer. + * + * @public @memberof xrt_fs */ static inline bool xrt_fs_stream_stop(struct xrt_fs *xfs) @@ -149,9 +163,11 @@ xrt_fs_stream_stop(struct xrt_fs *xfs) } /*! - * Helper for xrt_fs::is_running. + * @copydoc xrt_fs::is_running * - * @ingroup xrt_iface + * Helper for calling through the function pointer. + * + * @public @memberof xrt_fs */ static inline bool xrt_fs_is_running(struct xrt_fs *xfs) diff --git a/src/xrt/include/xrt/xrt_gfx_egl.h b/src/xrt/include/xrt/xrt_gfx_egl.h index afe414a76..266f1701c 100644 --- a/src/xrt/include/xrt/xrt_gfx_egl.h +++ b/src/xrt/include/xrt/xrt_gfx_egl.h @@ -25,7 +25,10 @@ typedef __eglMustCastToProperFunctionPointerType (*PFNEGLGETPROCADDRESSPROC)( struct time_state; /*! + * Create an OpenGL(ES) compositor client using EGL. + * * @ingroup xrt_iface + * @public @memberof xrt_compositor_fd */ struct xrt_compositor_gl * xrt_gfx_provider_create_gl_egl(struct xrt_compositor_fd *xcfd, diff --git a/src/xrt/include/xrt/xrt_gfx_fd.h b/src/xrt/include/xrt/xrt_gfx_fd.h index c8b18a6a0..ec8857e1a 100644 --- a/src/xrt/include/xrt/xrt_gfx_fd.h +++ b/src/xrt/include/xrt/xrt_gfx_fd.h @@ -23,6 +23,7 @@ struct time_state; * Creates the main fd compositor. * * @ingroup xrt_iface + * @relates xrt_compositor_fd */ struct xrt_compositor_fd * xrt_gfx_provider_create_fd(struct xrt_device *xdev, bool flip_y); diff --git a/src/xrt/include/xrt/xrt_gfx_vk.h b/src/xrt/include/xrt/xrt_gfx_vk.h index 0307147f2..bfe425c3c 100644 --- a/src/xrt/include/xrt/xrt_gfx_vk.h +++ b/src/xrt/include/xrt/xrt_gfx_vk.h @@ -38,7 +38,10 @@ void xrt_gfx_vk_get_versions(struct xrt_api_requirements *ver); /*! + * Create a Vulkan compositor client. + * * @ingroup xrt_iface + * @public @memberof xrt_compositor_fd */ struct xrt_compositor_vk * xrt_gfx_vk_provider_create(struct xrt_compositor_fd *xcfd, diff --git a/src/xrt/include/xrt/xrt_gfx_xlib.h b/src/xrt/include/xrt/xrt_gfx_xlib.h index aa43c9b7c..a934fd622 100644 --- a/src/xrt/include/xrt/xrt_gfx_xlib.h +++ b/src/xrt/include/xrt/xrt_gfx_xlib.h @@ -24,7 +24,10 @@ typedef void *GLXContext; struct time_state; /*! + * Create an OpenGL compositor client using xlib. + * * @ingroup xrt_iface + * @public @memberof xrt_compositor_fd */ struct xrt_compositor_gl * xrt_gfx_provider_create_gl_xlib(struct xrt_compositor_fd *xcfd, diff --git a/src/xrt/include/xrt/xrt_instance.h b/src/xrt/include/xrt/xrt_instance.h index 890eb5b83..33bd792d6 100644 --- a/src/xrt/include/xrt/xrt_instance.h +++ b/src/xrt/include/xrt/xrt_instance.h @@ -26,6 +26,8 @@ struct xrt_compositor_fd; */ /*! + * @interface xrt_instance + * * This interface acts as a root object for Monado. * It typically either wraps an @ref xrt_prober or forms a connection to an * out-of-process XR service. @@ -37,6 +39,8 @@ struct xrt_compositor_fd; * interface, which is exposed by implementing xrt_instance_create(). * * Additional information can be found in @ref md_targets + * + * @sa ipc_instance_create */ struct xrt_instance { @@ -130,17 +134,11 @@ struct xrt_instance }; /*! - * @name Method call helpers for xrt_instance - * Calling code should prefer using these instead of directly using the function - * pointer members. - * @{ - */ -/*! - * Helper function for @ref xrt_instance::select. + * @copydoc xrt_instance::select * - * See @ref xrt_instance::select for documentation. + * Helper for calling through the function pointer. * - * @relates xrt_instance + * @public @memberof xrt_instance */ static inline int xrt_instance_select(struct xrt_instance *xinst, @@ -151,11 +149,11 @@ xrt_instance_select(struct xrt_instance *xinst, } /*! - * Helper function for @ref xrt_instance::create_fd_compositor. + * @copydoc xrt_instance::create_fd_compositor * - * See @ref xrt_instance::create_fd_compositor for documentation. + * Helper for calling through the function pointer. * - * @relates xrt_instance + * @public @memberof xrt_instance */ static inline int xrt_instance_create_fd_compositor(struct xrt_instance *xinst, @@ -167,11 +165,11 @@ xrt_instance_create_fd_compositor(struct xrt_instance *xinst, } /*! - * Helper function for @ref xrt_instance::get_prober. + * @copydoc xrt_instance::get_prober * - * See @ref xrt_instance::get_prober for documentation. + * Helper for calling through the function pointer. * - * @relates xrt_instance + * @public @memberof xrt_instance */ static inline int xrt_instance_get_prober(struct xrt_instance *xinst, struct xrt_prober **out_xp) @@ -180,14 +178,14 @@ xrt_instance_get_prober(struct xrt_instance *xinst, struct xrt_prober **out_xp) } /*! - * Helper function for @ref xrt_instance::destroy. + * Destroy an xrt_instance - helper function. * * @param[in,out] xinst_ptr A pointer to your instance implementation pointer. * * Will destroy the instance if *xinst_ptr is not NULL. Will then set *xinst_ptr * to NULL. * - * @relates xrt_instance + * @public @memberof xrt_instance */ static inline void xrt_instance_destroy(struct xrt_instance **xinst_ptr) @@ -200,10 +198,6 @@ xrt_instance_destroy(struct xrt_instance **xinst_ptr) xinst->destroy(xinst); *xinst_ptr = NULL; } -/*! - * @} - */ - /*! * @name Factory diff --git a/src/xrt/include/xrt/xrt_prober.h b/src/xrt/include/xrt/xrt_prober.h index e237e8b34..b66f2a5c5 100644 --- a/src/xrt/include/xrt/xrt_prober.h +++ b/src/xrt/include/xrt/xrt_prober.h @@ -224,8 +224,7 @@ struct xrt_prober /*! * Helper function for @ref xrt_prober::probe. * - * @ingroup xrt_iface - * @relates xrt_prober + * @public @memberof xrt_prober */ static inline int xrt_prober_probe(struct xrt_prober *xp) @@ -236,8 +235,7 @@ xrt_prober_probe(struct xrt_prober *xp) /*! * Helper function for @ref xrt_prober::dump. * - * @ingroup xrt_iface - * @relates xrt_prober + * @public @memberof xrt_prober */ static inline int xrt_prober_dump(struct xrt_prober *xp) @@ -248,8 +246,7 @@ xrt_prober_dump(struct xrt_prober *xp) /*! * Helper function for @ref xrt_prober::select. * - * @ingroup xrt_iface - * @relates xrt_prober + * @public @memberof xrt_prober */ static inline int xrt_prober_select(struct xrt_prober *xp, @@ -262,8 +259,7 @@ xrt_prober_select(struct xrt_prober *xp, /*! * Helper function for @ref xrt_prober::open_hid_interface. * - * @ingroup xrt_iface - * @relates xrt_prober + * @public @memberof xrt_prober */ static inline int xrt_prober_open_hid_interface(struct xrt_prober *xp, @@ -277,8 +273,7 @@ xrt_prober_open_hid_interface(struct xrt_prober *xp, /*! * Helper function for @ref xrt_prober::get_string_descriptor. * - * @ingroup xrt_iface - * @relates xrt_prober + * @public @memberof xrt_prober */ static inline int xrt_prober_get_string_descriptor(struct xrt_prober *xp, @@ -294,8 +289,7 @@ xrt_prober_get_string_descriptor(struct xrt_prober *xp, /*! * Helper function for @ref xrt_prober::can_open. * - * @ingroup xrt_iface - * @relates xrt_prober + * @public @memberof xrt_prober */ static inline bool xrt_prober_can_open(struct xrt_prober *xp, struct xrt_prober_device *xpdev) @@ -307,8 +301,7 @@ xrt_prober_can_open(struct xrt_prober *xp, struct xrt_prober_device *xpdev) /*! * Helper function for @ref xrt_prober::xrt_prober_open_video_device. * - * @ingroup xrt_iface - * @relates xrt_prober + * @public @memberof xrt_prober */ static inline int xrt_prober_open_video_device(struct xrt_prober *xp, @@ -322,8 +315,7 @@ xrt_prober_open_video_device(struct xrt_prober *xp, /*! * Helper function for @ref xrt_prober::list_video_devices. * - * @ingroup xrt_iface - * @relates xrt_prober + * @public @memberof xrt_prober */ static inline int xrt_prober_list_video_devices(struct xrt_prober *xp, @@ -336,8 +328,7 @@ xrt_prober_list_video_devices(struct xrt_prober *xp, /*! * Helper function for @ref xrt_prober::destroy. * - * @ingroup xrt_iface - * @relates xrt_prober + * @public @memberof xrt_prober */ static inline void xrt_prober_destroy(struct xrt_prober **xp_ptr) @@ -360,13 +351,15 @@ xrt_prober_destroy(struct xrt_prober **xp_ptr) * created xrt_prober instance. * @param[in] list Prober entry list * - * @ingroup xrt_iface - * @relates xrt_prober + * @public @memberof xrt_prober */ int xrt_prober_create_with_lists(struct xrt_prober **out_xp, struct xrt_prober_entry_lists *list); +/*! + * @public @memberof xrt_prober + */ bool xrt_prober_match_string(struct xrt_prober *xp, struct xrt_prober_device *dev, @@ -380,7 +373,11 @@ xrt_prober_match_string(struct xrt_prober *xp, */ /*! - * A simple prober to probe for a HMD device connected to the system. + * @interface xrt_auto_prober + * + * An interface to be exposed by a device driver that should probe for the + * existence of its own device on the system, rather than using shared probers + * with vendor/product IDs, etc. * * @ingroup xrt_iface */ diff --git a/src/xrt/include/xrt/xrt_tracking.h b/src/xrt/include/xrt/xrt_tracking.h index 36f5952fe..da57ddbad 100644 --- a/src/xrt/include/xrt/xrt_tracking.h +++ b/src/xrt/include/xrt/xrt_tracking.h @@ -49,6 +49,8 @@ enum xrt_tracking_type /*! * A tracking system or device origin. + * + * Tracking systems will typically extend this structure. */ struct xrt_tracking_origin { @@ -66,6 +68,7 @@ struct xrt_tracking_origin }; /*! + * @interface xrt_tracking_factory * Tracking factory. */ struct xrt_tracking_factory @@ -98,6 +101,8 @@ struct xrt_tracking_sample }; /*! + * @interface xrt_tracked_psmv + * * A single tracked PS Move controller, camera and ball are not synced. * * @todo How do we communicate ball colour change? @@ -140,6 +145,8 @@ struct xrt_tracked_psmv }; /*! + * @interface xrt_tracked_psvr + * * A tracked PSVR headset. * * @todo How do we communicate led lighting status? @@ -180,6 +187,7 @@ struct xrt_tracked_psvr * */ +//! @public @memberof xrt_tracked_psmv static inline void xrt_tracked_psmv_get_tracked_pose(struct xrt_tracked_psmv *psmv, enum xrt_input_name name, @@ -189,6 +197,7 @@ xrt_tracked_psmv_get_tracked_pose(struct xrt_tracked_psmv *psmv, psmv->get_tracked_pose(psmv, name, when_ns, out_relation); } +//! @public @memberof xrt_tracked_psmv static inline void xrt_tracked_psmv_push_imu(struct xrt_tracked_psmv *psmv, timepoint_ns timestamp_ns, @@ -197,6 +206,7 @@ xrt_tracked_psmv_push_imu(struct xrt_tracked_psmv *psmv, psmv->push_imu(psmv, timestamp_ns, sample); } +//! @public @memberof xrt_tracked_psmv static inline void xrt_tracked_psmv_destroy(struct xrt_tracked_psmv **xtmv_ptr) { @@ -209,6 +219,7 @@ xrt_tracked_psmv_destroy(struct xrt_tracked_psmv **xtmv_ptr) *xtmv_ptr = NULL; } +//! @public @memberof xrt_tracked_psmv static inline void xrt_tracked_psvr_get_tracked_pose(struct xrt_tracked_psvr *psvr, timepoint_ns when_ns, @@ -217,6 +228,7 @@ xrt_tracked_psvr_get_tracked_pose(struct xrt_tracked_psvr *psvr, psvr->get_tracked_pose(psvr, when_ns, out_relation); } +//! @public @memberof xrt_tracked_psmv static inline void xrt_tracked_psvr_push_imu(struct xrt_tracked_psvr *psvr, timepoint_ns timestamp_ns, @@ -225,6 +237,7 @@ xrt_tracked_psvr_push_imu(struct xrt_tracked_psvr *psvr, psvr->push_imu(psvr, timestamp_ns, sample); } +//! @public @memberof xrt_tracked_psmv static inline void xrt_tracked_psvr_destroy(struct xrt_tracked_psvr **xtvr_ptr) { diff --git a/src/xrt/ipc/ipc_client.h b/src/xrt/ipc/ipc_client.h index 1576fdf05..b9ca6bc29 100644 --- a/src/xrt/ipc/ipc_client.h +++ b/src/xrt/ipc/ipc_client.h @@ -86,7 +86,11 @@ typedef struct ipc_connection } ipc_connection_t; - +/*! + * @name IPC low-level interface + * These functions are called by generated IPC client code. + * @{ + */ ipc_result_t ipc_client_send_message(ipc_connection_t *ipc_c, void *message, size_t size); @@ -105,7 +109,9 @@ ipc_client_send_and_get_reply_fds(ipc_connection_t *ipc_c, size_t reply_size, int *fds, size_t num_fds); - +/*! + * @} + */ /* * diff --git a/src/xrt/ipc/ipc_client_compositor.c b/src/xrt/ipc/ipc_client_compositor.c index adae97f60..f92aef098 100644 --- a/src/xrt/ipc/ipc_client_compositor.c +++ b/src/xrt/ipc/ipc_client_compositor.c @@ -32,7 +32,10 @@ * Internal structs and helpers. * */ - +/*! + * Client proxy for an xrt_compositor_fd implementation over IPC. + * @implements xrt_compositor_fd + */ struct ipc_client_compositor { struct xrt_compositor_fd base; @@ -50,6 +53,10 @@ struct ipc_client_compositor } layers; }; +/*! + * Client proxy for an xrt_swapchain_fd implementation over IPC. + * @implements xrt_swapchain_fd + */ struct ipc_client_swapchain { struct xrt_swapchain_fd base; diff --git a/src/xrt/ipc/ipc_client_device.c b/src/xrt/ipc/ipc_client_device.c index 052cfb2c9..36d63163d 100644 --- a/src/xrt/ipc/ipc_client_device.c +++ b/src/xrt/ipc/ipc_client_device.c @@ -35,6 +35,10 @@ * */ +/*! + * An IPC client proxy for an @ref xrt_device. + * @implements xrt_device + */ struct ipc_client_device { struct xrt_device base; @@ -125,6 +129,9 @@ ipc_client_device_set_output(struct xrt_device *xdev, } } +/*! + * @public @memberof ipc_client_device + */ struct xrt_device * ipc_client_device_create(ipc_connection_t *ipc_c, struct xrt_tracking_origin *xtrack, diff --git a/src/xrt/ipc/ipc_client_hmd.c b/src/xrt/ipc/ipc_client_hmd.c index bfe1b81f7..c1c517921 100644 --- a/src/xrt/ipc/ipc_client_hmd.c +++ b/src/xrt/ipc/ipc_client_hmd.c @@ -35,6 +35,10 @@ * */ +/*! + * An IPC client proxy for an HMD @ref xrt_device. + * @implements xrt_device + */ struct ipc_client_hmd { struct xrt_device base; @@ -117,6 +121,9 @@ ipc_client_hmd_get_view_pose(struct xrt_device *xdev, } } +/*! + * @public @memberof ipc_client_hmd + */ struct xrt_device * ipc_client_hmd_create(ipc_connection_t *ipc_c, struct xrt_tracking_origin *xtrack, diff --git a/src/xrt/ipc/ipc_client_instance.c b/src/xrt/ipc/ipc_client_instance.c index 71fe7493e..bfe30a830 100644 --- a/src/xrt/ipc/ipc_client_instance.c +++ b/src/xrt/ipc/ipc_client_instance.c @@ -34,8 +34,12 @@ * */ +/*! + * @implements xrt_instance + */ struct ipc_client_instance { + //! @public Base struct xrt_instance base; ipc_connection_t ipc_c; @@ -173,6 +177,11 @@ ipc_client_instance_destroy(struct xrt_instance *xinst) * */ +/*! + * Constructor for xrt_instance IPC client proxy. + * + * @public @memberof ipc_instance + */ int ipc_instance_create(struct xrt_instance **out_xinst) { diff --git a/src/xrt/state_trackers/gui/gui_common.h b/src/xrt/state_trackers/gui/gui_common.h index 21f592c66..31bfd2a8e 100644 --- a/src/xrt/state_trackers/gui/gui_common.h +++ b/src/xrt/state_trackers/gui/gui_common.h @@ -55,7 +55,10 @@ struct gui_program }; /*! + * @interface gui_scene * A single currently running scene. + * + * @ingroup gui */ struct gui_scene { diff --git a/src/xrt/state_trackers/gui/gui_ogl.c b/src/xrt/state_trackers/gui/gui_ogl.c index ea6153837..4bb40fb21 100644 --- a/src/xrt/state_trackers/gui/gui_ogl.c +++ b/src/xrt/state_trackers/gui/gui_ogl.c @@ -16,6 +16,11 @@ #include +/*! + * An @ref xrt_frame_sink that shows sunk frames in the GUI. + * @implements xrt_frame_sink + * @implements xrt_frame_node + */ struct gui_ogl_sink { struct gui_ogl_texture tex; diff --git a/src/xrt/state_trackers/gui/gui_scene_calibrate.c b/src/xrt/state_trackers/gui/gui_scene_calibrate.c index ab1fd8084..db3dde515 100644 --- a/src/xrt/state_trackers/gui/gui_scene_calibrate.c +++ b/src/xrt/state_trackers/gui/gui_scene_calibrate.c @@ -29,7 +29,10 @@ #include - +/*! + * An OpenCV-based camera calibration scene. + * @implements gui_scene + */ struct calibration_scene { struct gui_scene base; diff --git a/src/xrt/state_trackers/gui/gui_scene_debug.c b/src/xrt/state_trackers/gui/gui_scene_debug.c index af1491464..df3722ba8 100644 --- a/src/xrt/state_trackers/gui/gui_scene_debug.c +++ b/src/xrt/state_trackers/gui/gui_scene_debug.c @@ -31,6 +31,10 @@ #include +/*! + * A GUI scene showing the variable tracking provided by @ref util/u_var.h + * @implements gui_scene + */ struct debug_scene { struct gui_scene base; diff --git a/src/xrt/state_trackers/gui/gui_scene_main_menu.c b/src/xrt/state_trackers/gui/gui_scene_main_menu.c index 70ef386fa..da881012f 100644 --- a/src/xrt/state_trackers/gui/gui_scene_main_menu.c +++ b/src/xrt/state_trackers/gui/gui_scene_main_menu.c @@ -15,6 +15,10 @@ static ImVec2 button_dims = {256, 0}; +/*! + * A main menu GUI scene allowing selection of which scene to proceed to. + * @implements gui_scene + */ struct main_menu { struct gui_scene base; diff --git a/src/xrt/state_trackers/gui/gui_scene_video.c b/src/xrt/state_trackers/gui/gui_scene_video.c index 498201450..b3c5002b7 100644 --- a/src/xrt/state_trackers/gui/gui_scene_video.c +++ b/src/xrt/state_trackers/gui/gui_scene_video.c @@ -18,6 +18,10 @@ #include "gui_imgui.h" +/*! + * A GUI scene that lets the user select a user device. + * @implements gui_scene + */ struct video_select { struct gui_scene base; diff --git a/src/xrt/state_trackers/prober/p_prober.h b/src/xrt/state_trackers/prober/p_prober.h index b32396b7a..bf7a3417c 100644 --- a/src/xrt/state_trackers/prober/p_prober.h +++ b/src/xrt/state_trackers/prober/p_prober.h @@ -80,7 +80,9 @@ struct prober_v4l #endif /*! - * A prober device. + * A single device found by a @ref prober. + * + * @implements xrt_prober_device */ struct prober_device { @@ -127,6 +129,9 @@ struct prober_device #endif }; +/*! + * @implements xrt_prober + */ struct prober { struct xrt_prober base; @@ -180,24 +185,33 @@ struct prober /*! * Load the JSON config file. + * + * @public @memberof prober */ void p_json_open_or_create_main_file(struct prober *p); /*! * Extract tracking settings from the JSON. + * + * @public @memberof prober + * @relatesalso xrt_settings_tracking */ bool p_json_get_tracking_settings(struct prober *p, struct xrt_settings_tracking *s); /*! * Dump the given device to stdout. + * + * @public @memberof prober */ void p_dump_device(struct prober *p, struct prober_device *pdev, int id); /*! * Get or create a @ref prober_device from the device. + * + * @public @memberof prober */ int p_dev_get_usb_dev(struct prober *p, @@ -209,6 +223,8 @@ p_dev_get_usb_dev(struct prober *p, /*! * Get or create a @ref prober_device from the device. + * + * @public @memberof prober */ int p_dev_get_bluetooth_dev(struct prober *p, @@ -217,28 +233,58 @@ p_dev_get_bluetooth_dev(struct prober *p, uint16_t product_id, struct prober_device **out_pdev); +/*! + * @name Tracking systems + * @{ + */ /*! * Init the tracking factory. + * + * @private @memberof prober + * @relatesalso xrt_tracking_factory */ int p_tracking_init(struct prober *p); /*! * Teardown the tracking factory. + * + * @private @memberof prober + * @relatesalso xrt_tracking_factory */ void p_tracking_teardown(struct prober *p); +/*! + * @} + */ + #ifdef XRT_HAVE_LIBUSB +/*! + * @name libusb + * @{ + */ +/*! + * @private @memberof prober + */ int p_libusb_init(struct prober *p); +/*! + * @private @memberof prober + */ void p_libusb_teardown(struct prober *p); +/*! + * @private @memberof prober + */ int p_libusb_probe(struct prober *p); +/*! + * @private @memberof prober + */ int p_libusb_get_string_descriptor(struct prober *p, struct prober_device *pdev, @@ -246,22 +292,56 @@ p_libusb_get_string_descriptor(struct prober *p, unsigned char *buffer, int length); +/*! + * @private @memberof prober + */ bool p_libusb_can_open(struct prober *p, struct prober_device *pdev); + +/*! + * @} + */ #endif #ifdef XRT_HAVE_LIBUVC +/*! + * @name libuvc + * @{ + */ +/*! + * @private @memberof prober + */ int p_libuvc_init(struct prober *p); +/*! + * @private @memberof prober + */ void p_libuvc_teardown(struct prober *p); +/*! + * @private @memberof prober + */ int p_libuvc_probe(struct prober *p); + +/*! + * @} + */ #endif #ifdef XRT_HAVE_LIBUDEV +/*! + * @name udev + * @{ + */ +/*! + * @private @memberof prober + */ int p_udev_probe(struct prober *p); +/*! + * @} + */ #endif diff --git a/src/xrt/state_trackers/prober/p_tracking.c b/src/xrt/state_trackers/prober/p_tracking.c index 642e1a85b..072a93426 100644 --- a/src/xrt/state_trackers/prober/p_tracking.c +++ b/src/xrt/state_trackers/prober/p_tracking.c @@ -32,6 +32,10 @@ * */ +/*! + * @implements xrt_tracking_factory + * @extends xrt_tracking_origin + */ struct p_factory { //! Base struct. diff --git a/src/xrt/targets/common/target_instance_parts.h b/src/xrt/targets/common/target_instance_parts.h index bb2ef1dc6..96cd43fa7 100644 --- a/src/xrt/targets/common/target_instance_parts.h +++ b/src/xrt/targets/common/target_instance_parts.h @@ -22,6 +22,13 @@ * */ +/*! + * Main "real" instance implementation. + * + * Used in instances both with and without compositor access. + * + * @implements xrt_instance + */ struct t_instance { struct xrt_instance base; diff --git a/src/xrt/targets/gui/gui_sdl2.h b/src/xrt/targets/gui/gui_sdl2.h index 87f0b620f..2079e776f 100644 --- a/src/xrt/targets/gui/gui_sdl2.h +++ b/src/xrt/targets/gui/gui_sdl2.h @@ -29,6 +29,7 @@ extern "C" { * Common struct holding state for the GUI interface. * * @ingroup gui + * @extends gui_program */ struct sdl2_program { @@ -43,15 +44,15 @@ struct sdl2_program /*! * Init SDL2, create and show a window and bring up any other structs needed. * - * @ingroup gui + * @public @memberof sdl2_program */ int gui_sdl2_init(struct sdl2_program *p); /*! - * Loop until user request quit and show Imgui interface. + * Loop until user requests quit, and show Imgui interface. * - * @ingroup gui + * @public @memberof sdl2_program */ void gui_sdl2_imgui_loop(struct sdl2_program *p); @@ -59,7 +60,7 @@ gui_sdl2_imgui_loop(struct sdl2_program *p); /*! * Loop until quit signal has been received. * - * @ingroup gui + * @public @memberof sdl2_program */ void gui_sdl2_loop(struct sdl2_program *p); @@ -67,7 +68,7 @@ gui_sdl2_loop(struct sdl2_program *p); /*! * Destroy all SDL things and quit SDL. * - * @ingroup gui + * @public @memberof sdl2_program */ void gui_sdl2_quit(struct sdl2_program *p); diff --git a/src/xrt/targets/openxr/oxr_sdl2_hack.c b/src/xrt/targets/openxr/oxr_sdl2_hack.c index 54ea7cc5b..1c84e795d 100644 --- a/src/xrt/targets/openxr/oxr_sdl2_hack.c +++ b/src/xrt/targets/openxr/oxr_sdl2_hack.c @@ -48,6 +48,7 @@ DEBUG_GET_ONCE_BOOL_OPTION(gui, "OXR_DEBUG_GUI", false) /*! * Common struct holding state for the GUI interface. + * @extends gui_program */ struct sdl2_program {