Maps

Functions
mapper_map	mapper_map_new (int num_sources, mapper_signal *sources, int num_destinations, mapper_signal *destinations)
void	mapper_map_set_user_data (mapper_map map, const void *user_data)
void *	mapper_map_user_data (mapper_map map)
void	mapper_map_release (mapper_map map)
const char *	mapper_map_description (mapper_map map)
int	mapper_map_num_slots (mapper_map map, mapper_location loc)
int	mapper_map_num_destinations (mapper_map map)
mapper_slot	mapper_map_slot (mapper_map map, mapper_location loc, int index)
mapper_slot	mapper_map_slot_by_signal (mapper_map map, mapper_signal sig)
mapper_id	mapper_map_id (mapper_map map)
int	mapper_map_is_local (mapper_map map)
mapper_mode	mapper_map_mode (mapper_map map)
const char *	mapper_map_expression (mapper_map map)
int	mapper_map_muted (mapper_map map)
mapper_location	mapper_map_process_location (mapper_map map)
mapper_protocol	mapper_map_protocol (mapper_map map)
mapper_device *	mapper_map_scopes (mapper_map map)
int	mapper_map_ready (mapper_map map)
void	mapper_map_set_description (mapper_map map, const char *description)
void	mapper_map_set_mode (mapper_map map, mapper_mode mode)
void	mapper_map_set_expression (mapper_map map, const char *expression)
void	mapper_map_set_muted (mapper_map map, int muted)
void	mapper_map_set_process_location (mapper_map map, mapper_location location)
void	mapper_map_set_protocol (mapper_map map, mapper_protocol proto)
int	mapper_map_set_property (mapper_map map, const char *name, int length, char type, const void *value, int publish)
void	mapper_map_clear_staged_properties (mapper_map map)
void	mapper_map_push (mapper_map map)
void	mapper_map_refresh (mapper_map map)
int	mapper_map_remove_property (mapper_map map, const char *name)
void	mapper_map_add_scope (mapper_map map, mapper_device dev)
void	mapper_map_remove_scope (mapper_map map, mapper_device dev)
int	mapper_map_num_properties (mapper_map map)
int	mapper_map_property (mapper_map map, const char *name, int *length, char *type, const void **value)
int	mapper_map_property_index (mapper_map map, unsigned int index, const char **name, int *length, char *type, const void **value)
mapper_map *	mapper_map_query_union (mapper_map *query1, mapper_map *query2)
mapper_map *	mapper_map_query_intersection (mapper_map *query1, mapper_map *query2)
mapper_map *	mapper_map_query_difference (mapper_map *query1, mapper_map *query2)
mapper_map	mapper_map_query_index (mapper_map *query, int index)
mapper_map *	mapper_map_query_next (mapper_map *query)
mapper_map *	mapper_map_query_copy (mapper_map *query)
void	mapper_map_query_done (mapper_map *query)
void	mapper_map_print (mapper_map map)

Detailed Description

Maps define dataflow connections between sets of signals. A map consists of one or more source slots, one destination slot, and properties which determine how the source data is processed.

Function Documentation

mapper_map_add_scope()

void mapper_map_add_scope	(	mapper_map	map,
		mapper_device	dev
	)

Add a scope to this map. Map scopes configure the propagation of signal instance updates across the map. Changes to remote maps will not take effect until synchronized with the network using mapper_map_push().

Parameters

map	The map to modify.
dev	Device to add as a scope for this map. After taking effect, this setting will cause instance updates originating at this device to be propagated across the map.

mapper_map_clear_staged_properties()

void mapper_map_clear_staged_properties

(

mapper_map

map

)

Clear any staged property changes.

Parameters

map	The map to operate on.

mapper_map_description()

const char* mapper_map_description

(

mapper_map

map

)

Get the description for a specific map.

Parameters

map	The map to check.

Returns

The map description.

mapper_map_expression()

const char* mapper_map_expression

(

mapper_map

map

)

