// Copyright 2025-2026, NVIDIA CORPORATION. // SPDX-License-Identifier: BSL-1.0 /*! * @file * @brief Tracking objects to IDs. * @author Jakob Bornecrantz * @ingroup ipc_server */ #pragma once #include "xrt/xrt_results.h" struct xrt_space; struct xrt_body_tracker; struct xrt_hand_tracker; struct ipc_client_state; /* * * Device functions. * */ /*! * Get a device by its per-client-connection slot index. * * The @p id is a @c uint32_t index into @c ics->objects.xdevs used for IPC * message lookups. It is not @ref xrt_device::id. * * Must only be called from the per client thread as this function accesses the * client state's memory. * * @param ics The client state instance. * @param id The per-client slot index. * @param out_xdev Will be filled with the device object on success. * @return XRT_SUCCESS on success, some other result on failure. * * @ingroup ipc_server */ xrt_result_t ipc_server_objects_get_xdev_and_validate(volatile struct ipc_client_state *ics, uint32_t id, struct xrt_device **out_xdev); /*! * Get or allocate a per-client-connection slot index for a device object. * * The returned @c uint32_t is used in IPC messages to look up @p xdev on the * server. It is not @ref xrt_device::id, which is assigned at device creation * and synchronized to clients via @ref ipc_device_info. * * Must only be called from the per client thread as this function accesses the * client state's memory. * * @param ics The client state instance. * @param xdev The device object. * @param out_id Will be filled with the slot index on success. * @return XRT_SUCCESS on success, some other result on failure. * * @ingroup ipc_server */ xrt_result_t ipc_server_objects_get_xdev_id_or_add(volatile struct ipc_client_state *ics, struct xrt_device *xdev, uint32_t *out_id); /* * * Tracking origin functions. * */ /*! * Get a tracking origin by ID, must only be called from the per client * thread as this function accesses the client state's memory. * * @param ics The client state instance. * @param id The tracking origin ID. * @param out_xtrack Will be filled with the tracking origin object on success. * @return XRT_SUCCESS on success, some other result on failure. * * @ingroup ipc_server */ xrt_result_t ipc_server_objects_get_xtrack_and_validate(volatile struct ipc_client_state *ics, uint32_t id, struct xrt_tracking_origin **out_xtrack); /*! * Get a tracking origin ID for a given tracking origin object, must only be * called from the per client thread as this function accesses the client * state's memory. * * @param ics The client state instance. * @param xtrack The tracking origin object. * @param out_id Will be filled with the tracking origin ID on success. * @return XRT_SUCCESS on success, some other result on failure. * * @ingroup ipc_server */ xrt_result_t ipc_server_objects_get_xtrack_id_or_add(volatile struct ipc_client_state *ics, struct xrt_tracking_origin *xtrack, uint32_t *out_id); /* * * Space functions. * */ /*! * Get a space by ID, must only be called from the per client thread. * * @ingroup ipc_server */ xrt_result_t ipc_server_objects_get_xspc_and_validate(volatile struct ipc_client_state *ics, uint32_t id, struct xrt_space **out_xspc); /*! * Track a space and return its ID. Grabs and stores a reference if newly * tracked. * * @ingroup ipc_server */ xrt_result_t ipc_server_objects_get_xspc_id_or_add(volatile struct ipc_client_state *ics, struct xrt_space *xspc, uint32_t *out_id); /*! * Destroy a tracked space. * * @ingroup ipc_server */ xrt_result_t ipc_server_objects_destroy_xspc(volatile struct ipc_client_state *ics, uint32_t id); /* * * Body tracker functions. * */ /*! * Get a body tracker by ID, must only be called from the per client thread. * * @ingroup ipc_server */ xrt_result_t ipc_server_objects_get_xbt_and_validate(volatile struct ipc_client_state *ics, uint32_t id, struct xrt_body_tracker **out_xbt); /*! * Track a newly created body tracker and return its ID. Takes ownership of * @p xbt until explicit destroy or client disconnect. * * @ingroup ipc_server */ xrt_result_t ipc_server_objects_get_xbt_id_or_add(volatile struct ipc_client_state *ics, struct xrt_body_tracker *xbt, uint32_t *out_id); /*! * Destroy a tracked body tracker. * * @ingroup ipc_server */ xrt_result_t ipc_server_objects_destroy_xbt(volatile struct ipc_client_state *ics, uint32_t id); /* * * Hand tracker functions. * */ /*! * Get a hand tracker by ID, must only be called from the per client thread. * * @ingroup ipc_server */ xrt_result_t ipc_server_objects_get_xht_and_validate(volatile struct ipc_client_state *ics, uint32_t id, struct xrt_hand_tracker **out_xht); /*! * Track a newly created hand tracker and return its ID. Takes ownership of * @p xht until explicit destroy or client disconnect. * * @ingroup ipc_server */ xrt_result_t ipc_server_objects_get_xht_id_or_add(volatile struct ipc_client_state *ics, struct xrt_hand_tracker *xht, uint32_t *out_id); /*! * Destroy a tracked hand tracker. * * @ingroup ipc_server */ xrt_result_t ipc_server_objects_destroy_xht(volatile struct ipc_client_state *ics, uint32_t id); /* * * App policy functions. * */ xrt_result_t ipc_server_objects_get_xainst_and_validate(volatile struct ipc_client_state *ics, uint32_t id, struct xrt_app_instance **out_xainst); xrt_result_t ipc_server_objects_get_xainst_id_or_add(volatile struct ipc_client_state *ics, struct xrt_app_instance *xainst, uint32_t *out_id); xrt_result_t ipc_server_objects_destroy_xainst(volatile struct ipc_client_state *ics, uint32_t id); xrt_result_t ipc_server_objects_get_xasys_and_validate(volatile struct ipc_client_state *ics, uint32_t id, struct xrt_app_system **out_xasys); xrt_result_t ipc_server_objects_get_xasys_id_or_add(volatile struct ipc_client_state *ics, struct xrt_app_system *xasys, uint32_t *out_id); xrt_result_t ipc_server_objects_destroy_xasys(volatile struct ipc_client_state *ics, uint32_t id);