A single HMD or input device. More...

#include <xrt/xrt_device.h>

Inheritance diagram for xrt_device:

[legend]

Collaboration diagram for xrt_device:

[legend]

Public Member Functions
static void	xrt_device_update_inputs (struct xrt_device *xdev)
	Helper function for xrt_device::update_inputs. More...

static void	xrt_device_get_tracked_pose (struct xrt_device xdev, enum xrt_input_name name, uint64_t at_timestamp_ns, struct xrt_space_relation out_relation)
	Helper function for xrt_device::get_tracked_pose. More...

static void	xrt_device_get_hand_tracking (struct xrt_device xdev, enum xrt_input_name name, uint64_t desired_timestamp_ns, struct xrt_hand_joint_set out_value, uint64_t *out_timestamp_ns)
	Helper function for xrt_device::get_hand_tracking. More...

static xrt_result_t	xrt_device_get_face_tracking (struct xrt_device xdev, enum xrt_input_name facial_expression_type, struct xrt_facial_expression_set out_value)
	Helper function for xrt_device::get_face_tracking. More...

static void	xrt_device_set_output (struct xrt_device xdev, enum xrt_output_name name, const union xrt_output_value value)
	Helper function for xrt_device::set_output. More...

static void	xrt_device_get_view_poses (struct xrt_device xdev, const struct xrt_vec3 default_eye_relation, uint64_t at_timestamp_ns, uint32_t view_count, struct xrt_space_relation out_head_relation, struct xrt_fov out_fovs, struct xrt_pose *out_poses)
	Helper function for xrt_device::get_view_poses. More...

static bool	xrt_device_compute_distortion (struct xrt_device xdev, uint32_t view, float u, float v, struct xrt_uv_triplet out_result)
	Helper function for xrt_device::compute_distortion. More...

static xrt_result_t	xrt_device_get_visibility_mask (struct xrt_device xdev, enum xrt_visibility_mask_type type, uint32_t view_index, struct xrt_visibility_mask *out_mask)
	Helper function for xrt_device::get_visibility_mask. More...

static xrt_result_t	xrt_device_ref_space_usage (struct xrt_device *xdev, enum xrt_reference_space_type type, enum xrt_input_name name, bool used)
	Helper function for xrt_device::ref_space_usage. More...

static bool	xrt_device_is_form_factor_available (struct xrt_device *xdev, enum xrt_form_factor form_factor)
	Helper function for xrt_device::is_form_factor_available. More...

static void	xrt_device_destroy (struct xrt_device **xdev_ptr)
	Helper function for xrt_device::destroy. More...

Data Fields
enum xrt_device_name	name
	Enum identifier of the device. More...

enum xrt_device_type	device_type

char	str [256]
	A string describing the device. More...

char	serial [256]
	A unique identifier. Persistent across configurations, if possible. More...

struct xrt_hmd_parts *	hmd
	Null if this device does not interface with the users head. More...

struct xrt_tracking_origin *	tracking_origin
	Always set, pointing to the tracking system for this device. More...

size_t	binding_profile_count
	Number of bindings in xrt_device::binding_profiles. More...

struct xrt_binding_profile *	binding_profiles

size_t	input_count
	Number of inputs. More...

struct xrt_input *	inputs
	Array of input structs. More...

size_t	output_count
	Number of outputs. More...

struct xrt_output *	outputs
	Array of output structs. More...

bool	orientation_tracking_supported

bool	position_tracking_supported

bool	hand_tracking_supported

bool	eye_gaze_supported

bool	force_feedback_supported

bool	ref_space_usage_supported

bool	form_factor_check_supported

bool	stage_supported

bool	face_tracking_supported

void(*	update_inputs )(struct xrt_device *xdev)
	Update any attached inputs. More...

void(*	get_tracked_pose )(struct xrt_device xdev, enum xrt_input_name name, uint64_t at_timestamp_ns, struct xrt_space_relation out_relation)
	Get relationship of a tracked device to the tracking origin space as the base space. More...

void(*	get_hand_tracking )(struct xrt_device xdev, enum xrt_input_name name, uint64_t desired_timestamp_ns, struct xrt_hand_joint_set out_value, uint64_t *out_timestamp_ns)
	Get relationship of hand joints to the tracking origin space as the base space. More...

