Monado OpenXR Runtime
Public Member Functions | Data Fields
xrt_prober Struct Reference

The main prober that probes and manages found but not opened HMD devices that are connected to the system. More...

#include <xrt/xrt_prober.h>

Inheritance diagram for xrt_prober:
Inheritance graph
[legend]
Collaboration diagram for xrt_prober:
Collaboration graph
[legend]

Public Member Functions

bool u_prober_match_string (struct xrt_prober *xp, struct xrt_prober_device *dev, enum xrt_prober_string type, const char *to_match)
 Helper to match various strings of a xrt_prober_device to. More...
 
static xrt_result_t xrt_prober_probe (struct xrt_prober *xp)
 Enumerate all connected devices, whether or not we have an associated driver. More...
 
static xrt_result_t xrt_prober_lock_list (struct xrt_prober *xp, struct xrt_prober_device ***out_devices, size_t *out_device_count)
 Locks the prober list of probed devices and returns it. More...
 
static xrt_result_t xrt_prober_unlock_list (struct xrt_prober *xp, struct xrt_prober_device ***devices)
 Unlocks the list, allowing for xrt_prober::probe to be called. More...
 
static int xrt_prober_dump (struct xrt_prober *xp)
 Dump a listing of all devices found on the system to platform dependent output (stdout). More...
 
static xrt_result_t xrt_prober_create_system (struct xrt_prober *xp, struct xrt_system_devices **out_xsysd)
 Create system devices. More...
 
static int xrt_prober_select (struct xrt_prober *xp, struct xrt_device **xdevs, size_t xdev_capacity)
 Iterate through drivers (by ID and auto-probers) checking to see if they can handle any connected devices from the last xrt_prober::probe call, opening those devices to create instances of xrt_device implementations. More...
 
static int xrt_prober_open_hid_interface (struct xrt_prober *xp, struct xrt_prober_device *xpdev, int iface, struct os_hid_device **out_hid_dev)
 Open a HID (Human Interface Device) interface using native HID support. More...
 
static int xrt_prober_get_string_descriptor (struct xrt_prober *xp, struct xrt_prober_device *xpdev, enum xrt_prober_string which_string, unsigned char *out_buffer, size_t max_length)
 Returns a string property on the device of the given type which_string in out_buffer. More...
 
static bool xrt_prober_can_open (struct xrt_prober *xp, struct xrt_prober_device *xpdev)
 Determine whether a prober device can be opened. More...
 
static int xrt_prober_open_video_device (struct xrt_prober *xp, struct xrt_prober_device *xpdev, struct xrt_frame_context *xfctx, struct xrt_fs **out_xfs)
 Opens the selected video device and returns a xrt_fs, does not start it. More...
 
static int xrt_prober_list_video_devices (struct xrt_prober *xp, xrt_prober_list_video_func_t cb, void *ptr)
 Iterate through available video devices, calling your callback cb with your userdata ptr. More...
 
static int xrt_prober_get_entries (struct xrt_prober *xp, size_t *out_entry_count, struct xrt_prober_entry ***out_entries, struct xrt_auto_prober ***out_auto_probers)
 Retrieve the raw xrt_prober_entry and xrt_auto_prober arrays. More...
 
static void xrt_prober_destroy (struct xrt_prober **xp_ptr)
 Destroy the prober and set the pointer to null. More...
 
int xrt_prober_create_with_lists (struct xrt_prober **out_xp, struct xrt_prober_entry_lists *list)
 Create a prober with a list of known devices and autoprobers. More...
 

Data Fields

struct xrt_tracking_factorytracking
 Factory for producing tracked objects. More...
 
xrt_result_t(* probe )(struct xrt_prober *xp)
 Enumerate all connected devices, whether or not we have an associated driver. More...
 
xrt_result_t(* lock_list )(struct xrt_prober *xp, struct xrt_prober_device ***out_devices, size_t *out_device_count)
 Locks the prober list of probed devices and returns it. More...
 
xrt_result_t(* unlock_list )(struct xrt_prober *xp, struct xrt_prober_device ***devices)
 Unlocks the list, allowing for xrt_prober::probe to be called. More...
 
