Connecting Instruments

After you have created and set instruments, you can connect them together for combined effects such as applying an envelope from envelope.dsp to the amplitude of another instrument. You can connect instruments together to mix sounds, such as combining a sawtooth instrument and a sampled sound instrument in a submixer. And you can connect instruments to a mixer so their audio signals are fed to the DAC, a necessary step if the instrument is to be heard at all.

Connecting One Instrument to Another

When you connect one instrument to another, you can connect one output of the first instrument to either an input or a knob of the second instrument. When an output of one instrument is connected to an input of a second, the second instrument usually acts upon the incoming signal from the first instrument. For example, if a sampled sound player is connected to an input of a mixer, the mixer mixes the sampled sound output with other audio signals and puts out the mix to the DAC.

When an output of one instrument is connected to a knob of a second, the second instrument usually acts according to the incoming signal from the first instrument. For example, a slowly oscillating triangle wave generator connected to the frequency knob of a sawtooth generator causes the sawtooth generator to create a sawtooth wave that moves up and down in pitch.

To connect an output of one instrument to an input or knob of a second instrument, use this call:

Err ConnectInstruments( Item SrcIns, char *SrcName, Item DstIns, char *DstName )

The call accepts four arguments. The first, SrcIns, is the item number of the source instrument (the first instrument). The second, *SrcName, is a pointer to a string containing the name of the source instrument's output used for connection. The third, DstIns, is the item number of the destination instrument (the second instrument). And the fourth, *DstName, is a pointer to a string containing the name of the destination instrument's input or knob used for connection.

When setting the parameter values for ConnectInstruments(), the names for each of an instrument's outputs, inputs, and knobs are listed in Instrument Templates, in the 3DO Music and Audio Programmer's Reference.

When ConnectInstruments() executes, it connects the specified output of the source instrument to the specified input or knob of the destination instrument. If successful, it returns 0. If unsuccessful, it returns a negative value (an error code).

Note that if you connect a source instrument's output to a knob of the destination instrument, that knob is no longer available for tweaking by a task (using TweakKnob() or StartInstrument() tag arguments, both described in Playing Instruments) until the source instrument is disconnected.

Disconnecting One Instrument From Another

To disconnect a source instrument's output from a destination instrument's input or knob, use this call:

Err DisconnectInstruments( Item SrcIns, char *SrcName, Item DstIns, char *DstName )

This call accepts the same four arguments as ConnectInstruments() accepts. They specify an output on the source instrument and an input or knob on the destination instrument.

When it executes, DisconnectInstruments() breaks the specified connection. It returns 0 if successful, and a negative value (an error code) if unsuccessful.

Once the connection to a knob is broken, the knob is unavailable for tweaking.