Firelight Technologies FMOD Studio API
FMOD_DSP_SHOULDIPROCESS_CALLBACK
Called to allow the plugin writer to tell FMOD's mixer whether the FMOD_DSP_READ_CALLBACK callback should be called or not. This can be used as an optimization to reduce CPU overhead. If the effect produces silence such as when it is receiving no signal, then FMOD_ERR_DSP_SILENCE can be returned in the FMOD_DSP_SHOULDIPROCESS_CALLBACK callback. If the effect does not modify the sound in any way with the current effect parameter settings, then FMOD_ERR_DSP_DONTPROCESS can be returned. Either of these return values will cause FMOD's mixer to skip the FMOD_DSP_READ_CALLBACK callback.
C/C++ Syntax
FMOD_RESULT F_CALLBACK FMOD_DSP_SHOULDIPROCESS_CALLBACK(
FMOD_DSP_STATE *dsp_state,
bool inputsidle,
unsigned int length,
FMOD_CHANNELMASK inmask,
int inchannels,
FMOD_SPEAKERMODE speakermode
);
Parameters
dsp_state
Pointer to the plugin state. The user can use this variable to access runtime plugin specific variables and plugin writer user data. Do not cast this to FMOD_DSP! The handle to the user created DSP handle is stored within the FMOD_DSP_STATE structure.
inputsidle
This is true if no audio is being fed to this unit. Code can then either set a countdown timer based on the tail length of their effect and then call FMOD_ERR_DSP_DONTPROCESS, or just immediately return FMOD_ERR_DSP_DONTPROCESS if no further processing is required.
length
The length of the incoming and outgoing buffer in samples. To get the length of the buffer in bytes, the user must multiply this number by the number of channels coming in (and out, they may be different) and then multiply by 4 for 1 float = 4 bytes.
inmask
A description of the speaker layout of the incoming buffer using FMOD_CHANNELMASK bitfield. For each channel in inchannels parameter, a bit will identify which speaker it belongs to. A value of 0 means default mapping as ordered by FMOD_CHANNELMASK.
inchannels
The number of channels of PCM data in the coming input. A mono signal coming in would be 1. A stereo signal coming in would be 2.
speakermode
A speakermode that corresponds to the channel count and channel mask. Default is FMOD_SPEAKERMODE_DEFAULT. Where it would differ, is if the channel count is lower than the specified speaker mode's channel count, ie 1 channel could be specified, and use FMOD_SPEAKERMODE_5POINT1 as the speaker mode, and the mask could tell the callback that it is FMOD_CHANNELMASK_LOW_FREQUENCY.
Return Values
If the function succeeds then the return value is FMOD_OK.
If the function fails then the return value will be one of the values defined in the FMOD_RESULT enumeration.
Remarks
An example of an effect that would continue processing silence would be an echo or reverb effect that needs to play a tail sound until it fades out to silence. At that point it could return FMOD_ERR_DSP_SILENCE as well.
Typically inmask and speakermode parameters will not be important to the plugin, unless it cares about speaker positioning. If it processes any data regardless of channel format coming in, it can safely ignore these 2 parameters.
NOTE: Effects that do not stop processing may keep the signal chain alive when it is not desirable to do so. In the case of FMOD Studio it may result in events that keep playing indefinitely.
The following code can be used for DSP effects that have no tail:
static FMOD_RESULT F_CALLBACK shouldIProcess(FMOD_DSP_STATE *dsp_state, bool inputsidle, unsigned int length, FMOD_CHANNELMASK inmask, int inchannels, FMOD_SPEAKERMODE speakermode)
{
if (inputsidle)
{
return FMOD_ERR_DSP_SILENCE;
}
return FMOD_OK;
}
See Also
Version 1.10.03 Built on Feb 1, 2018