u_system.h

Go to the documentation of this file.

// Copyright 2023, Collabora, Ltd.
// Copyright 2024-2025, NVIDIA CORPORATION.
// SPDX-License-Identifier: BSL-1.0
/*!
 * @file
 * @brief  Helper to implement @ref xrt_system.
 * @author Jakob Bornecrantz <jakob@collabora.com>
 * @ingroup aux_util
 */
 
#pragma once
 
#include "xrt/xrt_system.h"
#include "xrt/xrt_session.h"
#include "os/os_threading.h"
 
 
#ifdef __cplusplus
extern "C" {
#endif
 
struct xrt_session;
struct xrt_session_event_sink;
union xrt_session_event;
 
/*!
 * A pair of @ref xrt_session and @ref xrt_session_event_sink that has been
 * registered to this system, used to multiplex events to all sessions.
 *
 * @ingroup aux_util
 */
struct u_system_session_pair
{
        struct xrt_session *xs;
        struct xrt_session_event_sink *xses;
};
 
/*!
 * A helper to implement a @ref xrt_system, takes care of multiplexing events
 * to sessions.
 *
 * @ingroup aux_util
 * @implements xrt_system
 */
struct u_system
{
        struct xrt_system base;
 
        //! Pushes events to all sessions created from this system.
        struct xrt_session_event_sink broadcast;
 
        struct
        {
                struct os_mutex mutex;
 
                //! Number of session and event sink pairs.
                uint32_t count;
                //! Capacity of the session array.
                uint32_t capacity;
                //! Array of session and event sink pairs.
                struct u_system_session_pair *pairs;
        } sessions;
 
        /*!
         * Used to implement @ref xrt_system::create_session, can be NULL. This
         * field should be set with @ref u_system_set_system_compositor.
         */
        struct xrt_system_compositor *xsysc;
};
 
/*!
 * Create a @ref u_system, creates a fully working system. Objects wishing to
 * use @ref u_system as a parent class should use @ref u_system_init.
 *
 * @public @memberof u_system
 * @ingroup aux_util
 * @see u_system_init
 */
struct u_system *
u_system_create(void);
 
/*!
 * Inits a @ref u_system struct when used as a parent class, only to be used
 * by base class. Not needed to be called if created by @ref u_system_create.
 *
 * @protected @memberof u_system
 * @ingroup aux_util
 */
bool
u_system_init(struct u_system *usys, void (*destroy_fn)(struct xrt_system *));
 
/*!
 * Finalizes a @ref u_system struct when used as a parent class, only to be used
 * by base class. This will not free the @ref u_system pointer itself but will
 * free any resources created by the default implementation functions. Not
 * needed to be called if created by @ref u_system_create, instead use
 * xrt_system::destroy.
 *
 * @protected @memberof u_system
 * @ingroup aux_util
 */
void
u_system_fini(struct u_system *usys);
 
/*!
 * Add a @ref xrt_session to be tracked and to receive multiplexed events.
 *
 * @public @memberof u_system
 * @ingroup aux_util
 */
void
u_system_add_session(struct u_system *usys, struct xrt_session *xs, struct xrt_session_event_sink *xses);
 
/*!
 * Remove a @ref xrt_session from tracking, it will no longer receive events,
 * the given @p xses needs to match when it was added.
 *
 * @public @memberof u_system
 * @ingroup aux_util
 */
void
u_system_remove_session(struct u_system *usys, struct xrt_session *xs, struct xrt_session_event_sink *xses);
 
/*!
 * Broadcast event to all sessions under this system.
 *
 * @public @memberof u_system
 * @ingroup aux_util
 */
void
u_system_broadcast_event(struct u_system *usys, const union xrt_session_event *xse);
 
/*!
 * Set the system compositor, used in the @ref xrt_system_create_session call.
 *
 * @public @memberof u_system
 * @ingroup aux_util
 */
void
u_system_set_system_compositor(struct u_system *usys, struct xrt_system_compositor *xsysc);
 
/*!
 * Fill system properties.
 *
 * @public @memberof u_system
 * @ingroup aux_util
 */
void
u_system_fill_properties(struct u_system *usys, const char *name);
 
/*!
 * Destroy an @ref u_system_create allocated @ref u_system - helper function.
 *
 * @param[in,out] usys_ptr A pointer to the @ref u_system_create allocated
 * struct pointer.
 *
 * Will destroy the system devices if @p *usys_ptr is not NULL. Will then set
 * @p *usys_ptr to NULL.
 *
 * @public @memberof u_system
 */
static inline void
u_system_destroy(struct u_system **usys_ptr)
{
        struct u_system *usys = *usys_ptr;
        if (usys == NULL) {
                return;
        }
 
        *usys_ptr = NULL;
        usys->base.destroy(&usys->base);
}
 
 
#ifdef __cplusplus
}
#endif