Monado OpenXR Runtime
xrt_space_overseer Struct Reference

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

#include <xrt/xrt_space.h>

Collaboration diagram for xrt_space_overseer:

Static 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_spaces (struct xrt_space_overseer *xso, struct xrt_space *base_space, const struct xrt_pose *base_offset, uint64_t at_timestamp_ns, struct xrt_space **spaces, uint32_t space_count, const struct xrt_pose *offsets, struct xrt_space_relation *out_relations)
 Locate spaces 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 xrt_result_t xrt_space_overseer_get_tracking_origin_offset (struct xrt_space_overseer *xso, struct xrt_tracking_origin *torig, struct xrt_pose *out_offset)
 Read the offset from a tracking origin, not all implementations of xrt_space_overseer may support this. More...
 
static xrt_result_t xrt_space_overseer_set_tracking_origin_offset (struct xrt_space_overseer *xso, struct xrt_tracking_origin *torig, const struct xrt_pose *offset)
 Apply an offset to a tracking origin, not all implementations of xrt_space_overseer may support this. More...
 
static 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)
 Read the offset from the given reference space, not all implementations of xrt_space_overseer may support this. More...
 
static 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)
 Apply an offset to the given reference space, not all implementations of xrt_space_overseer may support this. More...
 
static xrt_result_t xrt_space_overseer_create_local_space (struct xrt_space_overseer *xso, struct xrt_space **out_space)
 
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
 
struct xrt_spacelocalspace [128]
 Ptrs to the localspace. More...
 
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_spaces )(struct xrt_space_overseer *xso, struct xrt_space *base_space, const struct xrt_pose *base_offset, uint64_t at_timestamp_ns, struct xrt_space **spaces, uint32_t space_count, const struct xrt_pose *offsets, struct xrt_space_relation *out_relations)
 Locate spaces 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...
 
xrt_result_t(* get_tracking_origin_offset )(struct xrt_space_overseer *xso, struct xrt_tracking_origin *xto, struct xrt_pose *out_offset)
 Read the offset from a tracking origin, not all implementations of xrt_space_overseer may support this. More...
 
xrt_result_t(* set_tracking_origin_offset )(struct xrt_space_overseer *xso, struct xrt_tracking_origin *xto, const struct xrt_pose *offset)
 Apply an offset to a tracking origin, not all implementations of xrt_space_overseer may support this. More...
 
xrt_result_t(* get_reference_space_offset )(struct xrt_space_overseer *xso, enum xrt_reference_space_type type, struct xrt_pose *out_offset)
 Read the offset from the given reference space, not all implementations of xrt_space_overseer may support this. More...
 
xrt_result_t(* set_reference_space_offset )(struct xrt_space_overseer *xso, enum xrt_reference_space_type type, const struct xrt_pose *offset)
 Apply an offset to the given reference space, not all implementations of xrt_space_overseer may support this. More...
 
xrt_result_t(* create_local_space )(struct xrt_space_overseer *xso, struct xrt_space **out_space)
 Create a localspace. 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_local_space()

static xrt_result_t xrt_space_overseer_create_local_space ( struct xrt_space_overseer xso,
struct xrt_space **  out_space 
)
inlinestatic

Helper for calling through the function pointer.

References create_local_space.

◆ 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 
)
inlinestatic

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

Parameters
[in]xsoOwning space overseer.
[in]parentThe parent space for the new space.
[in]offsetOffset to the space.
[out]out_spaceThe 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 
)
inlinestatic

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]xsoOwning space overseer.
[in]xdevDevice to get the pose from.
[in]nameName of the pose input.
[out]out_spaceThe newly created space.

Helper for calling through the function pointer.

References create_pose_space.

Referenced by oxr_space_xdev_pose_create(), and 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)
inlinestatic

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

References destroy.

◆ xrt_space_overseer_get_reference_space_offset()

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

Read the offset from the given reference space, not all implementations of xrt_space_overseer may support this.

Outputs are only valid if XRT_SUCCESS is returned.

