RTcmix version 3.0 adds a major feature: the ability to route signals
between instruments and to multiple outputs. A new instrument by Dave
Topper, MIXN, takes full advantage of multiple outputs.



Bus architecture
----------------

Formerly, all instruments added their output into one master mix bus.
Now you can tell an instrument to send its output into an intermediate
bus, called an "aux" bus, and to take its input from another aux bus.
This lets you create a chain of instruments. For example, you could
send the output of WAVETABLE into FLANGE, and then send the output
of FLANGE into REVERBIT. In addition to instrument chaining, RTcmix
lets you make full use of multi-channel audio cards. You can route
STEREO to outputs 0 and 1, while routing FILTSWEEP to outputs 2 and 3.



The bus_config Minc function
----------------------------

There are three types of bus:

  "in"   input from file or from real-time audio source (e.g., mic)
  "aux"  intermediate bus, functioning as either an input or an output
  "out"  output to a file or to the sound card

You configure the arrangement of buses with a new Minc function,
bus_config. This associates an instrument name with a set of buses.
Every call to the instrument following its bus_config uses this bus
configuration. It's possible to change this with another call to
bus_config, which overrides the first (in the manner of makegen).

The first argument to bus_config is the name of the instrument, in
double quotes. Following that are any number of bus specification
strings, which combine the name of a bus type ("in", "out") with a
bus number or range of numbers. Buses are numbered from zero. Since
an aux bus can be an input or an output, you have to say which.

Some examples (the quotes are obligatory):

   bus_config("WAVETABLE", "out 0-1")

      This sends the output of subsequent WAVETABLE calls to the
      first two channels of the sound card (or to a file, if rtoutput
      has been called).

   bus_config("WAVETABLE", "out 0", "out 1")

      This means the same thing.

   bus_config("WAVETABLE", "out 3", "out 7")

      Output goes to channels 3 and 7 (counting from zero).

   bus_config("WAVETABLE", "aux 0-1 out")

      Output goes to aux buses 0 and 1. Unless another instrument reads
      these and sends output to the sound card, you'll hear nothing.

   bus_config("INPUTSIG", "aux 4-5 in", "out 0-1")

      Input comes from aux buses 4 and 5; output goes to channels 0 
      and 1 of the sound card (or rtoutput file).

      (Notice that the instrument name is not the family name ("IIR"),
      but the name of the function you call to make sound. Same thing
      goes for the STRUM family.)

   bus_config("FILTSWEEP", "aux 2 in", "aux 5 in", "aux 1 out", "aux 7 out")

      Reads from aux buses 2 and 5; writes to aux buses 1 and 7.

   bus_config("STEREO", "in 0", "out 0-1")

      You'd think this would read from channel 0 of an input file, even
      if the file has more channels. But RTcmix insists on reading all
      channels from a file. (See below for more about this inconsistency.)
      If the last rtinput call gives the source as "MIC", then the inst
      does read just from the first channel.


There are 16 "aux" buses available (defined as MAXBUS in H/bus.h). You
set the maximum number of "out" buses in the call to rtsetparams. 

If you don't call bus_config before using an instrument, you'll get
a default configuration roughly equal to:

   bus_config("FOO", "in 0-1", "out 0-1")

Currently it is not possible to read from both an "in" bus and an "aux"
bus in the same instrument. Nor is it possible to write to both an "out"
bus and an "aux" bus. This restriction will be removed later.



An inconsistency for file input
-------------------------------

Executive summary:
When reading from a file, RTcmix ignores the bus numbers you use with
the "in" bus in the call to bus_config. Instead, it reads all the
channels in the file. This behavior may change in a future version.

More detail:
"Aux" buses and real-time "in" buses (e.g., mic) are shared among all
instruments using them. Unlike these, sound file input buses are not
shared between instruments. They aren't really buses at all, but private
buffers. That's because instrument calls will often read from different
parts of a file, so it would make no sense for them to share file buses.
So we have an inconsistency in bus_config. When you specify that an
instrument reads from "in" buses, and you make it read -- via rtinput --
from a file rather than a real-time source, then RTcmix will ignore the
bus numbers you give bus_config, and will read all the channels in the
file. Note that many instruments have an  pfield to let you say
which channel you want.

It's possible that this scheme will change in the future.



Some constraints on reading from an aux bus
-------------------------------------------

A call to an instrument reading from a real-time audio source, whether it
be an aux bus or microphone input, MUST use an inskip of zero. You can't
read a segment of sound that hasn't happened yet!

Also, some instruments just won't work well (or at all) when reading from
a real-time source. TRANS is an example of this. When it transposes up an
octave, it has to consume two samples for every output sample. So it will
always be left gasping for more input.  When it transposes down, it has
no way of keeping the ever-lengthening history of samples it would need
to generate output.


(For instruments that need to look into the future by a constant interval,
like COMPLIMIT with non-zero lookahead, the instrument merely delays its
output enough to "catch up" with its input.)



For instrument designers
------------------------

Please see "README.inst_porting" for instructions on making your instruments
compatible with this version of RTcmix.





John Gibson
Dave Topper