Object that oversees and manages spaces, one created for each XR system. More...

#include <xrt/xrt_space.h>

Collaboration diagram for xrt_space_overseer:

[legend]

Public Member Functions
static 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)
	Create a space with a fixed offset to the parent space. More...

static 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)
	Create a space that wraps the `xdev` input pose described by input `name`, implicitly make the device's tracking space the parent of the created space. More...

static xrt_result_t	xrt_space_overseer_locate_space (struct xrt_space_overseer xso, struct xrt_space base_space, const struct xrt_pose base_offset, uint64_t at_timestamp_ns, struct xrt_space space, const struct xrt_pose offset, struct xrt_space_relation out_relation)
	Locate a space in the base space. More...

static xrt_result_t	xrt_space_overseer_locate_device (struct xrt_space_overseer xso, struct xrt_space base_space, const struct xrt_pose base_offset, uint64_t at_timestamp_ns, struct xrt_device xdev, struct xrt_space_relation *out_relation)
	Locate a the origin of the tracking space of a device, this is not the same as the device position. More...

static xrt_result_t	xrt_space_overseer_ref_space_inc (struct xrt_space_overseer *xso, enum xrt_reference_space_type type)
	Increment the usage count of a reference space (aka semantic space). More...

static xrt_result_t	xrt_space_overseer_ref_space_dec (struct xrt_space_overseer *xso, enum xrt_reference_space_type type)
	Decrement the usage count of a reference space (aka semantic space). More...

static xrt_result_t	xrt_space_overseer_recenter_local_spaces (struct xrt_space_overseer *xso)
	Trigger a re-center of the local and local_floor spaces, not all implementations of xrt_space_overseer may support recenter. More...

static void	xrt_space_overseer_destroy (struct xrt_space_overseer **xso_ptr)
	Helper for calling through the function pointer: does a null check and sets xc_ptr to null if freed. More...

Data Fields
struct {
struct xrt_space * root
	Root space, always available. More...

struct xrt_space * view
	View space, may be null (in very rare cases). More...

struct xrt_space * local
	Local space, may be null (in very rare cases). More...

struct xrt_space * local_floor
	Local floor space, may be null. More...

struct xrt_space * stage
	Stage space, may be null. More...

struct xrt_space * unbounded
	Unbounded space, only here for slam trackers. More...

}	semantic

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 with a fixed offset to the parent space. More...

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)
	Create a space that wraps the `xdev` input pose described by input `name`, implicitly make the device's tracking space the parent of the created space. More...

xrt_result_t(*	locate_space )(struct xrt_space_overseer xso, struct xrt_space base_space, const struct xrt_pose base_offset, uint64_t at_timestamp_ns, struct xrt_space space, const struct xrt_pose offset, struct xrt_space_relation out_relation)
	Locate a space in the base space. More...

xrt_result_t(*	locate_device )(struct xrt_space_overseer xso, struct xrt_space base_space, const struct xrt_pose base_offset, uint64_t at_timestamp_ns, struct xrt_device xdev, struct xrt_space_relation *out_relation)
	Locate a the origin of the tracking space of a device, this is not the same as the device position. More...

xrt_result_t(*	ref_space_inc )(struct xrt_space_overseer *xso, enum xrt_reference_space_type type)
	Increment the usage count of a reference space (aka semantic space). More...

xrt_result_t(*	ref_space_dec )(struct xrt_space_overseer *xso, enum xrt_reference_space_type type)
	Decrement the usage count of a reference space (aka semantic space). More...

xrt_result_t(*	recenter_local_spaces )(struct xrt_space_overseer *xso)
	Trigger a re-center of the local and local_floor spaces, not all implementations of xrt_space_overseer may support recenter. More...

void(*	destroy )(struct xrt_space_overseer *xs)
	Destroy function. More...

Detailed Description

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 u_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 also: Spaces in Monado design

Member Function Documentation

◆ xrt_space_overseer_create_offset_space()

static 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
	)

inline

Create a space with a fixed offset to the parent space.

Parameters

[in]	xso	Owning space overseer.
[in]	parent	The parent space for the new space.
[in]	offset	Offset to the space.
[out]	out_space	The newly created space.

Helper for calling through the function pointer.

References create_offset_space.

Referenced by u_space_overseer::u_space_overseer_create_offset_space().

