mapper::Device Class Reference

#include <mapper_cpp.h>

Inheritance diagram for mapper::Device:

Public Member Functions
	Device (const str_type &name, const Graph &graph)
	Device (const str_type &name)
Signal	add_signal (Direction dir, const str_type &name, unsigned int len, Type type, const str_type &unit=0, void *min=0, void *max=0, int *num_inst=0)
Device &	remove_signal (Signal &sig)
List< Signal >	signals (Direction dir=Direction::ANY) const
List< Map >	maps (Direction dir=Direction::ANY) const
int	poll (int block_ms=0) const
Device &	start (int block_ms=100)
Device &	stop ()
bool	ready () const
Time	get_time ()
Device &	set_time (Time time)
Device &	update_maps ()
const Device &	push () const
Public Member Functions inherited from mapper::Object
	operator bool () const
Type	type () const
Graph	graph () const
int	get_status () const
Object &	reset_status ()
template<typename... Values>
Object &	set_property (const Values... vals)
template<typename... Values>
Object &	set_local_property (const Values... vals)
virtual Object &	remove_property (Property prop)
virtual Object &	remove_property (const str_type &key)
int	num_props (bool staged=false) const
PropVal	property (const str_type &key=NULL) const
PropVal	property (Property prop) const
PropVal	property (int idx) const

Additional Inherited Members
Public Types inherited from mapper::Object
enum class	Status {   UNDEFINED = MPR_STATUS_UNDEFINED , EXPIRED = MPR_STATUS_EXPIRED , NEW = MPR_STATUS_NEW , MODIFIED = MPR_STATUS_MODIFIED ,   STAGED = MPR_STATUS_STAGED , ACTIVE = MPR_STATUS_ACTIVE , REMOVED = MPR_STATUS_REMOVED , HAS_VALUE = MPR_STATUS_HAS_VALUE ,   NEW_VALUE = MPR_STATUS_NEW_VALUE , UPDATE_LOC = MPR_STATUS_UPDATE_LOC , UPDATE_REM = MPR_STATUS_UPDATE_REM , REL_UPSTRM = MPR_STATUS_REL_UPSTRM ,   REL_DNSTRM = MPR_STATUS_REL_DNSTRM , INST_OFLW = MPR_STATUS_OVERFLOW , ANY = MPR_STATUS_ANY }
Protected Member Functions inherited from mapper::Object
Protected Attributes inherited from mapper::Object

Detailed Description

A Device is an entity on the network which has input and/or output Signals. The Device is the primary interface through which a program uses libmapper. A Device must have a name, to which a unique ordinal is subsequently appended. It can also be given other user-specified metadata. Signals can be mapped using local code or messages over the network, usually sent from an external GUI.

Constructor & Destructor Documentation

Device() [1/2]

mapper::Device::Device ( const str_type & name, const Graph & graph )

inline

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 object to use.

Device() [2/2]

mapper::Device::Device ( const str_type & name )

inline

Allocate and initialize a Device.

Parameters

name	A short descriptive string to identify the Device. Must not contain spaces or the slash character '/'.

Member Function Documentation

add_signal()

Signal mapper::Device::add_signal ( Direction dir, const str_type & name, unsigned int len, Type type, const str_type & unit = 0, void * min = 0, void * max = 0, int * num_inst = 0 )

inline

Add a Signal to this Device.

Parameters

dir	Directionality of the signal to create. Must be either Direction::INCOMING or Direction::OUTGOING.
name	A descriptive name for the signal.
len	Vector length for the signal.
type	Data type for the signal (INT32, FLOAT, or DOUBLE).
unit	Descriptive unit for the signal (optional).
min	Minimum value for the signal (optional). Must point to an array of length and type specified by the len and type arguments.
max	maximum value for the signal (optional). Must point to an array of length and type specified by the len and type arguments.
num_inst	The number of instances to be allocated for the signal. For singleton (non-instanced) signals pass NULL for this argument, otherwise provide the number of instances to pre-allocate. Additional instances may be allocated later using Signal::reserve_instances().

Returns

A newly allocated Signal.

get_time()

Time mapper::Device::get_time ( )

inline

Get the current time for a device.

Returns

The current time.

maps()

List< Map > mapper::Device::maps ( Direction dir = Direction::ANY ) const

inline

Get a list of Maps involving this Device.

Parameters

dir	The directionality of the Maps (with reference to the Device) to include in the list. Use Direction::ANY to include all Maps.

Returns

A List of Maps.

poll()

int mapper::Device::poll ( int block_ms = 0 ) const

inline

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

block_ms

The number of milliseconds to block, or 0 for non-blocking behavior.

Returns

The number of handled messages.

push()

const Device & mapper::Device::push ( ) const

inlinevirtual

Push "staged" property changes out to the distributed graph.

Returns

Self.

Reimplemented from mapper::Object.

ready()

bool mapper::Device::ready ( ) const

inline

Detect whether a device is completely initialized.

Returns

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

remove_signal()

Device & mapper::Device::remove_signal ( Signal & sig )

inline

Remove and destroy a Signal from this Device.

Parameters

sig	The signal to remove.

Returns

Self.

set_time()

Device & mapper::Device::set_time ( Time time )

inline

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

Parameters

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().

Returns

Self.

signals()

List< Signal > mapper::Device::signals ( Direction dir = Direction::ANY ) const

inline

Get a list of Signals belonging to this Device.

Parameters

dir	The directionality of the Signals to include in the list. Use Direction::ANY to include all Signals.

Returns

A List of Signals.

start()

Device & mapper::Device::start ( int block_ms = 100 )

inline

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

Parameters

block_ms

The number of milliseconds to block on each iteration, or <0 to process all incoming messages.

Returns

Self.

stop()

Device & mapper::Device::stop ( )

inline

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

Returns

Self.

update_maps()

Device & mapper::Device::update_maps ( )

inline

Indicate that all signal values have been updated for a given timestep. This function can be omitted if poll() is called each sampling timestep, however calling poll() at a lower rate may be more performant.

Returns

Self.