xrt: Add xrt_system and xrt_session

This commit is contained in:
Jakob Bornecrantz 2023-12-01 19:47:28 +00:00
parent d7b3b1b827
commit 76c630d2bd
2 changed files with 346 additions and 2 deletions
src/xrt/include/xrt

View file

@ -0,0 +1,240 @@
// Copyright 2020-2023, Collabora, Ltd.
// SPDX-License-Identifier: BSL-1.0
/*!
* @file
* @brief Header for session object.
* @author Jakob Bornecrantz <jakob@collabora.com>
* @ingroup xrt_iface
*/
#pragma once
#include "xrt/xrt_compiler.h"
#include "xrt/xrt_defines.h"
#ifdef __cplusplus
extern "C" {
#endif
struct xrt_compositor_native;
/*
*
* Session events.
*
*/
/*!
* Type of a @ref xrt_session event.
*
* @see xrt_session_event
* @ingroup xrt_iface
*/
enum xrt_session_event_type
{
//! This session has no pending events.
XRT_SESSION_EVENT_NONE = 0,
//! The state of the session has changed.
XRT_SESSION_EVENT_STATE_CHANGE = 1,
//! The state of the primary session has changed.
XRT_SESSION_EVENT_OVERLAY_CHANGE = 2,
//! The session is about to be lost.
XRT_SESSION_EVENT_LOSS_PENDING = 3,
//! The session has been lost.
XRT_SESSION_EVENT_LOST = 4,
//! The referesh rate of session (compositor) has changed.
XRT_SESSION_EVENT_DISPLAY_REFRESH_RATE_CHANGE = 5,
};
/*!
* Session state changes event, type @ref XRT_SESSION_EVENT_STATE_CHANGE.
*
* @see xrt_session_event
* @ingroup xrt_iface
*/
struct xrt_session_event_state_change
{
enum xrt_session_event_type type;
bool visible;
bool focused;
};
/*!
* Primary session state changes event,
* type @ref XRT_SESSION_EVENT_OVERLAY_CHANGE.
*
* @see xrt_session_event
* @ingroup xrt_iface
*/
struct xrt_session_event_overlay
{
enum xrt_session_event_type type;
bool primary_focused;
};
/*!
* Loss pending event, @ref XRT_SESSION_EVENT_LOSS_PENDING.
*
* @see xrt_session_event
* @ingroup xrt_iface
*/
struct xrt_session_event_loss_pending
{
enum xrt_session_event_type type;
uint64_t loss_time_ns;
};
/*!
* Session lost event, type @ref XRT_SESSION_EVENT_LOST.
*
* @see xrt_session_event
* @ingroup xrt_iface
*/
struct xrt_session_event_lost
{
enum xrt_session_event_type type;
};
/*!
* Display refresh rate of compositor changed event,
* type @ref XRT_SESSION_EVENT_DISPLAY_REFRESH_RATE_CHANGE.
*
* @see xrt_session_event
* @ingroup xrt_iface
*/
struct xrt_session_event_display_refresh_rate_change
{
enum xrt_session_event_type type;
float from_display_refresh_rate_hz;
float to_display_refresh_rate_hz;
};
/*!
* Union of all session events, used to return multiple events through one call.
* Each event struct must start with a @ref xrt_session_event_type field.
*
* @see xrt_session_event
* @ingroup xrt_iface
*/
union xrt_session_event {
enum xrt_session_event_type type;
struct xrt_session_event_state_change state;
struct xrt_session_event_state_change overlay;
struct xrt_session_event_loss_pending loss_pending;
struct xrt_session_event_lost lost;
struct xrt_session_event_display_refresh_rate_change display;
};
/*!
* Used internally from producers of events to push events into session, some
* sinks might mutliplex events to multiple sessions.
*
* @ingroup xrt_iface
*/
struct xrt_session_event_sink
{
/*!
* Push one event to this sink, data is copied so pointer only needs to
* be valid for the duration of the call.
*
* @param xses Self-pointer to event sink.
* @param xse A pre-filled out event.
*/
xrt_result_t (*push_event)(struct xrt_session_event_sink *xses, const union xrt_session_event *xse);
};
/*!
* @copydoc xrt_session_event_sink::push_event
*
* Helper for calling through the function pointer.
*
* @public @memberof xrt_session_event_sink
*/
XRT_CHECK_RESULT static inline xrt_result_t
xrt_session_event_sink_push(struct xrt_session_event_sink *xses, const union xrt_session_event *xse)
{
return xses->push_event(xses, xse);
}
/*
*
* Session.
*
*/
/*!
* The XRT representation of `XrSession`, this object does not have all of the
* functionality of a session, most are partitioned to the session level
* compositor object. Often this is @ref xrt_compositor_native, note that
* interface may also be a system level object depending in implementor.
*
* @ingroup xrt_iface
*/
struct xrt_session
{
/*!
* Poll a single event from this session, if no event is available then
* the type of the event will be @ref XRT_SESSION_EVENT_NONE.
*
* @param xs Pointer to self
* @param[out] out_xse Event to be returned.
*/
xrt_result_t (*poll_events)(struct xrt_session *xs, union xrt_session_event *out_xse);
/*!
* Destroy the session, must be destroyed after the native compositor.
*
* Code consuming this interface should use @ref xrt_session_destroy.
*
* @param xs Pointer to self
*/
void (*destroy)(struct xrt_session *xs);
};
/*!
* @copydoc xrt_session::poll_events
*
* Helper for calling through the function pointer.
*
* @public @memberof xrt_session
*/
XRT_CHECK_RESULT static inline xrt_result_t
xrt_session_poll_events(struct xrt_session *xs, union xrt_session_event *out_xse)
{
return xs->poll_events(xs, out_xse);
}
/*!
* Destroy an xrt_session - helper function.
*
* @param[in,out] xsd_ptr A pointer to the xrt_session struct pointer.
*
* Will destroy the system if `*xs_ptr` is not NULL. Will then set `*xs_ptr` to
* NULL.
*
* @public @memberof xrt_session
*/
static inline void
xrt_session_destroy(struct xrt_session **xs_ptr)
{
struct xrt_session *xs = *xs_ptr;
if (xs == NULL) {
return;
}
*xs_ptr = NULL;
xs->destroy(xs);
}
#ifdef __cplusplus
}
#endif

