# 7. Core API Reference | DSPConnection

An interface that manages Digital Signal Processor (DSP) Connections

Mix Properties:

- DSPConnection::setMix Sets the connection's volume scale.
- DSPConnection::getMix Retrieves the connection's volume scale.
- DSPConnection::setMixMatrix Sets a 2 dimensional pan matrix that maps the signal from input channels (columns) to output speakers (rows).
- DSPConnection::getMixMatrix Retrieves a 2 dimensional pan matrix that maps the signal from input channels (columns) to output speakers (rows).

General:

- DSPConnection::getInput Retrieves the connection's input DSP unit.
- DSPConnection::getOutput Retrieves the connection's output DSP unit.
- DSPConnection::getType Retrieves the type of the connection between 2 DSP units.
- DSPConnection::setUserData Sets a user value associated with this object.
- DSPConnection::getUserData Retrieves a user value associated with this object.

- FMOD_DSPCONNECTION_TYPE List of connection types between 2 DSP nodes.

## DSPConnection::getInput

Retrieves the connection's input DSP unit.

C
C++
C#
JS

    FMOD_RESULT DSPConnection::getInput(
      DSP **input
    );

    FMOD_RESULT FMOD_DSPConnection_GetInput(
      FMOD_DSPCONNECTION *dspconnection,
      FMOD_DSP **input
    );

    RESULT DSPConnection.getInput(
      out DSP input
    );

    DSPConnection.getInput(
      input
    );

input Out
  Input DSP unit. (DSP)

If DSP::addInput was just called, the connection might not be ready because the DSP system is still queued to be connected, and may need to wait several milliseconds for the next mix to occur. If so the function will return FMOD_ERR_NOTREADY and `input` will be null.

See Also: DSPConnection::getOutput, DSP::addInput

## DSPConnection::getMix

Retrieves the connection's volume scale.

C
C++
C#
JS

    FMOD_RESULT DSPConnection::getMix(
      float *volume
    );

    FMOD_RESULT FMOD_DSPConnection_GetMix(
      FMOD_DSPCONNECTION *dspconnection,
      float *volume
    );

    RESULT DSPConnection.getMix(
      out float volume
    );

    DSPConnection.getMix(
      volume
    );

volume Out

  Volume scale applied to the input before being passed to the output. 0 = silent, 1 = full. Negative level inverts the signal. Values larger than 1 amplify the signal.

  - Units: Linear
  - Range: (-inf, inf)
  - Default: 1

See Also: DSPConnection::setMix

## DSPConnection::getMixMatrix

Retrieves a 2 dimensional pan matrix that maps the signal from input channels (columns) to output speakers (rows).

C
C++
C#
JS

    FMOD_RESULT DSPConnection::getMixMatrix(
      float *matrix,
      int *outchannels,
      int *inchannels,
      int inchannel_hop = 0
    );

    FMOD_RESULT FMOD_DSPConnection_GetMixMatrix(
      FMOD_DSPCONNECTION *dspconnection,
      float *matrix,
      int *outchannels,
      int *inchannels,
      int inchannel_hop
    );

    RESULT DSPConnection.getMixMatrix(
      float[] matrix,
      out int outchannels,
      out int inchannels,
      int inchannel_hop = 0
    );

    DSPConnection.getMixMatrix(
      matrix,
      outchannels,
      inchannels,
      inchannel_hop
    );

matrix Out Opt

  Two dimensional array of volume levels in row-major order. Each row represents an output speaker, each column represents an input channel. Passing null or equivalent as the matrix allows querying of `outchannels` and `inchannels`.

  - Units: Linear
  - Range: (-inf, inf)
outchannels Out Opt
  Number of valid output channels (rows) in `matrix`. Optional only when `matrix` is null or equivalent.
inchannels Out Opt
  Number of valid input channels (columns) in `matrix`. Optional only when `matrix` is null or equivalent.
inchannel_hop Opt
  Width (total number of columns) in destination `matrix`. Can be larger than `inchannels` to represent a smaller valid region inside a larger matrix.

A matrix element is referenced from the incoming matrix data as `outchannel * inchannel_hop + inchannel`.

See Also: DSPConnection::setMixMatrix

## DSPConnection::getOutput

Retrieves the connection's output DSP unit.

C
C++
C#
JS

    FMOD_RESULT DSPConnection::getOutput(
      DSP **output
    );

    FMOD_RESULT FMOD_DSPConnection_GetOutput(
      FMOD_DSPCONNECTION *dspconnection,
      FMOD_DSP **output
    );

    RESULT DSPConnection.getOutput(
      out DSP output
    );

    DSPConnection.getOutput(
      output
    );

output Out
  Output DSP unit. (DSP)

