Monado OpenXR Runtime
monado.h File Reference

Interface of libmonado. More...

#include <stdint.h>
#include <stdbool.h>
Include dependency graph for monado.h:

Go to the source code of this file.

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   5
 Minor version of the API. More...
 
#define MND_API_VERSION_PATCH   1
 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 ,
  MND_ERROR_UNSUPPORTED_OPERATION = -8
}
 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 , MND_PROPERTY_SUPPORTS_BRIGHTNESS_BOOL = 5
}
 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...
 
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

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   5

Minor version of the API.

◆ MND_API_VERSION_PATCH

#define MND_API_VERSION_PATCH   1

Patch version of the API.

Typedef Documentation

◆ 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

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

Supported in version 1.2 and above.

◆ 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

Bitflags for client application state.

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

Supported in version 1.5.0 and above.

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

MND_ERROR_UNSUPPORTED_OPERATION 

Supported in version 1.5 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_majorMajor version number, must be valid pointer.
[out]out_minorMinor version number, must be valid pointer.
[out]out_patchPatch 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_rootAddress 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_ptrPointer 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
rootThe libmonado state.
indexIndex to retrieve id for.
[out]out_client_idPointer 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
rootThe libmonado state.
client_idID of client to retrieve name from.
[out]out_namePointer 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
rootThe libmonado state.
client_idID of client to retrieve flags from.
[out]out_flagsPointer 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
rootThe libmonado state.
device_indexIndex of device to retrieve battery info from.
[out]out_presentPointer to value to populate with whether the device provides battery status info.
[out]out_chargingPointer to value to populate with whether the device is currently being charged.
[out]out_chargePointer 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
rootThe libmonado state.
device_indexIndex of device to retrieve brightness from.
[out]out_brightnessPointer 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
rootThe libmonado state.
[out]out_device_countPointer 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
rootThe libmonado state.
role_nameName 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_indexPointer 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
rootThe libmonado state.
device_indexIndex of device to retrieve name from.
[out]out_device_idPointer to value to populate with the device id at the given index.
[out]out_dev_namePointer 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
rootThe libmonado state.
device_indexIndex of device to retrieve name from.
propA boolean property enum.
[out]out_boolPointer 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
rootThe libmonado state.
device_indexIndex of device to retrieve name from.
propA float property enum.
[out]out_floatPointer 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
rootThe libmonado state.
device_indexIndex of device to retrieve name from.
propA int32_t property enum.
[out]out_i32Pointer 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
rootThe libmonado state.
device_indexIndex of device to retrieve name from.
propA string property enum.
[out]out_stringPointer 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
rootThe libmonado state.
device_indexIndex of device to retrieve name from.
propA uint32_t property enum.
[out]out_u32Pointer 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
rootThe libmonado state.
[out]out_numPointer 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
rootThe libmonado state.
typeThe reference space.
[out]out_offsetA 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
rootThe libmonado state.
out_track_countPointer 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
rootThe libmonado state.
origin_idThe ID of a tracking origin.
out_stringThe 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
rootThe libmonado state.
origin_idThe ID of the tracking origin.
[out]out_offsetA 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
rootThe 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
rootThe libmonado state.
client_idID 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
rootThe libmonado state.
client_idID 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
rootThe libmonado state.
device_indexIndex of device to retrieve battery info from.
[in]brightnessDesired 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]relativeWhether 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
rootThe libmonado state.
typeThe reference space.
offsetA 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
rootThe libmonado state.
origin_idThe ID of the tracking origin.
offsetA 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
rootThe libmonado state.
client_idID 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
rootThe libmonado state.
Returns
MND_SUCCESS on success