Parameters
[in]xsoThe space overseer.
[in]typeThe reference space.
[out]out_offsetPointer to write the offset to.

Helper for calling through the function pointer.

◆ xrt_space_overseer_get_tracking_origin_offset()

static xrt_result_t xrt_space_overseer_get_tracking_origin_offset ( struct xrt_space_overseer xso,
struct xrt_tracking_origin torig,
struct xrt_pose out_offset 
)
inlinestatic

Read the offset from a tracking origin, not all implementations of xrt_space_overseer may support this.

Outputs are only valid if XRT_SUCCESS is returned.

Parameters
[in]xsoThe space overseer.
[in]xtoThe tracking origin.
[out]out_offsetPointer to an xrt_pose to write the offset to

Helper for calling through the function pointer.

References get_tracking_origin_offset.

◆ 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 
)
inlinestatic

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]xsoOwning space overseer.
[in]base_spaceThe space that we want the pose in.
[in]base_offsetOffset if any to the base space.
[in]at_timestamp_nsAt which time.
[in]xdevDevice to get the pose from.
[out]out_relationResulting 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 
)
inlinestatic

Locate a space in the base space.

See also
xrt_device::get_tracked_pose.
Parameters
[in]xsoOwning space overseer.
[in]base_spaceThe space that we want the pose in.
[in]base_offsetOffset if any to the base space.
[in]at_timestamp_nsAt which time.
[in]spaceThe space to be located.
[in]offsetOffset if any to the located space.
[out]out_relationResulting pose.

Helper for calling through the function pointer.

References locate_space.

◆ xrt_space_overseer_locate_spaces()

static xrt_result_t xrt_space_overseer_locate_spaces ( struct xrt_space_overseer xso,
struct xrt_space base_space,
const struct xrt_pose base_offset,
uint64_t  at_timestamp_ns,
struct xrt_space **  spaces,
uint32_t  space_count,
const struct xrt_pose offsets,
struct xrt_space_relation out_relations 
)
inlinestatic

Locate spaces in the base space.

See also
xrt_device::get_tracked_pose.
Parameters
[in]xsoOwning space overseer.
[in]base_spaceThe space that we want the pose in.
[in]base_offsetOffset if any to the base space.
[in]at_timestamp_nsAt which time.
[in]spacesThe array of pointers to spaces to be located.
[in]space_countThe number of spaces to locate.
[in]offsetsArray of offset if any to the located spaces.
[out]out_relationsArray of resulting poses.

Helper for calling through the function pointer.

References locate_spaces.

◆ xrt_space_overseer_recenter_local_spaces()

static xrt_result_t xrt_space_overseer_recenter_local_spaces ( struct xrt_space_overseer xso)
inlinestatic

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]xsoThe 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 
)
inlinestatic

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

See xrt_space_overseer::ref_space_inc.

Parameters
[in]xsoOwning space overseer.
[in]typeWhich 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 
)
inlinestatic

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]xsoOwning space overseer.
[in]typeWhich reference space is being referenced.

Helper for calling through the function pointer.

◆ xrt_space_overseer_set_reference_space_offset()

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

Apply an offset to the given reference space, not all implementations of xrt_space_overseer may support this.

Parameters
[in]xsoThe space overseer.
[in]typeThe reference space.
[in]offsetThe offset to apply.

Helper for calling through the function pointer.

◆ xrt_space_overseer_set_tracking_origin_offset()

static xrt_result_t xrt_space_overseer_set_tracking_origin_offset ( struct xrt_space_overseer xso,
struct xrt_tracking_origin torig,
const struct xrt_pose offset 
)
inlinestatic

Apply an offset to a tracking origin, not all implementations of xrt_space_overseer may support this.

Parameters
[in]xsoThe space overseer.
[in]xtoThe tracking origin.
[in]offsetThe offset to apply.

Helper for calling through the function pointer.

References set_tracking_origin_offset.

Field Documentation

◆ create_local_space

