xrt_space.h

Go to the documentation of this file.

// Copyright 2019-2023, Collabora, Ltd.
// Copyright 2025-2026, NVIDIA CORPORATION.
// SPDX-License-Identifier: BSL-1.0
/*!
 * @file
 * @brief  Header defining xrt space and space overseer.
 * @author Jakob Bornecrantz <jakob@collabora.com>
 * @ingroup xrt_iface
 */
 
#pragma once
 
#include "xrt/xrt_defines.h"
 
#ifdef __cplusplus
extern "C" {
#endif
 
#define XRT_MAX_CLIENT_SPACES 128
struct xrt_device;
struct xrt_tracking_origin;
 
/*!
 * A space very similar to a OpenXR XrSpace but not a full one-to-one mapping,
 * but used to power XrSpace.
 *
 * @see @ref xrt_space_overseer
 * @see @ref design-spaces
 * @ingroup xrt_iface
 */
struct xrt_space
{
        /*!
         * Reference helper.
         */
        struct xrt_reference reference;
 
        /*!
         * Destroy function.
         */
        void (*destroy)(struct xrt_space *xs);
};
 
/*!
 * Update the reference counts on space(s).
 *
 * @param[in,out] dst Pointer to a object reference: if the object reference is
 *                    non-null will decrement its counter. The reference that
 *                    @p dst points to will be set to @p src.
 * @param[in] src New object for @p dst to refer to (may be null).
 *                If non-null, will have its refcount increased.
 * @ingroup xrt_iface
 * @relates xrt_space
 */
static inline void
xrt_space_reference(struct xrt_space **dst, struct xrt_space *src)
{
        struct xrt_space *old_dst = *dst;
 
        if (old_dst == src) {
                return;
        }
 
        if (src) {
                xrt_reference_inc(&src->reference);
        }
 
        *dst = src;
 
        if (old_dst) {
                if (xrt_reference_dec_and_is_zero(&old_dst->reference)) {
                        old_dst->destroy(old_dst);
                }
        }
}
 
/*!
 * Object that oversees and manages spaces, one created for each XR system.
 *
 * The space overseer is used by the state tracker to query the poses of spaces
 * and devices in that space system. While the default implementation
 * @ref b_space_overseer implements the spaces as a graph of relatable spaces,
 * that is a implementation detail (the interface also lends itself to that
 * since bases have parents). As such the graph is not exposed in this interface
 * and spaces are technically free floating.
 *
 * One advantage of the free floating nature is that an overseer implementation
 * has much greater flexibility in configuring the graph to fit the current XR
 * system the best, it also have freedom to reconfigure the graph at runtime
 * should that be needed. Since any potential graph isn't exposed there is no
 * need to synchronise it across the app process and the service process.
 *
 * @see @ref design-spaces
 * @ingroup xrt_iface
 */
struct xrt_space_overseer
{
        struct
        {
                struct xrt_space *root;        //!< Root space, always available
                struct xrt_space *view;        //!< View space, may be null (in very rare cases).
                struct xrt_space *local;       //!< Local space, may be null (in very rare cases).
                struct xrt_space *local_floor; //!< Local floor space, may be null.
                struct xrt_space *stage;       //!< Stage space, may be null.
                struct xrt_space *unbounded;   //!< Unbounded space, only here for slam trackers.
 
                /*!
                 * Semantic spaces to be mapped to OpenXR spaces.
                 */
        } semantic;
 
        //! Ptrs to the localspace
        struct xrt_space *localspace[XRT_MAX_CLIENT_SPACES];
        //! Ptrs to the localfloorspace
        struct xrt_space *localfloorspace[XRT_MAX_CLIENT_SPACES];
 
        /*!
         * Create a space with a fixed offset to the parent space.
         *
         * @param[in] xso        Owning space overseer.
         * @param[in] parent     The parent space for the new space.
         * @param[in] offset     Offset to the space.
         * @param[out] out_space The newly created space.
         */
        xrt_result_t (*create_offset_space)(struct xrt_space_overseer *xso,
                                            struct xrt_space *parent,
                                            const struct xrt_pose *offset,
                                            struct xrt_space **out_space);
 
        /*!
         * Create a space that wraps the @p xdev input pose described by input
         * @p name, implicitly make the device's tracking space the parent of
         * the created space. The name pose_space was chosen because while most
         * input poses are part of the device, they may also be things tracked
         * by the device. The important part is that the space is following the
         * pose, that it happens to be attached to device is coincidental.
         *
         * @param[in] xso        Owning space overseer.
         * @param[in] xdev       Device to get the pose from.
         * @param[in] name       Name of the pose input.
         * @param[out] out_space The newly created space.
         */
        xrt_result_t (*create_pose_space)(struct xrt_space_overseer *xso,
                                          struct xrt_device *xdev,
                                          enum xrt_input_name name,
                                          struct xrt_space **out_space);
 
        /*!
         * Locate a space in the base space.
         *
         * @see xrt_device::get_tracked_pose.
         *
         * @param[in] xso             Owning space overseer.
         * @param[in] base_space      The space that we want the pose in.
         * @param[in] base_offset     Offset if any to the base space.
         * @param[in] at_timestamp_ns At which time.
         * @param[in] space           The space to be located.
         * @param[in] offset          Offset if any to the located space.
         * @param[out] out_relation   Resulting pose.
         */
        xrt_result_t (*locate_space)(struct xrt_space_overseer *xso,
                                     struct xrt_space *base_space,
                                     const struct xrt_pose *base_offset,
                                     int64_t at_timestamp_ns,
                                     struct xrt_space *space,
                                     const struct xrt_pose *offset,
                                     struct xrt_space_relation *out_relation);
 
        /*!
         * Locate spaces in the base space.
         *
         * @see xrt_device::get_tracked_pose.
         *
         * @param[in] xso             Owning space overseer.
         * @param[in] base_space      The space that we want the pose in.
         * @param[in] base_offset     Offset if any to the base space.
         * @param[in] at_timestamp_ns At which time.
         * @param[in] spaces          The array of pointers to spaces to be located.
         * @param[in] space_count     The number of spaces to locate.
         * @param[in] offsets         Array of offset if any to the located spaces.
         * @param[out] out_relations  Array of resulting poses.
         */
        xrt_result_t (*locate_spaces)(struct xrt_space_overseer *xso,
                                      struct xrt_space *base_space,
                                      const struct xrt_pose *base_offset,
                                      int64_t at_timestamp_ns,
                                      struct xrt_space **spaces,
                                      uint32_t space_count,
                                      const struct xrt_pose *offsets,
                                      struct xrt_space_relation *out_relations);
 
        /*!
         * Locate a the origin of the tracking space of a device, this is not
         * the same as the device position. In other words, what is the position
         * of the space that the device is in, and which it returns its poses
         * in. Needed to use @ref xrt_device::get_view_poses and
         * @ref xrt_device::get_hand_tracking.
         *
         * @see xrt_device::get_tracked_pose.
         *
         * @param[in] xso             Owning space overseer.
         * @param[in] base_space      The space that we want the pose in.
         * @param[in] base_offset     Offset if any to the base space.
         * @param[in] at_timestamp_ns At which time.
         * @param[in] xdev            Device to get the pose from.
         * @param[out] out_relation   Resulting pose.
         */
        xrt_result_t (*locate_device)(struct xrt_space_overseer *xso,
                                      struct xrt_space *base_space,
                                      const struct xrt_pose *base_offset,
                                      int64_t at_timestamp_ns,
                                      struct xrt_device *xdev,
                                      struct xrt_space_relation *out_relation);
 
        /*!
         * Increment the usage count of a reference space (aka semantic space).
         * This lets the overseer know when different spaces are being used,
         * allowing it to triggering a recenter if the local space is used for
         * the first time, or stopping calculating where the stage space is if
         * it is not used by the current application.
         *
         * @param[in] xso   Owning space overseer.
         * @param[in] type  Which reference space is being referenced.
         */
        xrt_result_t (*ref_space_inc)(struct xrt_space_overseer *xso, enum xrt_reference_space_type type);
 
        /*!
         * Decrement the usage count of a reference space (aka semantic space).
         * See @ref xrt_space_overseer::ref_space_inc.
         *
         * @param[in] xso   Owning space overseer.
         * @param[in] type  Which reference space is being referenced.
         */
        xrt_result_t (*ref_space_dec)(struct xrt_space_overseer *xso, enum xrt_reference_space_type type);
 
        /*!
         * Trigger a re-center of the local and local_floor spaces, not all
         * implementations of @ref xrt_space_overseer may support recenter. The
         * recenter operation will normally mean that the local and local_floor
         * will move to the where the view space currently is.
         *
         * @param[in] xso The space overseer.
         */
        xrt_result_t (*recenter_local_spaces)(struct xrt_space_overseer *xso);
 
        /*!
         * Read the offset from a tracking origin, not all
         * implementations of @ref xrt_space_overseer may support this.
         * Outputs are only valid if XRT_SUCCESS is returned.
         *
         * @param[in] xso The space overseer.
         * @param[in] xto The tracking origin.
         * @param[out] out_offset Pointer to an xrt_pose to write the offset to
         */
        xrt_result_t (*get_tracking_origin_offset)(struct xrt_space_overseer *xso,
                                                   struct xrt_tracking_origin *xto,
                                                   struct xrt_pose *out_offset);
 
        /*!
         * Apply an offset to a tracking origin, not all
         * implementations of @ref xrt_space_overseer may support this.
         *
         * @param[in] xso The space overseer.
         * @param[in] xto The tracking origin.
         * @param[in] offset The offset to apply.
         */
        xrt_result_t (*set_tracking_origin_offset)(struct xrt_space_overseer *xso,
                                                   struct xrt_tracking_origin *xto,
                                                   const struct xrt_pose *offset);
 
        /*!
         * Read the offset from the given reference space, not all
         * implementations of @ref xrt_space_overseer may support this.
         * Outputs are only valid if XRT_SUCCESS is returned.
         *
         * @param[in] xso The space overseer.
         * @param[in] type The reference space.
         * @param[out] out_offset Pointer to write the offset to.
         */
        xrt_result_t (*get_reference_space_offset)(struct xrt_space_overseer *xso,
                                                   enum xrt_reference_space_type type,
                                                   struct xrt_pose *out_offset);
 
        /*!
         * Apply an offset to the given reference space, not all
         * implementations of @ref xrt_space_overseer may support this.
         *
         * @param[in] xso The space overseer.
         * @param[in] type The reference space.
         * @param[in] offset The offset to apply.
         */
        xrt_result_t (*set_reference_space_offset)(struct xrt_space_overseer *xso,
                                                   enum xrt_reference_space_type type,
                                                   const struct xrt_pose *offset);
 
        /*!
         * Create a localspace and a localfloorspace.
         *
         * @param[in] xso        Owning space overseer.
         * @param[out] out_local_space The newly created localspace.
         * @param[out] out_local_floor_space The newly created localfloorspace.
         */
        xrt_result_t (*create_local_space)(struct xrt_space_overseer *xso,
                                           struct xrt_space **out_local_space,
                                           struct xrt_space **out_local_floor_space);
 
        /*
         *
         * Special inter-monado component functions.
         *
         */
 
        /*!
         * Add a new device to be tracked by the space overseer. The exact
         * semantic of the space is determined by the implementation of the
         * space overseer. And may be outright rejected by the implementation.
         *
         * After this call completes successfully, the device can be passed
         * into the @ref xrt_space_overseer::locate_device function, but may
         * not be locatable immediately.
         *
         * This function is not intended to be called by the OpenXR state
         * tracker, but by other monado components that need to add devices
         * but does not own the space overseer. Components like the fixer
         * uppers or for push devices.
         *
         * @param[in] xso The space overseer.
         * @param[in] xdev The device to be tracked.
         * @return XRT_SUCCESS if added, otherwise an error code.
         */
        xrt_result_t (*add_device)(struct xrt_space_overseer *xso, struct xrt_device *xdev);
 
        /*!
         * Remove a device that was previously added with
         * @ref xrt_space_overseer::add_device. After this call the device can no
         * longer be located through this space overseer and any pose spaces that
         * were created for it become invalid.
         *
         * Removing a device that was never added (or has already been removed)
         * is a safe no-op.
         *
         * Like @ref xrt_space_overseer::add_device this is not intended to be
         * called by the OpenXR state tracker, but by other monado components
         * that add devices but do not own the space overseer, for instance to
         * support hotplugging.
         *
         * @param[in] xso The space overseer.
         * @param[in] xdev The device to stop tracking.
         * @return XRT_SUCCESS if removed or not present, otherwise an error code.
         */
        xrt_result_t (*remove_device)(struct xrt_space_overseer *xso, struct xrt_device *xdev);
 
        /*!
         * Attach a device to a different space then it was associated with
         * originally, the space overseer might not support this operation.
         *
         * For some space overseer implementations this operation requires
         * that the device has the tracking origin type of
         * @ref XRT_TRACKING_TYPE_ATTACHABLE. Which space that becomes the
         * parent space of the device when @p space is NULL is undefined,
         * and the device might become un-trackable.
         *
         * @param[in] xso    Owning space overseer.
         * @param[in] xdev   Device to attach.
         * @param[in] space  Space to attach the device to, may be NULL.
         *
         * @return XRT_SUCCESS on success.
         * @return XRT_ERROR_DEVICE_NOT_ATTACHABLE if the device does not have
         *         the XRT_TRACKING_TYPE_ATTACHABLE tracking origin type.
         */
        xrt_result_t (*attach_device)(struct xrt_space_overseer *xso, struct xrt_device *xdev, struct xrt_space *space);
 
 
        /*
         *
         * Destroy function always comes last.
         *
         */
 
        /*!
         * Destroy function.
         *
         * @param xso The space overseer.
         */
        void (*destroy)(struct xrt_space_overseer *xs);
};
 
/*!
 * @copydoc xrt_space_overseer::create_offset_space
 *
 * Helper for calling through the function pointer.
 *
 * @public @memberof xrt_space_overseer
 */
XRT_NONNULL_ALL static inline xrt_result_t
xrt_space_overseer_create_offset_space(struct xrt_space_overseer *xso,
                                       struct xrt_space *parent,
                                       const struct xrt_pose *offset,
                                       struct xrt_space **out_space)
{
        return xso->create_offset_space(xso, parent, offset, out_space);
}
 
/*!
 * @copydoc xrt_space_overseer::create_pose_space
 *
 * Helper for calling through the function pointer.
 *
 * @public @memberof xrt_space_overseer
 */
XRT_NONNULL_ALL static inline xrt_result_t
xrt_space_overseer_create_pose_space(struct xrt_space_overseer *xso,
                                     struct xrt_device *xdev,
                                     enum xrt_input_name name,
                                     struct xrt_space **out_space)
{
        return xso->create_pose_space(xso, xdev, name, out_space);
}
 
/*!
 * @copydoc xrt_space_overseer::locate_space
 *
 * Helper for calling through the function pointer.
 *
 * @public @memberof xrt_space_overseer
 */
XRT_NONNULL_ALL static inline xrt_result_t
xrt_space_overseer_locate_space(struct xrt_space_overseer *xso,
                                struct xrt_space *base_space,
                                const struct xrt_pose *base_offset,
                                int64_t at_timestamp_ns,
                                struct xrt_space *space,
                                const struct xrt_pose *offset,
                                struct xrt_space_relation *out_relation)
{
        return xso->locate_space(xso, base_space, base_offset, at_timestamp_ns, space, offset, out_relation);
}
 
/*!
 * @copydoc xrt_space_overseer::locate_spaces
 *
 * Helper for calling through the function pointer.
 *
 * @public @memberof xrt_space_overseer
 */
XRT_NONNULL_ALL static inline xrt_result_t
xrt_space_overseer_locate_spaces(struct xrt_space_overseer *xso,
                                 struct xrt_space *base_space,
                                 const struct xrt_pose *base_offset,
                                 int64_t at_timestamp_ns,
                                 struct xrt_space **spaces,
                                 uint32_t space_count,
                                 const struct xrt_pose *offsets,
                                 struct xrt_space_relation *out_relations)
{
        return xso->locate_spaces(xso, base_space, base_offset, at_timestamp_ns, spaces, space_count, offsets,
                                  out_relations);
}
 
/*!
 * @copydoc xrt_space_overseer::locate_device
 *
 * Helper for calling through the function pointer.
 *
 * @public @memberof xrt_space_overseer
 */
XRT_NONNULL_ALL static inline xrt_result_t
xrt_space_overseer_locate_device(struct xrt_space_overseer *xso,
                                 struct xrt_space *base_space,
                                 const struct xrt_pose *base_offset,
                                 int64_t at_timestamp_ns,
                                 struct xrt_device *xdev,
                                 struct xrt_space_relation *out_relation)
{
        return xso->locate_device(xso, base_space, base_offset, at_timestamp_ns, xdev, out_relation);
}
 
/*!
 * @copydoc xrt_space_overseer::ref_space_inc
 *
 * Helper for calling through the function pointer.
 *
 * @public @memberof xrt_space_overseer
 */
XRT_NONNULL_ALL static inline xrt_result_t
xrt_space_overseer_ref_space_inc(struct xrt_space_overseer *xso, enum xrt_reference_space_type type)
{
        return xso->ref_space_inc(xso, type);
}
 
/*!
 * @copydoc xrt_space_overseer::ref_space_dec
 *
 * Helper for calling through the function pointer.
 *
 * @public @memberof xrt_space_overseer
 */
XRT_NONNULL_ALL static inline xrt_result_t
xrt_space_overseer_ref_space_dec(struct xrt_space_overseer *xso, enum xrt_reference_space_type type)
{
        return xso->ref_space_dec(xso, type);
}
 
/*!
 * @copydoc xrt_space_overseer::recenter_local_spaces
 *
 * Helper for calling through the function pointer.
 *
 * @public @memberof xrt_space_overseer
 */
XRT_NONNULL_ALL static inline xrt_result_t
xrt_space_overseer_recenter_local_spaces(struct xrt_space_overseer *xso)
{
        return xso->recenter_local_spaces(xso);
}
 
/*!
 * @copydoc xrt_space_overseer::get_tracking_origin_offset
 *
 * Helper for calling through the function pointer.
 *
 * @public @memberof xrt_space_overseer
 */
XRT_NONNULL_ALL static inline xrt_result_t
xrt_space_overseer_get_tracking_origin_offset(struct xrt_space_overseer *xso,
                                              struct xrt_tracking_origin *xto,
                                              struct xrt_pose *out_offset)
{
        return xso->get_tracking_origin_offset(xso, xto, out_offset);
}
 
/*!
 * @copydoc xrt_space_overseer::set_tracking_origin_offset
 *
 * Helper for calling through the function pointer.
 *
 * @public @memberof xrt_space_overseer
 */
XRT_NONNULL_ALL static inline xrt_result_t
xrt_space_overseer_set_tracking_origin_offset(struct xrt_space_overseer *xso,
                                              struct xrt_tracking_origin *xto,
                                              const struct xrt_pose *offset)
{
        return xso->set_tracking_origin_offset(xso, xto, offset);
}
 
/*!
 * @copydoc xrt_space_overseer::get_reference_space_offset
 *
 * Helper for calling through the function pointer.
 *
 * @public @memberof xrt_space_overseer
 */
XRT_NONNULL_ALL static inline xrt_result_t
xrt_space_overseer_get_reference_space_offset(struct xrt_space_overseer *xso,
                                              enum xrt_reference_space_type type,
                                              struct xrt_pose *out_offset)
{
        return xso->get_reference_space_offset(xso, type, out_offset);
}
 
/*!
 * @copydoc xrt_space_overseer::set_reference_space_offset
 *
 * Helper for calling through the function pointer.
 *
 * @public @memberof xrt_space_overseer
 */
XRT_NONNULL_ALL static inline xrt_result_t
xrt_space_overseer_set_reference_space_offset(struct xrt_space_overseer *xso,
                                              enum xrt_reference_space_type type,
                                              const struct xrt_pose *offset)
{
        return xso->set_reference_space_offset(xso, type, offset);
}
 
/*!
 * @copydoc xrt_space_overseer::create_local_space
 *
 * Helper for calling through the function pointer.
 *
 * @public @memberof xrt_space_overseer
 */
XRT_NONNULL_ALL static inline xrt_result_t
xrt_space_overseer_create_local_space(struct xrt_space_overseer *xso,
                                      struct xrt_space **out_local_space,
                                      struct xrt_space **out_local_floor_space)
{
        return xso->create_local_space(xso, out_local_space, out_local_floor_space);
}
 
/*!
 * @copydoc xrt_space_overseer::add_device
 *
 * Helper for calling through the function pointer.
 *
 * @public @memberof xrt_space_overseer
 */
XRT_NONNULL_ALL static inline xrt_result_t
xrt_space_overseer_add_device(struct xrt_space_overseer *xso, struct xrt_device *xdev)
{
        return xso->add_device(xso, xdev);
}
 
/*!
 * @copydoc xrt_space_overseer::remove_device
 *
 * Helper for calling through the function pointer.
 *
 * @public @memberof xrt_space_overseer
 */
XRT_NONNULL_ALL static inline xrt_result_t
xrt_space_overseer_remove_device(struct xrt_space_overseer *xso, struct xrt_device *xdev)
{
        return xso->remove_device(xso, xdev);
}
 
/*!
 * @copydoc xrt_space_overseer::attach_device
 *
 * Helper for calling through the function pointer.
 *
 * @public @memberof xrt_space_overseer
 */
XRT_NONNULL_ALL static inline xrt_result_t
xrt_space_overseer_attach_device(struct xrt_space_overseer *xso, struct xrt_device *xdev, struct xrt_space *space)
{
        return xso->attach_device(xso, xdev, space);
}
 
/*!
 * Helper for calling through the function pointer: does a null check and sets
 * xc_ptr to null if freed.
 *
 * @see xrt_space_overseer::destroy
 * @public @memberof xrt_space_overseer
 */
static inline void
xrt_space_overseer_destroy(struct xrt_space_overseer **xso_ptr)
{
        struct xrt_space_overseer *xso = *xso_ptr;
        if (xso == NULL) {
                return;
        }
 
        xso->destroy(xso);
        *xso_ptr = NULL;
}
 
 
#ifdef __cplusplus
}
#endif