◆ xrt_space_overseer_create_pose_space()

static 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
	)

inline

Create a space that wraps the xdev input pose described by input 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.

Parameters

[in]	xso	Owning space overseer.
[in]	xdev	Device to get the pose from.
[in]	name	Name of the pose input.
[out]	out_space	The newly created space.

Helper for calling through the function pointer.

References create_pose_space.

Referenced by u_space_overseer::u_space_overseer_create_pose_space().

◆ xrt_space_overseer_destroy()

static void xrt_space_overseer_destroy ( struct xrt_space_overseer ** xso_ptr )

inline

Helper for calling through the function pointer: does a null check and sets xc_ptr to null if freed.

See also: xrt_space_overseer::destroy

◆ xrt_space_overseer_locate_device()

static xrt_result_t xrt_space_overseer_locate_device	(	struct xrt_space_overseer *	xso,
		struct xrt_space *	base_space,
		const struct xrt_pose *	base_offset,
		uint64_t	at_timestamp_ns,
		struct xrt_device *	xdev,
		struct xrt_space_relation *	out_relation
	)

inline

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 xrt_device::get_view_poses and xrt_device::get_hand_tracking.

See also: xrt_device::get_tracked_pose.

Parameters

[in]	xso	Owning space overseer.
[in]	base_space	The space that we want the pose in.
[in]	base_offset	Offset if any to the base space.
[in]	at_timestamp_ns	At which time.
[in]	xdev	Device to get the pose from.
[out]	out_relation	Resulting pose.

Helper for calling through the function pointer.

References locate_device.

◆ xrt_space_overseer_locate_space()

static xrt_result_t xrt_space_overseer_locate_space	(	struct xrt_space_overseer *	xso,
		struct xrt_space *	base_space,
		const struct xrt_pose *	base_offset,
		uint64_t	at_timestamp_ns,
		struct xrt_space *	space,
		const struct xrt_pose *	offset,
		struct xrt_space_relation *	out_relation
	)

inline

Locate a space in the base space.

See also: xrt_device::get_tracked_pose.

Parameters

[in]	xso	Owning space overseer.
[in]	base_space	The space that we want the pose in.
[in]	base_offset	Offset if any to the base space.
[in]	at_timestamp_ns	At which time.
[in]	space	The space to be located.
[in]	offset	Offset if any to the located space.
[out]	out_relation	Resulting pose.

Helper for calling through the function pointer.

References locate_space.

◆ xrt_space_overseer_recenter_local_spaces()

static xrt_result_t xrt_space_overseer_recenter_local_spaces ( struct xrt_space_overseer * xso )

inline

Trigger a re-center of the local and local_floor spaces, not all implementations of 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.

Parameters

[in] xso The space overseer.

Helper for calling through the function pointer.

References recenter_local_spaces.

◆ xrt_space_overseer_ref_space_dec()

static xrt_result_t xrt_space_overseer_ref_space_dec	(	struct xrt_space_overseer *	xso,
		enum xrt_reference_space_type	type
	)

inline

Decrement the usage count of a reference space (aka semantic space).

See xrt_space_overseer::ref_space_inc.

Parameters

[in]	xso	Owning space overseer.
[in]	type	Which reference space is being referenced.

Helper for calling through the function pointer.

◆ xrt_space_overseer_ref_space_inc()

static xrt_result_t xrt_space_overseer_ref_space_inc	(	struct xrt_space_overseer *	xso,
		enum xrt_reference_space_type	type
	)

inline

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.

Parameters

[in]	xso	Owning space overseer.
[in]	type	Which reference space is being referenced.

Helper for calling through the function pointer.

Field Documentation

◆ create_offset_space

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)

Create a space with a fixed offset to the parent space.

Parameters

[in]	xso	Owning space overseer.
[in]	parent	The parent space for the new space.
[in]	offset	Offset to the space.
[out]	out_space	The newly created space.

Referenced by u_space_overseer_create(), and xrt_space_overseer_create_offset_space().

◆ create_pose_space

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)

Create a space that wraps the xdev input pose described by input 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.

Parameters

[in]	xso	Owning space overseer.
[in]	xdev	Device to get the pose from.
[in]	name	Name of the pose input.
[out]	out_space	The newly created space.