int(* dump )(struct xrt_prober *xp)
 Dump a listing of all devices found on the system to platform dependent output (stdout). More...
 
xrt_result_t(* create_system )(struct xrt_prober *xp, struct xrt_system_devices **out_xsysd)
 Create system devices. More...
 
int(* select )(struct xrt_prober *xp, struct xrt_device **xdevs, size_t xdev_capacity)
 Iterate through drivers (by ID and auto-probers) checking to see if they can handle any connected devices from the last xrt_prober::probe call, opening those devices to create instances of xrt_device implementations. More...
 
int(* open_hid_interface )(struct xrt_prober *xp, struct xrt_prober_device *xpdev, int iface, struct os_hid_device **out_hid_dev)
 Open a HID (Human Interface Device) interface using native HID support. More...
 
int(* open_video_device )(struct xrt_prober *xp, struct xrt_prober_device *xpdev, struct xrt_frame_context *xfctx, struct xrt_fs **out_xfs)
 Opens the selected video device and returns a xrt_fs, does not start it. More...
 
int(* list_video_devices )(struct xrt_prober *xp, xrt_prober_list_video_func_t cb, void *ptr)
 Iterate through available video devices, calling your callback cb with your userdata ptr. More...
 
int(* get_entries )(struct xrt_prober *xp, size_t *out_entry_count, struct xrt_prober_entry ***out_entries, struct xrt_auto_prober ***out_auto_probers)
 Retrieve the raw xrt_prober_entry and xrt_auto_prober arrays. More...
 
int(* get_string_descriptor )(struct xrt_prober *xp, struct xrt_prober_device *xpdev, enum xrt_prober_string which_string, unsigned char *out_buffer, size_t max_length)
 Returns a string property on the device of the given type which_string in out_buffer. More...
 
bool(* can_open )(struct xrt_prober *xp, struct xrt_prober_device *xpdev)
 Determine whether a prober device can be opened. More...
 
void(* destroy )(struct xrt_prober **xp_ptr)
 Destroy the prober and set the pointer to null. More...
 

Detailed Description

The main prober that probes and manages found but not opened HMD devices that are connected to the system.

Member Function Documentation

◆ u_prober_match_string()

bool u_prober_match_string ( struct xrt_prober xp,
struct xrt_prober_device dev,
enum xrt_prober_string  type,
const char *  to_match 
)

Helper to match various strings of a xrt_prober_device to.

◆ xrt_prober_can_open()

static bool xrt_prober_can_open ( struct xrt_prober xp,
struct xrt_prober_device xpdev 
)
inline

Determine whether a prober device can be opened.

Parameters
xpPointer to self
xpdevprober device
Returns
true if xpdev can be opened.

Helper function for xrt_prober::can_open.

References can_open.

◆ xrt_prober_create_system()

static xrt_result_t xrt_prober_create_system ( struct xrt_prober xp,
struct xrt_system_devices **  out_xsysd 
)
inline

Create system devices.

Parameters
[in]xpProber self parameter.
[out]out_xsysdReturn of system devices, the pointed pointer must be NULL.
Note
Code consuming this interface should use xrt_prober_create_system()

Helper function for xrt_prober::create_system.

References create_system.

Referenced by u_system_devices_create_from_prober().

◆ xrt_prober_create_with_lists()

int xrt_prober_create_with_lists ( struct xrt_prober **  out_xp,
struct xrt_prober_entry_lists list 
)

Create a prober with a list of known devices and autoprobers.

Typically used by xrt_instance_create implementations to create the prober, often with a shared list called target_list.

Parameters
[out]out_xpPointer to xrt_prober pointer, will be populated with created xrt_prober instance.
[in]listProber entry list

References U_TYPED_CALLOC.

Referenced by xrt_instance::xrt_instance_create().

◆ xrt_prober_destroy()

static void xrt_prober_destroy ( struct xrt_prober **  xp_ptr)
inline

Destroy the prober and set the pointer to null.

Code consuming this interface should use xrt_prober_destroy().

Parameters
xp_ptrpointer to self-pointer

Helper for calling through the function pointer: does a null check and sets xp_ptr to null if freed.

References destroy.

◆ xrt_prober_dump()

static int xrt_prober_dump ( struct xrt_prober xp)
inline