xrt_result_t(*	get_face_tracking )(struct xrt_device xdev, enum xrt_input_name facial_expression_type, struct xrt_facial_expression_set out_value)
	Get the requested blend shape properties & weights for a face tracker. More...

void(*	set_output )(struct xrt_device xdev, enum xrt_output_name name, const union xrt_output_value value)
	Set a output value. More...

void(*	get_view_poses )(struct xrt_device xdev, const struct xrt_vec3 default_eye_relation, uint64_t at_timestamp_ns, uint32_t view_count, struct xrt_space_relation out_head_relation, struct xrt_fov out_fovs, struct xrt_pose *out_poses)
	Get the per-view pose in relation to the view space. More...

bool(*	compute_distortion )(struct xrt_device xdev, uint32_t view, float u, float v, struct xrt_uv_triplet out_result)
	Compute the distortion at a single point. More...

xrt_result_t(*	get_visibility_mask )(struct xrt_device xdev, enum xrt_visibility_mask_type type, uint32_t view_index, struct xrt_visibility_mask *out_mask)
	Get the visibility mask for this device. More...

xrt_result_t(*	ref_space_usage )(struct xrt_device *xdev, enum xrt_reference_space_type type, enum xrt_input_name name, bool used)
	Called by the xrt_space_overseer when a reference space that is implemented by this device is first used, or when the last usage of the reference space stops. More...

bool(*	is_form_factor_available )(struct xrt_device *xdev, enum xrt_form_factor form_factor)
	Check if given form factor is available or not. More...

void(*	destroy )(struct xrt_device *xdev)
	Destroy device. More...

Related Functions
(Note that these are not member functions.)
void	u_distortion_mesh_fill_in_compute (struct xrt_device *xdev)
	Given a xrt_device generates meshes by calling xdev->compute_distortion(), populates `xdev->hmd_parts.distortion.mesh` & `xdev->hmd_parts.distortion.models`. More...

void	u_distortion_mesh_fill_in_none (struct xrt_device *xdev)
	Given a xrt_device generates a no distortion mesh, populates `xdev->hmd_parts.distortion.mesh` & `xdev->hmd_parts.distortion.models`. More...

void	u_distortion_mesh_set_none (struct xrt_device *xdev)
	Given a xrt_device generates a no distortion mesh, also sets `xdev->compute_distortion()` and populates `xdev->hmd_parts.distortion.mesh` & `xdev->hmd_parts.distortion.models`. More...

Detailed Description

A single HMD or input device.

Member Function Documentation

◆ xrt_device_compute_distortion()

static bool xrt_device_compute_distortion	(	struct xrt_device *	xdev,
		uint32_t	view,
		float	u,
		float	v,
		struct xrt_uv_triplet *	out_result
	)

inline

Helper function for xrt_device::compute_distortion.

Compute the distortion at a single point. The input is u v in screen/output space (that is, predistorted), you are to compute and return the u,v coordinates to sample the render texture. The compositor will step through a range of u,v parameters to build the lookup (vertex attribute or distortion texture) used to pre-distort the image as required by the device's optics.

Parameters

	xdev	the device
	view	the view index
	u	horizontal texture coordinate
	v	vertical texture coordinate
[out]	out_result	corresponding u,v pairs for all three color channels.

References compute_distortion.

◆ xrt_device_destroy()

static void xrt_device_destroy ( struct xrt_device ** xdev_ptr )

inline

Helper function for xrt_device::destroy.

Handles nulls, sets your pointer to null.

Referenced by u_system_devices_close().

◆ xrt_device_get_face_tracking()

static xrt_result_t xrt_device_get_face_tracking	(	struct xrt_device *	xdev,
		enum xrt_input_name	facial_expression_type,
		struct xrt_facial_expression_set *	out_value
	)

inline

Helper function for xrt_device::get_face_tracking.

Get the requested blend shape properties & weights for a face tracker.

Parameters

[in]	xdev	The device.
[in]	facial_expression_type	The facial expression data type (XR_FB_face_tracking, XR_HTC_facial_tracking, etc).
[in]	out_value	Set of requested expression weights & blend shape properties.

See also: xrt_input_name

