Interface of libmonado. More...

#include <stdint.h>
#include <stdbool.h>

Include dependency graph for monado.h:

Data Structures
struct	mnd_pose
	A pose composed of a position and orientation. More...

Macros
#define	MND_API_VERSION_MAJOR 1
	Major version of the API. More...

#define	MND_API_VERSION_MINOR 4
	Minor version of the API. More...

#define	MND_API_VERSION_PATCH 0
	Patch version of the API. More...

Typedefs
typedef enum mnd_result	mnd_result_t
	Result codes for operations, negative are errors, zero or positives are success. More...

typedef enum mnd_client_flags	mnd_client_flags_t
	Bitflags for client application state. More...

typedef enum mnd_property	mnd_property_t
	A property to get from a thing (currently only devices). More...

typedef struct mnd_root	mnd_root_t
	Opaque type for libmonado state. More...

typedef struct mnd_pose	mnd_pose_t
	A pose composed of a position and orientation. More...

typedef enum mnd_reference_space_type	mnd_reference_space_type_t
	Types of reference space. More...

Enumerations
enum	mnd_result { MND_SUCCESS = 0 , MND_ERROR_INVALID_VERSION = -1 , MND_ERROR_INVALID_VALUE = -2 , MND_ERROR_CONNECTING_FAILED = -3 , MND_ERROR_OPERATION_FAILED = -4 , MND_ERROR_RECENTERING_NOT_SUPPORTED = -5 , MND_ERROR_INVALID_PROPERTY = -6 , MND_ERROR_INVALID_OPERATION = -7 }
	Result codes for operations, negative are errors, zero or positives are success. More...

enum	mnd_client_flags { MND_CLIENT_PRIMARY_APP = (1u << 0u) , MND_CLIENT_SESSION_ACTIVE = (1u << 1u) , MND_CLIENT_SESSION_VISIBLE = (1u << 2u) , MND_CLIENT_SESSION_FOCUSED = (1u << 3u) , MND_CLIENT_SESSION_OVERLAY = (1u << 4u) , MND_CLIENT_IO_ACTIVE = (1u << 5u) }
	Bitflags for client application state. More...

enum	mnd_property { MND_PROPERTY_NAME_STRING = 0 , MND_PROPERTY_SERIAL_STRING = 1 , MND_PROPERTY_TRACKING_ORIGIN_U32 = 2 , MND_PROPERTY_SUPPORTS_POSITION_BOOL = 3 , MND_PROPERTY_SUPPORTS_ORIENTATION_BOOL = 4 }
	A property to get from a thing (currently only devices). More...

enum	mnd_reference_space_type { MND_SPACE_REFERENCE_TYPE_VIEW , MND_SPACE_REFERENCE_TYPE_LOCAL , MND_SPACE_REFERENCE_TYPE_LOCAL_FLOOR , MND_SPACE_REFERENCE_TYPE_STAGE , MND_SPACE_REFERENCE_TYPE_UNBOUNDED }
	Types of reference space. More...

Functions
void	mnd_api_get_version (uint32_t out_major, uint32_t out_minor, uint32_t *out_patch)
	Returns the version of the API (not Monado itself), follows the versioning semantics of https://semver.org/ standard. More...

mnd_result_t	mnd_root_create (mnd_root_t **out_root)
	Create libmonado state and connect to service. More...

void	mnd_root_destroy (mnd_root_t **root_ptr)
	Destroy libmonado state, disconnecting from the service, and zeroing the pointer. More...

mnd_result_t	mnd_root_update_client_list (mnd_root_t *root)
	Update our local cached copy of the client list. More...

mnd_result_t	mnd_root_get_number_clients (mnd_root_t root, uint32_t out_num)
	Get the number of active clients. More...

mnd_result_t	mnd_root_get_client_id_at_index (mnd_root_t root, uint32_t index, uint32_t out_client_id)
	Get the id from the current client list. More...

mnd_result_t	mnd_root_get_client_name (mnd_root_t root, uint32_t client_id, const char *out_name)
	Get the name of the client at the given index. More...