xrt_result_t(* xrt_space_overseer::create_local_space) (struct xrt_space_overseer *xso, struct xrt_space **out_space)

Create a localspace.

Parameters
[in]xsoOwning space overseer.
[out]out_spaceThe newly created localspace.

Referenced by u_space_overseer_create(), and xrt_space_overseer_create_local_space().

◆ 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]xsoOwning space overseer.
[in]parentThe parent space for the new space.
[in]offsetOffset to the space.
[out]out_spaceThe newly created space.

Referenced by 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]xsoOwning space overseer.
[in]xdevDevice to get the pose from.
[in]nameName of the pose input.
[out]out_spaceThe 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
xsoThe space overseer.

Referenced by xrt_space_overseer_destroy().

◆ get_reference_space_offset

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)

Read the offset from the given reference space, not all implementations of xrt_space_overseer may support this.

Outputs are only valid if XRT_SUCCESS is returned.

Parameters
[in]xsoThe space overseer.
[in]typeThe reference space.
[out]out_offsetPointer to write the offset to.

◆ get_tracking_origin_offset

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)

Read the offset from a tracking origin, not all implementations of xrt_space_overseer may support this.

Outputs are only valid if XRT_SUCCESS is returned.

Parameters
[in]xsoThe space overseer.
[in]xtoThe tracking origin.
[out]out_offsetPointer to an xrt_pose to write the offset to

Referenced by xrt_space_overseer_get_tracking_origin_offset().

◆ 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.

◆ localspace

struct xrt_space* xrt_space_overseer::localspace[128]

Ptrs to the localspace.

◆ 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]xsoOwning space overseer.
[in]base_spaceThe space that we want the pose in.
[in]base_offsetOffset if any to the base space.
[in]at_timestamp_nsAt which time.
[in]xdevDevice to get the pose from.
[out]out_relationResulting 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]xsoOwning space overseer.
[in]base_spaceThe space that we want the pose in.
[in]base_offsetOffset if any to the base space.
[in]at_timestamp_nsAt which time.
[in]spaceThe space to be located.
[in]offsetOffset if any to the located space.
[out]out_relationResulting pose.

Referenced by xrt_space_overseer_locate_space().

◆ locate_spaces

xrt_result_t(* xrt_space_overseer::locate_spaces) (struct xrt_space_overseer *xso, struct xrt_space *base_space, const struct xrt_pose *base_offset, uint64_t at_timestamp_ns, struct xrt_space **spaces, uint32_t space_count, const struct xrt_pose *offsets, struct xrt_space_relation *out_relations)

Locate spaces in the base space.

See also
xrt_device::get_tracked_pose.
Parameters
[in]xsoOwning space overseer.
[in]base_spaceThe space that we want the pose in.
[in]base_offsetOffset if any to the base space.
[in]at_timestamp_nsAt which time.
[in]spacesThe array of pointers to spaces to be located.
[in]space_countThe number of spaces to locate.
[in]offsetsArray of offset if any to the located spaces.
[out]out_relationsArray of resulting poses.

Referenced by xrt_space_overseer_locate_spaces().

◆ 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]xsoThe 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]xsoOwning space overseer.
[in]typeWhich 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]xsoOwning space overseer.
[in]typeWhich reference space is being referenced.

◆ root

struct xrt_space* xrt_space_overseer::root

Root space, always available.

Referenced by u_space_overseer_legacy_setup().

◆ set_reference_space_offset

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)

Apply an offset to the given reference space, not all implementations of xrt_space_overseer may support this.

Parameters
[in]xsoThe space overseer.
[in]typeThe reference space.
[in]offsetThe offset to apply.

◆ set_tracking_origin_offset

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)

Apply an offset to a tracking origin, not all implementations of xrt_space_overseer may support this.

Parameters
[in]xsoThe space overseer.
[in]xtoThe tracking origin.
[in]offsetThe offset to apply.

Referenced by xrt_space_overseer_set_tracking_origin_offset().

◆ 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: