DSP

DSP

FMOD Object: DSP

This module contains functionality related to DSPs (Digital Signal Processors), which are nodes within a graph that transforms input audio signals to an output stream.

See the DSP Architecture Guide for more information.

Functions

This module offers a collection of functions designed to address specific tasks and provide utilities for various purposes. Explore the available functions to make the most of the functionalities provided by this module.

• fmod_dsp_add_input
• fmod_dsp_get_input
• fmod_dsp_get_output
• fmod_dsp_get_num_inputs
• fmod_dsp_get_num_outputs
• fmod_dsp_disconnect_all
• fmod_dsp_disconnect_from
• fmod_dsp_get_data_parameter_index
• fmod_dsp_get_num_parameters
• fmod_dsp_set_parameter_bool
• fmod_dsp_get_parameter_bool
• fmod_dsp_set_parameter_data
• fmod_dsp_get_parameter_data
• fmod_dsp_set_parameter_float
• fmod_dsp_get_parameter_float
• fmod_dsp_set_parameter_int
• fmod_dsp_get_parameter_int
• fmod_dsp_get_parameter_info
• fmod_dsp_set_channel_format
• fmod_dsp_get_channel_format
• fmod_dsp_get_output_channel_format
• fmod_dsp_get_metering_info
• fmod_dsp_set_metering_enabled
• fmod_dsp_get_metering_enabled
• fmod_dsp_set_active
• fmod_dsp_get_active
• fmod_dsp_set_bypass
• fmod_dsp_get_bypass
• fmod_dsp_set_wet_dry_mix
• fmod_dsp_get_wet_dry_mix
• fmod_dsp_get_idle
• fmod_dsp_reset
• fmod_dsp_release
• fmod_dsp_get_type
• fmod_dsp_get_info
• fmod_dsp_get_cpu_usage
• fmod_dsp_set_user_data
• fmod_dsp_get_user_data
• fmod_dsp_set_callback
• fmod_dsp_get_system_object

---

Back To Top

fmod_dsp_add_input

FMOD Function: DSP::addInput

This function adds a DSP unit as an input to this object and returns the new DSPConnection between the two units.

The returned connection will remain valid until the units are disconnected.

Note

When a DSP has multiple inputs the signals are automatically mixed together, sent to the unit's output(s).

Syntax:

fmod_dsp_add_input(dsp_ref, dsp_input_ref, dsp_connection_type)

Argument	Type	Description
dsp_ref	Real	A reference to a DSP.
dsp_input_ref	Real	A reference to the DSP unit to be added to dsp_ref.
dsp_connection_type	FMOD_DSPCONNECTION_TYPE	The type of connection between the two units. Optional. Default is FMOD_DSPCONNECTION_TYPE.STANDARD.

Returns:

Real

---

Back To Top

fmod_dsp_get_input

FMOD Function: DSP::getInput

This function retrieves the DSP unit at the specified index in the input list.

The returned connection will remain valid until the units are disconnected.

Note

This will flush the DSP queue (which blocks against the mixer) to ensure the input list is correct, avoid this during time-sensitive operations.

Syntax:

fmod_dsp_get_input(dsp_ref, dsp_chain_index)

Argument	Type	Description
dsp_ref	Real	A reference to a DSP.
dsp_chain_index	Real	The offset into dsp_ref's input list. A value in the range [0, fmod_dsp_get_num_inputs]

Returns:

FmodDSPConnectionData

---

Back To Top

fmod_dsp_get_output

FMOD Function: DSP::getOutput

This function retrieves the DSP unit at the specified index in the output list.

The returned connection will remain valid until the units are disconnected.

Note

This will flush the DSP queue (which blocks against the mixer) to ensure the input list is correct, avoid this during time sensitive operations.

Syntax:

fmod_dsp_get_output(dsp_ref, dsp_chain_index)

Argument	Type	Description
dsp_ref	Real	A reference to a DSP.
dsp_chain_index	Real	A value in the range [0, fmod_dsp_get_num_inputs]

Returns:

FmodDSPConnectionData

---

Back To Top

fmod_dsp_get_num_inputs

FMOD Function: DSP::getNumInputs

This function retrieves the number of DSP units in the given DSP's input list.

Note

This will flush the DSP queue (which blocks against the mixer) to ensure the input list is correct, avoid this during time sensitive operations.

Syntax:

fmod_dsp_get_num_inputs(dsp_ref)

Argument	Type	Description
dsp_ref	Real	A reference to a DSP.

Returns:

Real

---

Back To Top

fmod_dsp_get_num_outputs

FMOD Function: DSP::getNumOutputs

This function retrieves the number of DSP units in the given DSP's output list.

Note

This will flush the DSP queue (which blocks against the mixer) to ensure the input list is correct, avoid this during time sensitive operations.

Syntax:

fmod_dsp_get_num_outputs(dsp_ref)

Argument	Type	Description
dsp_ref	Real	A reference to a DSP.

Returns:

Real

---

Back To Top

fmod_dsp_disconnect_all

FMOD Function: DSP::disconnectAll

This function disconnects all inputs and/or outputs.

This is a convenience function that is faster than disconnecting all inputs and outputs individually.

Syntax:

fmod_dsp_disconnect_all(dsp_ref, inputs, outputs)

Argument	Type	Description
dsp_ref	Real	A reference to a DSP.
inputs	Boolean	Whether all inputs should be disconnected.
outputs	Boolean	Whether all outputs should be disconnected.

Returns:

N/A

---

Back To Top

fmod_dsp_disconnect_from

FMOD Function: DSP::disconnectFrom

This function disconnects the specified input DSP.

If dsp_other_ref had only one output, after this operation that entire subgraph will no longer be connected to the DSP network.

After this operation dsp_connection_ref is no longer valid.

Syntax:

fmod_dsp_disconnect_from(dsp_ref, dsp_other_ref, dsp_connection_ref)

Argument	Type	Description
dsp_ref	Real	A reference to a DSP.
dsp_other_ref	Real	The input unit to disconnect, if not specified all inputs and outputs are disconnected from this unit.
dsp_connection_ref	Real	When there is more than one connection between two units this can be used to define which of the connections should be disconnected. Defaults to the value 0.

Returns:

N/A

---

Back To Top

fmod_dsp_get_data_parameter_index

FMOD Function: DSP::getDataParameterIndex

This function retrieves the index of the first data parameter of a particular data type.

The function returns the index of the first data parameter of type data_type after the function is called. This will be -1 if no matches were found.

fmod_last_result returns FMOD_RESULT.OK if a parameter of matching type is found and FMOD_RESULT.ERR_INVALID_PARAM if no matches were found.

Syntax:

fmod_dsp_get_data_parameter_index(dsp_ref, data_type)

Argument	Type	Description
dsp_ref	Real	A reference to a DSP.
data_type	Real	The type of data to find. Typically of type FMOD_DSP_PARAMETER_DATA_TYPE.

Returns:

Real

---

Back To Top

fmod_dsp_get_num_parameters

FMOD Function: DSP::getNumParameters

This function retrieves the number of parameters exposed by this unit.

You can use this value to enumerate all parameters of a DSP unit with fmod_dsp_get_parameter_info.

Syntax:

fmod_dsp_get_num_parameters(dsp_ref)

Argument	Type	Description
dsp_ref	Real	A reference to a DSP.

Returns:

Real

---

Back To Top

fmod_dsp_set_parameter_bool

FMOD Function: DSP::setParameterBool

This function sets a boolean parameter by index.

Syntax:

fmod_dsp_set_parameter_bool(dsp_ref, parameter_index, value)

Argument	Type	Description
dsp_ref	Real	A reference to a DSP.
parameter_index	Real	The parameter index. A value in the range [0, fmod_dsp_get_num_parameters - 1].
value	Boolean	The parameter value.

Returns:

N/A

---

Back To Top

fmod_dsp_get_parameter_bool

FMOD Function: DSP::getParameterBool

This function retrieves a boolean parameter by index.

Syntax:

fmod_dsp_get_parameter_bool(dsp_ref, parameter_index)

Argument	Type	Description
dsp_ref	Real	A reference to a DSP.
parameter_index	Real	The parameter index. A value in the range [0, fmod_dsp_get_num_parameters - 1].

