Devices

Functions
mpr_dev	mpr_dev_new (const char *name, mpr_graph graph)
void	mpr_dev_free (mpr_dev device)
mpr_id	mpr_dev_generate_unique_id (mpr_dev device)
mpr_list	mpr_dev_get_sigs (mpr_dev device, mpr_dir direction)
mpr_list	mpr_dev_get_maps (mpr_dev device, mpr_dir direction)
int	mpr_dev_poll (mpr_dev device, int block_ms)
int	mpr_dev_start_polling (mpr_dev device, int block_ms)
int	mpr_dev_stop_polling (mpr_dev device)
int	mpr_dev_get_is_ready (mpr_dev device)
mpr_time	mpr_dev_get_time (mpr_dev device)
void	mpr_dev_set_time (mpr_dev device, mpr_time time)
void	mpr_dev_update_maps (mpr_dev device)

Detailed Description

A device is an entity on the distributed graph which has input and/or output signals. The mpr_dev is the primary interface through which most programs use libmapper. A device must have a name, to which a unique ordinal is automatically appended. It can also be given other user-specified metadata.

Function Documentation

mpr_dev_free()

void mpr_dev_free

(

mpr_dev

device

)

Remove a device from the graph and free its resources.

Parameters

device

The device to free.

mpr_dev_generate_unique_id()

mpr_id mpr_dev_generate_unique_id

(

mpr_dev

device

)

Return a unique identifier associated with a given device.

Parameters

device

The device to use.

Returns

A new unique id.

mpr_dev_get_is_ready()

int mpr_dev_get_is_ready

(

mpr_dev

device

)

Detect whether a device is completely initialized.

Parameters

device

The device to query.

Returns

Non-zero if device is completely initialized, i.e., has an allocated receiving port and unique identifier. Zero otherwise.

mpr_dev_get_maps()

mpr_list mpr_dev_get_maps	(	mpr_dev	device,
		mpr_dir	direction )

Return the list of maps for a given device.

Parameters

device	The device to query.
direction	The direction of the maps to return, should be MPR_DIR_IN, MPR_DIR_OUT, or MPR_DIR_ANY.

Returns

A list of results. Use mpr_list_get_next() to iterate.

mpr_dev_get_sigs()

mpr_list mpr_dev_get_sigs	(	mpr_dev	device,
		mpr_dir	direction )

Return the list of signals for a given device.

Parameters

device	The device to query.
direction	The direction of the signals to return, should be MPR_DIR_IN, MPR_DIR_OUT, or MPR_DIR_ANY.

Returns

A list of results. Use mpr_list_get_next() to iterate.

mpr_dev_get_time()

mpr_time mpr_dev_get_time

(

mpr_dev

device

)

Get the current time for a device.

Parameters

device

The device to use.

Returns

The current time.

mpr_dev_new()

mpr_dev mpr_dev_new	(	const char *	name,
		mpr_graph	graph )

Allocate and initialize a device.

Parameters

name	A short descriptive string to identify the device. Must not contain spaces or the slash character '/'.
graph	A previously allocated graph structure to use. If 0, one will be allocated for use with this device.

Returns

A newly allocated device. Should be freed using mpr_dev_free().

mpr_dev_poll()

int mpr_dev_poll	(	mpr_dev	device,
		int	block_ms )

Poll this device for new messages. Note, if you have multiple devices, the right thing to do is call this function for each of them with block_ms=0, and add your own sleep if necessary.

Parameters

device	The device to check messages for.
block_ms	Number of milliseconds to block waiting for messages, or 0 for non-blocking behaviour. Setting block_ms<0 will process all queued messages and then return immediately.

Returns

The number of handled messages. May be zero if there was nothing to do.

mpr_dev_set_time()

void mpr_dev_set_time	(	mpr_dev	device,
		mpr_time	time )

Set the time for a device. Use only if user code has access to a more accurate timestamp than the operating system.

Parameters

device	The device to use.
time	The time to set. This time will be used for tagging signal updates until the next occurrence mpr_dev_set_time() or mpr_dev_poll().

mpr_dev_start_polling()

int mpr_dev_start_polling	(	mpr_dev	device,
		int	block_ms )

Start automatically polling this device for new messages in a separate thread.

Parameters

device	The device to check messages for.
block_ms	Number of milliseconds to block waiting for messages on each iteration, or <0 to process all incoming messages.

Returns

Zero if successful, less than zero otherwise.

mpr_dev_stop_polling()

int mpr_dev_stop_polling

(

mpr_dev

device

)

Stop automatically polling this device for new messages in a separate thread.

Parameters

device

The device to check messages for.

Returns

Zero if successful, less than zero otherwise.

mpr_dev_update_maps()

void mpr_dev_update_maps

(

mpr_dev

device

)

Trigger map propagation for a given timestep. This function can be omitted if mpr_dev_poll() is called each sampling timestep, however calling mpr_dev_poll() at a lower rate may be more performant.

Parameters

device

The device to use.