IXAudio2Voice::DisableEffect method (xaudio2.h)

Disables the effect at a given position in the effect chain of the voice.

Syntax

\\HRESULT DisableEffect(
  [in] UINT32 EffectIndex,
  [in] UINT32 OperationSet
);

Parameters

[in] EffectIndex

Zero-based index of an effect in the effect chain of the voice.

[in] OperationSet

Identifies this call as part of a deferred batch. See the XAudio2 Operation Sets overview for more information.

Return value

Returns S_OK if successful; otherwise, an error code. See XAudio2 Error Codes for descriptions of valid error codes.

Remarks

The effects in a given XAudio2 voice's effect chain must consume and produce audio at that voice's processing sample rate. The only aspect of the audio format they can change is the channel count. For example a reverb effect can convert mono data to 5.1. The client can use the XAUDIO2_EFFECT_DESCRIPTOR structure's OutputChannels field to specify the number of channels it wants each effect to produce. Each effect in an effect chain must produce a number of channels that the next effect can consume. Any calls to IXAudio2Voice::EnableEffect or IXAudio2Voice::DisableEffect that would make the effect chain stop fulfilling these requirements will fail.

Disabling an effect immediately removes it from the processing graph. Any pending audio in the effect—such as a reverb tail—is not played. Be careful disabling an effect while the voice that hosts it is running. This can result in an audible artifact if the effect significantly changes the audio's pitch or volume.

DisableEffect takes effect immediately when called from an XAudio2 callback with an OperationSet of XAUDIO2_COMMIT_NOW.

Platform Requirements

Requirements

See also

IXAudio2Voice

XAPO Overview