makeconnection - establish a control connection to an external device or process
pfield = makeconnection("connection_type"[, arg1, arg2, ...])
Parameters inside the [brackets] are optional.
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.
pfield = makeconnection("mouse", "axis", min, max, default, lag[, "prefix"[, "units"], precision])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:
Note that if min and max are inverted, the mouse
will deliver values 'backwards'.
pfield = makeconnection("midi", min, max, default, lag, chan, "type"[, "subtype"])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:
Note that if min and max are inverted, the mouse
will deliver values 'backwards'.
value MIDI data --------------------------------------------------------------- "noteonpitch" MIDI note # for noteon events "noteonvel" MIDI velocity for noteon events "noteooffpitch" MIDI note # for noteoff events "noteoffvel" MIDI velocity for noteoff events "cntl" use "subtype" to specify which MIDI controller to use "prog" MIDI program change # "bend" MIDI pitch-bend data "chanpress" MIDI channel change value "polypress" use "subtype" somehow
subtype MIDI controller --------------------------------------------------------------- "mod" modulator wheel "foot" foot pedal "breath" breath controller "data" data slider "volume" volume slider "pan" pan silder
If type is set to "polypress", then somehow a MIDI note number is used for something.
pfield = makeconnection("datafile", "filename", lag, [skiptime[, timefactor[, filerate, format, swap]]])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:
pfield = makeconnection("inlet", inlet_number, default)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.
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.
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.
maketable, makeLFO, makerandom, makefilter, makeconverter, makemonitor