u_system_helpers.h

Go to the documentation of this file.

// Copyright 2022-2023, Collabora, Ltd.
// SPDX-License-Identifier: BSL-1.0
/*!
 * @file
 * @brief  Helpers for system objects like @ref xrt_system_devices.
 * @author Jakob Bornecrantz <jakob@collabora.com>
 * @ingroup aux_util
 */
 
#pragma once
 
#include "xrt/xrt_results.h"
#include "xrt/xrt_frame.h"
#include "xrt/xrt_system.h"
#include "xrt/xrt_instance.h"
#include "xrt/xrt_tracking.h"
 
 
#ifdef __cplusplus
extern "C" {
#endif
 
struct xrt_session_event_sink;
 
 
/*!
 * Helper struct to manage devices by implementing the @ref xrt_system_devices.
 *
 * The default destroy function that is set by @ref u_system_devices_allocate
 * will first destroy all of the @ref xrt_device and then destroy all nodes
 * in the @ref xrt_frame_context.
 *
 * @ingroup aux_util
 */
struct u_system_devices
{
        struct xrt_system_devices base;
 
        //! Optional frame context for visual tracking.
        struct xrt_frame_context xfctx;
 
        //! Optional shared tracking origin.
        struct xrt_tracking_origin origin;
};
 
/*!
 * Small inline helper to cast from @ref xrt_system_devices.
 *
 * @ingroup aux_util
 */
static inline struct u_system_devices *
u_system_devices(struct xrt_system_devices *xsysd)
{
        return (struct u_system_devices *)xsysd;
}
 
/*!
 * Allocates a empty @ref u_system_devices to be filled in by the caller, only
 * the destroy function is filled in.
 *
 * @ingroup aux_util
 */
struct u_system_devices *
u_system_devices_allocate(void);
 
/*!
 * Destroys all devices and clears out the frame context, doesn't free the
 * struct itself, useful for code embedding the system devices struct into
 * other objects where it's not the first member or C++ classes.
 *
 * @ingroup aux_util
 */
void
u_system_devices_close(struct xrt_system_devices *xsysd);
 
/*!
 * Destroy an u_system_devices_allocate and owned devices - helper function.
 *
 * @param[in,out] usysd_ptr A pointer to the u_system_devices_allocate struct pointer.
 *
 * Will destroy the system devices if *usysd_ptr is not NULL. Will then set *usysd_ptr to NULL.
 *
 * @public @memberof u_system_devices_allocate
 */
static inline void
u_system_devices_destroy(struct u_system_devices **usysd_ptr)
{
        struct u_system_devices *usysd = *usysd_ptr;
        if (usysd == NULL) {
                return;
        }
 
        *usysd_ptr = NULL;
        usysd->base.destroy(&usysd->base);
}
 
 
/*
 *
 * Static helper.
 *
 */
 
/*!
 * Helper struct to manage devices by implementing the @ref xrt_system_devices,
 * this has only static device roles.
 *
 * @ingroup aux_util
 */
struct u_system_devices_static
{
        struct u_system_devices base;
 
        //! Is automatically returned.
        struct xrt_system_roles cached;
 
        //! Tracks usage of device features.
        struct xrt_reference feature_use[XRT_DEVICE_FEATURE_MAX_ENUM];
};
 
/*!
 * Small inline helper to cast from @ref xrt_system_devices.
 *
 * @ingroup aux_util
 */
static inline struct u_system_devices_static *
u_system_devices_static(struct xrt_system_devices *xsysd)
{
        return (struct u_system_devices_static *)xsysd;
}
 
/*!
 * Allocates a empty @ref u_system_devices to be filled in by the caller, only
 * the destroy function is filled in.
 *
 * @ingroup aux_util
 */
struct u_system_devices_static *
u_system_devices_static_allocate(void);
 
/*!
 * Finalizes the static struct with the given input devices, the system devices
 * will always return these devices for the left and right role. This function
 * must be called before @ref xrt_system_devices_get_roles is called.
 *
 * @ingroup aux_util
 */
void
u_system_devices_static_finalize(struct u_system_devices_static *usysds,
                                 struct xrt_device *left,
                                 struct xrt_device *right,
                                 struct xrt_device *gamepad);
 
 
/*
 *
 * Generic system devices helper.
 *
 */
 
/*!
 * Takes a @ref xrt_instance, gets the prober from it and then uses the prober
 * to allocate a filled in @ref u_system_devices.
 *
 * @ingroup aux_util
 */
xrt_result_t
u_system_devices_create_from_prober(struct xrt_instance *xinst,
                                    struct xrt_session_event_sink *broadcast,
                                    struct xrt_system_devices **out_xsysd,
                                    struct xrt_space_overseer **out_xso);
 
/*!
 * Helper function.
 *
 * Looks through @ref xrt_system_devices's devices and returns the first device
 * that supports hand tracking and the supplied input name.
 *
 * Used by target_builder_lighthouse to find Knuckles controllers in the list of
 * devices returned, the legacy builder to find hand tracking devices, etc.
 *
 * @ingroup aux_util
 */
struct xrt_device *
u_system_devices_get_ht_device(struct xrt_system_devices *xsysd, enum xrt_input_name name);
 
/*!
 * Helper to get the first left (unobstructed) hand-tracking device,
 * uses @ref u_system_devices_get_ht_device.
 *
 * @ingroup aux_util
 */
static inline struct xrt_device *
u_system_devices_get_ht_device_unobstructed_left(struct xrt_system_devices *xsysd)
{
        return u_system_devices_get_ht_device(xsysd, XRT_INPUT_HT_UNOBSTRUCTED_LEFT);
}
 
/*!
 * Helper to get the first (unobstructed) right hand-tracking device,
 * uses @ref u_system_devices_get_ht_device.
 *
 * @ingroup aux_util
 */
static inline struct xrt_device *
u_system_devices_get_ht_device_unobstructed_right(struct xrt_system_devices *xsysd)
{
        return u_system_devices_get_ht_device(xsysd, XRT_INPUT_HT_UNOBSTRUCTED_RIGHT);
}
 
/*!
 * Helper to get the first left (conforming) hand-tracking device,
 * uses @ref u_system_devices_get_ht_device.
 *
 * @ingroup aux_util
 */
static inline struct xrt_device *
u_system_devices_get_ht_device_conforming_left(struct xrt_system_devices *xsysd)
{
        return u_system_devices_get_ht_device(xsysd, XRT_INPUT_HT_CONFORMING_LEFT);
}
 
/*!
 * Helper to get the first (conforming) right hand-tracking device,
 * uses @ref u_system_devices_get_ht_device.
 *
 * @ingroup aux_util
 */
static inline struct xrt_device *
u_system_devices_get_ht_device_conforming_right(struct xrt_system_devices *xsysd)
{
        return u_system_devices_get_ht_device(xsysd, XRT_INPUT_HT_CONFORMING_RIGHT);
}
 
#ifdef __cplusplus
}
#endif