# 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.