Using Probes

A Probe is an item that gives a program access to the output of a DSP instrument. It is sort of like the opposite of a knob. Multiple probes can be connected to a single output. A probe does not interfere with a connection between instruments.

Creating Probes

You can create a probe for any named output of any DSP instrument using this call:

Item CreateProbe( Item Instrument, const char *Name, const TagArg *Tags )

Item CreateProbeVA( Item Instrument, const char *Name, uint32 tag1, ... )

CreateProbe() accepts three arguments: Item, the Item number of the instrument; Name, the name of the output; and Tags, which should be a NULL pointer because there are currently no tag arguments defined for Probes. The call creates a Probe item that provides a fast connection between a task and one of an instrument's outputs. You can then call ReadProbe() to poll the value of output. When you finish with the probe item, you should call DeleteProbe() to deallocate the item.

CreateProbe() returns the item number of the probe if successful, or an error code (a negative value) if an error occurs.

Reading Probes

You can read the most recent value of an output for which you have created a Probe. To do so, use the ReadProbe() call:

Err ReadProbe( Item ProbeItem, int32 *ValuePtr )

The call accepts two arguments: ProbeItem, the Item number of the knob to be tweaked; and ValuePtr, a pointer to where to put result. The task must have write permission for the address specified by ValuePtr.

ReadProbe() reads the instantaneous value of an instrument output. It is useful for reading the output of slowly changing instruments such as envelope.dsp, envfollower.dsp, minimum.dsp, and maximum.dsp. It replaces the now obsolete function DSPReadEO().

ReadProbe() returns a non-negative value if successful, or an error code ( a negative value) if unsuccessful.

Deleting Probes

When you are finished using a Probe, you should delete it with this call:

Err DeleteProbe( Item ProbeItem )

The call accepts one argument: ProbeItem, the Item number of the Probe to delete. DeleteProbe() deletes the probe item created by CreateProbe(), freeing its resource and disconnecting the task that created the probe item from the instrument containing the probe.

DeleteProbe() returns a non-negative value if successful, or an error code ( a negative value) if an error occurs.