References get_face_tracking.

◆ xrt_device_get_hand_tracking()

static void xrt_device_get_hand_tracking	(	struct xrt_device *	xdev,
		enum xrt_input_name	name,
		uint64_t	desired_timestamp_ns,
		struct xrt_hand_joint_set *	out_value,
		uint64_t *	out_timestamp_ns
	)

inline

Helper function for xrt_device::get_hand_tracking.

Get relationship of hand joints to the tracking origin space as the base space. It is the responsibility of the device driver to either do prediction or return joints from a previous time and write that time out to out_timestamp_ns.

The timestamps are system monotonic timestamps, such as returned by os_monotonic_get_ns().

Parameters

[in]	xdev	The device.
[in]	name	Some devices may have multiple poses on them, select the one using this field. For hand tracking use `XRT_INPUT_GENERIC_HAND_TRACKING_DEFAULT_SET`.
[in]	desired_timestamp_ns	If the device can predict or has a history of positions, this is when the caller wants the pose to be from.
[out]	out_value	The hand joint data read from the device.
[out]	out_timestamp_ns	The timestamp of the data being returned.

See also: xrt_input_name

References get_hand_tracking, and name.

Referenced by oxr_xdev_get_hand_tracking_at().

◆ xrt_device_get_tracked_pose()

static void xrt_device_get_tracked_pose	(	struct xrt_device *	xdev,
		enum xrt_input_name	name,
		uint64_t	at_timestamp_ns,
		struct xrt_space_relation *	out_relation
	)

inline

Helper function for xrt_device::get_tracked_pose.

Get relationship of a tracked device to the tracking origin space as the base space. It is the responsibility of the device driver to do any prediction, there are helper functions available for this.

The timestamps are system monotonic timestamps, such as returned by os_monotonic_get_ns().

Parameters

[in]	xdev	The device.
[in]	name	Some devices may have multiple poses on them, select the one using this field. For HMDs use `XRT_INPUT_GENERIC_HEAD_POSE`. For Unbounded Reference Space you can use `XRT_INPUT_GENERIC_UNBOUNDED_SPACE_POSE` to get the origin of that space.
[in]	at_timestamp_ns	If the device can predict or has a history of positions, this is when the caller wants the pose to be from.
[out]	out_relation	The relation read from the device.

See also: xrt_input_name

References get_tracked_pose, and name.

Referenced by u_device_get_view_poses().

◆ xrt_device_get_view_poses()

static void xrt_device_get_view_poses	(	struct xrt_device *	xdev,
		const struct xrt_vec3 *	default_eye_relation,
		uint64_t	at_timestamp_ns,
		uint32_t	view_count,
		struct xrt_space_relation *	out_head_relation,
		struct xrt_fov *	out_fovs,
		struct xrt_pose *	out_poses
	)

inline

Helper function for xrt_device::get_view_poses.

Get the per-view pose in relation to the view space. On most devices with coplanar displays and no built-in eye tracking or IPD sensing, this just calls a helper to process the provided eye relation, but this may also handle canted displays as well as eye tracking.

Incorporates a call to xrt_device::get_tracked_pose or a wrapper for it

Parameters

