Signals

Topics
	Instances

Typedefs
typedef void	mpr_sig_handler(mpr_sig signal, mpr_status event, mpr_id instance, int length, mpr_type type, const void *value, mpr_time time)

Functions
mpr_sig	mpr_sig_new (mpr_dev parent, mpr_dir direction, const char *name, int length, mpr_type type, const char *unit, const void *minimum, const void *maximum, int *num_instances, mpr_sig_handler *handler, int events)
void	mpr_sig_set_value (mpr_sig signal, mpr_id instance, int length, mpr_type type, const void *value)
const void *	mpr_sig_get_value (mpr_sig signal, mpr_id instance, mpr_time *time)
mpr_list	mpr_sig_get_maps (mpr_sig signal, mpr_dir direction)
mpr_dev	mpr_sig_get_dev (mpr_sig signal)
void	mpr_sig_set_cb (mpr_sig signal, mpr_sig_handler *handler, int events)

Detailed Description

Signals define inputs or outputs for devices. A signal consists of a scalar or vector value of some integer or floating-point type. A signal must be associated with a parent device. It can optionally be provided with some metadata such as range, unit, or other properties. Signals can be dynamically connected together in a dataflow graph by creating Maps using the libmapper API or an external session manager.

Typedef Documentation

mpr_sig_handler

typedef void mpr_sig_handler(mpr_sig signal, mpr_status event, mpr_id instance, int length, mpr_type type, const void *value, mpr_time time)

A signal handler function can be called whenever a signal value changes.

Parameters

signal	The signal that has changed.
event	The type of event that has occurred, e.g. MPR_SIG_UPDATE when the value has changed. Event types are listed in the enum mpr_sig_evt found in mapper_constants.h
instance	The identifier of the instance that has been changed, if applicable.
length	The array length of the current value in the case of MPR_SIG_UPDATE events, or 0 for other events.
type	The data type of the signal.
value	A pointer to the current value in the case of MPR_SIG_UPDATE events, or NULL for other events.
time	The timetag associated with this event.

Function Documentation

mpr_sig_get_dev()

mpr_dev mpr_sig_get_dev

(

mpr_sig

signal

)

Get the parent mpr_dev for a specific signal.

Parameters

signal

The signal to check.

Returns

The signal's parent device.

mpr_sig_get_maps()

mpr_list mpr_sig_get_maps	(	mpr_sig	signal,
		mpr_dir	direction )

Return the list of maps associated with a given signal.

Parameters

signal	Signal record to query for maps.
direction	The direction of the map relative to the given signal.

Returns

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

mpr_sig_get_value()

const void * mpr_sig_get_value	(	mpr_sig	signal,
		mpr_id	instance,
		mpr_time *	time )

Get the value of a signal instance.

Parameters

signal	The signal to operate on.
instance	A pointer to the identifier of the instance to query, or 0 for the default instance.
time	A location to receive the value's time tag (Optional, pass 0 to ignore).

Returns

A pointer to an array containing the value of the signal instance, or 0 if the signal instance has no value.

mpr_sig_new()

mpr_sig mpr_sig_new	(	mpr_dev	parent,
		mpr_dir	direction,
		const char *	name,
		int	length,
		mpr_type	type,
		const char *	unit,
		const void *	minimum,
		const void *	maximum,
		int *	num_instances,
		mpr_sig_handler *	handler,
		int	events )

Allocate and initialize a signal. Values and strings pointed to by this call will be copied. For minimum and maximum values, type must match 'type' (if type=MPR_INT32, then int*, etc) and length must match 'length' (i.e. a scalar if length=1, or an array with length elements).

Parameters

parent	The object to add a signal to.
direction	The signal direction.
name	The name of the signal.
length	The length of the signal vector, or 1 for a scalar.
type	The type of the signal value.
unit	The unit of the signal, or NULL for none.
minimum	Pointer to a minimum value, or NULL for none.
maximum	Pointer to a maximum value, or NULL for none.
num_instances	Pointer to the number of signal instances, or NULL to indicate that instances will not be used.
handler	Function to be called when the signal is updated, or NULL for none.
events	Bitflags for types of events that should trigger the handler. Event types are listed in the enum mpr_sig_evt found in mapper_constants.h

Returns

The new signal.

mpr_sig_set_cb()

void mpr_sig_set_cb	(	mpr_sig	signal,
		mpr_sig_handler *	handler,
		int	events )

Set or unset the message handler for a signal.

Parameters

signal	The signal to operate on.
handler	A pointer to a mpr_sig_handler function for processing incoming messages.
events	Bitflags for types of events we are interested in. Event types are listed in the enum mpr_sig_evt found in mapper_constants.h

mpr_sig_set_value()

void mpr_sig_set_value	(	mpr_sig	signal,
		mpr_id	instance,
		int	length,
		mpr_type	type,
		const void *	value )

Update the value of a signal instance. The signal will be routed according to external requests.

Parameters

signal	The signal to operate on.
instance	A pointer to the identifier of the instance to update, or 0 for the default instance.
length	Length of the value argument. Expected to be equal to the signal length.
type	Data type of the value argument.
value	A pointer to a new value for this signal. If the type argument is MPR_INT32, this should be int*; if the type argument is MPR_FLOAT, this should be float* (etc). It should be an array at least as long as the length argument.