Dump a listing of all devices found on the system to platform dependent output (stdout).

Note
Code consuming this interface should use xrt_prober_dump()

Helper function for xrt_prober::dump.

References dump.

◆ xrt_prober_get_entries()

static int xrt_prober_get_entries ( struct xrt_prober xp,
size_t *  out_entry_count,
struct xrt_prober_entry ***  out_entries,
struct xrt_auto_prober ***  out_auto_probers 
)
inline

Retrieve the raw xrt_prober_entry and xrt_auto_prober arrays.

Parameters
xpPointer to self
[out]out_entry_countThe size of out_entries
[out]out_entriesAn array of prober entries
[out]out_auto_probersAn array of up to XRT_MAX_AUTO_PROBERS auto-probers
Returns
0 on success, <0 on error.

Helper function for xrt_prober::get_entries.

References get_entries.

◆ xrt_prober_get_string_descriptor()

static int xrt_prober_get_string_descriptor ( struct xrt_prober xp,
struct xrt_prober_device xpdev,
enum xrt_prober_string  which_string,
unsigned char *  out_buffer,
size_t  max_length 
)
inline

Returns a string property on the device of the given type which_string in out_buffer.

Parameters
[in]xpProber.
[in]xpdevDevice to get string property from.
[in]which_stringWhich string property to query.
[in,out]out_bufferTarget buffer.
[in]max_lengthMax length of the target buffer.
Returns
The length of the string, or negative on error.

Helper function for xrt_prober::get_string_descriptor.

References get_string_descriptor.

Referenced by hdk_found().

◆ xrt_prober_list_video_devices()

static int xrt_prober_list_video_devices ( struct xrt_prober xp,
xrt_prober_list_video_func_t  cb,
void *  ptr 
)
inline

Iterate through available video devices, calling your callback cb with your userdata ptr.

Parameters
xpPointer to self
cbCallback function
ptrOpaque pointer for your userdata, passed through to the callback.
See also
xrt_prober_list_video_func_t
Returns
0 on success, <0 on error.

Helper function for xrt_prober::list_video_devices.

References list_video_devices.

Referenced by p_factory_ensure_frameserver().

◆ xrt_prober_lock_list()

static xrt_result_t xrt_prober_lock_list ( struct xrt_prober xp,
struct xrt_prober_device ***  out_devices,
size_t *  out_device_count 
)
inline

Locks the prober list of probed devices and returns it.

While locked, calling xrt_prober::probe is forbidden. Not thread safe.

See xrt_prober::probe for more detailed expected usage.

See also
xrt_prober::probe, xrt_prober::unlock_list

Helper function for xrt_prober::lock_list.

References lock_list.

◆ xrt_prober_open_hid_interface()

static int xrt_prober_open_hid_interface ( struct xrt_prober xp,
struct xrt_prober_device xpdev,
int  iface,
struct os_hid_device **  out_hid_dev 
)
inline

Open a HID (Human Interface Device) interface using native HID support.

Parameters
xpPointer to self
xpdevprober device
ifaceHID interface number
[out]out_hid_devinstance of os_hid_device for the given interface
Returns
0 on success, <0 on error.

Helper function for xrt_prober::open_hid_interface.

References open_hid_interface.

Referenced by psmv_device_create().

◆ xrt_prober_open_video_device()

static int xrt_prober_open_video_device ( struct xrt_prober xp,
struct xrt_prober_device xpdev,
struct xrt_frame_context xfctx,
struct xrt_fs **  out_xfs 
)
inline

Opens the selected video device and returns a xrt_fs, does not start it.

Helper function for xrt_prober::xrt_prober_open_video_device.

References open_video_device.

Referenced by p_factory_ensure_slam_frameserver().

◆ xrt_prober_probe()

static xrt_result_t xrt_prober_probe ( struct xrt_prober xp)
inline

Enumerate all connected devices, whether or not we have an associated driver.

Can not be called with the device list is locked xrt_prober::lock_list and xrt_prober::unlock_list.

This function along with lock/unlock allows a xrt_builder to re-probe the devices after having opened another device. A bit more detailed: It can get a list of devices, search it, open the enabling one, release the list, do a probe, get the list again and re-scan to detect any additional devices that may show up once the first device has been been started.