mnd_result_t	mnd_root_get_client_state (mnd_root_t root, uint32_t client_id, uint32_t out_flags)
	Get the state flags of the client at the given index. More...

mnd_result_t	mnd_root_set_client_primary (mnd_root_t *root, uint32_t client_id)
	Set the client at the given index as "primary". More...

mnd_result_t	mnd_root_set_client_focused (mnd_root_t *root, uint32_t client_id)
	Set the client at the given index as "focused". More...

mnd_result_t	mnd_root_toggle_client_io_active (mnd_root_t *root, uint32_t client_id)
	Toggle io activity for the client at the given index. More...

mnd_result_t	mnd_root_get_device_count (mnd_root_t root, uint32_t out_device_count)
	Get the number of devices. More...

mnd_result_t	mnd_root_get_device_info_bool (mnd_root_t root, uint32_t device_index, mnd_property_t prop, bool out_bool)
	Get boolean property for the device at the given index. More...

mnd_result_t	mnd_root_get_device_info_i32 (mnd_root_t root, uint32_t device_index, mnd_property_t prop, uint32_t out_i32)
	Get int32_t property for the device at the given index. More...

mnd_result_t	mnd_root_get_device_info_u32 (mnd_root_t root, uint32_t device_index, mnd_property_t prop, uint32_t out_u32)
	Get uint32_t property for the device at the given index. More...

mnd_result_t	mnd_root_get_device_info_float (mnd_root_t root, uint32_t device_index, mnd_property_t prop, float out_float)
	Get float property for the device at the given index. More...

mnd_result_t	mnd_root_get_device_info_string (mnd_root_t root, uint32_t device_index, mnd_property_t prop, const char *out_string)
	Get string property for the device at the given index. More...

mnd_result_t	mnd_root_get_device_info (mnd_root_t root, uint32_t device_index, uint32_t out_device_id, const char **out_dev_name)
	Get device info at the given index. More...

mnd_result_t	mnd_root_get_device_from_role (mnd_root_t root, const char role_name, int32_t *out_index)
	Get the device index associated for a given role name. More...

mnd_result_t	mnd_root_recenter_local_spaces (mnd_root_t *root)
	Trigger a recenter of the local spaces. More...

mnd_result_t	mnd_root_get_reference_space_offset (mnd_root_t root, mnd_reference_space_type_t type, mnd_pose_t out_offset)
	Get the current offset value of the specified reference space. More...

mnd_result_t	mnd_root_set_reference_space_offset (mnd_root_t root, mnd_reference_space_type_t type, const mnd_pose_t offset)
	Apply an offset to the specified reference space. More...

mnd_result_t	mnd_root_get_tracking_origin_offset (mnd_root_t root, uint32_t origin_id, mnd_pose_t out_offset)
	Read the current offset of a tracking origin. More...

mnd_result_t	mnd_root_set_tracking_origin_offset (mnd_root_t root, uint32_t origin_id, const mnd_pose_t offset)
	Apply an offset to the specified tracking origin. More...

mnd_result_t	mnd_root_get_tracking_origin_count (mnd_root_t root, uint32_t out_track_count)
	Retrieve the number of tracking origins available. More...

mnd_result_t	mnd_root_get_tracking_origin_name (mnd_root_t root, uint32_t origin_id, const char *out_string)
	Retrieve the name of the indicated tracking origin. More...

mnd_result_t	mnd_root_get_device_battery_status (mnd_root_t root, uint32_t device_index, bool out_present, bool out_charging, float out_charge)
	Get battery status of a device. More...

Detailed Description

Interface of libmonado.

Author: Jakob Bornecrantz jakob.nosp@m.@col.nosp@m.labor.nosp@m.a.co.nosp@m.m; Rylie Pavlik rylie.nosp@m..pav.nosp@m.lik@c.nosp@m.olla.nosp@m.bora..nosp@m.com

Macro Definition Documentation

◆ MND_API_VERSION_MAJOR

#define MND_API_VERSION_MAJOR 1

Major version of the API.

◆ MND_API_VERSION_MINOR

#define MND_API_VERSION_MINOR 4

Minor version of the API.

