Implementation of libmonado. More...

#include "monado.h"
#include "xrt/xrt_defines.h"
#include "xrt/xrt_results.h"
#include "util/u_misc.h"
#include "util/u_file.h"
#include "util/u_logging.h"
#include "shared/ipc_protocol.h"
#include "client/ipc_client_connection.h"
#include "client/ipc_client.h"
#include "ipc_client_generated.h"
#include <limits.h>
#include <stdint.h>
#include <assert.h>

Include dependency graph for monado.c:

Data Structures
struct	mnd_root

Macros
#define	P(...) fprintf(stdout, __VA_ARGS__)

#define	PE(...) fprintf(stderr, __VA_ARGS__)

#define	CHECK_NOT_NULL(ARG)

#define	CHECK_CLIENT_ID(ID)

#define	CHECK_CLIENT_INDEX(INDEX)

#define	CHECK_DEVICE_INDEX(INDEX)

#define	TO_ENUM(STRING, ENUM)

#define	CASE_ROLE_HAND(UC_SRC, SRC)

Enumerations
enum	role_enum { ROLE_HEAD , ROLE_EYES , ROLE_LEFT , ROLE_RIGHT , ROLE_GAMEPAD , ROLE_HAND_UNOBSTRUCTED_LEFT , ROLE_HAND_UNOBSTRUCTED_RIGHT , ROLE_HAND_CONFORMING_LEFT , ROLE_HAND_CONFORMING_RIGHT }

Functions
static int	get_client_info (mnd_root_t *root, uint32_t client_id)

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

mnd_result_t	mnd_root_get_device_brightness (mnd_root_t root, uint32_t device_index, float out_brightness)
	Get current brightness of a display device. More...

mnd_result_t	mnd_root_set_device_brightness (mnd_root_t *root, uint32_t device_index, float brightness, bool relative)
	Set the display brightness. More...

Detailed Description

Implementation of libmonado.

Author: Jakob Bornecrantz jakob.nosp@m.@col.nosp@m.labor.nosp@m.a.co.nosp@m.m; Pete Black pblac.nosp@m.k@co.nosp@m.llabo.nosp@m.ra.c.nosp@m.om; Rylie Pavlik rylie.nosp@m..pav.nosp@m.lik@c.nosp@m.olla.nosp@m.bora..nosp@m.com

Macro Definition Documentation

◆ CASE_ROLE_HAND

#define CASE_ROLE_HAND	(	UC_SRC,
		SRC
	)

Value:

        case ROLE_HAND_##UC_SRC##_LEFT: *out_index = root->ipc_c.ism->roles.hand_tracking.SRC.left;                    \
            return MND_SUCCESS;                                                                                        \
        case ROLE_HAND_##UC_SRC##_RIGHT:                                                                               \
                *out_index = root->ipc_c.ism->roles.hand_tracking.SRC.right;                                           \
                return MND_SUCCESS;

◆ CHECK_CLIENT_ID

#define CHECK_CLIENT_ID ( ID )

Value:

        do {                                                                                                           \
                if (ID == 0 && ID > INT_MAX) {                                                                         \
                        PE("Invalid client id (%u)", ID);                                                              \
                        return MND_ERROR_INVALID_VALUE;                                                                \
                }                                                                                                      \
        } while (false)

◆ CHECK_CLIENT_INDEX

#define CHECK_CLIENT_INDEX ( INDEX )

Value:

        do {                                                                                                           \
                if (INDEX >= root->clients.id_count) {                                                                 \
                        PE("Invalid client index, too large (%u)", INDEX);                                             \
                        return MND_ERROR_INVALID_VALUE;                                                                \
                }                                                                                                      \
        } while (false)

◆ CHECK_DEVICE_INDEX

#define CHECK_DEVICE_INDEX ( INDEX )

Value:

        do {                                                                                                           \
                if (INDEX >= root->ipc_c.ism->isdev_count) {                                                           \
                        PE("Invalid device index (%u)", INDEX);                                                        \
                        return MND_ERROR_INVALID_VALUE;                                                                \
                }                                                                                                      \
        } while (false)

◆ CHECK_NOT_NULL

#define CHECK_NOT_NULL ( ARG )

Value:

        do {                                                                                                           \
                if (ARG == NULL) {                                                                                     \
                        PE("Argument '" #ARG "' can not be null!");                                                    \
                        return MND_ERROR_INVALID_VALUE;                                                                \
                }                                                                                                      \
        } while (false)

◆ TO_ENUM

#define TO_ENUM	(	STRING,
		ENUM
	)

Value:

        if (strcmp(role_name, STRING) == 0) {                                                                          \
                role = ENUM;                                                                                           \
        } else

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_brightness()

mnd_result_t mnd_root_get_device_brightness	(	mnd_root_t *	root,
		uint32_t	device_index,
		float *	out_brightness
	)

Get current brightness of a display device.

Parameters

	root	The libmonado state.
	device_index	Index of device to retrieve brightness from.
[out]	out_brightness	Pointer to value to populate with the current device brightness, where 0 is 0%, and 1 is 100%.

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. Possible values are: "head" "left" "right" "gamepad" "eyes" "hand-tracking-unobstructed-[left\|right]" "hand-tracking-conforming-[left\|right]"

DEPRECATED: The role names "hand-tracking-[left|right]" are deprecated as of v1.5. They now map to "hand-tracking-unobstructed-[left|right]" and are scheduled for removal in v2.0.

Parameters

[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

*DEPRECATED** following roles name are deprecated, to be removed in the next major version

◆ 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.
[out]	out_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.
[out]	out_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_device_brightness()

mnd_result_t mnd_root_set_device_brightness	(	mnd_root_t *	root,
		uint32_t	device_index,
		float	brightness,
		bool	relative
	)

Set the display brightness.

Parameters

	root	The libmonado state.
	device_index	Index of device to retrieve battery info from.
[in]	brightness	Desired display brightness, usually between 0 and 1. Some devices may allow exceeding 1 if the supported range exceeds 100%, but it will be clamped to the supported range.
[in]	relative	Whether to add brightness to the current brightness, instead of overwriting the current brightness.

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

Enumerations

Functions

Detailed Description

Macro Definition Documentation

◆ CASE_ROLE_HAND

◆ CHECK_CLIENT_ID

◆ CHECK_CLIENT_INDEX

◆ CHECK_DEVICE_INDEX

◆ CHECK_NOT_NULL

◆ TO_ENUM

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_brightness()

◆ 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_device_brightness()

◆ mnd_root_set_reference_space_offset()

◆ mnd_root_set_tracking_origin_offset()

◆ mnd_root_toggle_client_io_active()

◆ mnd_root_update_client_list()