NAME

makeconnection - establish a control connection to an external device or process


SYNOPSIS

pfield = makeconnection("connection_type"[, arg1, arg2, ...])

Parameters inside the [brackets] are optional.


DESCRIPTION

makeconnection is a utility command used to associate data coming from "outside" RTcmix with a pfield-handle variable. This variable can then be used to deliver values to an Instrument during scorefile execution. This is very similar to the mechanism used by the maketable scorefile command to deliver table data to Instruments through table-handle variables. Indeed, table-handles and pfield-handles are nearly identical in terms of scorefile use and behavior. The main difference is that table-handle variables are accessing values from a previously-created table, while pfield-handle variables are funneling (in real-time) data from some external process of device into RTcmix.

This is almost the inverse of how the 'imbedded' RTcmix object works. The RTcmix object can be used inside another application, with all interface tasks mediated through the "wrapping" application. RTcmix is a subsidiary object in this case. makeconnection allows an interface application to be developed within RTcmix, with the interface code existing as a PField class object. Interfaces can then be "connected" to control different Instrument/note parameters through a pfield-handle.

Because device and interface characteristics can vary widely, the syntax of a makeconnection command will also be relatively unique for particular interfaces. At present, three different connection_type interfaces are included in RTcmix.

Many of the arguments for makeconnection may themselves also be pfield-handles.


ARGUMENTS
"connection_type"
This string value (i.e. enclosed in "double quotes" in the scorefile) determines the device or interface that will be associated with the pfield-handle returned by makeconnection. Currently three different connection_types are included in the RTcmix distribution, "mouse", "midi", "datafile", and "inlet" (in the Max/MSP rtcmix~ object distribution). Each connection_type used loads a library containing the interface code. These libraries should be in the RTcmix/shlib/ directory or some other directory on the RTcmix dynamic-loading search path. The default RTcmix installation procedure should set this up properly.

arg1, arg2, ...
Any number of arguments that are needed to set up the interface/device connection. These depend on the connection type. See documentation for each type below.


Connection Types

mouse
This establishes a PField variable that will draw data from the mouse screen position. The syntax is: This will cause a window to be displayed, and movement of the mouse relative to that window will be tracked. An executing note using the pfield variable as an Instrument parameter will draw data from the position of the mouse to provide the values for that parameter. More than one parameter or Instrument may be controlled simultaneously, depending on how the connections are specified in the scorefile. The other arguments determine how the mouse data will be set and interpreted:

midi
This establishes a PField variable that will accept data from an attached MIDI interface. The syntax is: An executing note using the pfield variable as an Instrument parameter will draw data from a MIDI controller attached to a MIDI interface to provide the values for that parameter. As with the "mouse" connection type, more than one parameter or Instrument may be controlled simultaneously, depending on how the connections are specified in the scorefile. The other arguments establish which MIDI channel and parameter will be monitored and determine how the MIDI data will be interpreted:

datafile
This establishes a PField variable that will read control data from an existing datafile, probably created using the makemonitor scorefile command. The syntax is: This will open the file filename for reading. An executing note using the pfield variable as an Instrument parameter will draw data from the file to provide the values for that parameter. More than one parameter or Instrument may be controlled simultaneously, depending on how the connections are specified in the scorefile. The arguments determine how the file will be opened and read:

inlet (Max/MSP rtcmix~ only)
This establishes a PField variable that will read data coming from an 'inlet' on the Max/MSP rtcmix~ object. The syntax is: An executing note using the pfield variable as an Instrument parameter will draw data from a max-patch through one of the rtcmix~ object inlets. As with the "mouse" and "midi" connection types, more than one parameter or Instrument may be controlled simultaneously, depending on how the connections are specified in the scorefile. Please refer to the rtcmix~ object help-patch for more information on how this connection type is used.


EXAMPLES
   pan = makeconnection("mouse", "x", 1, 0, .5, lag=50, "pan")
   deltime = makeconnection("mouse", "x", 0.0002, .5, .5, lag=90, "delay time", "", 5)
   feedback = makeconnection("mouse", "y", 0, 1, 0, lag=20, "feedback")
   DELAY(0, 0, 10, 1.0, deltime, feedback, 1.0, 0, pan)
This scorefile uses three different pfield-handle variables: pan, deltime and feedback. pan and deltime are controlled by the 'x' position of the mouse, scaled by the min and max values for each ([1, 0], [0.0002, 0.5]). The deltime parameter is set with a high lag percentage to prevent glitching as the delay-time of the DELAY instrument is changed. The feedback parameter tracks the 'y' position of the mouse, scaling values between 0 and 1. Notice that these pfield-handle variables function in the same way that maketable table-handle variables do.

See the RTcmix/docs/sample_scores/dynamic_insts/ subdirectory in the RTcmix distrubition for more examples of different connection types.


NOTES

The makeconnection command will dynamically-load the library containing the interface code used for each connection type. For example:

   makeconnection("mouse", ...)
will look for the dynamic library libmouse.so. As discussed above, this library needs to be locatable along the RTcmix library search path. The default RTcmix installation will compile and install this library into the RTcmix/shlib/ directory.


SEE ALSO

maketable, makeLFO, makerandom, makefilter, makeconverter, makemonitor