View file

@ -1,4 +1,4 @@
// Copyright 2020-2022, Collabora, Ltd.
// Copyright 2020-2023, Collabora, Ltd.
// Copyright 2023, NVIDIA CORPORATION.
// SPDX-License-Identifier: BSL-1.0
/*!
@ -13,8 +13,107 @@
#include "xrt/xrt_compiler.h"
#include "xrt/xrt_defines.h"
struct xrt_system_devices;
#ifdef __cplusplus
extern "C" {
#endif
struct xrt_instance;
struct xrt_system_devices;
struct xrt_session;
struct xrt_compositor_native;
struct xrt_session_info;
/*
*
* System.
*
*/
/*!
* A system is a collection of devices, policies and optionally a compositor
* that is organised into a chosive group that is usable by one user, most of
* the functionality of a system is exposed through other objects, this is the
* main object. It is from this you create sessions that is used to by apps to
* interact with the "system".
*
* Sibling objects: @ref xrt_system_devices, @ref xrt_system_compositor and
* @ref xrt_space_overseer.
*
* @ingroup xrt_iface
*/
struct xrt_system
{
/*!
* Create a @ref xrt_session and optionally a @ref xrt_compositor_native
* for this system.
*
* param[in] xsys Pointer to self.
* param[in] xsi Session info.
* param[out] out_xs Created session.
* param[out] out_xcn Native compositor for this session, optional.
*/
xrt_result_t (*create_session)(struct xrt_system *xsys,
const struct xrt_session_info *xsi,
struct xrt_session **out_xs,
struct xrt_compositor_native **out_xcn);
/*!
* Destroy the system, must be destroyed after system devices and system
* compositor has been destroyed.
*
* Code consuming this interface should use @ref xrt_system_destroy.
*
* @param xsys Pointer to self
*/
void (*destroy)(struct xrt_system *xsys);
};
/*!
* @copydoc xrt_system::create_session
*
* Helper for calling through the function pointer.
*
* @public @memberof xrt_system
*/
static inline xrt_result_t
xrt_system_create_session(struct xrt_system *xsys,
const struct xrt_session_info *xsi,
struct xrt_session **out_xs,
struct xrt_compositor_native **out_xcn)
{
return xsys->create_session(xsys, xsi, out_xs, out_xcn);
}
/*!
* Destroy an xrt_system - helper function.
*
* @param[in,out] xsysd_ptr A pointer to the xrt_system struct pointer.
*
* Will destroy the system if `*xsys_ptr` is not NULL. Will then set
* `*xsys_ptr` to NULL.
*
* @public @memberof xrt_system
*/
static inline void
xrt_system_destroy(struct xrt_system **xsys_ptr)
{
struct xrt_system *xsys = *xsys_ptr;
if (xsys == NULL) {
return;
}
*xsys_ptr = NULL;
xsys->destroy(xsys);
}
/*
*
* System devices.
*
*/
/*!
* Maximum number of devices simultaneously usable by an implementation of
@ -212,3 +311,8 @@ xrt_system_devices_destroy(struct xrt_system_devices **xsysd_ptr)
*xsysd_ptr = NULL;
xsysd->destroy(xsysd);
}
#ifdef __cplusplus
}
#endif