Get the expression property for a specific map.

Parameters

map	The map to check.

Returns

The expression property for this map.

mapper_map_id()

mapper_id mapper_map_id

(

mapper_map

map

)

Get the unique id for a specific map.

Parameters

map	The map to check.

Returns

The unique id assigned to this map.

mapper_map_is_local()

int mapper_map_is_local

(

mapper_map

map

)

Indicate whether this map is local.

Parameters

map	The map to check.

Returns

1 if the map is local, 0 otherwise.

mapper_map_mode()

mapper_mode mapper_map_mode

(

mapper_map

map

)

Get the mode property for a specific map.

Parameters

map	The map to check.

Returns

The mode property for this map.

mapper_map_muted()

int mapper_map_muted

(

mapper_map

map

)

Get the muted property for a specific map.

Parameters

map	The map to check.

Returns

One if this map is muted, 0 otherwise.

mapper_map_new()

mapper_map mapper_map_new	(	int	num_sources,
		mapper_signal *	sources,
		int	num_destinations,
		mapper_signal *	destinations
	)

Create a map between a set of signals.

Parameters

num_sources	The number of source signals in this map.
sources	Array of source signal data structures.
num_destinations	The number of destination signals in this map. Currently restricted to 1.
destinations	Array of destination signal data structures.

Returns

A map data structure – either loaded from the database (if the map already existed) or newly created. In the latter case the map will not take effect until it has been added to the network using mapper_map_push().

mapper_map_num_destinations()

int mapper_map_num_destinations

(

mapper_map

map

)

Get the number of destination signals for to a specific map.

Parameters

map	The map to check.

Returns

The number of destination signals.

mapper_map_num_properties()

int mapper_map_num_properties

(

mapper_map

map

)

Get the total number of properties for a specific map.

Parameters

map	The map to check.

Returns

The number of properties.

mapper_map_num_slots()

int mapper_map_num_slots	(	mapper_map	map,
		mapper_location	loc
	)

Get the number of source signals for to a specific map.

Parameters

map	The map to check.
loc	MAPPER_LOC_SOURCE, MAPPER_LOC_DESTINATION,

Returns

The number of slots.

mapper_map_print()

void mapper_map_print

(

mapper_map

map

)

Helper to print the properties of a specific map.

Parameters

map	The map to print.

mapper_map_process_location()

mapper_location mapper_map_process_location

(

mapper_map

map

)

Get the process location for a specific map.

Parameters

map	The map to check.

Returns

MAPPER_LOC_SOURCE if processing is evaluated at the source device, MAPPER_LOC_DESTINATION otherwise.

mapper_map_property()

int mapper_map_property	(	mapper_map	map,
		const char *	name,
		int *	length,
		char *	type,
		const void **	value
	)

Look up a map property by name.

Parameters

map	The map to check.
name	The name of the property to retrieve.
length	A pointer to a location to receive the vector length of the property value. (Required.)
type	A pointer to a location to receive the type of the property value. (Required.)
value	A pointer to a location to receive the address of the property's value. (Required.)

Returns

Zero if found, otherwise non-zero.

mapper_map_property_index()

int mapper_map_property_index	(	mapper_map	map,
		unsigned int	index,
		const char **	name,
		int *	length,
		char *	type,
		const void **	value
	)

Look up a map property by index. To iterate all properties, call this function from index=0, increasing until it returns zero.

Parameters

map	The map to check.
index	Numerical index of a map property.
name	Address of a string pointer to receive the name of indexed property. May be zero.
length	A pointer to a location to receive the vector length of the property value. (Required.)
type	A pointer to a location to receive the type of the property value. (Required.)
value	A pointer to a location to receive the address of the property's value. (Required.)

Returns

Zero if found, otherwise non-zero.

mapper_map_protocol()

mapper_protocol mapper_map_protocol

(

mapper_map

map

)

Get the network protocol for a specific map.

Parameters

map	The map to check.

Returns