◆ MND_API_VERSION_PATCH

#define MND_API_VERSION_PATCH 0

Patch version of the API.

Typedef Documentation

◆ mnd_client_flags_t

typedef enum mnd_client_flags mnd_client_flags_t

Bitflags for client application state.

◆ mnd_pose_t

typedef struct mnd_pose mnd_pose_t

A pose composed of a position and orientation.

◆ mnd_property_t

typedef enum mnd_property mnd_property_t

A property to get from a thing (currently only devices).

Supported in version 1.2 and above.

◆ mnd_reference_space_type_t

typedef enum mnd_reference_space_type mnd_reference_space_type_t

Types of reference space.

◆ mnd_result_t

typedef enum mnd_result mnd_result_t

Result codes for operations, negative are errors, zero or positives are success.

◆ mnd_root_t

typedef struct mnd_root mnd_root_t

Opaque type for libmonado state.

Enumeration Type Documentation

◆ mnd_client_flags

enum mnd_client_flags

Bitflags for client application state.

◆ mnd_property

enum mnd_property

A property to get from a thing (currently only devices).

Supported in version 1.2 and above.

Enumerator
MND_PROPERTY_NAME_STRING	Supported in version 1.2 and above.
MND_PROPERTY_SERIAL_STRING	Supported in version 1.2 and above.
MND_PROPERTY_TRACKING_ORIGIN_U32	Supported in version 1.4.0 and above.
MND_PROPERTY_SUPPORTS_POSITION_BOOL	Supported in version 1.4.0 and above.
MND_PROPERTY_SUPPORTS_ORIENTATION_BOOL	Supported in version 1.4.0 and above.

◆ mnd_reference_space_type

enum mnd_reference_space_type

Types of reference space.

◆ mnd_result

enum mnd_result

Result codes for operations, negative are errors, zero or positives are success.

Enumerator
MND_ERROR_RECENTERING_NOT_SUPPORTED	Supported in version 1.1 and above.
MND_ERROR_INVALID_PROPERTY	Supported in version 1.2 and above.
MND_ERROR_INVALID_OPERATION	Supported in version 1.3 and above.

Function Documentation

◆ mnd_api_get_version()

void mnd_api_get_version	(	uint32_t *	out_major,
		uint32_t *	out_minor,
		uint32_t *	out_patch
	)

Returns the version of the API (not Monado itself), follows the versioning semantics of https://semver.org/ standard.

In short if the major version mismatch then the interface is incompatible.

Parameters

[out]	out_major	Major version number, must be valid pointer.
[out]	out_minor	Minor version number, must be valid pointer.
[out]	out_patch	Patch version number, must be valid pointer.

Always succeeds, or crashes if any pointer isn't valid.

References MND_API_VERSION_MAJOR, MND_API_VERSION_MINOR, and MND_API_VERSION_PATCH.

◆ mnd_root_create()

mnd_result_t mnd_root_create ( mnd_root_t ** out_root )

Create libmonado state and connect to service.

Parameters

[out] out_root Address to populate with the opaque state type.

Returns: MND_SUCCESS on success

◆ mnd_root_destroy()

void mnd_root_destroy ( mnd_root_t ** root_ptr )

Destroy libmonado state, disconnecting from the service, and zeroing the pointer.

Parameters

root_ptr Pointer to your libmonado state. Null-checked, will be set to null.

References ipc_client_connection_fini().

◆ mnd_root_get_client_id_at_index()

mnd_result_t mnd_root_get_client_id_at_index	(	mnd_root_t *	root,
		uint32_t	index,
		uint32_t *	out_client_id
	)

Get the id from the current client list.

Parameters

	root	The libmonado state.
	index	Index to retrieve id for.
[out]	out_client_id	Pointer to value to populate with the id at the given index.

◆ mnd_root_get_client_name()

mnd_result_t mnd_root_get_client_name	(	mnd_root_t *	root,
		uint32_t	client_id,
		const char **	out_name
	)

Get the name of the client at the given index.

The string returned is only valid until the next call into libmonado.

Parameters

	root	The libmonado state.
	client_id	ID of client to retrieve name from.