See also
xrt_prober::lock_list, xrt_prober::unlock_list

Helper function for xrt_prober::probe.

References probe.

Referenced by u_system_devices_create_from_prober().

◆ xrt_prober_select()

static int xrt_prober_select ( struct xrt_prober xp,
struct xrt_device **  xdevs,
size_t  xdev_capacity 
)
inline

Iterate through drivers (by ID and auto-probers) checking to see if they can handle any connected devices from the last xrt_prober::probe call, opening those devices to create instances of xrt_device implementations.

If no HMD (not even a simulated HMD) is found, then no devices will be returned (all xdevs will be NULL). Otherwise, xdevs will be populated with the HMD in xdevs[0], and any subsequent non-NULL values referring to additional non-HMD devices.

Parameters
xpPointer to self
[in,out]xdevsPointer to xrt_device array. Array elements will be populated.
[in]xdev_capacityThe capacity of the xdevs array.
Returns
0 on success (including "no HMD found"), <0 on error.

Returned devices have their ownership transferred to the caller: all should be cleaned up with xrt_device_destroy().

Note
Code consuming this interface should use xrt_prober_select(). Typically used through an xrt_instance and the xrt_instance_select() method which usually calls xrt_prober_probe() and xrt_prober_select().

Helper function for xrt_prober::select.

References select.

◆ xrt_prober_unlock_list()

static xrt_result_t xrt_prober_unlock_list ( struct xrt_prober xp,
struct xrt_prober_device ***  devices 
)
inline

Unlocks the list, allowing for xrt_prober::probe to be called.

Takes a pointer to the list pointer and clears it. Not thread safe. See xrt_prober::probe for more detailed expected usage.

See also
xrt_prober::probe, xrt_prober::lock_list

Helper function for xrt_prober::unlock_list.

References unlock_list.

Field Documentation

◆ can_open

bool(* xrt_prober::can_open) (struct xrt_prober *xp, struct xrt_prober_device *xpdev)

Determine whether a prober device can be opened.

Parameters
xpPointer to self
xpdevprober device
Returns
true if xpdev can be opened.

Referenced by xrt_prober_can_open().

◆ create_system

xrt_result_t(* xrt_prober::create_system) (struct xrt_prober *xp, struct xrt_system_devices **out_xsysd)

Create system devices.

Parameters
[in]xpProber self parameter.
[out]out_xsysdReturn of system devices, the pointed pointer must be NULL.
Note
Code consuming this interface should use xrt_prober_create_system()

Referenced by xrt_prober_create_system().

◆ destroy

void(* xrt_prober::destroy) (struct xrt_prober **xp_ptr)

Destroy the prober and set the pointer to null.

Code consuming this interface should use xrt_prober_destroy().

Parameters
xp_ptrpointer to self-pointer

Referenced by xrt_prober_destroy().

◆ dump

int(* xrt_prober::dump) (struct xrt_prober *xp)

Dump a listing of all devices found on the system to platform dependent output (stdout).

Note
Code consuming this interface should use xrt_prober_dump()

Referenced by xrt_prober_dump().

◆ get_entries

int(* xrt_prober::get_entries) (struct xrt_prober *xp, size_t *out_entry_count, struct xrt_prober_entry ***out_entries, struct xrt_auto_prober ***out_auto_probers)

Retrieve the raw xrt_prober_entry and xrt_auto_prober arrays.

Parameters
xpPointer to self
[out]out_entry_countThe size of out_entries
[out]out_entriesAn array of prober entries
[out]out_auto_probersAn array of up to XRT_MAX_AUTO_PROBERS auto-probers
Returns
0 on success, <0 on error.

Referenced by xrt_prober_get_entries().

◆ get_string_descriptor

int(* xrt_prober::get_string_descriptor) (struct xrt_prober *xp, struct xrt_prober_device *xpdev, enum xrt_prober_string which_string, unsigned char *out_buffer, size_t max_length)

Returns a string property on the device of the given type which_string in out_buffer.

Parameters
[in]xpProber.
[in]xpdevDevice to get string property from.
[in]which_stringWhich string property to query.
[in,out]out_bufferTarget buffer.
[in]max_lengthMax length of the target buffer.
Returns
The length of the string, or negative on error.