Returns:

Boolean

---

Back To Top

fmod_dsp_set_parameter_data

FMOD Function: DSP::setParameterData

This function sets a binary data parameter by index.

You write the binary data for the parameter to a buffer using the Buffer functions and then pass the buffer and the length of the data, in bytes, to this function. The first byte of the buffer is the first byte of the data.

Note

This function doesn't take an offset, so the first byte of data is at the start of the buffer (at an offset of 0 bytes).

Syntax:

fmod_dsp_set_parameter_data(dsp_ref, parameter_index, buffer, length)

Argument	Type	Description
dsp_ref	Real	A reference to a DSP.
parameter_index	Real	The parameter index. A value in the range [0, fmod_dsp_get_num_parameters - 1].
buffer	Buffer	The Buffer that stores the data.
length	Real	The length of the data in the buffer, in bytes.

Returns:

N/A

---

Back To Top

fmod_dsp_get_parameter_data

FMOD Function: DSP::getParameterData

This function retrieves a binary data parameter by index.

It returns 0 if the function succeeds or a value greater than 0 that's the buffer size needed to store the parameter data. In this case you should resize the buffer to the return value using buffer_resize.

The binary data is copied to the Buffer that you specify. A total number of length bytes are written.

Note

This function doesn't take an offset, so the data is written to the start of the buffer (at an offset of 0 bytes).

Warning

The Buffer that receives the data should be large enough to hold the parameter value, as this function doesn't resize the buffer. Any parameter data beyond the length of the buffer will not be included.

Syntax:

fmod_dsp_get_parameter_data(dsp_ref, parameter_index, buffer, length)

Argument	Type	Description
dsp_ref	Real	A reference to a DSP.
parameter_index	Real	The parameter index. A value in the range [0, fmod_dsp_get_num_parameters - 1].
buffer	Buffer	The Buffer that receives the data.
length	Real	The length of the data to copy into the buffer, in bytes.

Returns:

Real

Example:

/// Step Event
var _required_size = fmod_dsp_get_parameter_data(dsp_fft, FMOD_DSP_FFT.SPECTRUMDATA, fft_buffer);
if (buffer_get_size(fft_buffer) < _required_size)
{
    buffer_resize(fft_buffer, _required_size);
}

The code example above attempts to get the spectrum data of an FFT DSP and store it in a buffer fft_buffer. If the size of the buffer is less than the size returned, the buffer is resized. Note that no new call to the function is made since this code executes in the Step event and will be executed again in the next step anyway.

---

Back To Top

fmod_dsp_set_parameter_float

FMOD Function: DSP::setParameterFloat

This function sets a floating point parameter by index.

Syntax:

fmod_dsp_set_parameter_float(dsp_ref, parameter_index, value)

Argument	Type	Description
dsp_ref	Real	A reference to a DSP.
parameter_index	Real	The parameter index. A value in the range [0, fmod_dsp_get_num_parameters - 1].
value	Real	The parameter floating point data.

Returns:

N/A

---

Back To Top

fmod_dsp_get_parameter_float

FMOD Function: DSP::getParameterFloat

This function retrieves a floating point parameter by index.

Syntax:

fmod_dsp_get_parameter_float(dsp_ref, parameter_index)

Argument	Type	Description
dsp_ref	Real	A reference to a DSP.
parameter_index	Real	The parameter index. A value in the range [0, fmod_dsp_get_num_parameters - 1].

Returns:

Real

---

Back To Top

fmod_dsp_set_parameter_int

FMOD Function: DSP::setParameterInt

This function sets an integer parameter by index.

Syntax:

fmod_dsp_set_parameter_int(dsp_ref, parameter_index, value)

Argument	Type	Description
dsp_ref	Real	A reference to a DSP.
parameter_index	Real	The parameter index. A value in the range [0, fmod_dsp_get_num_parameters - 1].
value	Real	The parameter integer data.

Returns:

N/A

---

Back To Top

fmod_dsp_get_parameter_int

FMOD Function: DSP::getParameterInt

This function retrieves an integer parameter by index.