MAPPER_PROTO_UDP or MAPPER_PROTO_TCP.

mapper_map_push()

void mapper_map_push

(

mapper_map

map

)

Push any property changes out to the network.

Parameters

map	The map to operate on.

mapper_map_query_copy()

mapper_map* mapper_map_query_copy

(

mapper_map *

query

)

Copy a previously-constructed map query.

Parameters

query

The previous map record pointer.

Returns

A double-pointer to the copy of the list, or zero if none. Use mapper_map_query_next() to iterate.

mapper_map_query_difference()

mapper_map* mapper_map_query_difference	(	mapper_map *	query1,
		mapper_map *	query2
	)

Get the difference between two map queries (maps matching query1 but NOT query2).

Parameters

query1	The first map query.
query2	The second map query.

Returns

A double-pointer to the first item in a list of results. Use mapper_map_query_next() to iterate.

mapper_map_query_done()

void mapper_map_query_done

(

mapper_map *

query

)

Given a map record pointer returned from a previous map query, indicate that we are done iterating.

Parameters

query

The previous map record pointer.

mapper_map_query_index()

mapper_map mapper_map_query_index	(	mapper_map *	query,
		int	index
	)

Given a map record pointer returned from a previous map query, get an indexed item in the list.

Parameters

query	The previous map record pointer.
index	The index of the list element to retrieve.

Returns

A pointer to the map record, or zero if it doesn't exist.

mapper_map_query_intersection()

mapper_map* mapper_map_query_intersection	(	mapper_map *	query1,
		mapper_map *	query2
	)

Get the intersection of two map queries (maps matching query1 AND query2).

Parameters

query1	The first map query.
query2	The second map query.

Returns

A double-pointer to the first item in a list of results. Use mapper_map_query_next() to iterate.

mapper_map_query_next()

mapper_map* mapper_map_query_next

(

mapper_map *

query

)

Given a map record pointer returned from a previous map query, get the next item in the list.

Parameters

query

The previous map record pointer.

Returns

A double-pointer to the next map record in the list, or zero if no more maps.

mapper_map_query_union()

mapper_map* mapper_map_query_union	(	mapper_map *	query1,
		mapper_map *	query2
	)

Get the union of two map queries (maps matching query1 OR query2).

Parameters

query1	The first map query.
query2	The second map query.

Returns

A double-pointer to the first item in a list of results. Use mapper_map_query_next() to iterate.

mapper_map_ready()

int mapper_map_ready

(

mapper_map

map

)

Detect whether a map is completely initialized.

Parameters

map	The device to query.

Returns

Non-zero if map is completely initialized, zero otherwise.

mapper_map_refresh()

void mapper_map_refresh

(

mapper_map

map

)

Re-create stale map if necessary.

Parameters

map	The map to operate on.

mapper_map_release()

void mapper_map_release

(

mapper_map

map

)

Remove a map between a set of signals.

Parameters

map	The map to destroy.

mapper_map_remove_property()

int mapper_map_remove_property	(	mapper_map	map,
		const char *	name
	)

Remove a property of a map.

Parameters

map	The map to operate on.
name	The name of the property to remove.

Returns

1 if property has been removed, 0 otherwise.

mapper_map_remove_scope()

void mapper_map_remove_scope	(	mapper_map	map,
		mapper_device	dev
	)

Remove a scope from this map. Map scopes configure the propagation of signal instance updates across the map. Changes to remote maps will not take effect until synchronized with the network using mapper_map_push().

Parameters

map	The map to modify.
dev	Device to remove as a scope for this map. After taking effect, this setting will cause instance updates originating at this device to be blocked from propagating across the map.

mapper_map_scopes()

mapper_device* mapper_map_scopes

(

mapper_map

map

)

Get the scopes property for a specific map.

Parameters

map	The map to check.

Returns

A double-pointer to the first item in the list of results or zero if none. Use mapper_map_query_next() to iterate.

mapper_map_set_description()