Referenced by xrt_prober_get_string_descriptor().

◆ list_video_devices

int(* xrt_prober::list_video_devices) (struct xrt_prober *xp, xrt_prober_list_video_func_t cb, void *ptr)

Iterate through available video devices, calling your callback cb with your userdata ptr.

Parameters
xpPointer to self
cbCallback function
ptrOpaque pointer for your userdata, passed through to the callback.
See also
xrt_prober_list_video_func_t
Returns
0 on success, <0 on error.

Referenced by xrt_prober_list_video_devices().

◆ lock_list

xrt_result_t(* xrt_prober::lock_list) (struct xrt_prober *xp, struct xrt_prober_device ***out_devices, size_t *out_device_count)

Locks the prober list of probed devices and returns it.

While locked, calling xrt_prober::probe is forbidden. Not thread safe.

See xrt_prober::probe for more detailed expected usage.

See also
xrt_prober::probe, xrt_prober::unlock_list

Referenced by xrt_prober_lock_list().

◆ open_hid_interface

int(* xrt_prober::open_hid_interface) (struct xrt_prober *xp, struct xrt_prober_device *xpdev, int iface, struct os_hid_device **out_hid_dev)

Open a HID (Human Interface Device) interface using native HID support.

Parameters
xpPointer to self
xpdevprober device
ifaceHID interface number
[out]out_hid_devinstance of os_hid_device for the given interface
Returns
0 on success, <0 on error.

Referenced by hydra_found(), and xrt_prober_open_hid_interface().

◆ open_video_device

int(* xrt_prober::open_video_device) (struct xrt_prober *xp, struct xrt_prober_device *xpdev, struct xrt_frame_context *xfctx, struct xrt_fs **out_xfs)

Opens the selected video device and returns a xrt_fs, does not start it.

Referenced by xrt_prober_open_video_device().

◆ probe

xrt_result_t(* xrt_prober::probe) (struct xrt_prober *xp)

Enumerate all connected devices, whether or not we have an associated driver.

Can not be called with the device list is locked xrt_prober::lock_list and xrt_prober::unlock_list.

This function along with lock/unlock allows a xrt_builder to re-probe the devices after having opened another device. A bit more detailed: It can get a list of devices, search it, open the enabling one, release the list, do a probe, get the list again and re-scan to detect any additional devices that may show up once the first device has been been started.

See also
xrt_prober::lock_list, xrt_prober::unlock_list

Referenced by xrt_prober_probe().

◆ select

int(* xrt_prober::select) (struct xrt_prober *xp, struct xrt_device **xdevs, size_t xdev_capacity)

Iterate through drivers (by ID and auto-probers) checking to see if they can handle any connected devices from the last xrt_prober::probe call, opening those devices to create instances of xrt_device implementations.

If no HMD (not even a simulated HMD) is found, then no devices will be returned (all xdevs will be NULL). Otherwise, xdevs will be populated with the HMD in xdevs[0], and any subsequent non-NULL values referring to additional non-HMD devices.

Parameters
xpPointer to self
[in,out]xdevsPointer to xrt_device array. Array elements will be populated.
[in]xdev_capacityThe capacity of the xdevs array.
Returns
0 on success (including "no HMD found"), <0 on error.

Returned devices have their ownership transferred to the caller: all should be cleaned up with xrt_device_destroy().

Note
Code consuming this interface should use xrt_prober_select(). Typically used through an xrt_instance and the xrt_instance_select() method which usually calls xrt_prober_probe() and xrt_prober_select().

Referenced by xrt_prober_select().

◆ tracking

struct xrt_tracking_factory* xrt_prober::tracking

Factory for producing tracked objects.

◆ unlock_list

xrt_result_t(* xrt_prober::unlock_list) (struct xrt_prober *xp, struct xrt_prober_device ***devices)

Unlocks the list, allowing for xrt_prober::probe to be called.

Takes a pointer to the list pointer and clears it. Not thread safe. See xrt_prober::probe for more detailed expected usage.

See also
xrt_prober::probe, xrt_prober::lock_list

Referenced by xrt_prober_unlock_list().


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