Syntax:

fmod_dsp_get_parameter_int(dsp_ref, parameter_index)

Argument	Type	Description
dsp_ref	Real	A reference to a DSP.
parameter_index	Real	The parameter index. A value in the range [0, fmod_dsp_get_num_parameters - 1].

Returns:

Real

---

Back To Top

fmod_dsp_get_parameter_info

FMOD Function: DSP::getParameterInfo

This function retrieves information about a specified parameter.

Syntax:

fmod_dsp_get_parameter_info(dsp_ref)

Argument	Type	Description
dsp_ref	Real	A reference to a DSP.

Returns:

FmodDspParameterDesc

---

Back To Top

fmod_dsp_set_channel_format

FMOD Function: DSP::setChannelFormat

This function sets the PCM input format this DSP will receive when processing.

Note

Setting the number of channels on a unit will force either a down or up mix to that channel count before processing the DSP read/process callback.

Syntax:

fmod_dsp_set_channel_format(dsp_ref, channel_mask, num_channels, speaker_mode)

Argument	Type	Description
dsp_ref	Real	A reference to a DSP.
channel_mask	FMOD_CHANNELMASK	Deprecated.
num_channels	Real	The number of channels to be processed. A value in the range [0, FMOD_MAX_CHANNEL_WIDTHfmod_dsp_get_output_channel_format].
speaker_mode	FMOD_SPEAKERMODE	The speaker mode to describe the channel mapping.

Returns:

N/A

---

Back To Top

fmod_dsp_get_channel_format

FMOD Function: DSP::getChannelFormat

This function retrieves the PCM input format this DSP will receive when processing.

Syntax:

fmod_dsp_get_channel_format(dsp_ref)

Argument	Type	Description
dsp_ref	Real	A reference to a DSP.

Returns:

FmodDSPChannelFormat

---

Back To Top

fmod_dsp_get_output_channel_format

FMOD Function: DSP::getOutputChannelFormat

This function retrieves the output format this DSP will produce when processing based on the input specified.

Syntax:

fmod_dsp_get_output_channel_format(dsp_ref, channel_mask_in, num_channels_in, speaker_mode_in)

Argument	Type	Description
dsp_ref	Real	A reference to a DSP.
channel_mask_in	FMOD_CHANNELMASK	Deprecated.
num_channels_in	Real	The number of channels for the input signal.
speaker_mode_in	FMOD_SPEAKERMODE	The speaker mode for the input signal.

Returns:

FmodDSPChannelFormat

---

Back To Top

fmod_dsp_get_metering_info

FMOD Function: DSP::getMeteringInfo

This function retrieves the signal metering information.

Note

Requesting metering information when it hasn't been enabled will result in FMOD_RESULT.ERR_BADCOMMAND.

Note

FMOD_INIT.PROFILE_METER_ALL with fmod_system_init will automatically enable metering for all DSP units inside the mixer graph.

Syntax:

fmod_dsp_get_metering_info(dsp_ref)

Argument	Type	Description
dsp_ref	Real	A reference to a DSP.

Returns:

FmodDSPInOutMeteringInfo

---

Back To Top

fmod_dsp_set_metering_enabled

FMOD Function: DSP::setMeteringEnabled

This function sets the input and output signal metering enabled states.

Input metering is pre-processing, while output metering is post-processing.

Enabled metering allows fmod_dsp_get_metering_info to return metering information and allows FMOD profiling tools to visualize the levels.

Note

FMOD_INIT.PROFILE_METER_ALL with fmod_system_init will automatically enable metering for all DSP units inside the mixer graph.

Syntax:

fmod_dsp_set_metering_enabled(dsp_ref, enabled_in, enabled_out)

Argument	Type	Description
dsp_ref	Real	A reference to a DSP.
enabled_in	Boolean	The metering enabled state for the input signal.
enabled_out	Boolean	The metering enabled state for the output signal.

Returns:

N/A

---

Back To Top

fmod_dsp_get_metering_enabled

FMOD Function: DSP::getMeteringEnabled

This function retrieves the input and output signal metering enabled states.

Syntax:

fmod_dsp_get_metering_enabled(dsp_ref)

Argument	Type	Description
dsp_ref	Real	A reference to a DSP.

Returns:

FmodDSPMeteringEnableInfo

---

Back To Top

fmod_dsp_set_active

FMOD Function: DSP::setActive

This function sets the processing active state.

If active is false, processing of this unit and its inputs are stopped.

Note

When created, a DSP is inactive. If fmod_channel_control_add_dsp is used it will automatically be activated, otherwise it must be set to active manually.

Syntax:

fmod_dsp_set_active(dsp_ref, active)

Argument	Type	Description
dsp_ref	Real	A reference to a DSP.
active	Boolean	The active state. Default is false.

Returns:

N/A

---

Back To Top

fmod_dsp_get_active

FMOD Function: DSP::getActive

This function retrieves the processing active state.

If active is false, processing of this unit and its inputs are stopped.

Note

When created, a DSP is inactive. If fmod_channel_control_add_dsp is used it will automatically be activated, otherwise it must be set to active manually.

Syntax:

fmod_dsp_get_active(dsp_ref)

Argument	Type	Description
dsp_ref	Real	A reference to a DSP.

Returns:

Boolean

---

Back To Top

fmod_dsp_set_bypass

FMOD Function: DSP::setBypass

This function sets the processing bypass state.

If bypass is true, processing of this unit is skipped but it continues to process its inputs.

Syntax:

fmod_dsp_set_bypass(dsp_ref, bypass)

Argument	Type	Description
dsp_ref	Real	A reference to a DSP.
bypass	Boolean	The bypass state. Default is false.

Returns:

N/A

---

Back To Top

fmod_dsp_get_bypass

FMOD Function: DSP::getBypass

This function retrieves the processing bypass state.

If the returned value is true, processing of this unit is skipped but it continues to process its inputs.

Syntax:

fmod_dsp_get_bypass(dsp_ref)

Argument	Type	Description
dsp_ref	Real	A reference to a DSP.

Returns:

Boolean

---

Back To Top

fmod_dsp_set_wet_dry_mix

FMOD Function: DSP::setWetDryMix

This function sets the scale of the wet and dry signal components.

Syntax:

fmod_dsp_set_wet_dry_mix(dsp_ref, prewet, postwet, dry)

Argument	Type	Description
dsp_ref	Real	A reference to a DSP.
prewet	Real	The level of the 'Dry' (pre-processed signal) mix that is processed by the DSP. 0 = silent, 1 = full. Negative level inverts the signal. Values larger than 1 amplify the signal. Default is 1.
postwet	Real	The level of the 'Wet' (post-processed signal) mix that is output. 0 = silent, 1 = full. Negative level inverts the signal. Values larger than 1 amplify the signal. Default is 1.
dry	Real	The level of the 'Dry' (pre-processed signal) mix that is output. 0 = silent, 1 = full. Negative level inverts the signal. Values larger than 1 amplify the signal. The default is 0.

Returns:

N/A

---

Back To Top

fmod_dsp_get_wet_dry_mix

FMOD Function: DSP::getWetDryMix

This function retrieves the scale of the wet and dry signal components.

Syntax:

fmod_dsp_get_wet_dry_mix(dsp_ref)

Argument	Type	Description
dsp_ref	Real	A reference to a DSP.

Returns:

FmodDSPWetDryMixInfo

---

Back To Top

fmod_dsp_get_idle

FMOD Function: DSP::getIdle

This function retrieves the idle state.

A DSP is considered idle when it stops receiving input signal and all internal processing of stored input has been exhausted.

Each DSP type has the potential to have differing idle behaviour based on the type of effect. A reverb or echo may take a longer time to go idle after it stops receiving a valid signal, compared to an effect with a shorter tail length like an EQ filter.

Syntax:

fmod_dsp_get_idle(dsp_ref)

Argument	Type	Description
dsp_ref	Real	A reference to a DSP.

Returns:

Boolean

---

Back To Top

fmod_dsp_reset

FMOD Function: DSP::reset

This function resets a DSP's internal state ready for new input signal.

