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 two 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 two DSP units.

DSPConnection::getInput

Retrieves the connection's input DSP unit.

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 this function is called very soon after DSP::addInput, 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. When this occurs, the function returns FMOD_ERR_NOTREADY and input is null.

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

DSPConnection::getMix

Retrieves the connection's volume scale.

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

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 OutOpt

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 OutOpt

Number of valid output channels (rows) in matrix. Optional only when matrix is null or equivalent.

inchannels OutOpt

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.

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 this function is called very soon after DSP::addInput, 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. When this occurs, the function returns FMOD_ERR_NOTREADY and output is null.

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

DSPConnection::getType

Retrieves the type of the connection between two DSP units.

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.

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

User data set by calling DSPConnection::setUserData.

This function allows arbitrary user data to be retrieved from this object. See the User Data section of the glossary for an example of how to get and set user data.

DSPConnection::setMix

Sets the connection's volume scale.

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

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.

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.

This function allows arbitrary user data to be attached to this object. See the User Data section of the glossary for an example of how to get and set user data.

See Also: DSPConnection::getUserData

FMOD_DSPCONNECTION_TYPE

List of connection types between two DSP units.

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 executes 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 executes its input DSP if it has not been executed before.

This separate sidechain buffer exists so that the DSP can privately access it for analysis purposes. For example, a compressor DSP could analyze the signal and use the result of that analysis to control its own compression level and gain parameters.

When a sidechain is connected to a DSP, the sidechain buffer is a member of the FMOD_DSP_STATE struct, which is itself passed in as a parameter of the read callback. This data simplifies the development of effects that make use of sidechaining.

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 becomes part of the audible signal. A send connection will not execute its input DSP if it has not been executed before.

A send connection only reads 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 does not become part of the audible signal. A send sidechain connection does not execute its input DSP if it has not been executed before.

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

When a sidechain is connected to a DSP, the sidechain data is stored in the FMOD_DSP_STATE struct that is a function parameter of the read callback. This data simplifies the development of effects that make use of sidechaining.

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

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