[out]	out_name	Pointer to populate with the client name.

Precondition: Called mnd_root_update_client_list at least once

Returns: MND_SUCCESS on success

◆ mnd_root_get_client_state()

mnd_result_t mnd_root_get_client_state	(	mnd_root_t *	root,
		uint32_t	client_id,
		uint32_t *	out_flags
	)

Get the state flags of the client at the given index.

This result only changes on calls to mnd_root_update_client_list

Parameters

	root	The libmonado state.
	client_id	ID of client to retrieve flags from.
[out]	out_flags	Pointer to populate with the flags, a bitwise combination of mnd_client_flags.

Precondition: Called mnd_root_update_client_list at least once

Returns: MND_SUCCESS on success

◆ mnd_root_get_device_battery_status()

mnd_result_t mnd_root_get_device_battery_status	(	mnd_root_t *	root,
		uint32_t	device_index,
		bool *	out_present,
		bool *	out_charging,
		float *	out_charge
	)

Get battery status of a device.

Parameters

	root	The libmonado state.
	device_index	Index of device to retrieve battery info from.
[out]	out_present	Pointer to value to populate with whether the device provides battery status info.
[out]	out_charging	Pointer to value to populate with whether the device is currently being charged.
[out]	out_charge	Pointer to value to populate with the battery charge as a value between 0 and 1.

Returns: MND_SUCCESS on success

◆ mnd_root_get_device_count()

mnd_result_t mnd_root_get_device_count	(	mnd_root_t *	root,
		uint32_t *	out_device_count
	)

Get the number of devices.

Parameters

	root	The libmonado state.
[out]	out_device_count	Pointer to value to populate with the number of devices.

Returns: MND_SUCCESS on success

◆ mnd_root_get_device_from_role()

mnd_result_t mnd_root_get_device_from_role	(	mnd_root_t *	root,
		const char *	role_name,
		int32_t *	out_index
	)

Get the device index associated for a given role name.

Parameters

	root	The libmonado state.
	role_name	Name of the role, one-of: "head", "left", "right", "gamepad", "eyes", "hand-tracking-left", and, "hand-tracking-right":
[out]	out_index	Pointer to value to populate with the device index associated with given role name, -1 if not role is set.

Returns: MND_SUCCESS on success

◆ mnd_root_get_device_info()

mnd_result_t mnd_root_get_device_info	(	mnd_root_t *	root,
		uint32_t	device_index,
		uint32_t *	out_device_id,
		const char **	out_dev_name
	)

Get device info at the given index.

Deprecated:: Deprecated in version 1.2, scheduled for removal in version 2.0.0 currently.

Parameters

	root	The libmonado state.
	device_index	Index of device to retrieve name from.
[out]	out_device_id	Pointer to value to populate with the device id at the given index.
[out]	out_dev_name	Pointer to populate with the device name.

Returns: MND_SUCCESS on success

◆ mnd_root_get_device_info_bool()

mnd_result_t mnd_root_get_device_info_bool	(	mnd_root_t *	root,
		uint32_t	device_index,
		mnd_property_t	prop,
		bool *	out_bool
	)

Get boolean property for the device at the given index.

Supported in version 1.2 and above.

Parameters

	root	The libmonado state.
	device_index	Index of device to retrieve name from.
	prop	A boolean property enum.
[out]	out_bool	Pointer to populate with the boolean.

Returns: MND_SUCCESS on success

◆ mnd_root_get_device_info_float()

mnd_result_t mnd_root_get_device_info_float	(	mnd_root_t *	root,
		uint32_t	device_index,
		mnd_property_t	prop,
		float *	out_float
	)

Get float property for the device at the given index.

Supported in version 1.2 and above.

Parameters

	root	The libmonado state.
	device_index	Index of device to retrieve name from.
	prop	A float property enum.
[out]	out_float	Pointer to populate with the float.

Returns: MND_SUCCESS on success

◆ mnd_root_get_device_info_i32()

mnd_result_t mnd_root_get_device_info_i32	(	mnd_root_t *	root,
		uint32_t	device_index,
		mnd_property_t	prop,
		uint32_t *	out_i32
	)