[in]	xdev	The device.
[in]	default_eye_relation	The interpupillary relation as a 3D position. Most simple stereo devices would just want to set `out_pose->position.[x\|y\|z] = ipd.[x\|y\|z] / 2.0f` and adjust for left vs right view. Not to be confused with IPD that is absolute distance, this is a full 3D translation If a device has a more accurate/dynamic way of knowing the eye relation, it may ignore this input.
[in]	at_timestamp_ns	This is when the caller wants the poses and FOVs to be from.
[in]	view_count	Number of views.
[out]	out_head_relation	The head pose in the device tracking space. Combine with `out_poses` to get the views in device tracking space.
[out]	out_fovs	An array (of size `view_count` ) to populate with the device-suggested fields of view.
[out]	out_poses	An array (of size `view_count` ) to populate with view output poses in head space. When implementing, be sure to also set orientation: most likely identity orientation unless you have canted screens. (Caution: Even if you have eye tracking, you won't use eye orientation here!)

References get_view_poses.

◆ xrt_device_get_visibility_mask()

static xrt_result_t xrt_device_get_visibility_mask	(	struct xrt_device *	xdev,
		enum xrt_visibility_mask_type	type,
		uint32_t	view_index,
		struct xrt_visibility_mask **	out_mask
	)

inline

Helper function for xrt_device::get_visibility_mask.

Get the visibility mask for this device.

Parameters

[in]	xdev	The device.
[in]	type	The type of visibility mask.
[in]	view_index	The index of the view to get the mask for.
[out]	out_mask	Output mask, caller must free.

◆ xrt_device_is_form_factor_available()

static bool xrt_device_is_form_factor_available	(	struct xrt_device *	xdev,
		enum xrt_form_factor	form_factor
	)

inline

Helper function for xrt_device::is_form_factor_available.

Check if given form factor is available or not. This should only be used in HMD device, if the device driver supports form factor check.

Parameters

[in]	xdev	The device.
[in]	form_factor	Form factor to check.

Returns: true if given form factor is available; otherwise false.

References is_form_factor_available.

◆ xrt_device_ref_space_usage()

static xrt_result_t xrt_device_ref_space_usage	(	struct xrt_device *	xdev,
		enum xrt_reference_space_type	type,
		enum xrt_input_name	name,
		bool	used
	)

inline

Helper function for xrt_device::ref_space_usage.

Called by the xrt_space_overseer when a reference space that is implemented by this device is first used, or when the last usage of the reference space stops. What is provided is both the xrt_reference_space_type that triggered the usage change and the xrt_input_name (if any) that is used to drive the space.

See also: xrt_space_overseer_ref_space_inc; xrt_space_overseer_ref_space_dec; xrt_input_name; xrt_reference_space_type

◆ xrt_device_set_output()

static void xrt_device_set_output	(	struct xrt_device *	xdev,
		enum xrt_output_name	name,
		const union xrt_output_value *	value
	)

inline

Helper function for xrt_device::set_output.

Set a output value.

Parameters

[in]	xdev	The device.
[in]	name	The output component name to set.
[in]	value	The value to set the output to.

See also: xrt_output_name

References name, and set_output.

◆ xrt_device_update_inputs()

static void xrt_device_update_inputs ( struct xrt_device * xdev )

inline

Helper function for xrt_device::update_inputs.

Update any attached inputs.

Parameters

[in] xdev The device.

References update_inputs.

Field Documentation

◆ binding_profile_count

size_t xrt_device::binding_profile_count

Number of bindings in xrt_device::binding_profiles.

◆ compute_distortion

bool(* xrt_device::compute_distortion) (struct xrt_device *xdev, uint32_t view, float u, float v, struct xrt_uv_triplet *out_result)

Compute the distortion at a single point.

The input is u v in screen/output space (that is, predistorted), you are to compute and return the u,v coordinates to sample the render texture. The compositor will step through a range of u,v parameters to build the lookup (vertex attribute or distortion texture) used to pre-distort the image as required by the device's optics.

Parameters

	xdev	the device
	view	the view index
	u	horizontal texture coordinate
	v	vertical texture coordinate
[out]	out_result	corresponding u,v pairs for all three color channels.

Referenced by CDeviceDriver_Monado::ComputeDistortion(), and xrt_device_compute_distortion().

◆ destroy

void(* xrt_device::destroy) (struct xrt_device *xdev)

Destroy device.

◆ get_face_tracking

xrt_result_t(* xrt_device::get_face_tracking) (struct xrt_device *xdev, enum xrt_input_name facial_expression_type, struct xrt_facial_expression_set *out_value)

Get the requested blend shape properties & weights for a face tracker.

Parameters

[in]	xdev	The device.
[in]	facial_expression_type	The facial expression data type (XR_FB_face_tracking, XR_HTC_facial_tracking, etc).
[in]	out_value	Set of requested expression weights & blend shape properties.

See also: xrt_input_name

Referenced by xrt_device_get_face_tracking().

◆ get_hand_tracking

void(* xrt_device::get_hand_tracking) (struct xrt_device *xdev, enum xrt_input_name name, uint64_t desired_timestamp_ns, struct xrt_hand_joint_set *out_value, uint64_t *out_timestamp_ns)

Get relationship of hand joints to the tracking origin space as the base space.

It is the responsibility of the device driver to either do prediction or return joints from a previous time and write that time out to out_timestamp_ns.

The timestamps are system monotonic timestamps, such as returned by os_monotonic_get_ns().

Parameters

[in]	xdev	The device.
[in]	name	Some devices may have multiple poses on them, select the one using this field. For hand tracking use `XRT_INPUT_GENERIC_HAND_TRACKING_DEFAULT_SET`.
[in]	desired_timestamp_ns	If the device can predict or has a history of positions, this is when the caller wants the pose to be from.
[out]	out_value	The hand joint data read from the device.
[out]	out_timestamp_ns	The timestamp of the data being returned.

See also: xrt_input_name

Referenced by xrt_device_get_hand_tracking().

◆ get_tracked_pose

void(* xrt_device::get_tracked_pose) (struct xrt_device *xdev, enum xrt_input_name name, uint64_t at_timestamp_ns, struct xrt_space_relation *out_relation)

Get relationship of a tracked device to the tracking origin space as the base space.

It is the responsibility of the device driver to do any prediction, there are helper functions available for this.

The timestamps are system monotonic timestamps, such as returned by os_monotonic_get_ns().

Parameters

[in]	xdev	The device.
[in]	name	Some devices may have multiple poses on them, select the one using this field. For HMDs use `XRT_INPUT_GENERIC_HEAD_POSE`. For Unbounded Reference Space you can use `XRT_INPUT_GENERIC_UNBOUNDED_SPACE_POSE` to get the origin of that space.
[in]	at_timestamp_ns	If the device can predict or has a history of positions, this is when the caller wants the pose to be from.
[out]	out_relation	The relation read from the device.

See also: xrt_input_name

Referenced by multi_create_tracking_override(), and xrt_device_get_tracked_pose().

◆ get_view_poses

void(* xrt_device::get_view_poses) (struct xrt_device *xdev, const struct xrt_vec3 *default_eye_relation, uint64_t at_timestamp_ns, uint32_t view_count, struct xrt_space_relation *out_head_relation, struct xrt_fov *out_fovs, struct xrt_pose *out_poses)

Get the per-view pose in relation to the view space.

On most devices with coplanar displays and no built-in eye tracking or IPD sensing, this just calls a helper to process the provided eye relation, but this may also handle canted displays as well as eye tracking.

Incorporates a call to xrt_device::get_tracked_pose or a wrapper for it

Parameters

[in]	xdev	The device.
[in]	default_eye_relation	The interpupillary relation as a 3D position. Most simple stereo devices would just want to set `out_pose->position.[x\|y\|z] = ipd.[x\|y\|z] / 2.0f` and adjust for left vs right view. Not to be confused with IPD that is absolute distance, this is a full 3D translation If a device has a more accurate/dynamic way of knowing the eye relation, it may ignore this input.
[in]	at_timestamp_ns	This is when the caller wants the poses and FOVs to be from.
[in]	view_count	Number of views.
[out]	out_head_relation	The head pose in the device tracking space. Combine with `out_poses` to get the views in device tracking space.
[out]	out_fovs	An array (of size `view_count` ) to populate with the device-suggested fields of view.
[out]	out_poses	An array (of size `view_count` ) to populate with view output poses in head space. When implementing, be sure to also set orientation: most likely identity orientation unless you have canted screens. (Caution: Even if you have eye tracking, you won't use eye orientation here!)

Referenced by xrt_device_get_view_poses().

◆ get_visibility_mask

xrt_result_t(* xrt_device::get_visibility_mask) (struct xrt_device *xdev, enum xrt_visibility_mask_type type, uint32_t view_index, struct xrt_visibility_mask **out_mask)

Get the visibility mask for this device.

Parameters

[in]	xdev	The device.
[in]	type	The type of visibility mask.
[in]	view_index	The index of the view to get the mask for.
[out]	out_mask	Output mask, caller must free.

◆ hmd

struct xrt_hmd_parts* xrt_device::hmd

Null if this device does not interface with the users head.

Referenced by CDeviceDriver_Monado::CDeviceDriver_Monado(), comp_settings_init(), CDeviceDriver_Monado::ComputeDistortion(), render_resources::render_resources_init(), sdl_device_init(), steamvr_lh_get_devices(), u_device_free(), u_device_get_view_poses(), u_device_setup_one_eye(), u_device_setup_split_side_by_side(), u_distortion_mesh_fill_in_none(), u_distortion_mesh_set_none(), and u_extents_2d_split_side_by_side().

◆ input_count

size_t xrt_device::input_count

Number of inputs.

Referenced by create_controller(), oxr_xdev_find_input(), sdl_device_init(), and u_system_devices_get_ht_device().

◆ inputs

struct xrt_input* xrt_device::inputs

Array of input structs.

Referenced by oxr_xdev_find_input(), sdl_device_init(), and u_system_devices_get_ht_device().

◆ is_form_factor_available

bool(* xrt_device::is_form_factor_available) (struct xrt_device *xdev, enum xrt_form_factor form_factor)

Check if given form factor is available or not.

This should only be used in HMD device, if the device driver supports form factor check.

Parameters

[in]	xdev	The device.
[in]	form_factor	Form factor to check.

Returns: true if given form factor is available; otherwise false.

Referenced by xrt_device_is_form_factor_available().

◆ name

enum xrt_device_name xrt_device::name

◆ output_count

size_t xrt_device::output_count

Number of outputs.

Referenced by create_controller(), and oxr_xdev_find_output().

◆ outputs

struct xrt_output* xrt_device::outputs

Array of output structs.

Referenced by oxr_xdev_find_output().

◆ ref_space_usage

xrt_result_t(* xrt_device::ref_space_usage) (struct xrt_device *xdev, enum xrt_reference_space_type type, enum xrt_input_name name, bool used)

Called by the xrt_space_overseer when a reference space that is implemented by this device is first used, or when the last usage of the reference space stops.

What is provided is both the xrt_reference_space_type that triggered the usage change and the xrt_input_name (if any) that is used to drive the space.

See also: xrt_space_overseer_ref_space_inc; xrt_space_overseer_ref_space_dec; xrt_input_name; xrt_reference_space_type

◆ serial

char xrt_device::serial[256]

A unique identifier. Persistent across configurations, if possible.

◆ set_output

void(* xrt_device::set_output) (struct xrt_device *xdev, enum xrt_output_name name, const union xrt_output_value *value)

Set a output value.

Parameters

[in]	xdev	The device.
[in]	name	The output component name to set.
[in]	value	The value to set the output to.

See also: xrt_output_name

Referenced by xrt_device_set_output().

◆ str

char xrt_device::str[256]

A string describing the device.

◆ tracking_origin

struct xrt_tracking_origin* xrt_device::tracking_origin

Always set, pointing to the tracking system for this device.

Referenced by CDeviceDriver_Monado::GetPose(), multi_create_tracking_override(), sdl_device_init(), and u_builder_setup_tracking_origins().

◆ update_inputs

void(* xrt_device::update_inputs) (struct xrt_device *xdev)

Update any attached inputs.

Parameters

[in] xdev The device.

Implemented in Device.

Referenced by xrt_device_update_inputs().

The documentation for this interface was generated from the following files:

xrt/xrt_device.h
auxiliary/util/u_distortion_mesh.h

Public Member Functions

Data Fields

Related Functions

Detailed Description

Member Function Documentation

◆ xrt_device_compute_distortion()

◆ xrt_device_destroy()

◆ xrt_device_get_face_tracking()

◆ xrt_device_get_hand_tracking()

◆ xrt_device_get_tracked_pose()

◆ xrt_device_get_view_poses()

◆ xrt_device_get_visibility_mask()

◆ xrt_device_is_form_factor_available()

◆ xrt_device_ref_space_usage()

◆ xrt_device_set_output()

◆ xrt_device_update_inputs()

Field Documentation

◆ binding_profile_count

◆ compute_distortion

◆ destroy

◆ get_face_tracking

◆ get_hand_tracking

◆ get_tracked_pose

◆ get_view_poses

◆ get_visibility_mask

◆ hmd

◆ input_count

◆ inputs

◆ is_form_factor_available

◆ name

◆ output_count

◆ outputs

◆ ref_space_usage

◆ serial

◆ set_output

◆ str

◆ tracking_origin

◆ update_inputs