If DSP::addInput was just called, the connection might not be ready because the DSP system is still queued to be connected, and may need to wait several milliseconds for the next mix to occur. If so the function will return FMOD_ERR_NOTREADY and `output` will be null.

See Also: DSPConnection::getInput, DSP::addInput

## DSPConnection::getType

Retrieves the type of the connection between 2 DSP units.

C
C++
C#
JS

    FMOD_RESULT DSPConnection::getType(
      FMOD_DSPCONNECTION_TYPE *type
    );

    FMOD_RESULT FMOD_DSPConnection_GetType(
      FMOD_DSPCONNECTION *dspconnection,
      FMOD_DSPCONNECTION_TYPE *type
    );

    RESULT DSPConnection.getType(
      out DSPCONNECTION_TYPE type
    );

    DSPConnection.getType(
      type
    );

type Out
  Type of connection. (FMOD_DSPCONNECTION_TYPE)

## DSPConnection::getUserData

Retrieves a user value associated with this object.

C
C++
C#
JS

    FMOD_RESULT DSPConnection::getUserData(
      void **userdata
    );

    FMOD_RESULT FMOD_DSPConnection_GetUserData(
      FMOD_DSPCONNECTION *dspconnection,
      void **userdata
    );

    RESULT DSPConnection.getUserData(
      out IntPtr userdata
    );

    DSPConnection.getUserData(
      userdata
    );

userdata Out
  Value stored on this object.

See Also: DSPConnection::setUserData

## DSPConnection::setMix

Sets the connection's volume scale.

C
C++
C#
JS

    FMOD_RESULT DSPConnection::setMix(
      float volume
    );

    FMOD_RESULT FMOD_DSPConnection_SetMix(
      FMOD_DSPCONNECTION *dspconnection,
      float volume
    );

    RESULT DSPConnection.setMix(
      float volume
    );

    DSPConnection.setMix(
      volume
    );

volume

  Volume scale applied to the input before being passed to the output. 0 = silent, 1 = full. Negative level inverts the signal. Values larger than 1 amplify the signal.

  - Units: Linear
  - Range: (-inf, inf)
  - Default: 1

See Also: DSPConnection::getMix, DSPConnection::setMixMatrix, DSPConnection::getMixMatrix

## DSPConnection::setMixMatrix

Sets a 2 dimensional pan matrix that maps the signal from input channels (columns) to output speakers (rows).

C
C++
C#
JS

    FMOD_RESULT DSPConnection::setMixMatrix(
      float *matrix,
      int outchannels,
      int inchannels,
      int inchannel_hop = 0
    );

    FMOD_RESULT FMOD_DSPConnection_SetMixMatrix(
      FMOD_DSPCONNECTION *dspconnection,
      float *matrix,
      int outchannels,
      int inchannels,
      int inchannel_hop
    );

    RESULT DSPConnection.setMixMatrix(
      float[] matrix,
      int outchannels,
      int inchannels,
      int inchannel_hop = 0
    );

    DSPConnection.setMixMatrix(
      matrix,
      outchannels,
      inchannels,
      inchannel_hop
    );

matrix Opt

  Two dimensional array of volume levels in row-major order. Each row represents an output speaker, each column represents an input channel. Null or equivalent sets a 'default' matrix.

  - Units: Linear
  - Range: (-inf, inf)
outchannels

  Number of output channels (rows) in `matrix`.

  - Range: [0, FMOD_MAX_CHANNEL_WIDTH]
inchannels

  Number of input channels (columns) in `matrix`.

  - Range: [0, FMOD_MAX_CHANNEL_WIDTH]
inchannel_hop Opt
  Width (total number of columns) in source `matrix`. Can be larger than `inchannels` to represent a smaller valid region inside a larger matrix.

- Range: [0, FMOD_MAX_CHANNEL_WIDTH]
- Default: `inchannels`

A matrix element is referenced from the incoming matrix data as `outchannel * inchannel_hop + inchannel`.

If null or equivalent is passed in via `matrix` a default upmix, downmix, or unit matrix will take its place. A unit matrix allows a signal to pass through unchanged.

Example 5.1 unit matrix:

    1 0 0 0 0 0
    0 1 0 0 0 0
    0 0 1 0 0 0
    0 0 0 1 0 0
    0 0 0 0 1 0
    0 0 0 0 0 1

Matrix element values can be below 0 to invert a signal and above 1 to amplify the signal. Note that increasing the signal level too far may cause audible distortion.

See Also: DSPConnection::getMixMatrix

## DSPConnection::setUserData

Sets a user value associated with this object.