Get int32_t property for the device at the given index.

Supported in version 1.2 and above.

Parameters

	root	The libmonado state.
	device_index	Index of device to retrieve name from.
	prop	A int32_t property enum.
[out]	out_i32	Pointer to populate with the int32_t.

Returns: MND_SUCCESS on success

◆ mnd_root_get_device_info_string()

mnd_result_t mnd_root_get_device_info_string	(	mnd_root_t *	root,
		uint32_t	device_index,
		mnd_property_t	prop,
		const char **	out_string
	)

Get string property for the device at the given index.

Supported in version 1.2 and above.

Parameters

	root	The libmonado state.
	device_index	Index of device to retrieve name from.
	prop	A string property enum.
[out]	out_string	Pointer to populate with the string.

Returns: MND_SUCCESS on success

◆ mnd_root_get_device_info_u32()

mnd_result_t mnd_root_get_device_info_u32	(	mnd_root_t *	root,
		uint32_t	device_index,
		mnd_property_t	prop,
		uint32_t *	out_u32
	)

Get uint32_t property for the device at the given index.

Supported in version 1.2 and above.

Parameters

	root	The libmonado state.
	device_index	Index of device to retrieve name from.
	prop	A uint32_t property enum.
[out]	out_u32	Pointer to populate with the uint32_t.

Returns: MND_SUCCESS on success

◆ mnd_root_get_number_clients()

mnd_result_t mnd_root_get_number_clients	(	mnd_root_t *	root,
		uint32_t *	out_num
	)

Get the number of active clients.

This value only changes on calls to mnd_root_update_client_list

Parameters

	root	The libmonado state.
[out]	out_num	Pointer to value to populate with the number of clients.

Precondition: Called mnd_root_update_client_list at least once

Returns: MND_SUCCESS on success

◆ mnd_root_get_reference_space_offset()

mnd_result_t mnd_root_get_reference_space_offset	(	mnd_root_t *	root,
		mnd_reference_space_type_t	type,
		mnd_pose_t *	out_offset
	)

Get the current offset value of the specified reference space.

Supported in version 1.3 and above.

Parameters

root	The libmonado state.
type	The reference space.
offset	A pointer to where the offset should be written.

Returns: MND_SUCCESS on success

◆ mnd_root_get_tracking_origin_count()

mnd_result_t mnd_root_get_tracking_origin_count	(	mnd_root_t *	root,
		uint32_t *	out_track_count
	)

Retrieve the number of tracking origins available.

Supported in version 1.3 and above.

Parameters

root	The libmonado state.
out_track_count	Pointer to where the count should be written.

Returns: MND_SUCCESS on success

◆ mnd_root_get_tracking_origin_name()

mnd_result_t mnd_root_get_tracking_origin_name	(	mnd_root_t *	root,
		uint32_t	origin_id,
		const char **	out_string
	)

Retrieve the name of the indicated tracking origin.

Supported in version 1.3 and above.

Parameters

root	The libmonado state.
origin_id	The ID of a tracking origin.
out_string	The pointer to write the name's pointer to.

Returns: MND_SUCCESS on success

◆ mnd_root_get_tracking_origin_offset()

mnd_result_t mnd_root_get_tracking_origin_offset	(	mnd_root_t *	root,
		uint32_t	origin_id,
		mnd_pose_t *	out_offset
	)

Read the current offset of a tracking origin.

Supported in version 1.3 and above.

Parameters

root	The libmonado state.
origin_id	The ID of the tracking origin.
offset	A pointer to where the offset should be written.

Returns: MND_SUCCESS on success

References XRT_SUCCESS.

◆ mnd_root_recenter_local_spaces()

mnd_result_t mnd_root_recenter_local_spaces ( mnd_root_t * root )

Trigger a recenter of the local spaces.

Supported in version 1.1 and above.

Parameters

root	The libmonado state.

Returns: MND_SUCCESS on success

References XRT_SUCCESS.

◆ mnd_root_set_client_focused()

