Instances

Functions
int	mpr_sig_reserve_inst (mpr_sig signal, int number, mpr_id *ids, void **data)
void	mpr_sig_release_inst (mpr_sig signal, mpr_id instance)
void	mpr_sig_remove_inst (mpr_sig signal, mpr_id instance)
int	mpr_sig_get_inst_status (mpr_sig signal, mpr_id instance)
int	mpr_sig_activate_inst (mpr_sig signal, mpr_id instance)
mpr_id	mpr_sig_get_oldest_inst_id (mpr_sig signal)
mpr_id	mpr_sig_get_newest_inst_id (mpr_sig signal)
mpr_id	mpr_sig_get_inst_id (mpr_sig signal, int index, mpr_status status)
void	mpr_sig_set_inst_data (mpr_sig signal, mpr_id instance, const void *data)
void *	mpr_sig_get_inst_data (mpr_sig signal, mpr_id instance)
int	mpr_sig_get_num_inst (mpr_sig signal, mpr_status status)

Detailed Description

Signal Instances can be used to describe the multiplicity and/or ephemerality of phenomena associated with Signals. A signal describes the phenomena, e.g. the position of a 'blob' in computer vision, and the signal's instances will describe the positions of actual detected blobs.

Function Documentation

mpr_sig_activate_inst()

int mpr_sig_activate_inst	(	mpr_sig	signal,
		mpr_id	instance )

Activate a specific signal instance without setting its value. In general it is not necessary to use this function, since signal instances will be automatically activated as necessary when signals are updated by mpr_sig_set_value() or through a map.

Parameters

signal	The signal to operate on.
instance	The identifier of the instance to activate.

Returns

Non-zero if the instance is active, zero otherwise.

mpr_sig_get_inst_data()

void * mpr_sig_get_inst_data	(	mpr_sig	signal,
		mpr_id	instance )

Retrieve the arbitrary pointer associated with a signal instance.

Parameters

signal	The signal to operate on.
instance	The identifier of the instance to operate on.

Returns

A pointer associated with this instance.

mpr_sig_get_inst_id()

mpr_id mpr_sig_get_inst_id	(	mpr_sig	signal,
		int	index,
		mpr_status	status )

Get a signal instance's identifier by its index. Intended to be used for iterating over instances, along with mpr_sig_get_num_inst().

Parameters

signal	The signal to operate on.
index	The numerical index of the instance to retrieve. Should be between zero and the number of instances.
status	The statuses of the instances to search. Instances matching any of the status bitflags will be counted. For example, only active instances can be included by setting status to MPR_STATUS_ACTIVE.

Returns

The instance identifier associated with the given index, or zero if unsuccessful.

mpr_sig_get_inst_status()

int mpr_sig_get_inst_status	(	mpr_sig	signal,
		mpr_id	instance )

Get the status of a signal instance as a set of bitflags.

Parameters

signal	The signal to check.
instance	The identifier of the instance to check.

Returns

The status of the signal instance returned as bitflags. Test the return value against the constants defined in the enum mpr_status. Each time this function is called it will reset the bitflags for NEW, SET_*, and REL_DNSTRM. The bitflag for REL_UPSTRM will remain

mpr_sig_get_newest_inst_id()

mpr_id mpr_sig_get_newest_inst_id

(

mpr_sig

signal

)

Get the local identifier of the newest active instance.

Parameters

signal

The signal to operate on.

Returns

The instance identifier, or zero if unsuccessful.

mpr_sig_get_num_inst()

int mpr_sig_get_num_inst	(	mpr_sig	signal,
		mpr_status	status )

Get the number of instances for a specific signal.

Parameters

signal	The signal to check.
status	The statuses of the instances to search. Instances matching any of the status bitflags will be counted. For example, only active instances can be included by setting status to MPR_STATUS_ACTIVE.

Returns

The number of allocated signal instances matching the specified status.

mpr_sig_get_oldest_inst_id()

mpr_id mpr_sig_get_oldest_inst_id

(

mpr_sig

signal

)

Get the local identifier of the oldest active instance.

Parameters

signal

The signal to operate on.

Returns

The instance identifier, or zero if unsuccessful.

mpr_sig_release_inst()

void mpr_sig_release_inst	(	mpr_sig	signal,
		mpr_id	instance )

Release a specific instance of a signal by removing it from the list of active instances and adding it to the reserve list.

Parameters

signal	The signal to operate on.
instance	The identifier of the instance to suspend.

mpr_sig_remove_inst()

void mpr_sig_remove_inst	(	mpr_sig	signal,
		mpr_id	instance )

Remove a specific instance of a signal and free its memory.

Parameters

signal	The signal to operate on.
instance	The identifier of the instance to suspend.

mpr_sig_reserve_inst()

int mpr_sig_reserve_inst	(	mpr_sig	signal,
		int	number,
		mpr_id *	ids,
		void **	data )

Allocate new instances and add them to the reserve list. Note that if instance ids are specified, libmapper will not add multiple instances with the same id.

Parameters

signal	The signal to which the instances will be added.
number	The number of instances to add.
ids	Array of integer ids, one for each new instance, or 0 for automatically-generated instance ids.
data	Array of user context pointers, one for each new instance, or 0 if not needed.

Returns

Number of instances added.

mpr_sig_set_inst_data()

void mpr_sig_set_inst_data	(	mpr_sig	signal,
		mpr_id	instance,
		const void *	data )

Associate a signal instance with an arbitrary pointer.

Parameters

signal	The signal to operate on.
instance	The identifier of the instance to operate on.
data	A pointer to user data to be associated with this instance.