NAME

makemonitor - create and use a window to display PField data from pfield-handle or table-handle (or similar derived PField) variable, or capture PField data into a file.

SYNOPSIS

pfield = makemonitor(input_handle, "monitor_type", arg1, arg2, ...)

DESCRIPTION

makemonitor is a utility command used to set up a mechanism for viewing or recording data from a PField variable, the input_handle. The monitor_type determines which 'monitoring' operation will be performed. The arguments vary depending on each monitor_type.

ARGUMENTS

input_handle: This is pfield-handle variable referring to a data stream, possibly from an external device or interface or an internal PField data-generating process.
monitor_type: This string value (i.e. enclosed in "double quotes" in the scorefile) determines what kind of monitor will be used record or view the values coming through the input_handle. The pfield-handle returned from the makemonitor command will pass the data from the input_handle data stream unchanged.
arg1, arg2, ...: The arguments that are relevant for each monitor type. See documentation for each type below.

Monitor Types

datafile

This will record the values coming through the input_handle variable into a file. The syntax is:


pfield = makemonitor(input_pfield, "datafile", filename,
   [filerate[, format]])

This will open the file filename for writing, attaching an appropriate header containing information relevant to the interpretation of the file data. This header can be read by the RTcmix makeconnection scorefile command, or an external program can access the header fields. As the RTcmix score executes, data coming through the input_pfield variable will be stored into the file. The rate for writing data is the control reset rate (default 1000 times/second, this is set in the score by the RTcmix reset scorefile command), or it can be set independently using the optional filerate parameter. The default data format for the file is to store information in floating-point form ("float"). This can be set using the optional format parameter. Valid formats are "double", "float", "int64", "int32", "int16" or "byte".

RTcmix also has a built-in safeguard to prevent overwriting existing files. This feature is enabled/disabled using the set_option command. The default is to not allow overwriting of a file.

Note that using a filerate greater than the scorefile control reset rate will result in redundant data. Large values for filerate or the control reset rate are inefficient and will impact RTcmix performance.

display

This monitor type is used to create and use a window to display streaming PField data from a pfield-handle or table-handle (or similar derived PField) variable. The syntax is:


pfield = makemonitor(input_pfield, "display"[,
   "prefix"[, "units",]] [precision])"

The input_pfield is the PField stream that will be displayed in the window. This can be any PField-derived variable, such as a pfield-handle or table-handle. The optional arguments prefix, units and precision determine how the data will be printed in the widow. prefix is a string argument that will specify the label to display in the window for the input_pfield variable. If prefix is missing or is an empty string ("") then no label will be printed in the window. units is an optional string argument to set the 'units' (i.e. "Hz" or "MIDI note") to appear with the input_pfield data displayed. This option is only available if the prefix argument has been set. The precision is the number of digits after the decimal point to display in the window.

EXAMPLES

   xval = makeconnection("mouse", "x", 0, 100, 50, lag=50)
   makemonitor(xval, "display", "x-value", "pts")