This will clear all internal state derived from input signal while retaining any set parameter values. The intended use of the function is to avoid audible artifacts if moving the DSP from one part of the DSP network to another.

Syntax:

fmod_dsp_reset(dsp_ref)

Argument	Type	Description
dsp_ref	Real	A reference to a DSP.

Returns:

N/A

---

Back To Top

fmod_dsp_release

FMOD Function: DSP::release

This function frees a DSP object.

If the DSP is not removed from the network with fmod_channel_control_remove_dsp after being added with fmod_channel_control_add_dsp, it will not release and fmod_last_result will return FMOD_RESULT.ERR_DSP_INUSE.

Syntax:

fmod_dsp_release(dsp_ref)

Argument	Type	Description
dsp_ref	Real	A reference to a DSP.

Returns:

N/A

---

Back To Top

fmod_dsp_get_type

FMOD Function: DSP::getType

This function retrieves the pre-defined type of an FMOD registered DSP unit.

This is only valid for built-in FMOD effects. Any user plugins will simply return FMOD_DSP_TYPE.UNKNOWN.

Syntax:

fmod_dsp_get_type(dsp_ref)

Argument	Type	Description
dsp_ref	Real	A reference to a DSP.

Returns:

FMOD_DSP_TYPE

---

Back To Top

fmod_dsp_get_info

FMOD Function: DSP::getInfo

This function retrieves information about this DSP unit.

Syntax:

fmod_dsp_get_info(dsp_ref)

Argument	Type	Description
dsp_ref	Real	A reference to a DSP.

Returns:

FmodDSPInfo

---

Back To Top

fmod_dsp_get_cpu_usage

FMOD Function: DSP::getCPUUsage

This function retrieves statistics on the mixer thread CPU usage for this unit.

Note

FMOD_INIT.PROFILE_ENABLE with fmod_system_init is required to call this function.

Syntax:

fmod_dsp_get_cpu_usage(dsp_ref)

Argument	Type	Description
dsp_ref	Real	A reference to a DSP.

Returns:

FmodCPUTimeUsage

---

Back To Top

fmod_dsp_set_user_data

FMOD Function: DSP::setUserData

This function sets a floating-point user value associated with this object.

Note

While FMOD supports arbitrary User Data, this function only allows you to set a real value (a double-precision floating-point value).

Syntax:

fmod_dsp_set_user_data(dsp_ref, data)

Argument	Type	Description
dsp_ref	Real	A reference to a DSP.
data	Real	The floating point value stored on this object.

Returns:

N/A

---

Back To Top

fmod_dsp_get_user_data

FMOD Function: DSP::getUserData

This function retrieves a floating point user value associated with this object.

Note

While FMOD supports arbitrary User Data, this function only allows you to get a real value (a double-precision floating-point value).

Syntax:

fmod_dsp_get_user_data(dsp_ref)

Argument	Type	Description
dsp_ref	Real	A reference to a DSP.

Returns:

Real

---

Back To Top

fmod_dsp_set_callback

FMOD Function: DSP::setCallback

This function enables DSP notifications for the given DSP.

When enabled, callbacks for this DSP will be triggered as an Social Async Event.

This function operates asynchronously, which means that it does not immediately return the requested result. Instead, upon completion of the task, it will trigger the Social Async Event.

Syntax:

fmod_dsp_set_callback(dsp_ref)

Argument	Type	Description
dsp_ref	Real	A reference to a DSP.

Returns:

N/A

Triggers:

Social Async Event

Key	Type	Description
type	String	The string "fmod_dsp_set_callback".
kind	FMOD_DSP_CALLBACK_TYPE	The kind of DSP callback.
dsp_ref	Real	The DSP for which this callback is triggered.
parameter_index	Real	OPTIONAL The index of the DSP parameter that's released (only included when kind is FMOD_DSP_CALLBACK_TYPE.DATAPARAMETERRELEASE).

---

Back To Top

fmod_dsp_get_system_object

FMOD Function: DSP::getSystemObject

This function retrieves the parent System object.

Syntax:

fmod_dsp_get_system_object(dsp_ref)

Argument	Type	Description
dsp_ref	Real	A reference to a DSP.

Returns:

Real