void mapper_map_set_description	(	mapper_map	map,
		const char *	description
	)

Set the description property for a specific map. Changes to remote maps will not take effect until synchronized with the network using mapper_map_push().

Parameters

map	The map to modify.
description	The description value to set.

mapper_map_set_expression()

void mapper_map_set_expression	(	mapper_map	map,
		const char *	expression
	)

Set the expression property for a specific map. Changes to remote maps will not take effect until synchronized with the network using mapper_map_push().

Parameters

map	The map to modify.
expression	A string specifying an expression to be evaluated by the map.

mapper_map_set_mode()

void mapper_map_set_mode	(	mapper_map	map,
		mapper_mode	mode
	)

Set the mode property for a specific map. Changes to remote maps will not take effect until synchronized with the network using mapper_map_push().

Parameters

map	The map to modify.
mode	The mode value to set, can be MAPPER_MODE_EXPRESSION, MAPPER_MODE_LINEAR.

mapper_map_set_muted()

void mapper_map_set_muted	(	mapper_map	map,
		int	muted
	)

Set the muted property for a specific map. Changes to remote maps will not take effect until synchronized with the network using mapper_map_push().

Parameters

map	The map to modify.
muted	1 to mute this map, or 0 unmute.

mapper_map_set_process_location()

void mapper_map_set_process_location	(	mapper_map	map,
		mapper_location	location
	)

Set the process location property for this Map. Depending on the Map topology and expression specified it may not be possible to set the process location to MAPPER_LOC_SOURCE for all maps. E.g. for "convergent" topologies or for processing expressions that use historical values of the destination signal, libmapper will force processing to take place at the destination device. Changes to remote maps will not take effect until synchronized with the network using mapper_map_push().

Parameters

map	The map to modify.
location	MAPPER_LOC_SOURCE to indicate processing should be handled by the source device, MAPPER_LOC_DESTINATION for the destination.

mapper_map_set_property()

int mapper_map_set_property	(	mapper_map	map,
		const char *	name,
		int	length,
		char	type,
		const void *	value,
		int	publish
	)

Set an arbitrary property for a specific map. Changes to remote maps will not take effect until synchronized with the network using mapper_map_push().

Parameters

map	The map to modify.
name	The name of the property to add.
length	The length of value array.
type	The property datatype.
value	An array of property values.
publish	1 to publish property to network, 0 for local-only.

Returns

1 if property has been changed, 0 otherwise.

mapper_map_set_protocol()

void mapper_map_set_protocol	(	mapper_map	map,
		mapper_protocol	proto
	)

Set the network protocol property for a specific map. Changes to remote maps will not take effect until synchronized with the network using mapper_map_push().

Parameters

map	The map to modify.
proto	MAPPER_PROTO_UDP or MAPPER_PROTO_TCP.

mapper_map_set_user_data()

void mapper_map_set_user_data	(	mapper_map	map,
		const void *	user_data
	)

Associate a map with an arbitrary pointer.

Parameters

map	The map to operate on.
user_data	A pointer to user data to be associated.

mapper_map_slot()

mapper_slot mapper_map_slot	(	mapper_map	map,
		mapper_location	loc,
		int	index
	)

Retrieve a slot for a specific map.

Parameters

map	The map to check.
loc	The map endpoint, must be MAPPER_LOC_SOURCE or MAPPER_LOC_DESTINATION.
index	The slot index.

Returns

The slot, or NULL if not available.

mapper_map_slot_by_signal()

mapper_slot mapper_map_slot_by_signal	(	mapper_map	map,
		mapper_signal	sig
	)

Get the map slot matching a specific signal.

Parameters

map	The map to check.
sig	The signal corresponding to the desired slot.

Returns

The slot, or NULL if not found.

mapper_map_user_data()

void* mapper_map_user_data

(

mapper_map

map

)

Retrieve the arbitrary pointer associated with a map.

Parameters

map	The map to operate on.

Returns

A pointer associated with this map.