C
C++
C#
JS

    FMOD_RESULT DSPConnection::setUserData(
      void *userdata
    );

    FMOD_RESULT FMOD_DSPConnection_SetUserData(
      FMOD_DSPCONNECTION *dspconnection,
      void *userdata
    );

    RESULT DSPConnection.setUserData(
      IntPtr userdata
    );

    DSPConnection.setUserData(
      userdata
    );

userdata
  Value stored on this object.

Associates some data with this object to give it context, it can be retrieved with DSPConnection::getUserData but otherwise remain untouched.

See Also: DSPConnection::getUserData

## FMOD_DSPCONNECTION_TYPE

List of connection types between 2 DSP nodes.

C
C++
C#
JS

    typedef enum FMOD_DSPCONNECTION_TYPE {
      FMOD_DSPCONNECTION_TYPE_STANDARD,
      FMOD_DSPCONNECTION_TYPE_SIDECHAIN,
      FMOD_DSPCONNECTION_TYPE_SEND,
      FMOD_DSPCONNECTION_TYPE_SEND_SIDECHAIN,
      FMOD_DSPCONNECTION_TYPE_MAX
    } FMOD_DSPCONNECTION_TYPE;

    enum DSPCONNECTION_TYPE
    {
        STANDARD,
        SIDECHAIN,
        SEND,
        SEND_SIDECHAIN,
        MAX,
    }

    FMOD.DSPCONNECTION_TYPE_STANDARD
    FMOD.DSPCONNECTION_TYPE_SIDECHAIN
    FMOD.DSPCONNECTION_TYPE_SEND
    FMOD.DSPCONNECTION_TYPE_SEND_SIDECHAIN
    FMOD.DSPCONNECTION_TYPE_MAX

FMOD_DSPCONNECTION_TYPE_STANDARD
  Default connection type. Audio is mixed from the input to the output DSP's audible buffer.
FMOD_DSPCONNECTION_TYPE_SIDECHAIN
  Sidechain connection type. Audio is mixed from the input to the output DSP's sidechain buffer.
FMOD_DSPCONNECTION_TYPE_SEND
  Send connection type. Audio is mixed from the input to the output DSP's audible buffer, but the input is NOT executed, only copied from. A standard connection or sidechain needs to make an input execute to generate data.
FMOD_DSPCONNECTION_TYPE_SEND_SIDECHAIN
  Send sidechain connection type. Audio is mixed from the input to the output DSP's sidechain buffer, but the input is NOT executed, only copied from. A standard connection or sidechain needs to make an input execute to generate data.
FMOD_DSPCONNECTION_TYPE_MAX
  Maximum number of DSP connection types supported.

FMOD_DSP_CONNECTION_TYPE_STANDARD

Default DSPConnection type. Audio is mixed from the input to the output DSP's audible buffer, meaning it will be part of the audible signal. A standard connection will execute its input DSP if it has not been executed before.

FMOD_DSP_CONNECTION_TYPE_SIDECHAIN

Sidechain DSPConnection type. Audio is mixed from the input to the output DSP's sidechain buffer, meaning it will NOT be part of the audible signal. A sidechain connection will execute its input DSP if it has not been executed before.

The purpose of the seperate sidechain buffer in a DSP, is so that the DSP effect can privately access for analysis purposes. An example of use in this case, could be a compressor which analyzes the signal, to control its own effect parameters (ie a compression level or gain).

For the effect developer, to accept sidechain data, the sidechain data will appear in the FMOD_DSP_STATE struct which is passed into the read callback of a DSP unit.

FMOD_DSP_STATE::sidechaindata and FMOD_DSP_STATE::sidechainchannels will hold the mixed result of any sidechain data flowing into it.

FMOD_DSP_CONNECTION_TYPE_SEND

Send DSPConnection type. Audio is mixed from the input to the output DSP's audible buffer, meaning it will be part of the audible signal. A send connection will NOT execute its input DSP if it has not been executed before.

A send connection will only read what exists at the input's buffer at the time of executing the output DSP unit (which can be considered the 'return')

FMOD_DSP_CONNECTION_TYPE_SEND_SIDECHAIN

Send sidechain DSPConnection type. Audio is mixed from the input to the output DSP's sidechain buffer, meaning it will NOT be part of the audible signal. A send sidechain connection will NOT execute its input DSP if it has not been executed before.

A send sidechain connection will only read what exists at the input's buffer at the time of executing the output DSP unit (which can be considered the 'sidechain return').

For the effect developer, to accept sidechain data, the sidechain data will appear in the FMOD_DSP_STATE struct which is passed into the read callback of a DSP unit.

FMOD_DSP_STATE::sidechaindata and FMOD_DSP_STATE::sidechainchannels will hold the mixed result of any sidechain data flowing into it.

See Also: DSP::addInput, DSPConnection::getType