Referenced by xrt_space_overseer_create_pose_space().

◆ destroy

void(* xrt_space_overseer::destroy) (struct xrt_space_overseer *xs)

Destroy function.

Parameters

xso	The space overseer.

◆ local

struct xrt_space* xrt_space_overseer::local

Local space, may be null (in very rare cases).

◆ local_floor

struct xrt_space* xrt_space_overseer::local_floor

Local floor space, may be null.

◆ locate_device

xrt_result_t(* xrt_space_overseer::locate_device) (struct xrt_space_overseer *xso, struct xrt_space *base_space, const struct xrt_pose *base_offset, uint64_t at_timestamp_ns, struct xrt_device *xdev, struct xrt_space_relation *out_relation)

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 xrt_device::get_view_poses and xrt_device::get_hand_tracking.

See also: xrt_device::get_tracked_pose.

Parameters

[in]	xso	Owning space overseer.
[in]	base_space	The space that we want the pose in.
[in]	base_offset	Offset if any to the base space.
[in]	at_timestamp_ns	At which time.
[in]	xdev	Device to get the pose from.
[out]	out_relation	Resulting pose.

Referenced by xrt_space_overseer_locate_device().

◆ locate_space

xrt_result_t(* xrt_space_overseer::locate_space) (struct xrt_space_overseer *xso, struct xrt_space *base_space, const struct xrt_pose *base_offset, uint64_t at_timestamp_ns, struct xrt_space *space, const struct xrt_pose *offset, struct xrt_space_relation *out_relation)

Locate a space in the base space.

See also: xrt_device::get_tracked_pose.

Parameters

[in]	xso	Owning space overseer.
[in]	base_space	The space that we want the pose in.
[in]	base_offset	Offset if any to the base space.
[in]	at_timestamp_ns	At which time.
[in]	space	The space to be located.
[in]	offset	Offset if any to the located space.
[out]	out_relation	Resulting pose.

Referenced by xrt_space_overseer_locate_space().

◆ recenter_local_spaces

xrt_result_t(* xrt_space_overseer::recenter_local_spaces) (struct xrt_space_overseer *xso)

Trigger a re-center of the local and local_floor spaces, not all implementations of 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.

Parameters

[in] xso The space overseer.

Referenced by xrt_space_overseer_recenter_local_spaces().

◆ ref_space_dec

xrt_result_t(* xrt_space_overseer::ref_space_dec) (struct xrt_space_overseer *xso, enum xrt_reference_space_type type)

Decrement the usage count of a reference space (aka semantic space).

See xrt_space_overseer::ref_space_inc.

Parameters

[in]	xso	Owning space overseer.
[in]	type	Which reference space is being referenced.

◆ ref_space_inc

xrt_result_t(* xrt_space_overseer::ref_space_inc) (struct xrt_space_overseer *xso, enum xrt_reference_space_type type)

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.

Parameters

[in]	xso	Owning space overseer.
[in]	type	Which reference space is being referenced.

◆ root

struct xrt_space* xrt_space_overseer::root

Root space, always available.

Referenced by u_space_overseer_legacy_setup().

◆ stage

struct xrt_space* xrt_space_overseer::stage

Stage space, may be null.

◆ unbounded

struct xrt_space* xrt_space_overseer::unbounded

Unbounded space, only here for slam trackers.

◆ view

struct xrt_space* xrt_space_overseer::view

View space, may be null (in very rare cases).

The documentation for this struct was generated from the following file:

xrt/xrt_space.h

Public Member Functions

Data Fields

Detailed Description

Member Function Documentation

◆ xrt_space_overseer_create_offset_space()

◆ xrt_space_overseer_create_pose_space()

◆ xrt_space_overseer_destroy()

◆ xrt_space_overseer_locate_device()

◆ xrt_space_overseer_locate_space()

◆ xrt_space_overseer_recenter_local_spaces()

◆ xrt_space_overseer_ref_space_dec()

◆ xrt_space_overseer_ref_space_inc()

Field Documentation

◆ create_offset_space

◆ create_pose_space

◆ destroy

◆ local

◆ local_floor

◆ locate_device

◆ locate_space

◆ recenter_local_spaces

◆ ref_space_dec

◆ ref_space_inc

◆ root

◆ stage

◆ unbounded

◆ view