mnd_result_t mnd_root_set_client_focused	(	mnd_root_t *	root,
		uint32_t	client_id
	)

Set the client at the given index as "focused".

Parameters

root	The libmonado state.
client_id	ID of the client set as focused.

Precondition: Called mnd_root_update_client_list at least once

Returns: MND_SUCCESS on success

◆ mnd_root_set_client_primary()

mnd_result_t mnd_root_set_client_primary	(	mnd_root_t *	root,
		uint32_t	client_id
	)

Set the client at the given index as "primary".

Parameters

root	The libmonado state.
client_id	ID of the client set as primary.

Precondition: Called mnd_root_update_client_list at least once

Returns: MND_SUCCESS on success

◆ mnd_root_set_reference_space_offset()

mnd_result_t mnd_root_set_reference_space_offset	(	mnd_root_t *	root,
		mnd_reference_space_type_t	type,
		const mnd_pose_t *	offset
	)

Apply an offset to the specified reference space.

Supported in version 1.3 and above.

Parameters

root	The libmonado state.
type	The reference space.
offset	A pointer to valid xrt_pose.

Returns: MND_SUCCESS on success

◆ mnd_root_set_tracking_origin_offset()

mnd_result_t mnd_root_set_tracking_origin_offset	(	mnd_root_t *	root,
		uint32_t	origin_id,
		const mnd_pose_t *	offset
	)

Apply an offset to the specified tracking origin.

Supported in version 1.3 and above.

Parameters

root	The libmonado state.
origin_id	The ID of the tracking origin.
offset	A pointer to valid xrt_pose.

Returns: MND_SUCCESS on success

References XRT_SUCCESS.

◆ mnd_root_toggle_client_io_active()

mnd_result_t mnd_root_toggle_client_io_active	(	mnd_root_t *	root,
		uint32_t	client_id
	)

Toggle io activity for the client at the given index.

Parameters

root	The libmonado state.
client_id	ID of the client to toggle IO for.

Precondition: Called mnd_root_update_client_list at least once

Returns: MND_SUCCESS on success

◆ mnd_root_update_client_list()

mnd_result_t mnd_root_update_client_list ( mnd_root_t * root )

Update our local cached copy of the client list.

Parameters

root	The libmonado state.

Returns: MND_SUCCESS on success

Data Structures

Macros

Typedefs

Enumerations

Functions

Detailed Description

Macro Definition Documentation

◆ MND_API_VERSION_MAJOR

◆ MND_API_VERSION_MINOR

◆ MND_API_VERSION_PATCH

Typedef Documentation

◆ mnd_client_flags_t

◆ mnd_pose_t

◆ mnd_property_t

◆ mnd_reference_space_type_t

◆ mnd_result_t

◆ mnd_root_t

Enumeration Type Documentation

◆ mnd_client_flags

◆ mnd_property

◆ mnd_reference_space_type

◆ mnd_result

Function Documentation

◆ mnd_api_get_version()

◆ mnd_root_create()

◆ mnd_root_destroy()

◆ mnd_root_get_client_id_at_index()

◆ mnd_root_get_client_name()

◆ mnd_root_get_client_state()

◆ mnd_root_get_device_battery_status()

◆ mnd_root_get_device_count()

◆ mnd_root_get_device_from_role()

◆ mnd_root_get_device_info()

◆ mnd_root_get_device_info_bool()

◆ mnd_root_get_device_info_float()

◆ mnd_root_get_device_info_i32()

◆ mnd_root_get_device_info_string()

◆ mnd_root_get_device_info_u32()

◆ mnd_root_get_number_clients()

◆ mnd_root_get_reference_space_offset()

◆ mnd_root_get_tracking_origin_count()

◆ mnd_root_get_tracking_origin_name()

◆ mnd_root_get_tracking_origin_offset()

◆ mnd_root_recenter_local_spaces()

◆ mnd_root_set_client_focused()

◆ mnd_root_set_client_primary()

◆ mnd_root_set_reference_space_offset()

◆ mnd_root_set_tracking_origin_offset()

◆ mnd_root_toggle_client_io_active()

◆ mnd_root_update_client_list()