# Mixer Actor

## Introduction

The mixer actor is a process actor that takes in multiple inputs and generates their linear combination for mixing purposes. It has two mixing modes: matrix and non-matrix. In non-matrix mode, all inputs are combined into one single (but may be multichannel) output, and the output is fed into the VSS main busses as any other actor, and is subject to SetPan and SetElev messages. This is the default mode.

In matrix mode, arbitrary combinations of mono inputs are sent to the output channels. The output channels directly correspond to VSS final output channels, i.e. the speakers. SetPan and SetElev are ignored. The dimension of the matrix can only be 2x2, 4x4 or 8x8, and cannot be greater than VSS channels.

## Usage

To use the mixer actor, load `mixer.so` and create an actor of type `MixerActor`. Then create a handler of the actor using `BeginSound`, and use the following messages to direct sound sources through the mixer. The maximum number of sources that can be mixed is currently set to 8.

## MixerActor messages

In addition to the messages understood by all generator actors, the MixerActor understands the following messages:

SetFaderAmp `hActor x`
  Set the default linear fader value for new instances created by this actor to the scalar `x`. Valid range is [-128,128].
SetFaderGain `hActor x`
  Set the default log fader value for new instances created by this actor to `x` dB. Valid range is (-Inf,42]. This log fader value is converted to linear value and stored in the variable for default linear fader value immediately. So SetFaderAmp and SetFaderGain override each other.
SetAllFaderAmp `hActor x time`
  Set the linear fader values of all children to `x`, and set the default value for all future children. If `time` is specified, children will modulate to the new value over the specified duration. Default value is always set immediately regardless of time.
SetAllFaderGain `hActor x time`
  Similar with SetAllFaderAmp. Same as SetFaderAmp and SetFaderGain, SetAllFaderAmp and SetAllFaderGain override each other.

## MixerActor handler messages

In addition to the messages understood by all handlers, the handler for the MixerActor understands the following messages:

SetNumberOfInputs `hHandler x`
  Set the total number of input sources feeding into the mixer `hHandler` to be `x`. The mixer will then sum its mixing channel 1 to `x`. Valid range is [1,8].
SetAllInputs `hHandler [hSound0 hSound1 ...]`
  Set the input sources for all mixing channels of the mixer handler `hHandler`. The number of sources should match the number set by SetNumberOfInputs. Use a special source name "-1" to keep the current source of the corresponding channel unchanged.
SetAllFaderAmp `hHandler [x0 x1 ...] time`
SetAllFaderGain `hHandler [x0 x1 ...] time`
  Set the linear/log fader values of all mixing channels (different from the mixer actor messages with the same names). The number of sources should match the number set by SetNumberOfInputs. Use a special value of 1000 (both for SetFaderAmp and SetFaderGain) to keep the current fader value of the corresponding channel unchanged. If `time` is specified, VSS will modulate to the new values over the specified duration.

The following messages deal with one specific channel:

SetOneChannelAmp `hHandler channel source x time`
SetOneChannelGain `hHandler channel source x time`
  Set the input source of `channel` to `source`, then set the linear/log fader value of the `channel` to x. If `time` is specified, VSS will modulate to the new value over the specified duration.
SetChannelNum `hHandler x`
  Set the number of channel to be used for later messages including SetOneInput, SetOneFaderAmp and SetOneFaderGain, to of the handler `hHandler` to be `x`. All following SetOne* messages will operate on that channel until a new channel number is set by SetChannelNum. Valid range is [1,8].
SetOneInput `hHandler hSound`
  Set the input source of current mixing channel to one sound source handler `hSound for` the mixer handler `hHandler`. If no `hSound` is specified, that channel will use a null source thus produce no output.
SetOneFaderAmp `hHandler channel x time`
SetOneFaderGain `hHandler channel x time`
  Set the linear/log fader value of the `channel`, or the current mixing channel if `channel` isn't specified, to x. If `time` is specified, VSS will modulate to the new value over the specified duration.
SetNumberOfInputs `hHandler x`
  This is the same message mentioned above. User should note that the number of inputs will be set to the number of parameters provided in each SetAll* message. So if a later SetOne* message is going to use a higher-numbered channel, SetNumberOfInputs must be used in order to include that channel into mixer output. For example, the following sequence of messages are valid (hMixer and h1-h6 are existing actor handlers):
  `SetNumberOfInputs hMixer 3;
  SetAllInputs hMixer [h1 h2 h3];
  SetAllFaderAmp hMixer [.2 .4 .6];
  SetNumberOfInputs hMixer 6;
  SetOneChannelGain hMixer 4 h4 .9 5;
  SetChannelNum hMixer 5;
  SetOneInput hMixer h5;
  SetOneFaderAmp hMixer .1;
  SetOneInput hMixer h6;
  SetOneFaderGain hMixer 6 .5 10;
  `

The following messages deal with matrix mode:

SetMatrixMode `hHandler boolean`
  Set matrix mode to `boolean`. Default to 0.
SetMatrixInRow `hHandler input_channel [x] time`
  Set one fader matrix row that corresponds to input_channel to array `x`, i.e. to specify the amplitudes of the input in input_channel to be sent to all output channels. If time is specified, modulate to the new values over that period.
SetMatrixOutCol `hHandler output_channel [x] time`
  Set one fader matrix column that corresponds to output_channel to array `x`, i.e. to specify the amplitudes of all the inputs to be sent to output_channel. If time is specified, modulate to the new values over that period.